Protocol Chaos reference server

The directory: every Event in brief, {id, title?, state, parents, progress?, updatedAt}, most recently updated first, from which you decide what to read. Pass sinceVersion (the version you cached) to learn whether anything changed; filter by state (a state, "open" or "closed"); page with limit and cursor (pass next).

Create an Entity: one specific person, animal, thing or place that recurs across Events or applications and has user-specific information to accumulate (otherwise use a {criteria} ref on the Event). Search first (entity_search). accountText holds the words it rests on; statements are its first facts, one fact each, 1 to 200 characters, with absolute dates. owner: true only for the user's own Entity (at most one). Verbatim rule: the words (text, accountText) are the user's actual words, trimmed and otherwise unchanged, never a summary or a third-person paraphrase; pass the part about this Entity. Statements are your one-fact interpretation; mark an inference with basis. Returns {entityId, version, accountId, added}.

Read one Entity. entityId is an Entity id or "current_user" (the user's own Entity). view "summary" returns {entity, summary}: the short list of Statements meant to be loaded into every conversation (never sensitive ones). view "full" (default) returns {entity, statements}: the Statements that are not outdated, by topic, then by creation. includeHistory adds history (the outdated ones); includeEvents adds referencedBy (the Events whose refs name it); topics restricts the Statements returned.

Record words about an Entity together with what they change: name, aliases (the complete new list), add (new Statements; may supersede or conflict with existing ones), update (status, reason, sensitivity, inSummary of existing Statements) and support (existing Statements these words also support). Saying the same thing again is merged into the existing Statement as more evidence. A Statement resting on the user's words can be superseded, or its status changed, only by the user's own words (USER_WORDS_PROTECTED): add your version with conflictsWith instead. A disputed Statement becomes current again only by the user's words (USER_CONFIRMATION_REQUIRED). Carry expectedVersion (the Entity's). Verbatim rule: the words (text, accountText) are the user's actual words, trimmed and otherwise unchanged, never a summary or a third-person paraphrase; pass the part about this Entity. Statements are your one-fact interpretation; mark an inference with basis. Returns {entityId, version, accountId, added?, merged?, changed?, supported?}.

Find the people, animals, things and places the user refers to (Entities), for example before creating one, so that one does not become two. Every Entity whose name or an alias equals the query (ignoring case) comes first, then names and aliases that start with or contain it, then Entities whose Statements contain it. Omit query to list every Entity; filter by kind. Returns {entities}: cards {id, kind, name, aliases?, owner?, version, statements}, where statements counts the Statements that are not outdated.

Link an Event (child) as part of a larger Event (parent). Link only when it is plainly part of it or a step toward it; two separate trips are siblings. Ground the link on Accounts of the child or of the parent. Adding an existing link changes nothing; a link that would close a cycle fails with PART_OF_CYCLE. Returns {eventId, version, parents} for the child.

Read one Event: {event, accounts, entities?}, the document, its most recent Accounts (default 20, or "all"), oldest first, and, when its refs name Entities, those Entities as {id, kind, name}. History is read with event_get_revisions.

Read the history of an Event: its Revisions in commit order. Page with limit and after (pass next).

Record the user's words on an Event, or start a new Event with them. Changes nothing else (it gives a title only to an Event that has none). With eventId the words are appended; without it a new Event starts in state emerging, optionally titled and placed under parentEventId. Check the directory first so one matter does not become two. Verbatim rule: text is the user's actual words, trimmed and otherwise unchanged, never a summary or a third-person paraphrase such as "The user confirmed…"; when a message covers several Events, pass the part about this Event, still in the user's words. Interpretation belongs in the fields. Returns a receipt.

Record words together with the changes they support, atomically: set any of title, state, progress, facts (goal, constraint, plan), refs and metadata. To fold words recorded earlier into fields, pass that Account's accountId and its exact text instead of appending new words. Each supplied field replaces the stored one, so supply its complete current content and carry over what still holds; null removes a field. Mark your own inferences inside the fact text with their basis. Verbatim rule: text is the user's actual words, trimmed and otherwise unchanged, never a summary or a third-person paraphrase such as "The user confirmed…"; when a message covers several Events, pass the part about this Event, still in the user's words. Interpretation belongs in the fields. Returns a receipt.

Remove the link "child is part of parent", grounded on Accounts of the child or of the parent. Removing a link that does not exist fails with NOT_FOUND. Returns {eventId, version, parents} for the child.

Find Events for a query you chose, such as the name of a matter, before creating one (so one matter does not become two). Matching is by words, not by meaning: every Event whose title contains the query (ignoring case) comes first, then Events whose facts, progress, refs or recorded words contain it, then Events that hold every word of the query. Returns {events} in brief, as in the directory, best matches first. Filter by state (a state, "open" or "closed"); limit caps the number returned.

Undo the latest change of an Event that has not been undone: a field.changed, parent.added or parent.removed Revision (words recorded since do not count). Events and words are never removed, so event.created and account.added cannot be undone, nor can an undo. Anything else fails with REVISION_NOT_REVERSIBLE, for example after another writer changed the Event: read it again and reconsider. Records a revision.reverted Revision and returns it; call again on the next change to walk further back.

The words recorded since a moment, for folding them into fields later or refreshing a cache. Returns {version, checkpoint, remaining, events}: each Event that gained Accounts after since, with its current title, state, facts, refs, progress and parents, and words, its new Accounts, oldest first. Pass checkpoint as the next since to continue; remaining counts the Accounts not yet returned. limit is the number of Events per batch (a batch never ends between two Accounts with the same createdAt). Going over the same words twice changes nothing, because each field write carries the complete current content.