agentic-mermaid 0.1.0 → 0.1.2

package/docs/mutation-testing.md

@@ -1,206 +0,0 @@
-# Mutation testing (ASCII layout core)
-
-Stryker mutation testing is scoped to the five ASCII layout modules where a
-silent logic regression is most expensive: `src/ascii/pathfinder.ts`,
-`src/ascii/edge-routing.ts`, `src/ascii/converter.ts`, `src/ascii/grid.ts`,
-`src/ascii/draw.ts`.
-The config is `stryker.ascii.config.json`; its command runner executes the
-ASCII test files (goldens, invariants, properties, unit tests) per mutant.
-
-## Running
-
-```bash
-# One module (preferred — a full module takes 5–15 minutes):
-npx stryker run stryker.ascii.config.json --mutate 'src/ascii/pathfinder.ts'
-
-# All five (also available as `bun run mutation-test:ascii`):
-npx stryker run stryker.ascii.config.json
-```
-
-(`stryker.families.config.json` / `bun run mutation-test:families` covers the
-agent family parsers, and `stryker.routes.config.json` / `bun run
-mutation-test:routes` covers the route-contracts module
-(`docs/design/system/route-contracts.md`), all with the same policy.)
-
-Narrow lanes for PR-scale survivor harvests:
-
-```bash
-bun run mutation-test:links            # text-embedded link-length parsing
-bun run mutation-test:routes:certs     # route-certificate finality + stale-route audit
-bun run mutation-test:routes:subgraph  # subgraph endpoint/LCA routing
-bun run sabotage:routes                # one-line revert checks against committed HEAD; expects focused tests to fail
-```
-
-The JSON report lands in `reports/mutation/` (gitignored). Beyond the lanes
-documented here, `stryker.*.config.json` also covers the per-family parsers
-(state/sequence/timeline/class/er/journey/pie/quadrant/gantt via
-`mutation-test:families`), characterization, and the link-grammar lane — see
-`package.json` scripts for the full index. Broad route lanes
-are intentionally not part of the PR gate, but `.github/workflows/nightly-route-mutation.yml`
-runs `mutation-test:routes`, `mutation-test:routes:certs`,
-`mutation-test:routes:subgraph`, and `sabotage:routes` nightly and on manual
-`workflow_dispatch`, uploading reports as artifacts — though every scheduled
-run to date has been cancelled at the 90-minute cap before uploading anything
-(the unsharded routes lane exceeds it; PR #63 carries the sharding fix), so
-current scores come from local runs. Run the narrow lane locally
-when you touch ASCII/route core logic and want immediate proof the tests bite.
-
-## Policy
-
-A SURVIVED mutant is a test gap until shown otherwise. Either kill it with a
-test (and sabotage-verify the test), or classify it below with a reason.
-Don't chase 100%: performance-guard and unreachable-branch mutants are
-documented, not killed with synthetic inputs.
-
-## Baseline (June 2026, first scoped run)
-
-| File | Score | Killed+timeout | Survived |
-| --- | --- | --- | --- |
-| pathfinder.ts | 60.3% → 70.8% after `ascii-pathfinder-units.test.ts` | 184 → 216 | 121 → 89 |
-| edge-routing.ts | 55.1% | 163 | 133 |
-| converter.ts | 38.4% | 94 | 151 |
-| grid.ts | 70.1% | 421 | 180 |
-| layout/passes/index.ts:931-1165 (linkrank packing repair) | 49.86% → 65.07% after the geometry-characterization harvest (355 mutants; killed 176 → 230+1 timeout). The +54 kills were the repair's candidate ORDERING / ahead-node selection / push-delta arithmetic — invisible to HARD-metric assertions (a mutant picking a different clear lane still yields zero violations), pinned instead by per-repro geometry snapshots in `linkrank-packing.test.ts` (layout determinism makes them stable). | 355 | 124 — see classification below |
-| route-contracts.ts | 58.1% → 72.3% → 75.6% → 73.1% across the first three batches; 54.31% at 0b43c90, then 50.69% at 526d9cf after the slanted-family batch (shapePorts generalization, convex-polygon geometry: 2659 → 2740 mutants — absolute kills 1444 → 1381). The percentage fell purely on denominator growth (~3× since batch 3); a survivor-harvest batch is the documented next quality step. | 882 → 2740 | 50.69% (1381 killed) — survivor harvest pending |
-
-(Numbers from the June 2026 runs; regenerate rather than trusting this
-table — the report lands in `reports/mutation/`.)
-
-## Survivor classification
-
-**linkrank lane residual (124 at the 65.07% run)**, classified:
-
-- **Real gap, next harvest**: the subgraph-scoped `separationUnit` branch (walk the
-  overlapped node's scope chain, push its outermost subgraph unit) never fires — the
-  degenerate repro set has no subgraphs. Killing these needs a subgraph + long-link
-  shove-overlap fixture.
-- **Unexercised defensive fallbacks**: the `rungSource` feedback family and some
-  min-lane branches fire only on inputs the deterministic enumeration no longer
-  produces (0 residual signatures); every adopted route is still runtime-validated by
-  `routeClearOfNodes`, so a wrong fallback cannot ship a through-node route.
-- **Equivalent on the real input domain**: exact-tie tiebreaks (`flowGap !== 0` id
-  fallback), the `pairKey` separator literal (any injective separator), the defensive
-  round cap (`nodes.length * 4` — forward-only motion terminates before it), and the
-  candidate-list `slice(0, 16)` caps (lists are shorter in practice).
-
-**Killed by `src/__tests__/ascii-pathfinder-units.test.ts`** (32 mutants):
-`buildMoveDirs` preferred-direction ordering (it only decides ties between
-equal-cost A* paths, which the golden corpus never isolates; the unit tests
-pin `path[1]` per direction), `heuristic` corner-penalty logic, and
-`mergePath` straight-run detection (backtracks and mixed-delta steps must
-be preserved).
-
-**Accepted — performance guards, not behavior** (pathfinder): the #66
-bounded-search mutants (`next.x > boundX || next.y > boundY` weakenings,
-`maxIterations` arithmetic). They change how much work an unreachable-target
-search does before returning null, not what any reachable search returns. A
-test would need to time the search, which is flakier than the risk warrants.
-
-**Accepted — unreachable via convention** (pathfinder): the `dy`-dominant
-fallback in `buildMoveDirs` (lines ~157–159). All nine 3×3 `Direction`
-constants either match an explicit cardinal branch or have `|dx| >= |dy|`,
-so the branch only runs for synthetic Direction values. Candidate for
-simplification, not for synthetic-input tests.
-
-**Found dead code**: the first mutation run showed the audit-suggested sort
-tie-breaks on the two `b.index - a.index` comparators in
-`determineLabelLine` could never fire — segment `index` is unique by
-construction — so they were reverted. Only the width-sort tie-break (where
-ties are real) remains. Mutation testing earning its keep: it falsified an
-audit assumption the test suite couldn't.
-
-**Killed by `route-contracts.test.ts` survivor harvests** (170 mutants
-across five passes): RL/BT axis orientation (reciprocal-pair regressions in
-both reversed directions), every `directLaneBlockers` blocker kind at its
-exact ±4px clearance boundary on both axes (non-square obstacles so a
-swapped width/height changes the verdict), own-label lane capacity in
-rendered-pill units, the same-edgeIndex self-exclusion, sub-epsilon
-polyline simplification, the hitch deviation rounding, `findLabelSlot`
-stagger and pill-boundary arithmetic, the primary-over-feedback exemption
-asymmetry, the feedback path of `findRouteHitches`, shared-trunk detection
-on both axes at its collinearity/pill-extent boundaries, the ±2px line
-between the stale and shape-misanchor tripwires, container perimeter
-tolerance, and the container repair's horizontal-gap axis selection.
-
-**Accepted — equivalent on the real input domain** (route-contracts): the
-collinearity cross-product variants in `simplifyPolyline` behave identically
-for the orthogonal polylines ELK produces (several algebraic rearrangements
-preserve the zero/non-zero verdict for axis-aligned triples), and the
-`isMonotoneStaircase` diagonal/backward guards are defensive against passes
-that do not currently exist — real extracted routes are orthogonal and the
-backward case is already excluded by feedback classification upstream.
-
-**Accepted — performance guards** (route-contracts): the `seen`-set and
-stack mechanics inside `classifyRoutes`' DFS change traversal cost, not
-reachability verdicts, on the small graphs flowcharts produce.
-
-**Accepted — bounded-iteration guard** (route-contracts): the fixed-point
-loop's `round < 4` weakenings only change how many re-prove rounds run;
-the duplicate-edge regression pins one unblocking round, and constructing
-a graph that needs three chained rounds would be a synthetic-input test.
-
-**Open test gaps** (highest-value first):
-- `directLaneBlockers` label-rect axis ternaries retain a few survivors on
-  rect width/height swaps for near-square pills; a multi-line (taller than
-  wide) label obstacle fixture would discriminate them.
-- `findLabelSlot`'s rect-overlap conjunction retains sign-variant survivors
-  for rects that only graze on one axis; corner-touching fixtures would
-  pin them.
-- The audit's pill-hit prefilter (`hitsPill`) retains inclusive-vs-strict
-  comparison survivors for segments that exactly graze the pill border;
-  they only widen the prefilter the collinearity check still gates.
-- The container repair's reversed-order gaps (target above / left of
-  source) lack fixtures; the gap arithmetic is symmetric with the two
-  covered directions.
-- `grid.ts` `ensureSubgraphSpacing` (~48 survivors): the overlap/min-spacing
-  resolution between root subgraphs is never triggered by the corpus —
-  placement upstream appears to avoid overlaps already. Needs either a
-  corpus sample that genuinely overlaps or a dead-code verdict.
-- `converter.ts` entry/exit attachment roles and phantom still-used checks
-  (`resolveSubgraphEdges` area): rendered-output invariants tolerate several
-  mutants because other mechanisms compensate. Needs assertions on the
-  resolved edge structure, not just the rendered text.
-- `edge-routing.ts` label segment filter (`width >= lenLabel && index > 1 &&
-  orientationMatches`): the labeled-fanout invariants pin the TD vertical-drop
-  case; LR orientation and the index>1 exclusion lack direct coverage.
-
-## Incremental per-PR lane (`stryker.incremental.config.json`)
-
-A fast lane gates the small, pure faithfulness counter on every PR (the
-`mutation-incremental` CI job), separate from the broad nightly lanes. It
-mutates `src/agent/structural-count.ts` (the counter + `faithfulnessWarning` +
-`isDrop`), run by the sub-second `structural-count.test.ts` unit runner. A full
-run is ~1 min, so it runs in full each PR.
-
-Score is ~96% (regenerate to confirm; the report lands in `reports/mutation/`),
-gated by `thresholds.break: 90`. The few survivors are all equivalent mutants,
-accepted not chased:
-
-- `structural-count.ts:96` (`case 'opaque': return null`) — two mutants
-  (the case label + its string). Equivalent: an opaque body returns `null`, and
-  the `default` branch *also* returns `null`, so mutating the `opaque` case
-  cannot change the result for any input.
-- `structural-count.ts:98` (`default:` exhaustiveness branch) — two mutants
-  (the branch condition + its block). Unreachable by construction: all twelve
-  families are handled explicitly and the `const _never: never = body` assigns
-  compile-time exhaustiveness, so the branch never executes at runtime.
-
-What earlier survivors taught us (now killed, kept as regression fixtures): the
-recursive `edges += inner.edges` state accumulation needed a *doubly-nested*
-composite-state fixture, and `nodes = services + junctions` needed an
-architecture fixture that actually contains a junction.
-
-### Why `verify.ts`'s faithfulness wrapper is NOT in the gated mutate set
-
-Move 2 measured `roundtripFaithfulnessWarnings` (the I/O wrapper around the pure
-`faithfulnessWarning`): **26.67% kill / 11 survivors**. The survivors are all on
-the wrapper's defensive branches — `if (!reparsed.ok) …`, `if (!after) …`, and
-the `catch` — which no *real* diagram exercises: a structured diagram's
-serialization always re-parses, and re-parses structured (not opaque), and never
-throws. Those branches are therefore unkillable through real `verifyMermaid`
-inputs without a synthetic drop, and the *decision logic* they guard already
-lives in `faithfulnessWarning`, which the incremental lane gates at 96%+. Adding
-the wrapper to the gated `mutate` would crater the score to ~27% and force either
-a meaningless break threshold or a pile of accepted survivors. So the wrapper
-stays out of the gated set and is recorded here as I/O-glue equivalents; its
-logic is covered where it actually lives.

package/docs/project/divergences.md

@@ -1,98 +0,0 @@
-# Divergences
-
-Current implementation decisions that differ from, or materially narrow, the broader `AGENT_NATIVE.md` architecture. This file is **not** a backlog; active work lives only in `TODO.md`. Historical loop logs were removed because they had become process noise. Use Git history for archaeology.
-
-## What still matters
-
-### Determinism is structural, not seeded
-
-- Removed the old `LayoutContext` / `SeededRNG` / `Clock` / `withSeededRandom` / font-metrics apparatus.
-- `RenderedLayout` has no `seed` field.
-- `VerifyOptions` is intentionally small: `{ suppress?, labelCharCap? }`.
-- Claim scope: same-input structural layout determinism is tested for the supported runtime/version matrix. Cross-machine or cross-architecture float equality is **not** claimed.
-
-### Package and compatibility choices
-
-- Product/docs, npm package name, and repository path are **Agentic Mermaid** / `agentic-mermaid` / `adewale/agentic-mermaid`. The agent surface ships as the `./agent` subpath.
-- `MermaidGraph` and `renderMermaidSVGAsync` remain for compatibility with existing renderer/tests/consumers.
-- ~~`state` diagrams currently share the flowchart body (`body.kind: 'flowchart'`)…~~ **Superseded by BUILD-19.** State diagrams now own a dedicated `StateBody` IR (`body.kind: 'state'`) with state-shaped ops and a real `asState` narrower. `asFlowchart` returns `null` on a state diagram (a breaking change within the unreleased agent surface). Verify still gets full Tier 1 + Tier 2 geometric coverage: the `StateBody` projects to a `MermaidGraph` via the legacy parser (`stateBodyToGraph`) and runs the identical flowchart `verifyGraph`. The modeled subset is simple states/transitions/`[*]` pseudostates/composites/`direction`; unmodeled syntax (`<<fork>>`/`<<choice>>`/`<<join>>`, history, concurrency `--`, notes, `classDef`/`class`/`:::`) falls back to a lossless opaque body. Corpus round-trip for state jumped 5% → 100%.
-
-### Mutation surface is intentionally narrower than Mermaid syntax
-
-Structured mutation is exposed for every built-in renderable family, but only when that body's parser/IR/serializer/verifier can preserve the modeled semantics:
-
-- flowchart/state;
-- sequence (BUILD-18 — segment-preserving: participant/message ops stay live while Note/alt/loop/par/activate/autonumber/title ride along verbatim as opaque-block segments; only un-segmentable input such as an unbalanced `end` falls back to whole-body opaque);
-- timeline;
-- class;
-- ER;
-- journey (BUILD-15 pilot);
-- architecture (BUILD-17 — the modeled subset of groups/services/junctions/edges);
-- xychart (BUILD-16 — the modeled subset of title/axes/series);
-- pie;
-- quadrant;
-- gantt.
-
-Opaque/source-level bodies:
-
-- any known-family diagram that falls back to opaque because it contains unmodeled syntax (e.g. architecture `{group}` boundary modifiers, accTitle/accDescr, malformed pie entries, out-of-range quadrant coordinates, or un-segmentable sequence/gantt syntax).
-
-For source-level bodies, agents may render, verify, describe, and round-trip preserved source. They do **not** get typed mutation ops. `am mutate` returns `UNSUPPORTED_FAMILY` for those bodies.
-
-### Structured-or-opaque is load-bearing
-
-Known-family input must never be partially parsed and then re-emitted with unknown constructs dropped. If the structured parser cannot preserve a construct, the body stays opaque/source-preserved and serializes from `body.source`.
-
-BUILD-18 refines "opaque/source-preserved" for sequence into a finer grain: a sequence body now interleaves structured statements with **opaque-block segments** holding unmodeled lines verbatim, so the structured ops survive instead of being forfeited at the first unmodeled line. The never-lossy invariant is unchanged — the segment lines are byte-for-byte preserved — and whole-body opaque is still the fallback for un-segmentable input. Class/ER/timeline can adopt the same segment-preserving body as follow-up work.
-
-This applies even when the diagram renders successfully. Render support is not the same as structured editing support.
-
-### Code Mode is local, synchronous, and lineage-checked
-
-- The MCP server exposes a Code Mode-style `execute(code)` tool backed by local `node:vm`; it is not Cloudflare Codemode and not a container/OS security boundary.
-- Code Mode is synchronous: no `async`/`await`, Promise jobs, dynamic import, finalizers, or blocking/realm-creating globals.
-- SDK-returned diagrams are read-only. Structured edits must go through `mermaid.mutate(...)` and must use trusted diagram lineage from parse/mutate/narrower outputs.
-
-### Runtime surfaces are part of the contract
-
-Keep these in sync when changing agent behavior:
-
-- `src/agent/*` public API;
-- `am capabilities` and CLI help;
-- MCP SDK declaration and server instructions;
-- `Instructions_for_agents.md` / `am --agent-instructions`;
-- `skills/agentic-mermaid-diagram-workflow/*`;
-- `skills/agentic-mermaid-live-editor/SKILL.md`;
-- `llms.txt`;
-- `docs/agent-api-cookbook.md`.
-
-Doc-sync tests exist because agents consume docs and capability JSON as runtime surface, not just prose.
-
-## Important fixed issues worth remembering
-
-These are retained only because they explain guardrails that may otherwise look excessive:
-
-- **Opaque fidelity:** opaque bodies serialize from preserved `body.source`, not normalized `canonicalSource`, so indentation/comments/source text survive parse → serialize.
-- **`am parse | am serialize`:** JSON payloads preserve flowchart styling maps and defensively normalize loose SDK-shaped subgraphs.
-- **Subgraph payload hardening:** `synthesizeFromGraph` tolerates missing `children`, null entries, cyclic references, non-tuple map arrays, and non-integer linkStyle keys.
-- **Timeline mutation:** timeline edits update `canonicalSource`, validate mutation text, allocate unique IDs, and fall back to opaque for header-suffix/lossy syntax.
-- **Shared routing cleanup:** SVG, ASCII, and agent parsing use shared diagram-family detection from `src/mermaid-source.ts`; agent parsing adds only a loose known-family path so malformed known headers can round-trip as opaque.
-- **Source-based `LABEL_OVERFLOW`:** verification checks labels for opaque/source-level families via family label extractors, so fallback does not mean "unverified."
-
-## Evidence and limits
-
-What the current suite demonstrates:
-
-- typed mutation works for the exposed structured families;
-- unsupported/opaque/source-level bodies refuse structured mutation instead of losing source;
-- verify-before-serialize and Code Mode trace linting catch key agent anti-patterns;
-- corpus gates cover Mermaid docs examples and MermaidSeqBench round-trip stability;
-- docs/capabilities/CLI/MCP declarations are checked for consistency.
-
-What it does **not** yet prove:
-
-- market demand;
-- that a real external consumer likes the API;
-- that a selected release model follows the intended loop from docs alone.
-
-Those validation items remain in `TODO.md`.

package/docs/project/dogfooding-docs-strategy.md

@@ -1,66 +0,0 @@
-# Dogfooding our docs: render and pin our own documentation with our own tools
-
-Status: strategy. Drafted 2026-06-20.
-
-Agentic Mermaid is a deterministic diagram engine with a typed, verifiable agent surface. Our
-documentation should meet the same bar as our output: **generated by the system it documents, and
-pinned by a test so it cannot silently drift.** An architecture diagram that rots, or a "supported
-families" list that lags the registry, is worse than no doc — it actively misleads.
-
-## Principle
-
-If a piece of documentation can be *derived* from the code, derive it — then add a test that
-regenerates it from the source of truth and fails when the committed doc disagrees. This is the
-documentation analogue of the determinism and round-trip guarantees the engine already enforces
-([`AGENT_NATIVE.md`](../../AGENT_NATIVE.md) §1, §3): the same inputs must produce the same artifact,
-and the artifact is checked, not trusted.
-
-Two regeneration shapes, both gated by `UPDATE_GOLDEN=1 bun test <file>`:
-
-| Shape | Source of truth | Artifact | Test asserts |
-|---|---|---|---|
-| **Rendered figure** | a committed `.mmd` | a committed `.svg`, rendered by `renderMermaidSVG` | deterministic re-render + byte-match (normalized) |
-| **Projected table/list** | a code registry (e.g. `BUILTIN_FAMILY_METADATA`) | a marked region in a `.md` | rebuild from the registry + region match |
-
-## Instances in the repo
-
-1. **The architecture figure** — `docs/design/system/architecture.{mmd,svg}`, pinned by
-   `src/__tests__/docs-architecture-diagram.test.ts`. The three-stacks diagram is authored as
-   Mermaid and rendered by our own engine; the test asserts the render is deterministic across
-   calls and matches the committed SVG. Docs *about* the system, produced *by* the system.
-2. **The family roster table** — the built-in-families table in
-   `docs/design/system/abstraction-audit.md` §2, pinned by `src/__tests__/audit-family-table.test.ts`.
-   It is generated from `BUILTIN_FAMILY_METADATA`; add or rename a family and the test fails until
-   the audit is regenerated.
-
-These join the repo's existing doc-sync guarantees, which already follow the same philosophy:
-
-- `Instructions_for_agents.md` is byte-identical to `am --agent-instructions` (doc-sync test).
-- `package.json` keywords, `llms.txt`, editor examples, and CLI capabilities are all projected from
-  `BUILTIN_FAMILY_METADATA` and checked (`doc-sync.test.ts`, `diagram-family-citizenship.test.ts`).
-- Every `LayoutWarning` code and `MutationOp` kind must appear in `AGENT_NATIVE.md` (doc-sync).
-
-## How to add a dogfooded doc
-
-**A rendered figure:**
-1. Author the source as `docs/.../<name>.mmd`.
-2. Add a snapshot test modeled on `docs-architecture-diagram.test.ts` that renders the `.mmd` with
-   `renderMermaidSVG` and compares to `<name>.svg`, with an `UPDATE_GOLDEN` write path.
-3. Run `UPDATE_GOLDEN=1 bun test <test>` to materialize the artifact; commit both.
-
-**A projected table/list:**
-1. Wrap the region in the doc with `<!-- NAME:start -->` / `<!-- NAME:end -->` markers.
-2. Add a test modeled on `audit-family-table.test.ts` that rebuilds the region from the code
-   registry and compares, with an `UPDATE_GOLDEN` write path.
-3. Regenerate and commit.
-
-## Boundaries
-
-- **Pin what is *derivable*.** Prose judgement — the audit's analysis, the recommendations — is not
-  mechanically generated; it is reviewed like code. Only the derivable parts (the figure, the
-  roster) are auto-pinned.
-- **Rendered-SVG snapshots carry the "within one ELK version" determinism assumption** of the
-  existing `*-svg-snapshot` goldens (`AGENT_NATIVE.md` §1). They guard drift within the CI
-  environment, not cross-version byte-equality.
-- **Keep generated regions small and clearly marked** so a reader — and `git diff` — can see what
-  is machine-owned versus hand-written.