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 HTML or 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 |
| Declare supported Python calls, imports and argument counts | Function calls | call preflight tests, function support contract |
| Observe assignments and public returns from captured code | Execution | authoring protocol integration |
| Describe inputs and outputs without executing calculations | describe, definition contract | manifest integration |
| Generate runtime handles and editor types without executing calculations | bindings, handles | authoring tests |
| Parse cross-language evidence | execution schema, authoring schema | execution contract tests |
| Validate numeric evidence and retain input kinds in artifact bindings | numeric contracts, input evidence, executionBindingFrom in execution contracts |
numeric contract tests, cross-package evidence |
| Parse notation and validate scoped Symbol display identity across documents | notation parser, Symbol display module | display contract tests, notation conformance |
| Validate whole Value tree structure and compare formulas, observations, outputs and references | verifyExecution, evaluator, operation roles and 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 HTML/PDF | document coordinator, shared HTML, browser inspection, evidence | HTML and layout checks, installed PDF cases, evidence tests |
Binding generation and invocation planning read the same static calculation
definitions. Generated .py modules create callable handles; adjacent .pyi
files describe their keyword arguments and public output keys. Importing a handle
does not execute the authored function. Calling it enters the capture, planning
and execution path above. See the Python library
for the developer workflow and the authoring guide
for composition.
The CLI entry point separates verified commands
from dev-export and dev-render. The local cso dev command uses the
server to validate requests and the
runtime to retain verified runs.
The standalone CLI browser UI edits declared
inputs. Generated projects instead use their owned
React page, with
Vite proxying /api to
cso dev; their launcher
starts Vite and one CLI process for each entry in
the report registry.
The legacy exporter
still serves older single-file sources. Development output is not verification.
Installable libraries and tools live in packages/. apps/demo is the
application that consumes them. The initializer keeps its template inside its
package and creates user projects outside this repository.
- Python owns source parsing, execution, generated handles and authoring rules.
- Core owns public schemas, reference identity, notation parsing, formula evaluation and conversion. It needs no Python, React, browser or filesystem access to verify supplied data.
- React owns preparation, MathML rendering 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 HTML/PDF publication.
- Initializer owns its synthetic project template, editable browser UI and setup scripts; it delegates calculation, verification and report routes to the installed CLI. Fresh-project acceptance exercises published-style dependencies through actual archives.
- Demo consumes packages and explicit data directories through its workspace launcher. Root example preparation reuses CLI verification and asset capture to supply the canonical prepared document. It also supplies the Python files in a companion bundle. The demo's source loader validates file hashes and the document's execution binding before exposing the code to React.
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.