Reference

Reference

This document gives the rules, commands, and configuration keys. README.md gives the introduction. If a check has a finding, first read its rule below. The command descriptions and configuration keys follow the rules.

What does systemap check reject?

systemap check executes the rules below. Each finding appears under its rule with a correction. The command exits 1 if a rule rejects the map.

A source module or test file that the extractor cannot read or parse does not reject the map. systemap is not a syntax checker, and a parser limit must not stop check for correct source. check prints such a module in the source inventory unresolved group, with the fix line of its cause. Each result that reads the module is not known, and not a pass:

• The component that claims the module has no source review digest. Thus judgement gives a stale source review line for it.
• An import rule that reads the module gives unknown.
• A missing entry, interface, or symbol name of the component is not known. check and delta do not report it.

A contract rule without a reason does not reject the map. check prints it in the contract reason group, and judgement gives the same line as a finding.

A meaning error, an import rule field error, or a placement error stops the check before it renders the map. Then the map layout line says that the check did not render the map. The map layout heading contains only the findings of positions, routes, labels, and text size.

An import rule can also have the result unknown. This result occurs if no resolved import is against the rule, but the facts possibly do not contain all imports of a rule module. check prints each unknown result as a warning and does not reject the map. Set unknown = "fail" in [rules] to make check reject the map for this result.

The labels rule rejects these conditions:

• A label touches a component, header, or other label. The finding shows the two labels and the applicable correction. For a full gutter, it shows the adjacent components and the region that must have more space. If not, the label can be wider than its seat.

• A container or region header is wider than its box. A sub uses more than two lines, or a header touches a component.

• A component's name or plain text does not fit its budget. The finding gives the budget. The map does not remove text to add an ellipsis.

Exit code 0 shows a map with no stale outputs. Exit code 1 shows a rejected check. Exit code 2 shows unusable configuration, an unusable model, or an unusable option value. To keep a module out of map coverage, add an ignore under [coverage]. Each ignore must have a reason.

The check compares components with the code. An import alone cannot show a flow's direction or artifact. The renderer and the checks use the evidence state of the stored source snapshot:

The stored value observed is an identifier. It does not mean that a program ran. The page legend, the Details panel, and systemap describe use the words "current source review". A current source review is a recorded source review whose source records still agree with the stored source snapshot.

For observed, a flow records source_refs and a review_digest. A reference has the form module[:symbol]@<source_sha256>. At least one reference must be in a module of the source component or the target component. A package pattern or a symbol claim in implemented_by also puts a component in a module. An actor has no modules. For a flow with an actor end, use a module of the other end. If no reference is in an endpoint module, the flow is not observed. systemap judgement then prints a no endpoint source finding. The facts file (docs/map/map.json by default) gives the source_sha256 of each module in components. systemap review --flow 'SRC->DST' writes the current review_digest of one flow. For a flow with an id, use systemap review --flow ID. It does not examine the claims for you. Examine the source before you record the values.

A source change gives a new source_sha256. A change to the flow or its relation sentence gives a new review_digest. The review_digest also contains the source_refs with the digest of each module. Thus a change to a module in source_refs makes the flow review not current, also when the claim does not change. A new digest in source_refs does not record a review. Examine the flow again. Then run systemap review --flow. A flow without source_refs, or with a source record that does not agree with the facts, has no current review.

A flow review from systemap 2.0.0

systemap 2.0.0 records a review_digest that contains only the claim. Such a digest does not identify the source that the reviewer examined. systemap refresh and systemap extract replace that digest one time with a digest of the claim and the current source_refs. The commands write only this value in the model file, and they tell you the files. The review stays current, with the label "review earlier than source tracking". systemap judgement gives the label in one row for each such flow. The row is not a finding. systemap judgement --json gives the flows in earlier_flow_reviews. The page gives the label in the evidence text of the flow. After the replacement, a change to a module in source_refs makes the review not current. To remove the label, examine the flow against the source. Then run systemap review --flow.

How do two flows connect one pair of components?

Each flow has an identifier. The identifier is the id of the flow. A flow without an id has the identifier SRC->DST. Thus, a model without ids keeps its digests, keys, and finding lines.

Two or more flows can connect one ordered pair only if each of these flows has its own id. An id contains only letters, digits, _, ., and -. In this example, the service sends two artifacts to the queue:

FLOWS = (
    Flow("OrderService", "OrderQueue", "order", "data", id="submit-order"),
    Flow("OrderService", "OrderQueue", "cancel", "control", id="cancel-order"),
)
RELATIONS = {
    "submit-order": "The service puts a new order in the queue.",
    "cancel-order": "The service tells the queue to remove an order.",
}
STEP = Step(acts=("OrderService",), measures=(), flow="cancel-order",
            say="The service tells the queue to remove the order.")

The map shows each flow as a different line with its own label. Each flow has its own sentence, source_refs, review_digest, and decision request. A finding line names a flow with an id as SRC -> DST [ID]. systemap review --flow submit-order writes the digest of that flow only.

The keys of relations, layer_overrides, and verb_overrides are flow identifiers. A (SRC, DST) key is also correct, but only for a pair that one flow connects. A sequence step names its flow with flow="ID". A step with edge=(SRC, DST) is correct only for a pair that one flow connects. On the page, each flow in the map data has an id key with its identifier. The other keys do not change.

A sequence step can have source_refs in the same form as a flow. Each record must resolve in the current facts. Each record must be in a module of an acting or measured component of the step. systemap judgement gives a step source finding for each record that does not agree.

What does the second pass find?

The check rejects contradictions. It cannot show all omissions. systemap judgement uses mechanical rules to find possible omissions. For each finding, change the model or record the reason for its stored state.

Without --strict, the report exits 0. With --strict, it exits 1 while a finding is open.

Each source component has one review state: missing (no source_review), stale (source_review is not the current digest), or current. systemap delta and systemap judgement use the same state. A stale review is a stale source review finding, so judgement --strict fails on it. A missing review is not a finding. Many maps have no source_review values, and these maps pass judgement --strict. With [judgement] require_reviews = true, a missing review is a missing source review finding, so judgement --strict fails on it. The report counts the three states on one line, for example source reviews: 16 current, 0 stale, 0 missing. [judgement] answered in systemap.toml contains recorded answers. Accepted answers suppress findings and increase the answered count. The report can print judgement: 3 possible map errors to examine, 21 answered. An answer that matches no finding is stale.

An answer can show exact lines or a family of lines:

• item shows one exact line.

• items shows multiple exact lines with one reason.

• crossing = ["A", "B", ...] shows crossings between any two listed ids.

• crossing_into = "A" shows crossings into A.

• crossing_from = "A" shows crossings from A.

• kind = "single module" shows all lines of that kind. "declared flow" and other kinds use the same form.

• module_sdk = "google.adk" shows all model-sdk findings for that import.

The maintainer examines these answers adjacent to the model. Before the second pass, systemap suggest gives proposed module groups. It gives one proposal for each package with two or more modules, and the imports between proposals. Examine these proposals against the source. A component must have one clear function. Module quantity alone does not identify a component.

An exact item or items answer includes evidence = "<SHA-256 digest>". When a fact that the finding cites changes, the finding opens again. judgement prints the current digest for examination. An exact answer without evidence stays pending until source review.

The evidence digest of a line contains only the evidence that the line names:

• For each component that the line names, the map claims of the component. These claims are the component fields, the plain name, and the flows, sequences, and invariants that name the component. The claim of an invariant is its number, its text, and its governs value. The reason of the invariant is not a claim. The source_review value, the flow review digests, and the source digests in source_refs are not claims.
• For each module that the line names, and each module of a named component, the cited facts of the module. The cited facts are the file, the package, the public names, and the imports in uses with the imported names. They also include the external imports, the parsed value, and the unknown records without their line numbers.
• For a crossing import line, the imports between the two components, with the imported names.
• For an entry point line, the entry point records of its modules. A record has the kind, module, target, and name values.
• For an unknown surface line of a module, the records of the line and the text of each cited source line. The records do not include the line number and the parser version. A new line above the statement does not change this evidence. A change to the statement changes it. A record without a line number uses the module evidence.
• For an unknown surface line of an entry point or a configuration file, the records of the line, with the count value.

A line about behavior also has the source file of each module: declared flow, flow review, no endpoint source, step source, stale source review, missing source review, and decision flow. A flow is about behavior, and the names and imports do not show behavior.

The cited facts do not include the comments, the function bodies, the tests, or the facts that a different module gives, such as imported_by. Thus a comment, a change to a function body, or a new test does not open a finding again that is not about behavior. A new public name, a new import, or a new entry point in a cited module opens it again. A change to a different component, or to a source_review value, also does not open the finding again. For example, a new import of a module from a different component does not open an entry point answer.

The evidence comes from the facts file. After a source change, use systemap extract or systemap refresh.

A line that names no component and no module uses the full evidence: the model files and the cited facts of all modules. The model files are the model file, the contract file, and each file that they import. An entry point line with the full evidence also has all entry point records.

Migration from systemap 2.0.0: the evidence of each exact answer changed. It contains the cited facts, and not the source files and the tests.

In the 2.0 releases, the first systemap refresh or systemap extract examines each evidence value in the 2.0.0 form. If the value agrees with the current source, the command replaces it with the new digest one time. The answer stays current. The command changes only the evidence value, and it keeps all other text of the configuration file.

A 2.0.0 value that does not agree with the source stays, and the answer stays pending, as before. From 2.1.0, an answer with a 2.0.0 value is pending. judgement prints the new digest in the pending answer line.

Migration from facts format 10: the evidence of an unknown surface line of a module or a test file changed. Thus each of these exact answers is pending one time after the update.

Migration: the full evidence of a model file that imports other model files changed. The evidence of each entry point line also changed. Thus each of these exact answers is pending one time after the update.

Migration to the contract file: the one move of the rules (see "What does the contract contain?") changes the model files. Thus it changes the full evidence of a line that names no component and no module. The command that moves the rules writes the new digest of each such answer that was current before the move. The move does not change the evidence of a line that names a component, because the rules do not change.

Migration from systemap 1.2.0: an exact answer in 1.2.0 had no evidence digest. Thus each exact answer from 1.2.0 is pending until you write its digest. A family answer from 1.2.0 must also get policy = true.

judgement prints the new digest in the pending answer line. Examine the source again. Then write the new digest in evidence.

A family answer is a policy for a family of lines and must have policy = true. The report counts current matches and matches outside the optional reviewed = ["<line>", ...] baseline. A family answer without policy = true stays pending.

What questions does Jev answer?

systemap audit is optional. CI does not execute this command. The command sends individual semantic questions to TypeSafe's Jev model. It prints a finding when Jev's answer does not agree with the map. The mechanical judgement rules use names and imports instead.

The development experiments selected thresholds on five mapped repositories in bench/jev. Three holdout maps used the same thresholds: systemap, scorecard, and a first map of httpie. The table gives measured results from the recorded prompts.

The prompts changed for ASD-STE100 after these measurements. The changed prompts have no new benchmark measurements. All measured repositories are Python repositories. No TypeScript result was measured. Do not use the recorded scores as results for the changed prompts or your system.

No question goes to Jev without TYPESAFE_API_KEY. audit --dry-run counts the questions and shows the data to send. The data contains module names, docstrings, public names, internal imports, component ids, sentences, invariants, and source lines at connections between components. With Jev and TYPESAFE_API_KEY, the dry run gets the Jev model list to count cached answers. It sends no map data. With OpenAI, the dry run sends no request.

A decision flow question gets its source lines from the call_sites fact of the modules at the two ends of the flow. The fact has the same form for Python and TypeScript. The context has these lines, in this sequence, until it has 60 lines:

1. The import lines and the lines that use a name from the other component.
2. The lines that read a property of a local name that gets its value from an imported name, such as ledger.record(parts) after ledger = Ledger().
3. The line of the function or method that contains each of these lines.

Then the context gives at most 12 lines from the facts of the target modules. These lines are the signature of each imported function, class, or method that a selected line uses, and the first sentence of each module description. A flow without such lines gets no question. The report gives the count of these flows.

Each Jev answer must agree with its question: a choice from the offered options, and numbers from 0 to 1. An answer that does not agree stops the command with a message. The cache does not keep that answer.

The cache is .systemap/jev-cache.json. Its key includes the model, release date, state, and question. A map without changes uses cached answers at no additional cost. A new model release causes new questions. If the model list is not available and the cache has every answer for the last known release, the command uses the cache. The usage line says so. Two commands can write the cache at the same time. A save holds a lock on the file jev-cache.json.lock and keeps the entries of the two commands.

Audit answers use [judgement] answered with item, items, or a kind such as "decision flow". audit reads only answers for the kinds in its report. A kind excluded from the report does not make its answer stale. judgement ignores all audit answers.

The decision mis-fold and decision owner lines do not contain the component that the provider selects. The detail row gives that component. Thus a new model release that changes only that component does not open an answer again. Earlier versions put that component at the end of the line, for example jev mis-fold: Writer claims pkg.emit, which reads like Reader. Previous versions also used the jev names. An answer with the earlier line text matches the current line, with the same evidence digest.

systemap triage "<issue>" gives the three components likely to change in an issue fix. The report includes their modules and adjacent components. On 80 closed issues from two repositories, the component of the pull request with the fix was first in 80% of predictions. It was in the first three in 88%.

delta sends questions to Jev only when you select Jev. To select Jev, give --decide, or set [jev] enabled = true in systemap.toml. [jev] enabled = true also must have TYPESAFE_API_KEY. A key alone does not select Jev. Without a selection, delta sends no data to Jev. If the request cannot complete, --decide gives the cause. --no-decide sends nothing, also with [jev] enabled = true. --jev and --no-jev are the previous names of these options. If delta has no question for Jev, it sends nothing and prints no Jev line.

Jev answers are suggestions for source examination. They are not evidence. They do not change the delta lines or the exit code. Thus a run with Jev, a run without a key, and a run in CI give the same result. The suggestions print under their own heading. If Jev does not answer, a delta --decide: line gives the reason under a different heading.

Jev examines removed modules that delta did not pair with added modules. Delta first compares source, public names, and filenames. A pair that Jev selects with confidence of at least 0.8 prints as a decision move line, for example decision move: pkg.ledger -> pkg.accounts.book (read as the same module by Jev, confidence 0.94). Jev also suggests a component for each module that no component claims, as a decision owner line.

With earlier prompts on Python repositories, delta found 66 renames. Jev selected 17 more pairs, and 16 of them were correct. An agent wrote reference labels from commits without Jev's answers. The records are in bench/jev.

A move candidate line has a necessary action while a component specifies the removed module in implemented_by. It also has a necessary action while an added module has no claim and no ignore. Read the two source files. Then change the claims. The line then moves to the changes with no necessary action.

suggest --decide groups modules from pair answers. Pairs have an import connection or the same package. Its groups were better than package-only groups on three of five development maps. They were not better on the other two. The measured first-map run saved no turns. Thus, the command stays optional.

Without a key, judgement prints an audit hint to stderr. delta prints a hint when a module was removed, a different module was added, and Jev is not selected. The delta hint tells how to select Jev. It prints with a key and without a key. Each hint gives a result that was measured with earlier prompts on Python repositories. [jev] enabled = false stops the hints.

Which decision provider answers the questions?

A decision provider is the model API that answers the questions of audit, triage, plan, suggest --decide, and delta --decide. judgement --order-by-drift always uses Jev, also when the configuration selects OpenAI. The default provider is TypeSafe's Jev. The second provider is OpenAI Decisions (POST https://api.openai.com/v1/decisions, model gpt-6-luna, public beta).

To select OpenAI, give --provider openai to the command, or set [decisions] provider = "openai" in systemap.toml. --provider jev selects Jev, also when the configuration selects OpenAI. A key in the environment does not select a provider. With OPENAI_API_KEY set and no selection, no request goes to OpenAI. If the selected provider does not give the answers, the command gives the cause and stops. It does not use the other provider.

OpenAI gets the same data as Jev:

• The evidence of each question, as JSON text in the input field: module names, docstrings, public names, internal imports, component ids, component sentences, invariants, source lines at connections between components, and the issue or task text.
• The question text and the options: component ids with their sentences, or the new module names of delta.

Use audit --dry-run --provider openai to count the questions and the characters before you send them.

The thresholds of OpenAI come from the Jev bench rows in bench/jev (2026-10-13). Each threshold was selected on the five development maps. On the holdout maps, each figure had to be 10 points or less from the development figure. A question type that did not satisfy this rule has no OpenAI threshold. The command does not send that question, and it gives the cause.

The owner question of delta --decide uses the decision owner threshold. The decision flow threshold came from a second measurement on 2026-10-13. It used the flow context from the call_sites fact, as the command does. All measured repositories are Python repositories. No TypeScript result was measured. The finding kinds have the same names for each provider. These names are identifiers in [judgement] answered. How do you change to the new finding names? gives the previous names.

An OpenAI answer must agree with its question, as a Jev answer must. A refusal for one question gives no finding for that question. The report gives the count of refused questions.

The cache is .systemap/openai-cache.json. It does not keep a refusal. Its key includes the provider name, the model, the evidence, and the question. Thus OpenAI does not use a Jev answer.

The cost line on stderr has the same form for each provider, for example openai: 1 sent, 0 from the cache; 290 input and 0 output tokens; gpt-6-luna. OpenAI charges $0.10 for each 1M input tokens and does not charge for output. The 1,636 bench requests used 1,211,893 input tokens ($0.12). The 256 requests of the second flow measurement used 213,942 input tokens ($0.02).

How do you change to the new finding names?

In this release, the diagnostic kinds of a decision provider have new names. The previous names started with jev. The new names start with decision, because Jev or OpenAI can give the answers.

This release also reads the previous names:

• An exact answer (item or items) with a previous name is an answer for the line with the new name.
• A family answer, for example kind = "jev flow", is an answer for the lines of the new diagnostic kind.
• audit --kind "jev flow" selects the new diagnostic kind and prints a warning.
• systemap explain "jev flow" gives the text of the new diagnostic kind.

audit and judgement print one warning to stderr for each previous name in [judgement] answered. The warning gives the new name. Only this release reads the previous names.

The evidence digest of a line is the same for the previous name and the new name. systemap calculates the digest of a line from the same line with its previous name. Thus an exact answer with one item keeps its evidence value after you change the name. But the digest of an items group also contains the text of each item. Thus a group with changed names gets a new digest, and audit prints a pending answer line.

The unknown surface line for a source parse error also has a new form, because a line must not name one language. The earlier line ended with under Python 3.11.10. The new line ends with (parser version 3.11.10). In this release, an answer item in the earlier form is an answer for the line in the new form. The evidence digest of the item does not change.

Two other unknown surface lines also have a new form for the same cause:

The same rule applies to these two lines.

The entry point line for a group of entry points gave the kind identifier, for example entry point 7 public_functions into Api have no sequence (component Api). The new line gives the kind value with a space in place of each _: entry point 7 public functions into Api have no sequence (component Api). The same rule applies to this line. A kind without _, for example route, does not change.

The unknown surface line for a TypeScript parse error also changed. Its source excerpt is the line of the error and the line before it, because the error can be one token, such as ','. From facts format 11, the excerpt and the parser version are in rows below the line. The line ends with The parser could not parse the source syntax. An answer item in an earlier form applies to the current line of the same module.

The parser can also refuse correct syntax. tree-sitter-typescript 0.23.2 refuses a generic function call with a typeof import() type argument and a comma after the last argument. For example, f<typeof import('./a')>(g(),) is correct TypeScript. At 2026-10-13, PyPI and npm have no grammar version after 0.23.2.

judgement prints one warning to stderr for each item in the earlier form. The warning gives the new line.

The unknown surface line for a re-export target outside the extracted module set also changed (facts format 10). The earlier line had the location :1, and a statement with two or more names gave one equal line for each name. The new line ends with the names, for example Names: Shape, Size. The at: row gives the line of the statement. An answer item in the earlier form can apply to a current line. The map, the module, the file, and the target must agree with one and only one current line. The evidence digest must agree. A target that is a declaration file has a different line with the cause declaration file. An answer item in the earlier form does not apply to that line, because the meaning changed. Thus judgement gives the earlier item as a stale answer. The command prints no warning for an item in the earlier form of this line.

Facts format 11 removes each value from an unknown surface line that changes while the finding stays the same. A recorded answer then stays applicable when a line is added above the cited statement.

The judgement report gives these values in rows below the line, and judgement --json gives them in open[].sources. An answer item in an earlier form applies to the line in the new form. judgement prints one warning to stderr for each item in an earlier form. The warning gives the new line. Two records with different line numbers can give the same line. Then one answer applies to the two records.

Facts format 13 removes the counts from two lines, because a count can change while the finding stays the same. A row below the line gives the count, and judgement --json gives it in open[].count.

The row below a crossing import line is, for example, count: 1 module. The row below a package_export line is, for example, count: 3 targets. The package_export record has the number of targets in count. Only the TypeScript adapter writes this record.

An answer item in an earlier form applies to the line in the new form. judgement prints one warning to stderr for each item in an earlier form. The warning gives the new line.

judgement gives no line about a test file, because a test file is not a part of the map. A question about a test file is not a question about the architecture. check and refresh continue to give each test_file_issues record. An answer for an unknown surface: test file line is a stale answer. The report gives the row stale answer: '<item>' is no longer a finding: judgement gives no line about a test file. Remove the item from [judgement] answered.

--decide is the new name of --jev in delta and suggest. --no-decide is the new name of --no-jev. The previous options stay for one release. They send the same requests as the new options. [jev] enabled and the other keys of the [jev] table do not change.

The printed text gives the name of the provider that gave the answers. For example, delta --decide --provider openai prints OpenAI suggestions. With Jev, it prints Jev suggestions.

To change a configuration to the new names, do these steps:

1. In systemap.toml, replace each previous name in [judgement] answered with its new name.
2. If you changed an items group, use systemap audit.
3. Examine the source of each pending answer line again. Then record the digest from that line.
4. Replace --jev with --decide and --no-jev with --no-decide in scripts and CI files.
5. Use systemap judgement --strict. Make sure that it prints no warning.

What do you do above forty components?

A large repository can exceed the capacity of one readable canvas. Above approximately forty components, each layer can contain almost all components. Layer selection then gives little separation.

A component can have map="gateway.py". This path is relative to its model file. The target module exports MODEL and MEANING. The nested map shows the parent component's internal structure. The component ID is also the directory name of the nested page. Thus the ID must not contain / or \, and it must not be . or ...

Each parent module must have one claim, without duplicates, in the nested map. No extra module is permitted. Only one component can open a nested model file. The map tree rejects a second component that opens the same file. Symbol claims are permitted. Empty package markers are excluded. Nested actors must be components from the parent map. Coverage counts the parent component one time.

The nesting rule rejects differences and shows each module or actor.

Commands use all maps in the map tree:

• check executes all rules on each map. A nested finding has its map id, as in Gateway: map layout: clean ....

• refresh and render write one page per map. The top page is docs/map/index.html. The nested page is docs/map/Gateway/index.html. Each page has a link to the other.

• figure --map Gateway renders one map. A [[figures]] entry also accepts map.

• place writes positions in each model file.

• describe and judgement use map-id prefixes. An item answer contains the printed line. A family answer can apply to all maps.

• An unknown surface line about a module occurs one time, in the map that owns the module. An unknown surface line about the repository occurs one time, in the top map. Migration: an earlier exact answer for such a line can have a different map prefix. If its item without the prefix agrees with one current line, the answer applies to that line.

• delta compares each map's claimed modules. A moved module shows its component and model file.

• suggest shows maps above forty components. It lists the components with the most modules as possible nested maps.

A second nested level uses an id such as Gateway/Routes. The self-map in the recorded experiment had no nested map. Its 18 components were below the threshold. The fixture in tests/test_nested.py has five top-level components. Two open nested maps.

What does a model contain?

The agent writes one model file in Python syntax with the frozen dataclasses of systemap. systemap reads the file as data. It does not run the file as Python code. This example contains two components and one flow from the self-map. A model does not declare the standard flow kinds. The page derives standard layers.

from systemap import Component, Flow, Meaning, Model, Region

MODEL = Model(
    canvas=(900, 420),
    containers=(),
    regions=(Region("gather", "GATHER", (24, 40, 400, 340)),
             Region("draw", "DRAW", (460, 40, 416, 340))),
    components=(
        Component(id="FactsExtractor", region="gather",
                  does="Reads the package syntax tree and writes facts.",
                  implemented_by=("systemap.extract",), entry="build"),
        Component(id="Schematic", region="draw",
                  does="Renders components, routes, and the interaction script.",
                  implemented_by=("systemap.schematic", "systemap.theme"), entry="render"),
    ),
    flows=(Flow("FactsExtractor", "Schematic", "map.json", "data"),),
    flow_kinds=(),
)

MEANING = Meaning(
    plain={"FactsExtractor": "what reads the code", "Schematic": "what renders the map"},
    relations={("FactsExtractor", "Schematic"):
               "The schematic reads module facts to show flow evidence for mapped components."},
)

The contract file (see "What does the contract contain?") can contain import rules. systemap check and systemap rules compare each rule with the resolved imports in the facts. This rule gives fail if a module of FactsExtractor imports a module of Schematic:

from systemap import ImportRule

IMPORT_RULES = (
    ImportRule(
        "facts-first",
        "forbid_import",
        src=("FactsExtractor",),
        dst=("Schematic",),
        reason="Extraction does not use the drawing.",
    ),
)

Give the tuple to Contract(..., import_rules=IMPORT_RULES). The schema file of the skill tells about the three kind values: forbid_import, allow_imports, and forbid_cycle. The page does not show import rules.

The example has no x or y values. systemap place writes these positions. After component additions or removals, systemap place --all writes new positions. A component with pinned=True keeps its selected position.

A model file can contain only these statements:

• The module docstring and from __future__ import annotations.
• from systemap import ... or from systemap.model import ... for the model classes and for AGENT_KINDS, KINDS, and STANDARD_KINDS.
• import NAME for the file NAME.py in the same directory, such as import journeys. NAME.VALUE gives a value from that file. The same rules apply to that file. systemap refuses a symbolic link to a file outside the directory, and an import cycle.
• NAME = value and NAME: annotation = value. systemap does not read the annotation.
• A type alias for annotations, such as Steps = tuple[Step, ...].

A value is a str, int, float, bool, or None constant, a minus sign before a number, or a tuple, list, set, or dict of values. A value can also be a call of a model class with positional and keyword values, or a name that an earlier statement in the same file defines. systemap refuses all other syntax before it makes a value. Examples are functions, classes, comprehensions, f-strings, operators, indexes, ** and * in a call, and other imports. The message gives the file, the line, and the refused syntax.

The reader also has limits: 512 KiB and 16 files for one model with the files that it imports, 100,000 values, 32 levels of nested values, and 8,000,000 parts and characters in one value when each name in it is written out. Move a part of a larger map into a nested map.

If you know that the code in a repository is safe, set SYSTEMAP_TRUST_MODEL_CODE=1 in the environment of the command. Then systemap runs each model file as Python code, as version 1.2.0 did. Only the value 1 gives this permission. systemap does not read this permission from systemap.toml, because the repository controls that file. To write a model file with code again as literal values, use systemap convert.

The page and the figures use some model names as CSS names and SVG IDs. Thus systemap refuses these names when it reads the model, and the command exits 2:

• A custom layer ID that contains a character other than a letter, a digit, _, or -.
• The component IDs _meta and __proto__. The page data uses these keys.

The full schema and examples are in SKILL.md and its references/.

What does the contract contain?

The contract file gives the rules of the map: the invariants and the import rules. The model files give the description of the code: the components, the flows, and the sequences. An agent changes the map freely. An agent changes a rule only with a reason. A change to a rule is a change to the contract file. Thus a reviewer sees each change to a rule in the pull request.

The contract file is in the folder of the model file. For map/model.py, it is map/contract.py. For a different model file, such as the nested map map/gateway.py, it is map/gateway_contract.py. The contract file uses the same statements as the model file. It gives CONTRACT as a Contract:

from systemap import Contract, Invariant

INVARIANTS = (
    Invariant(
        1,
        "Extraction does not use the drawing (README, Design).",
        governs=("FactsExtractor",),
        reason="The facts must not depend on the page.",
    ),
)

CONTRACT = Contract(invariants=INVARIANTS)

Each rule must have a reason from the code, the documentation, or the commit history. A rule without a reason gives a contract reason line in check and judgement. If a reviewer refuses a change to a rule, the agent adds the cause to the reason of the rule that stays. Thus the next agent reads the cause before it proposes the change again.

systemap keeps no list of owners or approvals. To select the reviewers of a change to the contract, add a CODEOWNERS line, for example /map/contract.py @team-leads. systemap init prints this line. It does not write CODEOWNERS, because it cannot know the team.

The rules of a map from before the contract file

A map from before the contract file gives its rules in Model(..., invariants=..., import_rules=...). In the 2.x releases, systemap reads the rules from the model file or from the contract file. If the two files give rules, systemap refuses the map with a configuration error that names the two files.

The first systemap refresh or systemap extract moves the rules to the contract file one time, for each map. The command removes only the invariants and import_rules values with their assignments and comments. It also removes each imported name that the model file does not use after the move. It writes the files only if systemap reads the same model from the new files. If not, it prints a warning and writes no file. An empty contract file from systemap init gets the moved rules. After the move, each rule without a reason gives a contract reason line. The agent writes the reasons. Examine the two changed files before you commit them.

Which command do you use?

All commands accept --root DIR before the command. All commands except explain also accept it after the command. This option shows a project outside the current directory. After decisions, put the option after the action, for example systemap decisions status --root DIR. Exit codes are 0 for current, 1 for stale or rejected, and 2 for unusable configuration, model, or option value. The line after an error tells you which input to correct. The input is a command option, systemap.toml or the model module, a tsconfig.json file, or a Git ref.

A command reads and writes a cache file or an output file only in the repository. The two exceptions are an absolute figure --out path and a delta --comment file outside the repository. If the file or one of its folders is a link out of the repository, the command stops with exit code 1. A FIFO or a device at the file also stops the command with exit code 1. The error gives the file and the cause. Remove the file or the link. Then use the command again.

A write replaces a link in the repository. It does not write to the target of the link. The configured cache files, out_dir, and model must be paths in the repository, without a .. part. An absolute path or a path with a .. part gives exit code 2.

systemap init [--no-ci | --strict-ci]

Writes systemap.toml, an initial model, an empty contract file, the skill directory, and a GitHub workflow. The workflow pins this version. The contract file is map/contract.py. If the model file is present, the command does not write the contract file. After it writes the contract file, the command prints a suggested CODEOWNERS line for it, such as /map/contract.py @OWNER. The command does not write CODEOWNERS. The command does not replace systemap.toml, the model, or the workflow. If pyproject.toml has a [tool.systemap] table and systemap.toml is missing, the command does not write systemap.toml, because the commands read that file before the table. Then it writes the model at the model path of the table. It writes the skill directory again on each run. If a symbolic link puts a file in a location that is not in the repository, the command writes no file and exits 2. It prints the instruction for your agent. --no-ci does not include the workflow.

The workflow has the variable SYSTEMAP_CI. Its default value is advisory: a map finding gives a warning annotation, and the job passes. With --strict-ci, the value is strict: a map finding makes the job fail. You can change the value in the workflow file later. If systemap cannot run (exit code 2 or more), the job fails with both values.

If the repository has no Python package and a directory has a tsconfig.json file, init selects TypeScript. For TypeScript, init selects the package root with this rule, in this sequence:

1. The repository root must have a tsconfig.json file.
2. If each include entry of tsconfig.json names a folder, and one of these folders has source, that folder is the root. An entry such as source/**/* names the folder source. A test folder or a type-test folder does not count. An entry that names a file, such as vite.config.ts, stops this step.
3. Then the root is src if it has source, then the repository root.

For example, the ky repository has "include": ["source"]. Thus init writes "source" = "ky". A configuration without [package_roots] uses the same rule.

If the rule selects no root, init writes no package roots and prints the cause. It also prints the [package_roots] table to write in systemap.toml. The table has one line for each folder with a tsconfig.json file, with the same rule in that folder. Keep only the lines of the packages of the system. extract and the other commands print the same text until you set the table.

init also writes test_patterns for the TypeScript type tests that it finds. A type test is a file that only tsc examines, for example with tsd or expectTypeOf. These files are test files, not modules of the map:

• A folder with the name test-d, the default folder of tsd, or the folder in the tsd.directory key of package.json.
• A folder with a name such as __tests_dts__: __test or __tests, more text, and __.
• A file with a name that ends in .test-d.ts or .spec-d.ts, as tsd and Vitest typecheck use.

The test_patterns key shows the rule in the configuration. You can change it there.

systemap extract [--check]

Reads the source tree and writes docs/map/map.json. Module records contain public surface, public names, internal imports, external imports, test references, and entry points. Package __init__ records include re-exports. The other commands read this file. Before it writes the file, the command replaces each flow review digest from systemap 2.0.0 one time. The section "A flow review from systemap 2.0.0" gives this replacement. It also moves the rules of each map from before the contract file to that file one time. The section "The rules of a map from before the contract file" gives this move.

Each language adapter also writes these facts with the same meaning for Python and TypeScript:

• package: the folder package of the module. A dot in a file name does not make a package.

• completeness: parsed, line, reason, and unresolved_imports. If the module did not parse, unresolved_imports is null, because the value is not known. A component with a module that did not parse gets no source review digest. An import rule for that module gives unknown.

• call_sites: the lines that use each imported name, and the lines that use a local name that gets its value from an imported name. The decision flow question reads this fact.

• classes and types: classes holds only class declarations. types holds each other type declaration, with its name, its category (interface, enum, or type_alias), and its methods.

• defined_in and defined_as on each re-export: the module and the symbol that define it.

• same_as on each entry point: the identity of a different entry point with the same start, or an empty string. A missing value is not known. Then the entry point must have its own sequence.

• symbol on each entry point: the name in its module that the entry point starts, or an empty string.

• cause on each unknown record: the cause that gives the fix: line, for example declaration file or script file.

The facts file has a format number in its version key. The current format is 13. A facts file of an earlier format is stale. Then check and extract --check exit 1. After an upgrade of systemap, run systemap refresh.

A test file that systemap cannot read or parse gives a test_file_issues record, for Python and for TypeScript. The record is not known. It does not reject the map. check and refresh print it with its cause and its fix: line. judgement gives no line about a test file.

systemap reads systemap.toml, pyproject.toml, package.json, and each tsconfig.json file only in the repository. A configuration file that is a link out of the repository, or that is not a regular file, gives a configuration error. The error gives the path and the cause. A missing configuration file gives an empty table, as before. A tsconfig.json target in the node_modules folder of the repository stays permitted.

• --check exits 1 if stored facts differ from the source tree. The facts file includes a digest of the values that extraction reads from each configuration file. Thus a change to such a value is also a difference. A comment, the text format, or a value that extraction does not read is not a difference. A file in an installed package folder, for example node_modules, is a difference only if it is on this computer. It also exits 1 if a model claim names a module that the source tree does not have. The report gives the two problem groups separately. For stale facts, run systemap extract. For a model claim, correct the model. A new extraction does not correct it.

systemap facts

Prints stored facts one view at a time. With no option, it prints the extraction summary.

• --modules prints one row per module. Each row gives the first docstring sentence and counts of names, imports, and tests.

• --docstrings prints the first sentence only.

• --module NAME prints the module's docstring, names and kinds, imports, importers, external imports, and test count. It does not print test names.

• --names NAME prints public names and kinds.

• --entry-points prints entry points and their targets.

• --external prints third-party imports and their importers.

• --imports NAME prints imports and importers for one module.

The module description is the first paragraph of the Python module docstring, or of the first TypeScript comment before the first statement. A license notice is not a description. A text is a notice if it starts with Copyright, ©, (c), SPDX-, Licensed under, @license, or @preserve, in capital or small letters. For TypeScript, a comment that starts with /*! or //! is also a notice. The // comments directly below a notice are part of the notice. Then the next TypeScript comment can give the description.

systemap place [--all] [--print] [--keep-order]

A component must have a position before you render the map. This command writes positions for unpositioned components on all maps. The command keeps positions already in the model. Only x=, y=, boxes, and the canvas change. The command changes keyword values and positional values. After the write, the command loads the model file again. It compares each position, box, and the canvas with the calculated values. If the command cannot load the file or a value is different, it restores the previous file contents. This error causes exit 1. For example, a box in an imported file is different, because the command changes only the model file.

Regions use a two-column grid with routing corridors. The search selects the region order with the best score. Barycenter sweeps through flows select component order within regions. With six or fewer regions, the search tries every order. For more regions, it uses a greedy start and pairwise swaps.

A bend estimate scores each candidate. The router renders the best twelve estimates and the model's listed order. It scores label collisions, rejected routes, bends, and length, in that order. The report gives the selected order and score. This line is from systemap place --all --print in this repository:

region order: draw, gather, mean, keep, operate. 159 bends, 32,562 units. 120 orders examined, 13 routed

The procedure is deterministic and uses only the standard library.

• --all writes new positions except for pinned=True components. Use it after you add or remove components.

• --keep-order uses the listed region order without a search.

• --print prints positions without file changes.

Before the command calculates positions, it examines the flows and the kind value of each component. A flow to an unknown component, or an unknown kind value, causes exit 1. The error gives the flow or the component. systemap describe also examines them.

systemap render [--check] [--base REF]

Writes the page from the facts and model. Without facts and without package roots, render, facts, and figure give the package-root error of extract and exit 2. Thus they do not tell you to use systemap extract when extract cannot operate.

• --check exits 1 if the page is stale. It renders the page with the same options and compares the two pages. Thus a page that render --base REF wrote is stale for render --check without --base REF.

• --base REF adds a change map relative to that revision. The page link #changes, for example index.html#changes, opens the Changes view. The Changes panel lists the map changes: the components, flows, sequences, and rules that the change added, removed, or changed in the model. The list compares the committed model at the merge base with the model on disk. A new digest for the same cited module or symbol is not a flow change. If the base model does not load, the panel gives the reason. The source text has the same rules as the extraction: UTF-8, with or without a byte order mark. If systemap cannot read a changed source file, the changes of its module are not known. The panel gives the read problem. A missing file is a removal. Each revision resolves the imports of its test files with the files of that revision: its configuration files, module paths, and modules. If systemap cannot read or parse a changed test file at a revision, the panel gives the file and the problem. The page has no test changes for that file. The panel also gives each changed path that the Git tree reader refuses, with its cause. The changes of such a path are not known.

• --pr N gives the pull request title of the change map. gh pr view gives the title. If gh cannot give the data, the command writes one note with the cause to stderr. The page then has no pull request title.

systemap check [--brief]

Executes all rules on all maps. A rejected map causes exit 1. Each finding gives a correction. Two rows below a rejected rule give its effect and the necessary action. Each condition that rejects the map prints its lines.

• --brief does not include these two rows.

The contract reason group gives each invariant and import rule without a reason. These lines do not reject the map. systemap judgement gives the same lines.

The unknown surface group gives the records that the extractor could not read or connect. These records do not reject the map. The adapter writes the cause of each record in the cause field. Below each line, the at:, excerpt:, and parser version: rows give the values that are not in the line, as systemap judgement gives them. The group gives one fix: line for each cause that occurs:

systemap figure --out FILE

Uses the page generator to render one figure for a document.

• --components A,B renders a plan's reach.

• --base REF renders a change.

• --layer ID renders that layer's flows and all components. The legend contains only that layer.

• --map ID selects a nested map.

• An --out filename with a .svg suffix writes the drawing without a frame.

• A relative --out path is relative to the output directory. Its folder must be in the repository after the resolution of links. If it is not, the command exits 1. An absolute --out path can be outside the repository. The command replaces a link at the --out path with a file. It does not write to the target of the link.

• --svg-id ID sets the HTML ID of the drawing. The default is lessonmap. The ID must start with a letter and contain only letters, digits, -, and _.

The figure shows the layer names, the caption, and the other model and configuration text as text, not as HTML.

systemap refresh

Executes extraction and the checks, and renders the page and the configured figures, in dependency order. Then it does a check of the written outputs. A result without changes prints map: The page agrees with the rendered model fields and the facts. A rejected check causes exit 1, and the command renders nothing. The last line gives the necessary action. If a second refresh gives the same result, the action is not refresh. If an output is stale after the command wrote it, the heading is stale after refresh. An example is a configured figure with the path of the page. After a check without errors, the command prints the source inventory unresolved group and the unknown surface group, as systemap check does. After a check without errors, the command examines the import rules, as systemap check does. It prints the rule results. A rule with the result fail causes exit 1. With [rules] unknown = "fail", a rule with the result unknown also causes exit 1. The command writes its outputs before it examines the rules. -q or --quiet prints only errors and check results. Before the extraction, the command replaces each flow review digest from systemap 2.0.0 one time. The section "A flow review from systemap 2.0.0" gives this replacement. It also moves the rules of each map from before the contract file to that file one time, as systemap extract does.

systemap suggest [--decide]

Proposes the first module groups for revision. From facts alone, it gives one component per package with two or more modules. It lists modules and imports across proposals. With a model, it also shows maps above forty components and large components that can become nested maps.

• --decide uses the module-pair answers of the decision provider instead of package groups. Set TYPESAFE_API_KEY for this option. --jev is the previous name of --decide. It stays for one release.

• --provider jev|openai selects the decision provider. OpenAI has no measured threshold for the pair question. Thus --provider openai sends nothing and exits 1.

systemap judgement [--strict] [--kind KIND] [--verbose] [--brief] [--json] [--order-by-drift]

Prints the second-pass findings. These include single-module components, possible incorrect assignments, missing sentences, thin layers, uncovered entry points, crossing imports, unreviewed flows, source records outside the flow endpoints, stale component source reviews, and model SDK imports outside agents. A line after the findings counts the component source reviews by state: current, stale, and missing. Then one row gives each flow with the label "review earlier than source tracking". These rows are not findings. A crossing-import row gives one component pair and a module count. Accepted answers under [judgement] answered suppress findings. The first finding of each kind has rows about its effect and necessary action.

• --strict exits 1 while a finding is open. If not, the exit code is 0. A model without components also gives exit 1 with --strict, as systemap check does.

• --kind KIND prints one kind.

• --verbose prints imports below each crossing-import row.

• Below a crossing import line, a count: row gives the number of modules of the first component that import the second component. Below a package_export line, a count: row gives the number of targets.

• --brief does not include the two explanation rows.

• Below each unknown surface line, a cause: row gives the cause that the adapter wrote. After the lines, the report gives one fix: line for each cause, as systemap check does. --brief does not remove these rows.

• Below the cause: row, the line of a module record gives its source rows. An at: row gives the file and the line of each cited statement. An excerpt: row gives the source excerpt. A parser version: row gives the version of the parser that refused the source. A finding line is the identity of the finding. Thus it does not contain these values (facts format 11). If two statements of one module give the same line, the line occurs one time with two at: rows.

• If the decision store has unknown decision requests, the report gives each one after the review counts. The row unknown request ID: CLAIM gives the claim. The report does not say that the claim is correct. An open line: row gives each open judgement line of the claim, and a CI: row gives the CI result of the claim. The systemap decisions section tells about decision requests.

• --json writes one JSON object to stdout for software, for example a CI step. The object has no explanation text. --brief and --verbose do not change it. The exit codes are the same as in the text mode, with and without --strict. Notices for a person go to stderr.

• With --json, --kind KIND selects the rows of open. The counts include all kinds. For a model without components, the lists are empty. The exit code is 1 with --strict, and 0 without it.

• --order-by-drift sends one Jev question for each open stale source review line. The answer is the drift score: the probability that the claims of the component agree with its changed source. The report puts the stale lines in sequence from the lowest drift score. The other lines do not move. A drift score: row below each stale line gives the score. With --json, each stale row has drift, and the object has drift_order.

  The option does not close a line, and it does not change a source review or an answer. The open lines and the exit code are the same with and without the option. The score has no threshold, because no measurement gives one (bench/jev/README.md, test 7). Examine each stale component, also the components at the end of the sequence. Set TYPESAFE_API_KEY for this option. Without the option, judgement sends no request. Without the key, or without an open stale source review line, the option also sends no request. The option always uses Jev. [decisions] provider does not apply to it.

  The question gives the claims that the source_review digest contains, and one part of the source. Git finds the last commit that added the recorded source_review digest below the folder of the model file. The source part is the diff of the module files of the component, from that commit to the working tree. If Git cannot find the commit, or the diff is empty, the source part is the current text of the module files. Each source part has a limit of 12,000 characters. A new file that is not in Git is not in the diff.

  A refusal or a request error gives no score. A line without a score goes to the end of the stale lines. A drift sequence: row gives the quantity of questions without a score and the cause. The answers go into the Jev cache. Thus, the next command sends no question. It reads the model list one time, as each Jev command does.

The JSON object has these fields:

The evidence digest is for an answer with one line. An items answer for more than one line has a different digest. The text report prints that digest in the pending-answer row.

systemap rules [--brief] [--json]

Prints the result of each import rule: pass, fail, or unknown. systemap check prints the same results. A fail result gives each import against the rule, as source module and target module. An unknown result gives each module with imports that are possibly not in the facts, and the cause.

The causes are a module that did not parse, unresolved imports, and an import of a module with no component. The command exits 1 for a fail, for an incorrect rule, or for missing facts. It also exits 1 for an unknown result with [rules] unknown = "fail". The ok value of --json agrees with the exit code. Missing facts are an item of problems.

• --brief does not include the two explanation rows.

• --json writes one JSON object to stdout for software. The keys are ok, unknown_policy, problems, counts, and rules. Each item of rules has map, id, kind, src, dst, reason, invariant, and result. It also has imports (source, target) and unknown (module, cause, detail). The cause values are no_facts, no_read_state, not_parsed, unresolved_not_known, unresolved_imports, and no_component.

systemap delta --base REF [--head REF] [--comment FILE --pr N] [--decide | --no-decide]

Compares extracted facts from two Git commits. Python and TypeScript use the configured language adapter, as the working tree does. The report shows moved, added, and removed modules with their components and model files. Delta reads the committed files. The Git attributes export-subst and export-ignore do not change them. Delta compares the head with the merge base of the two refs. If Git finds no merge base, the command gives an error and exits 2. Delta does not use a different commit as the base. Delta does not write a committed path that contains .., a backslash, or a colon. Thus the facts at a commit are the same on each platform. Before the report, delta gives each refused path and its cause under Not in this comparison. The changes of a refused path are not known. A refused module is not a removed module.

The first line gives the module counts. Then N of M components have changes gives the quantity of components that the delta lines name.

Findings include unclaimed new modules, removed entry and interface names, new crossing imports without flows, and flows with lost evidence. Each finding gives a correction. An answer for a new crossing import must agree with the judgement rule. An exact answer must have the current evidence digest. A family answer must have policy = true. The exit code is 0 if the map is current, or 1 if it is necessary to update the map.

The lines with a necessary action come first, under The map needs an update (N):. The lines with no necessary action follow. If no line has a necessary action, the last line starts with The map is current. If not, the last line tells you to do the actions and gives the next command.

Before its last line, the text report gives adjacent components. These have flows to the component with the most changes. This list gives context, not a finding. The list does not print if the component with the most changes connects to more than one-third of the map.

• --comment FILE --pr N writes the pull-request comment to FILE if [delta] page_url is set. The comment has one link to the Changes view of the page for pull request N. If it is necessary to update the map, one more line says so and gives the number of lines.

  The first comment line is <!-- systemap delta -->. CI finds the comment with it and changes that comment. Without page_url, the command writes no file. The comment does not change the delta lines or the exit code. If FILE is a link, the command replaces the link. It does not write to the target of the link. A relative FILE is relative to the current directory, not to --root. If FILE is in the repository, its folder must be in the repository after the resolution of links. If it is not, the command exits 1. FILE can be outside the repository, for example in a folder of the CI runner. If FILE is in the repository, each folder of FILE must be in the repository.

• --decide enables the suggestions of the decision provider for modules with changed names and content, and for unclaimed modules. The suggestions do not change the delta lines or the exit code. [jev] enabled = true in systemap.toml and the key of the provider also enable them. A key alone does not enable them. The heading of the suggestions names the provider, for example Jev suggestions.

• --no-decide sends nothing.

• --jev and --no-jev are aliases: the previous names of --decide and --no-decide. They stay for one release.

• --provider jev|openai selects the decision provider of --decide. With openai, [jev] enabled = true must have OPENAI_API_KEY. OpenAI has no measured threshold for the move question. Thus delta sends only the owner questions and gives the cause.

• --brief prints the lines without the explanation rows. systemap explain KIND gives the full explanation.

• The cost of the decision provider goes to stderr.

systemap describe

Prints measured map geometry for an agent that cannot see the page. The report includes position counts, components per region, region order, layout score, bends and length for each flow path, label gutters, and gutter seat usage. It also gives evidence-state counts, and the component and flow counts for each layer. Position counts distinguish pinned, placed, and temporary display positions. Flow paths with the worst geometry come first. A gutter line counts the labels that the flow paths put in that gutter.

The sequence section gives steps, the entry point where each sequence starts, steps without import evidence, unconfirmed agent drafts, and covered entry counts.

systemap audit [--dry-run] [--kind KIND]...

Sends questions about semantic claims to the decision provider. The finding kinds are decision mis-fold, decision owner, decision sentence, and decision governs. --kind "decision flow" also sends questions about flow claims. --kind also accepts the previous jev names for one release, with a warning. Answers use the cache. The command exits 0 for a completed report, or 1 if it cannot complete.

Set TYPESAFE_API_KEY for Jev, or OPENAI_API_KEY for OpenAI, before you run the command.

• Use --kind KIND again to select another question kind.

• --dry-run lists proposed questions and does not send them.

• --provider jev|openai selects the decision provider. With openai, the command does not send the decision mis-fold questions and gives the cause.

• --brief prints the findings without the explanation rows.

systemap plan "<task>" [--check ID] [--base REF]

Predicts components likely to change in a task. Jev compares the task with each component's function. The projection includes components with probability of at least 0.05. The report includes flows, sequences, and rules for each component. It lists six of each, then gives a count. The projection is in .systemap/plans/<id>.json. The ID has three parts: the date, a digest of the full task, and the first four words of the task. The same task on the same date gives the same ID. If the plan file of the ID contains a different task, the command does not replace it. It exits 1 and gives the file.

The measured threshold of 0.05 is in bench/jev/plan_eval.py. Set TYPESAFE_API_KEY before you run the command.

• --check ID --base REF compares the projection with changed components since REF. The default base is origin/main. The current model gives the components of each module. A component of a module claims the module, or a symbol in the module. If the current model does not claim a removed module, the model at the REF commit gives its component. It exits 1 for changed components outside the plan.

• - instead of a task reads stdin.

• --provider jev|openai selects the decision provider. OpenAI has no measured threshold for plan. Thus --provider openai sends nothing and exits 1.

systemap triage TEXT

Predicts the three components likely to change in an issue fix. The report includes their modules and adjacent components. - reads stdin. The text limit is 2,000 characters. Set TYPESAFE_API_KEY before you run the command.

• --provider jev|openai selects the decision provider. The OpenAI triage measurement did not satisfy the holdout rule. Thus --provider openai sends nothing and exits 1.

systemap journeys [--limit N] [--dry-run]

Writes a sequence for an entry point with no examined sequence. For multiple same-kind entries in one component, it can write a grouped sequence. Its covers field records the examined entry identities. An examination must add a new entry to that list before the entry counts as covered.

[agent] command reads source from the entry point. The agent gives components in the execution path and a sentence for each step. Each request contains the language policy of the [writing] profile. The command rejects a step with no authored flow and gives a finding. The command also rejects a step source record that does not resolve. It rejects a step source record in no module of an acting or measured component of the step. The command does not write that step. The agent cache keeps only an answer that gives an accepted sequence. Thus, after a rejected answer, the next command sends the question to the agent again.

The agent can write no more than 200,000 bytes to stdout. If it writes more, the command stops the agent, and the request does not complete. If a request does not complete, the command writes the accepted sequences of the other requests. Then it names each request that did not complete and exits 1. A rejected draft is also a request that did not complete.

Accepted sequences enter the model with drafted=True. The command writes them into the JOURNEYS = (...) tuple of the model. The tuple can have a type annotation, as in the model from init. If the model does not import Journey or Step, the command adds an import from systemap. Before the write, the model reader reads the changed model, as for each other command. If the reader refuses it, or the changed MEANING does not contain each accepted sequence, the command writes no file and exits 1. judgement prints drafted journey until a person examines the sequence and removes the mark.

By default, the command writes no more than three sequences.

• --limit N writes no more than N sequences. N must be 1 or more.

• --dry-run lists proposed sequences without file changes.

• With no [agent] command, the command also lists proposals and gives the reason it cannot write them.

systemap history [--since WHEN] [--every DAYS] [--top N] [--ref REF]

Reads source samples across repository history. The defaults are 1 year ago, a minimum interval of 14 days between two adjacent samples (--every), and the five largest windows (--top default 5). Each window compares two samples. A sample is the first commit after the minimum interval from the previous sample. The last sample is the ref, also if the interval before it is smaller. Thus a repository with a small number of commits gives intervals of more than --every days. Facts use the cache .systemap/facts/<sha>-<scope>.json.

Each window shows module and entry additions or removals, component size changes, and new and removed crossing imports. It shows the commits that added the files of new modules. A commit that only changes such a file is not in the list. All samples use the component assignments in the selected map. Thus, a moved module counts under its component in the selected map. TypeScript samples include .ts, .tsx, tests, and package entry points.

• --ref REF starts from that branch or commit instead of HEAD. Git must resolve REF to a commit. A value that starts with - is not an option to Git. If Git cannot resolve REF, or if a Git command fails, the command exits 2.

systemap explain [KIND]

Prints one finding kind's meaning, effect on the map, and necessary action. With no kind, it lists all printed kinds and their one-line meanings. An unknown kind causes exit 1. The command reads no repository files. Thus it has no --root option after the command.

systemap convert

Writes each model file that systemap refuses again, with literal values only. The command must run each refused file one time, so it needs SYSTEMAP_TRUST_MODEL_CODE=1. Examine the code of the model files before you set this value. Without the value, the command writes nothing and exits 2 if a model file is refused. If all model files have literal values only, it writes nothing and exits 0.

For each refused file, the command reads the new text with the reader that runs no code. It writes the file only if that reader gives the same model as the old file. Fields with their default values are not in the new text. If the old file imported a file beside it, the command names that file. The new file does not import it.

systemap review ID | --flow ID | --flow 'SRC->DST' [--map ID] [--dry-run]

Writes the current review digest of one target into the model file. systemap review ID writes source_review of the component ID. systemap review --flow ID writes review_digest of the flow with that identifier. systemap review --flow 'SRC->DST' writes review_digest of the flow from SRC to DST. A flow digest contains the flow claim and the source_refs with the digest of each module. The SRC->DST form is correct only for a pair that one flow connects. Put the SRC->DST value between quotation marks, because the shell reads > as a redirection. If the map has no flow with the ID, the command stops with exit 2. --map ID selects a nested map. --dry-run prints the digest and the file, and it writes nothing.

The command does not examine claims. Before you use it, examine the source and all the claims of the target. One command writes one target. The command has no option for all targets, because a person or an agent must examine each claim separately.

The command reads the source in the working tree. systemap judgement reads the stored facts, so run systemap refresh before systemap judgement. A flow digest is one of the claims of its two endpoint components. Thus, a new flow digest makes a current review of an endpoint stale, and the command tells you. Record flow digests before component digests.

The command writes the value into the file that defines the target. This file can be a file that the model file imports. The command changes only the value, or it adds one keyword argument. It keeps the comments and the format of the file. It writes the file only if the reader that runs no code gives the same model with only the new value. If the value is the current digest, the command writes nothing.

The command stops with exit 1 and writes nothing in these conditions:

• The map has no such component or flow, or two or more flows connect the SRC->DST pair.
• The component has no current digest. It claims no module, a claimed module is missing, or the parser cannot read a claimed module.
• The flow has no source_refs, or a source record does not agree with the current source.
• systemap cannot read the model file as data. Use systemap convert first.
• The command finds no literal call for the target, or more than one.

systemap decisions pending | submit FILE | status

These commands give the claims of the map to a coding agent in its current session. The agent examines each claim against the source code and sends a verdict. systemap examines each verdict and records the correct verdicts. The commands send no request to a model. An API key is not necessary. The skill procedure is in references/decisions.md.

The commands read the facts file. If the facts file does not agree with the source code, the commands stop with exit 1. Run systemap refresh first.

A decision request has one of three types:

A judgement line that a review digest closes is not a different decision request. These lines are stale source review and missing source review for a component with a source_review request. They are also flow review and declared flow for a flow with a flow_review request.

The id of a decision request contains the type, the target, and the first 16 characters of the claim digest. If the claim does not change, the id stays the same in a different session. A source change that does not change a judgement line does not change its id.

The decision store keeps one record for each target. The record does not use the claim digest. The target of a component is its ID. The target of a flow is its id, or SRC->DST for a flow without an id. The target of a judgement line is its kind and the names of the components and modules in the line, for example single module: Reader pkg.reader. If two current lines have the same kind and names, or a line names nothing, the target is the full line.

systemap decisions pending [--json]

Gives the pending decision requests. The command exits 0. An unknown decision request is not pending. The unknown count gives the quantity.

The JSON object has these fields:

For a judgement line, the files are the files of the components and the modules that the line names. If the line names no component or module, the list is empty.

systemap decisions submit FILE

Reads a JSON list of verdicts from FILE, or from stdin for -. Each verdict is an object with only these fields:

The command first examines all verdicts. If one verdict is incorrect, the command writes no file, gives each error, and exits 1. The command rejects a verdict in these conditions:

• The request_id is not a current decision request, or the decision request is unknown. A claim change gives a new id.
• The file has two verdicts for one request_id.
• A file is an absolute path, a Windows drive or UNC path, or contains .. or a backslash.
• A file is not a regular file, or is not a source file or a test file in the facts. A test file in the facts is the file of a test in the tests of a module record, or of a test_file_issues record.
• A file is a symbolic link to a file that is not in the repository.
• A line span is not in the file, or start_line is more than end_line.
• A sha256 is not the SHA-256 digest of the current file content.
• A supported verdict has no citation in a file of the claim. For a flow, these are the files of the two endpoint components. For a judgement line without files, one citation is necessary.
• A supported verdict has a decision request with a blocked value, or the review command cannot write the digest.
• A supported verdict for a component has a flow of that component with a contradicted or unknown verdict.

Then the command writes, in this sequence:

1. The review_digest of each supported flow.
2. The source_review of each supported component. A flow digest is one of the claims of its endpoint components. Thus, the flow digests come first.
3. One exact answer for each supported judgement line. A review digest can close a judgement line. Thus the command finds the open lines and their evidence digests after the review digests.
4. The decision store, .systemap/decisions.json. Git does not record this file.

A contradicted verdict adds one to the contradicted count of the target. The agent must correct the map and send a new verdict. At [decisions] max_contradicted verdicts, the decision request becomes unknown.

An insufficient_evidence verdict adds one to the insufficient_evidence count of the target. After the first insufficient_evidence verdict, the agent can examine more of the source and send one more verdict. At 2 insufficient_evidence verdicts, the decision request becomes unknown. A supported verdict sets the two counts to zero.

The decision store keeps each verdict of a target, with its summary, its citations, and its claim digest. systemap decisions status shows each verdict. The limits stop work that occurs again and again. They do not stop an agent that sends supported for a claim that it wrote.

A change of the map claim does not set the counts to zero, and does not make an unknown decision request pending. Thus an agent that changes the map after each contradicted verdict stops at the limit. A change of a source file of the target makes the decision request pending again, with counts of zero. A file that the map change adds to the target, or removes from it, is not a source change. To start all counts again, delete .systemap/decisions.json.

If .systemap/decisions.json does not contain correct JSON, or has a different version or form, the systemap decisions commands and systemap judgement stop with exit 1. The error gives the path and the cause. Remove the file. Then do the command again.

systemap decisions status [--json]

Gives the counts, the unknown decision requests, and the recorded verdicts. The command exits 0 if no decision request is pending or unknown. If not, it exits 1. An unknown decision request does not show that its claim is correct, and the text does not say that it is correct.

The text gives the CI result of each unknown decision request. An open judgement line of the claim stays open. Thus systemap judgement --strict exits 1. If the claim has no open judgement line, systemap judgement --strict does not exit 1 because of the claim. For example, with [judgement] require_reviews = false, a component without a source review has no open judgement line.

systemap serve [--port 8765]

Supplies the output directory through HTTP on the loopback address. The command prints the URL. If the port is not available, the command exits 2. Then use --port 0 to select an available port, or give a different port. The server answers only a request whose Host header is 127.0.0.1 or localhost with the server port. Thus a web page that makes its own domain name point at 127.0.0.1 cannot read the map. The server answers 404 for a symbolic link to a file that is not in the output directory. systemap live has the same rules. If the output directory is not in the repository after the resolution of links, the command exits 1. The server does not start.

systemap live [--port 8765] [--base REF] [--no-watch] [--json]

Renders the page of the working tree and supplies it through HTTP on the loopback address. The facts come from the source files in memory. The models come from the model files. The command writes the pages and change.svg into a temporary directory and deletes it when it stops. It does not write the output directory, the facts file, or a tracked file. For the comparison, it can add the facts of the merge base to the cache in .systemap/facts/, as systemap render --base does.

Each time that the command renders the page, the page gets a new version number. The command renders one version at a time. If a request occurs while the command renders, the command renders one more version after the current version. If the command cannot render a version, the last page stays and the command gives the error. Examples are a model file that does not load, a source syntax error, and an extraction error. If the first version fails, the page gives the error. If the command cannot write the pages of a version, the command gives the error, and the next version renders. After a good version, the command removes the pages of the maps that the version does not have.

• --base REF sets the base of the Changes view. The default is the first of origin/HEAD, origin/main, main, origin/master, and master that has a merge base with HEAD. If no ref has one, the page has no revision comparison. The Changes view compares the working tree with that merge base. The comparison includes the commits since the merge base, the edits that are not in a commit, and the untracked files that Git does not ignore.

• Without --no-watch, the command scans the configuration files, the model files, and the source and test files one time each second. The scan includes the language configuration files below each package root, such as packages/web/src/lib/package.json. It also includes these files in the folders between a package root and the repository root, such as packages/web/tsconfig.json. The scan skips the same folders as the source extraction of the language. For TypeScript, it does not skip a folder with the name build or dist. The scan includes each test file that extraction reads, also a file that test_patterns selects out of the package roots and the test directories. When a scan finds a change and the next scan finds no more change, the command renders the page again.

• --no-watch stops the scan. Then the command renders the page again only after POST /refresh.

• --json writes one JSON object on a line for each event. Without it, the command writes short text lines.

• --port 0 selects an available port. If the port is not available, the command exits 2.

The browser loads the page again after each version and keeps the view of the reader. DESIGN.md gives the parts of the view that the page keeps.

version in GET /status is the number of the last version that started. updates is the number of map update lines: the systemap delta lines that need an action, for the working tree and the merge base. action is the action of the line kind from systemap explain. components are the changed components of the top map. svg is the absolute path of change.svg. seconds is the time of the last good version.

On this repository, one version takes about 7 to 8 seconds. Thus the command waits until the files stop changing before it renders the page. bench/jev/README.md gives the measurements.

systemap skill [--dir PATH] [--print]

Reinstalls the skill directory from init: SKILL.md and references/.

• --dir PATH writes to another directory.

Each skill file must be in the repository (in PATH with --dir) after the resolution of symbolic links. If a file is not, the command writes no file and exits 2.

• --print writes SKILL.md to stdout.

What can you configure?

Use systemap.toml at the repository root or [tool.systemap] in pyproject.toml. All keys are optional. Unknown keys are rejected.

The environment of a command can set three values. A repository file cannot set them.

TypeScript discovery does not include .d.ts, .d.mts, and .d.cts declaration files. The external imports do not include Node.js built-in modules, such as node:fs and path.

Two types of import name a file of the same package through package.json. Thus they are internal imports:

• A self-name import names the package, as import ky from "ky" in the ky package. The nearest package.json above the file must have this name and an exports key.
• A subpath import starts with #, as #types/hot. The imports key of the nearest package.json gives the file. A target that names an npm package gives that package in external.

An import of a different package of the repository is also an internal import. The name in a package.json file of the repository identifies that package. The module that [package_roots] gives for the import must be in the folder of that package.json file. A [package_roots] name does not identify a package for other imports. Thus, if the package web has no exports key, import "web" in that package is an external import.

systemap uses the rules of Node.js and TypeScript for these imports: Self-referencing a package using its name, Subpath imports, and package.json "imports" and self-name imports.

The conditions are types, node, import, and default. A .cts file uses require and not import. systemap does not read moduleResolution or customConditions.

A target in outDir maps to its source file, as for a package entry point. A declaration file has no module. Thus an import with a declaration file as its target is an unresolved local import. An import without a target, for example a # name that imports does not have, is also an unresolved local import.

The suffix of an import selects the source suffix, as in tsc. .js selects .ts or .tsx, .mjs selects .mts, and .cjs selects .cts. An import without a suffix selects .ts or .tsx. If tsc cannot resolve a relative import, the import has no target. A paths alias names its first target file that is available, as in tsc. If no module has that file, the import is an unresolved local import. A different target does not replace it. An import path with a NUL character has no target.

A source file that systemap cannot read keeps its module record, with a read problem. A package.json file that systemap cannot read gives a configuration error. This also applies to a package.json file without a JSON object.

A TypeScript test name contains the names of the describe or suite functions that contain the test. The text > is between two names, as in orders > saves an order. If a file has two tests with the same name, the second name gets #2. If a different test of the file has that name, the name gets the next number that no test of the file has. A re-export from an npm package keeps the package name and gives no unknown record. A missing npm package in tsconfig.json extends gives an unknown surface finding. Extraction continues with the compiler options that it can read.

In each file of the extends chain, ${configDir} at the start of a path uses the top-level tsconfig.json directory. This applies to baseUrl, paths, rootDir, and outDir, as it does in tsc. A plain relative path uses the directory of the file that declares it.

Without rootDir, the source root follows the project's tsc rule:

• TypeScript 5 uses the longest common directory of selected non-declaration files. The files, include, and exclude options select files. An include pattern can select files that are not in the tsconfig.json directory, but only files in the repository. The selected files include tests and the source files that these files import.

• TypeScript 6 and later use the tsconfig.json directory.

• composite uses the tsconfig.json directory on all versions.

Each source file uses the compiler options of one tsconfig.json project. The nearest tsconfig.json file gives the project if its files or their imports contain the file. Then the first project in references that selects the file gives the project. Then the first project in references with files that import the file gives the project. These imports can go through other files. These imports include relative imports, paths aliases, self-name imports, and subpath imports. An import of a different package of the repository does not add a file to a project. tsc reads the declaration output of that package for such an import.

The version comes from node_modules/typescript/package.json, then the typescript range in package.json. This also applies if the repository root has no tsconfig.json file. If the two files do not give a version, systemap tries the two roots. A compiled target maps to a module only if one root gives a match and the other does not. Two matches leave the target unmapped.

check prints unknown records without rejection. Each unknown record must have a correction or accepted answer under [judgement] answered before judgement --strict accepts it.