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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jovesun-lab
• Source: jovesun-lab/arcgram
• License: Apache-2.0
• Homepage: https://arcgram.io

Install and usage instructions live in the source repository linked above.