| name | checkpoint |
| description | Validate an Arcgram diagram as a logic spec: is the flow well-formed and coherent? Reads node/edge structure (id/f/t/kind/role/type), never geometry. Typed findings - dangling edge, orphan node, missing branch, disconnected island, duplicate id, missing schema, plus optional coherence (every action traces to a goal). Marks, never blocks. Run after authoring or editing a diagram. Agent-neutral. Sibling to Reconcile (Checkpoint = structure; Reconcile = values). |
Checkpoint - Arcgram logic self-check validator
One input: a diagram (treated as a spec).
One question: is the flow logic well-formed and coherent?
Returns typed findings; marks, never blocks.
Sibling to Reconcile: Checkpoint checks structure from the diagram alone; Reconcile
checks values across diagram + code. Run both -> the diagram is a faithful, current spec.
It checks the graph's logic structure - not drawing quality (the engine auto-handles
overlaps/spacing/routing) and not semantic correctness (whether the logic is right - a
human call).
Red line: reads only the semantic field values id, f, t, kind, role, type
(plus optional status, flag). Never a coordinate, color, size, or spacing. The judge: am I
reading a semantic string, or a rendered visual quantity?
Findings
Tier A - structural integrity (always on). Domain-agnostic graph theory.
| finding | means |
|---|
dangling-edge | an edge points at an id that is not a node |
orphan-node | a node has no edge (chain broken) - except a declared type:'open' |
missing-branch | a decision (kind:'diamond') lacks its Y or N branch |
disconnected-island | a cluster with no edge to the main flow |
duplicate-id | a node id used more than once |
missing-field | a node has no id, or an edge no f/t |
missing-meta-version | ARCGRAM_META.version absent |
empty-diagram | no nodes - reported uncovered, never falsely "clean" |
Tier B - justification coherence (auto-on for a thinking flow). Does it read as reasoning:
every action traces back to a goal, every goal reaches an action, every decision sits
on a justification path. Auto-on when the diagram has a decision diamond (kind:'diamond', = the
engine's _isThinkflow); no-diamond diagrams skip it. Override --tier-b / --no-tier-b. Roles:
goal/action/decision (coherence-bearing) + constraint/evidence/state/output
(recognized). No resolvable role -> [?] uncovered, never guessed. cat is not read.
Each finding is { id, type, severity, note }; severity = defect or uncovered.
Output (same contract as Reconcile)
{ findings:[{id,type,severity,note}], summary, attestation, clean }
self-check ran HH:MM:SS | N findings | M unchecked
clean only when N=0 AND M=0 - "checked & clean" never looks like "never checked".
Human reads the marker; agent reads the type.
Use
node checkpoint.mjs diagram.html [--tier-b | --no-tier-b] [--json]
cat diagram.json | node checkpoint.mjs
import { checkpoint } from './checkpoint.mjs';
checkpoint({ nodes, edges, meta });
Exit 1 on any defect (advisory - never blocks).
Verify: node checkpoint-selftest.mjs (19 checks).
Render-time: the engine exposes the same check via window.__arcgramInspect() (the checkpoint
field of its result) + the on-canvas [?] badge and attestation stamp.
