# Substrate Language
## Status
Stable internal language. Pointbreak's substrate framing is supported by the code-review domain and one
agent task-supervision prototype. That is enough to use this vocabulary in source docs, architecture
discussion, and code review; it is not a claim that the substrate generalizes to every possible
software-work domain. See [Substrate Thesis Summary](substrate-thesis-summary.md) for the open
generality claim and its falsification criterion.
This document names the internal coordination vocabulary. It does not authorize a separate
substrate crate, SDK, product surface, or public API. User-facing command names and output documents
should stay domain-named.
## Purpose
Pointbreak is built around durable software work objects. Different actors can read, write, and interpret
facts about those objects without requiring one central controller to decide the workflow.
The substrate language keeps that architecture legible. It separates:
- substrate concepts, which describe the durable shared medium and its coordination rules;
- domain concepts, which describe the current product shape, such as revisions or task attempts;
- product language, which should stay clear to users and should not expose implementation jargon.
The important line is naming versus factoring. Naming the substrate is a vocabulary discipline.
Factoring it into a separate module or product boundary is a later architectural decision that needs
its own design and review.
## Core Model
Pointbreak coordinates through these pieces:
- **Append-only event log.** Recorded facts are immutable. Corrections, supersession, retraction,
and resolution are new facts, not edits to old facts.
- **Work objects.** Durable subjects that actors coordinate around. A Change is stable review work;
a Revision is one immutable captured state inside it. A task attempt is the prototype domain's
work object.
- **Targets within work objects.** A file range, observation, or task checkpoint can be addressed
without becoming a peer work object.
- **Actor-attributed assertions.** Events are claims by actors, not unqualified global truth.
- **Purpose-built projections.** Read views derive from the log for a specific purpose. They can
summarize, group, flag ambiguity, and apply explicit policy.
- **Named coordination policy.** Interpretive, attention, and executive policy should live in
locatable code and docs, not as hidden defaults spread across readers.
## Layering Vocabulary
The review domain names five related layers. Two of them — **Journal** and **Engagement** — are internal
architecture vocabulary and never surface in commands or JSON; **Change**, **Revision**, and **Object**
are domain terms because the CLI addresses them.
| **Journal** | The durable container that scopes one coordinated body of work within the append-only store. | Internal only. |
| **Engagement** | A retained activity/payload hint typed by **one domain axis** (`Review` or `Task`). Change replaces its derived connectivity as the review-work grouping; it remains relevant to non-Change substrate subjects. | Internal only. |
| **Change** | Stable multi-round review work. It owns attributed membership and contextual Revision-relation claims, but never owns Revision facts or content. | `change` is a permitted review-domain term. |
| **Revision** | One immutable captured state — the addressed, fact-carrying unit that observations, input requests, assessments, and validation evidence attach to. The pre-reshape `ReviewUnit` folds into this layer. | `revision` is a permitted domain term. |
| **Object** | A **content-only identity** that is a sub-layer of `Revision`: a hash of the captured content alone, git-optional. Many revisions can share one object (two clones capturing identical content converge on the same object id), so it is a dedup/grouping key, **not** a peer work-object kind. | `object` is a permitted domain term (listing/grouping only). |
On the surface, the review commands are flat top-level verbs (`pointbreak capture`, `pointbreak change …`,
`pointbreak revision …`, `pointbreak observation …`). Change names stable review work; Revision names one
captured state; Object names its content identity. Facts stay Revision-targeted even when several Revisions
belong to one Change.
These are related scopes, not a strict containment chain. Change claims use a journal-scoped target:
interactive writers use `journal:default`, while bulk adoption preserves the legacy root's journal id.
Exact Revision facts retain the review-domain EventTarget. Engagement is therefore not a parent from which
Change membership or current selection is inferred.
**Single-domain-axis guard.** The domain appears structurally in two places — the `Engagement` type
domain is **derived from / type-checked against** its engagement, never asserted as an independent wire
field. That is what keeps the layering from re-creating the diverged-identity trap one layer up — the
exact failure the reshape exists to fix (see the thesis summary's note on the aspirational
`WorkObjectId` claim).
## Substrate Concepts
| event | An atomic recorded fact. Authoritative as a record, not necessarily as world truth. |
| event log | The append-only stream of events. |
| projection | A derived read view over events for a specific purpose. |
| work object | A durable thing actors coordinate around, with stable identity and captured state. |
| target | A more specific address inside a work object. |
| actor | Any participant: human, coding agent, import pipeline, automation, or tool. |
| assertion | An attributed claim about a target. |
| advisory | Assertion mode meaning non-binding by default. |
| operative | Assertion mode meaning binding only under explicit projection policy. |
| stale | An action against captured state that has moved since the actor read it. |
| fingerprint | Opaque identity for a captured state. Equality is meaningful; internal structure is not. |
| supersedes | A directional Change-scoped claim that one exact Revision replaces another exact Revision. |
| supersession DAG | The fork-tolerant graph built from active exact Change-scoped relation claims. Current sets and divergence are derived per Change; competing successors are **surfaced**, never tie-broken. |
| provenance | Source information for a fact or imported assertion. |
| evidence | Material that supports an assertion, such as test output, logs, traces, or artifacts. |
| supersession | A new event that replaces an earlier event without mutating it. |
| retraction | A new event that withdraws an earlier event without mutating it. |
| representative selection | Stable choice of one representative for duplicate semantic facts. |
| projection diagnostic | A first-class signal that a projection saw ambiguity, conflict, drift, or data loss. |
| ambiguity preservation | The discipline of carrying disagreement as explicit state instead of picking a winner. |
| derived attention state | Projection output used to guide attention, not to authorize or block writes. |
### Change-Scoped Supersession Replaces Lineage and Derived Threads
Earlier designs used a scalar lineage, then proposal-borne `supersedes`/`continues` pointers whose connected
component formed a derived thread. Both are retired as current authority. Stable review work is an explicit
**Change** with attributed membership. Replacement is a separately keyed, exact-claim-withdrawable
Change-scoped relation between `RevisionRefV1` values.
The graph remains fork-tolerant. Two current Revisions with no intersecting replaced ancestry are valid
parallel work. Two current successors whose predecessor ancestry intersects are
`replacement_divergent`; the projection surfaces the conflict and never chooses by timestamp. A
consolidation may replace several predecessors. The same Revision may belong to several Changes, so relation
meaning is contextual rather than one global thread. Object identity remains a separate dedup/grouping lens
and never selects a current Revision.
## Policy Vocabulary
| interpretive policy | Rules that define what events or projection values mean. |
| attention policy | Rules that decide what is surfaced, hidden, grouped, sorted, or highlighted. |
| executive policy | Rules that decide what is allowed to proceed or treated as operative. |
| coordination semantics | The complete set of rules by which actors coordinate through the substrate. |
Executive policy is allowed, but it must be explicit and locatable. A projection that answers "may
this actor continue?" is acceptable when the rule is named, testable, diagnostic-rich, and derived
from events. A scheduler, hard lease system, write gate, or hidden global current-state field is a
different architecture.
### Attention Is Not Execution
"No controller" means **no executive controller** — no scheduler, lease, write gate, or daemon-owned
workflow state. It does **not** ban attention. Attention and notification are allowed and load-bearing:
a projection may surface what needs a human's or agent's attention, and a reader may poll for liveness
changes. The split is the discipline — attention output guides where to look; it never authorizes or
blocks a write.
**Notification-independence invariant.** A notification is **never a write precondition**. Every
durable write succeeds without anyone being notified first, and every reader re-reads durable state
before acting rather than trusting a delivered hint. There is no daemon and no filesystem-watch
dependency on the write path; freshness is pull-only. The input-request model states this boundary
directly — its "no filesystem notification" / "no daemon or notification service" Non-Goals are the
seam this invariant rests on (see [input-request-model.md](input-request-model.md)). The freshness and
liveness mechanics live in the same place.
## Wire Naming: When An Event Name Is Abstract
Event names follow one rule that unifies the abstract and domain halves of the vocabulary:
> An event name uses the abstract **`WorkObject`** term **iff** it spans both work-object kinds
> (`Revision` and `TaskAttempt`) **and** that cross-domain symmetry is load-bearing. Otherwise it names
> the domain work object (`Review*` / `Task*`, including the `Revision*` association family) or its own
> concept (`InputRequest*`, `ValidationCheckRecorded`, and so on).
`WorkObjectProposed` is the **sole** event that satisfies the rule. It is the generative move that proposes
one immutable captured Revision or TaskAttempt. Historical Revision proposals may carry legacy
`supersedes`, but current review writers express replacement through Change-scoped relation claims.
Change declaration and membership are separate review-domain events. Crucially, the domain is **not** a
separate field on the event: it rides `EventTarget.subject` (the `TargetRef` variant), the single
source of truth for which kind the subject is. A reader recovers the domain from the subject, never
from a parallel discriminator that could disagree with it.
Everything else names its domain directly: observations, assessments, and notes stay `Review*`; the
commit/ref association family is `Revision*` (`revision_commit_associated`, `revision_ref_withdrawn`,
…); input requests and validation evidence name their own concept. The surface verb is unchanged:
`pointbreak capture` is still how an author proposes a work object, even though the internal event is
`work_object_proposed`.
**Generative moves default and stay Advisory.** The highest-stakes rule for the generative move is that
proposing a work object — like every other recorded assertion — is **advisory by default**. A proposal
becomes operative only under explicit projection policy, never by being written. This is the same
advisory-first rule that governs resource claims; see
[ADR-0003](adr/adr-0003-agent-resource-claims-advisory-first.md).
## Current Domain: Code Review
| change | stable review work object | Multi-round review identity with attributed Revision membership and contextual replacement claims. |
| revision | exact captured state | Captured working-tree (or committed-range) state; the immutable fact/resource target. |
| object | content identity of a revision | The content-only hash a revision carries; groups revisions with identical content. |
| review observation | assertion | An attributed claim about a revision or target inside it. |
| review assessment | assertion | A formal review-domain call. |
| review note | imported assertion | A note imported from an external review source. |
| input request | assertion | A durable request for another actor's input, such as attention, decision, or explicit response. |
| input request response | assertion | A durable answer to an input request. |
| validation evidence | evidence | A completed check's facts attached to an exact captured revision. |
Review-domain terms remain correct in command names and user-facing JSON. Do not rename user-facing
surfaces to substrate terms just because the underlying pattern generalizes.
The domain surface is `pointbreak validation` and documents such as
`pointbreak.review-validation-list`. Internally, those records are evidence supporting an assertion, but
public commands and JSON stay review-domain named.
## Current Prototype Domain: Task Supervision
| task attempt | work object | A bounded attempt by an agent to perform a software task. |
| checkpoint | target within a task attempt | A captured assistant-turn boundary, not a peer work object. |
| task observation | assertion | An attributed claim or captured signal about a task attempt or checkpoint. |
| resumption projection | executive-policy projection | A read view that decides whether an agent may resume under explicit rules. |
The task-supervision prototype validates that these shapes can reuse the same event-log and
projection pattern without adding scheduler, lease, or controller primitives. It does not by itself
authorize a public task command surface.
## Carry-Forward Rules
- Keep substrate vocabulary internal unless a user-facing term is clearly better than the domain
term. Prefer `pointbreak revision show` over exposing "projection" in the command surface; keep `Journal`
and `Engagement` out of the command surface entirely.
- Preserve ambiguity in projections. Multiple distinct facts should surface as ambiguous or
diagnostic state, not disappear behind timestamp tie-breakers. Competing supersession heads are the
canonical case: surface them, never null or auto-pick.
- Treat event IDs and filenames as storage addresses, not causal order. Use explicit Change-scoped
relation claims for succession, not filename or timestamp order.
- Keep advisory and operative separate. Stored assertion mode is an actor's claim; treated-as-
operative is a projection rule.
- Keep resource claims advisory by default. See
[ADR-0003](adr/adr-0003-agent-resource-claims-advisory-first.md).
- Compare fingerprints as opaque values. Equality is the stable contract; domain-specific parsing
belongs outside the substrate rule.
- Add substrate primitives only when a real projection or writer needs them. Do not fill out a
speculative platform vocabulary.
### Two Conscious Relaxations
This vocabulary keeps every original guardrail, with two deliberate refinements worth naming:
- **"Named, not factored" now permits *internal* factoring.** Naming the substrate has always been the
discipline; the relaxation is that internal modules may be organized around these layers
(`Change`, `Revision`, `Object`, projections) without that counting as "factoring." What stays forbidden is a
*separate* substrate crate, SDK, or product boundary — an external factoring with its own design and
review.
- **The current-state-scalar suspicion is *strengthened*, not loosened.** The old guardrail was wary of
a global current-state field. A Change now derives a fork-tolerant current set from active exact relation
claims and surfaces parallel work or replacement divergence explicitly. No timestamp-selected scalar can
silently hide another current Revision.
## What This Does Not Authorize
- A separate substrate package, crate, or SDK.
- A scheduler, lease manager, daemon broker, or write-side gate.
- A global "current task" or "current actor" field for domains where ambiguity is normal.
- Productizing task supervision or any additional domain.
- Renaming existing review-domain commands simply to match the substrate vocabulary.
- Surfacing `Journal` or `Engagement` in any command, flag, or JSON document.
## Related Docs
- [ADR-0042: Stable Changes, Exact Revisions, and Explicit Store Activation](adr/adr-0042-stable-changes-exact-revisions-and-explicit-activation.md)
- [Substrate Thesis Summary](substrate-thesis-summary.md)