Checkpoint

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.