Event contract #

Canonical envelope #

Every event has these fields:

Field	Meaning
id	Stable globally unique event identity and Jazz row id, deterministically derived from (source, idempotencyKey).
type	NSID-style type, e.g. stream.thought.source.file.changed.
schemaVersion	Positive integer version for the payload contract.
source	Connector instance id, e.g. filesystem:coil-projects.
sourceKind	filesystem, rss, jetstream, fastmail, telegram, timer, agent, or extension.
sourceSequence	Monotonic integer assigned by the one producer process for this source namespace.
externalId	Stable source-native identity where available.
idempotencyKey	Deterministic key unique within a source.
occurredAt	Source time, if known.
observedAt	Local observation time.
actor	Source actor, system component, or agent id.
rootEventId	First event in a causal chain. A source event roots itself.
parentEventId	Immediate causal parent when derived.
correlationId	Groups a scan, poll, update batch, or run.
privacy	private, sensitive, or public-source.
payloadJson	Validated canonical JSON for the declared type/version.
payloadHash	SHA-256 of canonical payload JSON.
traceId	Optional consumer-execution or connector trace id.
createdByRuntime	Runtime build/version identifier.

Immutability #

Events are inserted once. They are never updated or deleted by application code. A correction references the wrong event and appends a new correction or retraction event. Retention compaction, if later added, must preserve a signed manifest and is out of scope for the first release.

Idempotency #

The canonical event identity is (source, idempotencyKey). thought stream derives a deterministic UUID-compatible event/Jazz row id from that pair and performs a caller-id insert. The source identity remains visible in event columns, but a query-before-insert check is not the uniqueness boundary.

The pinned local runtime rejects a second insert at the same row id and preserves the first row. After that rejection, existing content must match the candidate's stable identity fields and payload hash; a mismatch is an integrity failure, never an update. The source's one producer process serializes normal writes and advances its sourceSequence with its external cursor.

Examples:

• File version: documentId:sha256.
• File deletion: documentId:deleted:lastKnownSha256.
• Jetstream commit: did:collection:rkey:rev:operation.
• RSS item: feedUrl:itemGuidOrCanonicalUrl:contentHash.
• JMAP email state transition: accountId:emailId:emailState.
• Telegram update: accountId:chatId:messageId:editDateOrOriginal.
• Consumer output: consumerId:consumerVersion:executionId:attempt:outputIndex:outputType.

Lineage #

• Source events set rootEventId = id and have no parent.
• Consumer lifecycle events set rootEventId to the triggering root and parentEventId to the event that caused that transition.
• An execution over multiple roots lists all input ids in its payload but chooses the event that opened the execution as the envelope root.
• Correlation is not causation. correlationId groups operational work; parentEventId states a causal claim.

Event families #

Source #

• stream.thought.source.file.added
• stream.thought.source.file.changed
• stream.thought.source.file.renamed
• stream.thought.source.file.deleted
• stream.thought.source.rss.item
• stream.thought.source.atproto.commit
• stream.thought.source.x.activity
• stream.thought.source.email.observed
• stream.thought.source.telegram.message
• stream.thought.source.agent.message
• stream.thought.source.telegram.nonconversation
• stream.thought.source.telegram.reaction
• stream.thought.source.telegram.correction
• stream.thought.source.review.prompt
• stream.thought.source.course.question

stream.thought.source.course.question@1 is one sensitive, self-rooted web event for the exact web-course:post-training-model-factory source. Its payload binds a caller idempotency key, current repository-derived course revision, known lesson and optional section, bounded question text, and fixed interface identity. Divergent request-id reuse and stale course revisions fail before insertion. See courses.md.

Connector lifecycle #

• stream.thought.connector.poll.started
• stream.thought.connector.poll.completed
• stream.thought.connector.ingest.started
• stream.thought.connector.ingest.completed
• stream.thought.connector.subscription.started
• stream.thought.connector.subscription.connected
• stream.thought.connector.subscription.stopped
• stream.thought.connector.cursor.advanced
• stream.thought.connector.failed
• stream.thought.connector.recovered

Operational incidents #

• stream.thought.runtime.incident

An operational incident is a deterministic, content-dark projection over connector, scheduler, agent-run, and action failure/recovery evidence. It is always sensitive and contains only versioned classifications, bounded identifiers, retry/progress disposition, and strong references. See incidents.md.

Thought artifacts #

• stream.thought.artifact.requested@1
• stream.thought.artifact@1

The first event is append-only private evidence requesting promotion of one relative file from one explicit workspace lease. It grants no publication authority and contains no absolute root. The second is immutable metadata referencing verified bytes in the private content-addressed blob root; it contains hash, byte count, canonical relative blob path, media type, provenance, request lineage, visibility, publication eligibility (always false), and optional supersession, but no inline bytes or source path. See artifacts.md.

Consumer execution lifecycle #

• stream.thought.consumer.execution.received
• stream.thought.consumer.execution.started
• stream.thought.consumer.execution.trace
• stream.thought.consumer.execution.completed
• stream.thought.consumer.execution.failed
• stream.thought.consumer.execution.blocked
• stream.thought.consumer.execution.skipped
• stream.thought.consumer.execution.status-unknown
• stream.thought.consumer.execution.abandoned

Model adapter deployment evidence #

Adapter state is not mutated through domain events. One immutable startup deployment catalog selects an exact release for each declaration. Run, output, failure, judgment, and training evidence carries the public release identity, checkpoint-reference digest, catalog digest, and catalog generation. It never contains the resolved checkpoint value. Activation and retirement are coordinated stop/install/restart operations verified through process and loaded-digest receipts, not Jazz lifecycle events.

Repair coordination #

• stream.thought.agent.repair.requested

A repair request is deterministic append-only evidence over one eligible original failed run and one complete repair-policy identity. It contains immutable run/event/declaration/contract references and sanitized validation issues, never malformed candidate text or failed-trace content. Repeated reconciliation addresses the same row. Repair-origin and infrastructure failures cannot generate it.

Agent proposals and decisions #

• stream.thought.agent.memory-change.proposed
• stream.thought.agent.correction.proposed
• stream.thought.agent.public-knowledge-diff.proposed
• stream.thought.agent.proposal.decision
• stream.thought.agent.memory-change.materialized
• stream.thought.agent.memory-change.materialization.failed

Proposal events are sensitive, append-only agent requests bound by the trusted parent to one retry-stable context snapshot. They grant no canonicalization, judgment, file, publication, channel, or export authority. A human decision may accept, edit, or reject memory/correction proposals. Public Knowledge diff proposals currently have no decision or materialization path; any future path must consume a separate human decision and may never write or publish directly from the agent proposal. See proposals.md and public-knowledge.md.

Working documents #

• stream.thought.workbench.document.created@1
• stream.thought.workbench.document.version@1
• stream.thought.workbench.context.selected@1
• stream.thought.workbench.proposal.requested@1
• stream.thought.workbench.proposal.proposed@1
• stream.thought.workbench.proposal.decision@1

Workbench events are sensitive, append-only system events under source: workbench:documents, rooted at the origin observation's root so a working document is findable from that event's lineage. A version event references one immutable documentVersions row; the documents row is only the current-head projection. A proposal is inert runner output bound to one exact base version and one exact context snapshot; it grants no publication, file, or training authority. One deterministic decision identity per proposal makes same-submission retries converge and different submissions conflict. Accept appends a new version only when the base is still the head; a stale base fails closed. Decisions project through recordJudgment with quality and export eligibility fixed false. See documents.md.

Focus proposals #

• stream.thought.focus.declaration.proposed

A focus proposal contains one strict versioned focus declaration and its canonical fingerprint. It is always sensitive and effect-inert: proposal presence grants no consumer activation, source access, external action, training, or adapter promotion. Operator CLI proposals use focus-id@version as their idempotency boundary and therefore require a version bump for changed content. Agent-authored Telegram proposals use a run-scoped event identity so repeated semantic identities cannot wedge source progress; a later approval/compiler must resolve duplicate or conflicting focus ids and versions. See focuses.md.

Initial derived outputs #

• stream.thought.derived.output.correction.proposed
• stream.thought.derived.topics
• stream.thought.derived.entities
• stream.thought.derived.post.candidate
• stream.thought.derived.retrieval.recommendation
• stream.thought.derived.document.structure
• stream.thought.derived.charter.reevaluation
• stream.thought.derived.conversation.compaction
• stream.thought.derived.agent.message
• stream.thought.derived.public-knowledge.recommendation

Derived events are proposals or observations. A post candidate is never a publishing command. An output correction proposal is never an effective replacement without an active accept or correct judgment.

stream.thought.derived.conversation.compaction@1 is a sensitive recursive continuity boundary over one frozen canonical conversation prefix. It preserves the previous boundary reference, exact covered-through frontier, content-dark input hashes, completed compactor run, and one model-authored plain-text summary wrapped by the trusted parent in the typed output contract. It cannot delete events, become system policy, authorize an action, or enter Telegram egress. See compaction.md.

stream.thought.derived.public-knowledge.recommendation@1 is historical. Version 3 writes stream.thought.agent.public-knowledge-diff.proposed@1, which carries one exact private draft and either an absent new slug or an admitted existing slug plus base hash. Neither event can serve as a review receipt, promotion command, publication authorization, ATProto write request, or deployment trigger.

Judgments #

• stream.thought.judgment.training-example
• stream.thought.judgment.training-example.retracted

Judgments are append-only. A changed decision names the prior judgment in supersedesJudgmentEventId; removal appends a retraction naming retractedJudgmentEventId. Rebuildable training and effective-output projections exclude superseded and retracted judgments without deleting their evidence. A correct replacement is appended only after canonical output-contract validation. stream.thought.source.telegram.correction@1 is separate sensitive source evidence for an allowlisted target-bound /correct command; unresolved commands remain inert source rows and never become conversation turns.

Human Review #

• stream.thought.derived.review.response
• stream.thought.review.item.created
• stream.thought.review.decision

The source prompt holds complete bounded evidence. Candidate response events are ordinary contract-valid run outputs with a receipt proving one complete, unprojected, tool-free prompt context. A review item freezes two exact same-trigger completed runs, output ids, training-relevant run-receipt digests, and one deterministic blinded order without copying output. Queue, decision, and export projection revalidate those frozen receipts. A review decision records judgeability, preference, tie, correction, or skip and may supersede an earlier decision. Only the active externally eligible prefer or correct decision can project into a v4 training example. See review.md.