Glossary

Each term links to the page that owns it. Keywords appear in code font exactly as the grammar spells them.

Term	Meaning
Attestation	An attest KIND { source ... reason ... } declaration recording a reviewer’s decision that a changed file needs no Shape or docs update. It counts only when its source names the exact changed path, its reason is non-empty, and it is current. Coverage accepts only no_shape_change; a binding accepts the kinds its allow attest lines list. An attestation never satisfies a guard.
Binding	A binding declaration that pairs review surfaces: when a changed path matches when_changed, some changed path must match require_changed, or each triggering path needs a current attestation of a kind the binding allows. Only shp check --changed-files enforces bindings.
Candidate effect	An effect candidate declaration that records a machine-suggested effect for a function, usually from AST generation. It is not part of the function’s effect summary.
Change	A change declaration listing add, modify, and remove entries for model declarations. A modify or remove entry for a guarded target is the only thing that triggers its guards.
Checker	shp, the command-line tool that loads the Shape model and deterministically accepts or rejects it.
Claim	A declaration the author asserts in a .shape file, such as a resource’s traits or a function’s effect summary. The checker judges claims against each other; reviewers judge them against the code.
Complete effects	effects complete { ... }: a claim that the listed effects are all the function has. An empty block claims the function has none, so prefer unknown effects while effects are not known.
Component	A named part of the system that owns resources (owns), grants effects (grants), and holds function summaries (fn). owns is only name-checked: it does not gate grants and is not exclusive. Structural links to other components are relations, not component members.
Context type	The type a rationale or memory declares, written with its target, such as RefactorConstraint<fn Editor.mergeAutosaves>. A shape trait names the context type its target requires.
Coverage	The change-set check, run by shp coverage --changed-files and shp check --changed-files, that each changed file on a governed path has a current Shape update or a current no_shape_change attestation. It verifies that the model changed with the source, not that the model is accurate.
Current	For a Shape-update ref, declared in a .shape file that is in the changed-file list; currency is per file, so every ref in a touched file counts, including old ones. For an attestation, new relative to the base model when the check has one (--base-ref or --base-model); without a base, attestations follow the per-file rule too.
Design memory	The umbrella term for rationale, memory, guards, and reevaluation: typed records of why a target looks the way it does and which changes to it need review.
Diagnostic	A checker message naming what failed, why, and which declarations caused it (the caused by: block). Output is sorted by kind, then by rendered text.
Domain pack	A set of shared Shape modules vendored into the repository, conventionally under shape/vendor/, which default discovery loads with the rest of the model. A local declaration with the same name silently wins over an imported one.
Effect	A named operation, optionally targeted at a resource, such as Append<Revision>. Names are free identifiers matched literally. Only targeted effects are checked against final forbids and grants.
Evidence	A source ref on one effect entry (evidence ts("...")) that points at the code performing the effect. The checker never opens it; coverage matches its path, and the forbidden effect diagnostic prints it.
Final forbid	A forbid final member of a trait, or a forbid final in a rule. It rejects a matching effect on the resource with forbidden effect. Nothing waives it: not grants, rationale, memory, reevaluation, attestations, or imports.
Governed path	A source path matched by the paths of an implementation that declares on_change require shape_update. Changed .shape files are never governed.
Grant	A grants member of a component that permits the component’s functions to emit one targeted effect. A targeted effect without a grant fails with missing grant. A grant never overrides a final forbid.
Guard	A guards { ... } block in a rationale or memory, such as on_change require ReEvaluation<Self> or forbid transform L. A guard fires only when a change declaration modifies or removes its target, and then requires a valid reevaluation.
Hyperedge	One relation viewed as an edge of the hypergraph: it joins all the components and resources the relation connects.
Hypercycle	A cycle in the hypergraph, found by following the traversal steps that calls, callbacks, provides, and coordinated_call relations produce. A forbid hypercycle rule rejects one and reports a shortest witness.
Hypergraph	The graph whose vertices are components and resources and whose hyperedges are the declared relations. It contains only declared relations.
Implementation	An implementation declaration mapping source path globs (paths) to a component (conforms_to), with an optional on_change requirement. Coverage uses only paths and on_change require shape_update; other on_change values parse but are ignored.
Incidence	The index from each vertex to the hyperedges that touch it, which drives shp graph and hypercycle checks.
Memory	A memory declaration that records why a target has its current shape, who owns that context, what it protects, and which changes need a reevaluation.
Module	The namespace a .shape file declares with module name. An import lets a file refer to another module’s declarations without qualifying them.
Prelude	The built-in declarations every model can use without importing them: the AppendOnly trait and marker resource traits such as PII, the shape traits and their context types, and the relation kinds calls, callbacks, provides, and coordinated_call. A same-module declaration with the same name silently shadows a prelude trait.
Rationale	A rationale declaration that explains an intentional shape of a fn, component, resource, relation, implementation, or rule, typed by a context type such as InlineRationale.
Reevaluation	A reevaluation record that satisfies a named memory or rationale. While a valid one exists, none of that context’s guards fire. It is not tied to a particular change and does not expire.
RefactorConstraint	The memory context type that the RefactorSensitive shape trait requires on its target.
Relation	A top-level relation declaration that links two or more components or resources under a kind, with connects and optional roles, expects, and summary. Each relation is one hyperedge, and relations are never declared inside components.
Relation kind	The kind label of a relation. The prelude kinds have built-in endpoint rules (calls, callbacks, and provides take exactly two endpoints; coordinated_call takes an ordered A -> B -> ... chain) and traversal; any other name is accepted without endpoint checks and produces no traversal steps.
Required description	A non-empty function description, required by the RequiresDescription shape trait or by writing description required.
Resource	The data or other target a claim protects, such as Revision: a table, stream, endpoint, bucket, or domain object. It need not exist as a runtime type. Traits attach to resources, and components own them.
Rule	A top-level rule declaration. It can finally forbid an effect on every resource that has a given trait (when R has T with forbid final), or constrain the relation graph with forbid provides, forbid path, or forbid hypercycle.
Shape model	Every .shape file the checker loads, checked as one model. With no file arguments that is shape/**/*.shape under the working directory, including shape/vendor/; file arguments replace that discovery.
Shape trait	A trait such as RefactorSensitive or PreserveInline attached to a fn, component, or resource that adds a review obligation instead of constraining effects: the target must have a rationale or memory of the trait’s context type, and some traits also require a description.
Shape update	An edit to the Shape model, also called a model update. For coverage, a changed governed file counts as updated when a current .shape file names its exact path in a function source or in an effect entry’s evidence. Functions in generated-AST modules do not count.
Source ref	A reference written tag("path#symbol"), such as ts("src/history/log.ts#appendRevision"). The tag is never validated, and the checker neither resolves the path nor checks the anchor. Coverage matching drops the #anchor and any :line suffix. Prefer #symbol anchors to line numbers.
Trait	A trait declaration, or a prelude trait such as AppendOnly, attached to a resource with resource R : T. Only its forbid final and require_context members affect checking; allow, require, and plain forbid members parse but are not enforced.
Unknown effects	effects unknown: an explicit marker that a function’s effects are not known yet. Strict shp check rejects it in authored modules; --allow-unknown-effects downgrades it to a warning for local drafts, and generated-AST modules are exempt.