What does xylem do?
You will turn a repository into a source-grounded map. It has four views, in a static two-file site (index.html and deep-view.json):
| View | Shows |
|---|---|
| Explore | Components (the parts of the system) and the connections between them, grouped in layers |
| Customer journeys | Each journey a user can take, animated over the architecture: requests, replies and labelled hand-offs |
| State map | Every declared state dimension in the mapped scope, its states, and the transitions that journeys actually take |
| Code | Every mapped function as a tile in its region, with its decisions, calls and callers, and journey paths traced at function level |
The method matters more than the page. Every claim is tied to file:line. Every connection is real. Where the code cannot settle something, the map says so instead of guessing.
Ground rules (apply in every phase)
- Evidence or nothing. Every component, unit, decision, edge, state and action should cite
file:line. If you cannot cite it, mark itUNVERIFIEDor leave it out. This is an author/reviewer obligation: automated gates enforce architecture evidence and deep source locations, not every state/action citation or explanation?s meaning. - Assign IDs; never invent entities or connections. Use the scaffold?s file-position IDs; manually authored IDs must also be unique and stable. Cross-region edges must ride a declared architecture connection. If one is missing, record a
diagram_gapand verify it in code before adding it, with evidence. - Honest gaps beat impossible paths. If a journey outcome cannot be traced distinctly from the source, write
{"unavailable": "<specific reason>"}. Never copy the success path into a failure outcome. Never chain branches that cannot both be true. - Say what it is. Traces are static source paths, not recordings of real runs. Label them that way in the page.
- Read-only. Never edit the target repo. Write everything to
.xylem/(or a folder the user names). - Privacy. Do not send repo content to any outside service unless the user asks. The site makes only same-origin requests for its data and optional videos. It makes no external requests; serve it on loopback for offline use.
Output layout
.xylem/
census.json # every definition found in the code (scripts/census.py)
architecture.json # phase 1
journeys.json # phase 2
deep.json # phase 3 (function-level map)
validation.json # scripts/validate.py output
reviews/ # cross-review reports (phase 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
Formats for every file are in references/schemas.md. Read it before writing any JSON.
Phases and gates
Do the phases in order. Each phase ends with a gate. Do not continue until the gate passes, or the user accepts a documented gap. In an explicitly authorized trial, retain failing artifacts and logs unchanged and continue only within that trial scope; label subsequent outputs provisional. A structural pass does not establish full semantic coverage.
Phase 0: Census (deterministic)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
This inventories named definitions with Python AST, a standard-library JS/TS token walker, and approximate regexes for other supported languages. scannedFiles includes zero-definition source files. JS/TS covers generic arrows, concrete multiline/computed methods, overload signatures, lexical function/class owners, regex literals and template interpolations; anonymous callbacks are not census units. It is a measured inventory, not a proof of all language syntax. Qualify it with an independent parser or source sample before claiming completeness. Later percentages describe this inventory only.
Gate: the census counts look plausible against the repo size. Excluded paths are justified, for example generated code or node_modules.
Phase 1: Architecture
Read the entry points, build files, main modules and process boundaries. Then write architecture.json:
- layers: for example shell, UI, server, domain, storage, workers, external;
- components: each with
id,layer,files[], a plain responsibility, andprocessType; - connections: each
{from, to, label, kind}, wherekindis spawn, ipc, http, file, data or uses; - flows: the main end-to-end flows as ordered component steps.
Gate: python scripts/validate.py .xylem --only architecture passes. Every scannedFiles entry belongs to a component, or has a reasoned architecture.meta.fileExclusions entry. Evidence paths and lines must exist under the evidence root.
Phase 2: Journeys and states
Write journeys.json. Work these out from the UI, routes, CLI commands, jobs and error paths:
- stateDimensions: every independent state machine;
- screens: every screen;
- actions: each user action and system transition, with its outcomes, the exact text the user sees, and undo;
- journeys: start states plus steps.
Every action carries an ordered architecture trace (alternating component and connection). Return legs use {"connection": [a, b], "direction": "reply"}. When the next step does not start where the last one ended, the step carries transition.handoff, with a type and label: user, timer, queue, continuation, lifecycle or download. Cover happy, unhappy, recovery and edge journeys.
Gate: validate.py --only journeys passes:
- every journey replays through valid outcomes;
- zero silent jumps (each light-up is reached by a wire, a reply or a labelled hand-off);
- no orphan states.
Phase 3: Function-level map (final resolution)
- Generate a draft map from the census:
python scripts/scaffold_deep.py .xylem
It writes deep.json. The draft contains assigned census units, Python decisions from AST, and heuristic JS/TS if, while, for, switch and parenthesized catch points. JS/TS does not claim a complete inventory of ternaries, calculations or short-circuit decisions. Comments, literal contents and child declarations are excluded from each body. Generic calls retain distinct callsite positions. Call edges use source: heuristic and confidence: name-resolved; unresolved names are not invented links. Refine against source; name resolution is not type resolution.
2. Refine the draft by reading the code:
- business-readable
summaryper unit, written from the body, not the name; - for every decision, a
plainquestion ("Is this file larger than 16 MiB?") plus the exact codetest, akind(branch, calculation, loop or unconditional) and correct successors. Areturnorraiseends the path. A try block's normal and error continuations are separate, and a pending exception runsfinallyand then propagates. When you are unsure, mark the successorunresolved; neververified; risktags only on decisions that directly implement a known defect.
- Write
actionTraces: for each journey action and outcome, the ordered execution events{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.eventis one of call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally or resume. See schemas for activation frames, terminal events and supported replay limits.- Start at the real initiator, such as a UI handler, route or job.
- Follow calls, returns and process boundaries. A refusal must follow the real error path back to the user. It must never continue to "saved" or "success".
- Where the path is unknowable, emit
{"event": "unknown", "note": "..."}, or mark the whole outcome unavailable.
Large repos: split phase 3 by code area across several agents, each writing deep-<part>.json in the same format, then merge them with scripts/merge_deep.py. Reconcile IDs by file and definition line, never by name similarity.
Gate: validate.py passes the full set:
- every census definition emitted or explicitly excluded with a reason; emitted coverage and exclusion accounting are separate counters;
- every edge endpoint resolves;
- every cross-region edge rides a connection;
- decision successors resolve;
- trace references are valid;
- selector consistency: no activation takes mutually exclusive choices for unchanged values. Source writes can change a value; an iteration label alone cannot reset constraints. Supported grammar and limits are in the schema. For example,
x==='a'yes and thenx==='b'yes, or a value excluded and then required byincludes(). Fix the trace, or withdraw it tounavailable, naming the conflict.
Phase 4: Build the page
python scripts/build_site.py .xylem
This writes site/index.html and site/deep-view.json. Videos are optional: drop videos/<journeyId>.mp4 plus videos/manifest.json into .xylem/ first (see the schemas). Serve site/ over HTTP to view it, for example python -m http.server -d .xylem/site. A file:// page cannot load the Code view's data.
Gate: open the page and check each mode once:
- no console errors;
- phone width (420 px) has no horizontal scroll;
- keyboard and dark mode work.
Phase 5: Optional real-screen recordings
If the app has a UI you can run locally, record journeys with Playwright. A starter is scripts/record_journey.example.mjs. Rules for recordings:
- drive the real UI, with no mocked responses;
- add a caption per step;
- speed up idle waits, and caption the speed-up;
- record per-step
atSecinmanifest.json; - mark partial recordings as partial.
The viewer syncs a video to the map, so the video becomes the clock.
Phase 6: Cross-review council
Use two independent reviewers where possible: two different models or agents, or at least a fresh context with no access to the author's reasoning. Follow references/protocol.md:
- the author never grades their own work;
- the reviewer receives files and code, never the author's conclusions;
- the reviewer runs the independent checker and samples claims against source: the single sampling rule in protocol.md (all available items below its minima);
- findings go to
reviews/<reviewer>-<round>.mdwith severity, evidence and a concrete fix; - acceptance gate: an explicit ACCEPT, REJECT or BLOCKED for architecture, journeys, deep, page/data and the frozen bundle. Only material defects justify REJECT: a wrong conclusion, an impossible path, or a blocked core task. Declared limits, honest
unavailablemarkers and the static nature of traces are not grounds for rejection; - use a bounded review budget; stop with REJECT/BLOCKED and retained evidence if unresolved. Re-review the exact built artifact, not a description of it.
Gate: all frozen bundle artifacts are accepted by independent review. Never manufacture paths to meet a sampling quota.
Phase 7: Publish and report
Tell the user what is in the page, with real counts:
- functions, decisions, journeys and traced outcomes;
- how many outcomes are unavailable, and why;
- what was cross-reviewed.
Report limits plainly.
Scripts
| Script | Purpose |
|---|---|
census.py | Multi-language definition census (the coverage denominator) |
scaffold_deep.py | Draft function-level map from the census and the architecture |
merge_deep.py | Merge part maps; reconcile IDs by file and line |
validate.py | Every gate: schema, references, coverage, silent jumps, successors, selector consistency |
build_site.py | Export the compact Code view data and build the single-page site |
record_journey.example.mjs | Playwright starter for real-screen journey videos |
The Python scripts require Python 3.9+ and only the standard library. Optional .mjs browser/recording helpers require a separately available Playwright. The page uses no frameworks or external requests.