Python captures source and runtime observations. Core validates that evidence and evaluates the formulas independently. The CLI passes one verified execution to React for document preparation, then publishes the PDF and evidence.
| Step | Implementation | Behavior checks |
|---|---|---|
| Capture source bytes and resolve local dependencies | Capture | execution tests |
| Interpret parameters, defaults and public outputs once for generation and planning | Definitions, annotations | definition tests |
| Plan formulas, inherited inputs and document order | Planner, annotations | authoring tests |
| Observe assignments and public returns from captured code | Execution | authoring protocol integration |
| Generate editor types without executing calculations | bindings, handles | authoring tests |
| Parse cross-language evidence | execution schema, authoring schema | execution contract tests |
| Compare formulas, observations, outputs and references | verifyExecution, evaluator, numeric policy | verifier cases, numeric tests |
| Prepare ordered content bound to that execution | prepareExecutionDocument, document schemas | prepared-document tests |
| Select engineering context, operand details and retained-source pointers | context preparation | context tests |
| Capture assets, render and publish | pdfCommand, assets, evidence | installed PDF cases, evidence tests |
The CLI entry point separates verified commands
from dev-export and dev-render. The legacy exporter
still serves older single-file sources. Development output is not verification.
- Python owns source parsing, execution, generated handles and authoring rules.
- Core owns public schemas, reference identity, formula evaluation and conversion. It needs no Python, React, browser or filesystem access to verify supplied data.
- React owns preparation, mathematical notation and engineering presentation. It receives captured assets; it does not execute calculations or fetch files.
- CLI owns process and filesystem access, reports, asset policy and PDF publication.
- Demo consumes packages and explicit data directories through its workspace launcher.
See ADR 0001 for the dependency decision and ADR 0002 for the distinction between evidence and the displayed calculation.
- Core exports and React exports define the public APIs.
- Rendering maps JSON adapters, sheet schemas and notation to code.
- Authoring defines the rules for new
.cso.pycalculations. - Integration checks own canonical examples, synthetic fixtures and tests across installed packages.
Keep schema fields, function lists and option defaults in their implementations. Update this map when responsibility or execution order changes.