Use the React package for imports and a small
rendering example. FormulaSheet displays supplied values; numerical evaluation
belongs to core verification.
| Input | Use | Authoritative code |
|---|---|---|
CalculationSourceObject |
Formulas, symbols, source context and ordered content | object schema, parser |
| Value-tree JSON | Compact adapter for mathematical rows | schema, conversion |
SheetDocument |
Direct mathematical sheet passed to FormulaSheet |
schema, row traversal |
PreparedDocument |
Ordered engineering document with prose, figures and retained evidence | document contract, preparation, renderer |
Parse unknown input with the public schema/parser for that contract. Use
safeParse when the caller handles validation failures. Read accepted fields
and defaults from the schemas, rather than maintaining another interface here.
Value trees carry a root, references and supplied results. Reference identities must resolve; glyphs are display labels, not reference keys. Repeated placement of one symbol retains its identity. A math-only sheet cannot establish complete preservation of a source containing figures or standalone text.
For Python export, use the core code generator. It orders assignments by dependency and generates Python without executing it.
Passing or returning an existing quantity does not create a calculation step. Keep each function's inputs and outputs in the standard indexed quantity rows, with the binding's origin in the comment cell. Preserve existing comments too. Helper input rows identify each explicit connection's source; multiple calls remain distinct. Literal connections show the complete supplied number without result-display rounding. Computed arguments still have a separate derivation.
Direct forwarded returns use the existing captured quantity identity in case tables. Their symbolic rows show the source without a second equality row. Explicitly annotated aliases retain their full derivation as an authored change of notation or review quantity. Do not infer forwarding from equal values, matching glyphs or a numerical simplification. Arithmetic, conditional expressions and conversions remain calculations.
This is presentation of the retained plan: keep every formula tree, binding, call path, unit, qualification and diagnostic in the evidence. Older prepared reports retain equality rows for previously captured direct returns. Regenerate captures and prepare reports again to get compact return rows.
Default HTML/PDF shows the engineering narrative: ordered inputs and formulas, substitutions, units, explanations, diagrams, assumptions, qualifications and results. Full source/audit data stays in machine-readable evidence. Internal records and historical reviews do not become an automatic printed appendix.
PreparedFormulaSheet accepts showSourceDetails={false} to omit source-status
and the closing source/input note. Its default is true. Input rows and all
calculation content remain unchanged. Execution details close the report rather
than preceding its authored calculation. No automatic results overview is added.
Examples uses this option beside its Python viewer. CLI/PDF rendering keeps
the default.
Context preparation selects which source fields have a presentation role. Preserve unmapped extensions, own-key identities, empty/falsy values and ordered metadata in evidence. Map visible content back to retained source data. Historical attribution never approves a new execution. See ADR 0002.
PreparedDocument version 2 carries selected context on the document, sections
and item placements. Symbol placements also carry context for active operands
that have no placement of their own. The renderer consumes these fields without
searching historical reviews, selecting metadata or traversing operand context.
Every displayed context value has a JSON pointer to retained current-source
data; the document schema checks that the pointer resolves to the same value.
This checks attribution within the document, not independent numerical agreement.
Current source and section metadata remain in sourceMetadata and section
metadata. Item contextSource retains authored placement metadata, nested
content metadata and unconsumed content fields. Historical records remain
separate retained evidence; changing their order does not change presentation.
Reprepare after changing source context, symbols or placements.
Version 1 prepared JSON is rejected. Regenerate saved documents with
prepareExecutionDocument from the captured execution and assets, or with
prepareLegacyDocument from the original CSO, asset manifest and captured assets.
Reattach historical reviews through the preparation options. Synthetic documents
constructed directly must provide context arrays and symbol operand arrays.
Update core and React together. Prepared reports containing a method or table
use document version 6. Every reusable definition, including nested helpers,
retains a required function identity: original module path, Python function,
source hash and method revision. Every table carries its captured method ID and
the same identity; core rejects missing definitions or mismatched identities.
HTML/PDF always print the canonical module.cso.py::function identity, even
when general source details are hidden. Tables link to a report-local procedure
reference such as P1, and print continuations repeat that reference and identity.
Prepared comparison reports from versions 3, 4 and 5 must be regenerated from
retained execution and captured assets with prepareExecutionDocument. Do not
invent identities from titles or filenames, mutate saved JSON to version 6,
or rerun Python merely to migrate the presentation. Older supported execution
protocols retain their meaning. Plain reports remain prepared version 2;
external-only reports without a method/table remain version 4.
External captures use execution protocol 4, CSO schema 1.2.0 and prepared
document version 4 when no method or table is present. Comparisons use version 6.
They preserve one complete input/method/output block per captured call, including unused outputs and the external algorithm's formula
verification exclusion. An optional verificationReport passed to
prepareExecutionDocument must bind to that exact capture before its outcomes
can appear. Repreparation reads captured evidence and assets without running
the adapter. Static methods with an external boundary use prepared version 6
even when no cases run. A comparison retains complete external detail blocks for
each captured case/call path. Input and output quantities use the same indexed
description, variable, value, unit and comment cells as ordinary rows. Bound
reference summaries list checked and uncovered outputs; they do not claim that
an external algorithm was independently evaluated. Older captures retain their
original meaning.
A comparison's case headings show the captured case subscript, such as fp
for first_panel, so table values can be matched to downstream qualified
symbols. Row-oriented comparisons show it beside each case label. Unqualified
cases keep their ordinary headings; no suffix is inferred from the display title.
A comparison is one logical table. On screen it scrolls horizontally and keeps
the identifying column visible. Print divides the authored column axis into
parts that fit the page width, then continues a tall part onto later pages.
Each part repeats the identifying labels, group context and qualifications
needed to read that part. A single column or row that cannot fit at report
type size fails checked publication with DOCUMENT_LAYOUT_OVERFLOW and leaves
an existing output file unchanged. Publication does not shrink type, clip a
column, drop a case or switch orientation. Extracted page text is layout
evidence. Inspect every delivered PDF page before treating the report as
visually accepted. See ADR 0009
and ADR 0010.
The pure preparer receives captured data URLs and validates their binding to
the execution. The CLI owns file containment,
capture, media validation and image decoding. For imported documents, supply a
LegacyAssetManifest binding figure IDs and URLs to captured bytes, captions and
alt text. Authored widths remain preferred CSS pixel sizes constrained to the page.
Glyphs and units use the pure core notation parser.
Braces form transparent groups for subscripts, superscripts and fractions:
A_{rect}, mm^{2}, {height+width}/{2}. Parentheses and brackets form
visible fenced groups. Greek names may be plain or backslash-prefixed, such as
rho and \rho. Other backslash commands remain literal tokens; \frac and
\sqrt are not glyph commands.
The alias table lists supported
names. The typed tree preserves identifiers, numbers, operators and quoted text
for the React MathML adapter.
Unknown unquoted Unicode scalars remain intact as upright literal text. The
explicit Greek and mathematical italic identifier sets avoid differences between
runtime Unicode versions. Malformed nonempty notation is a contract error for
documents and verified output; the interactive view renders ? as feedback.
Input, node and nesting limits return diagnostics instead of overflowing the
renderer. Core notation tests and
React rendering tests
show the grammar and output roles.
Apply the authoring naming rules to new variables.
Formula structure comes from value-tree functions. Function specs
define IDs and precedence; MathML renderers
define layout. The calculation operations have constrained Python forms and
independent verification rules. The remaining noop and stub nodes retain
rendering and Python export support for grouping and placeholders; they are not
Python authoring functions or numerically verified operations. Logical and,
or, not and Boolean-only ^ are verified only as predicates that combine
comparisons. The
authoring guide defines
accepted argument forms and numerical roles.
Derivations wrap between complete equation parts. Each equals sign stays with its right-hand expression. Compound AND/OR predicates use continuation lines with their operators and grouping retained, so wide conditionals can use more height without shrinking notation or dropping a branch.
Declare each authored function once in Python's function calls module. Source preflight and planning derive allowed imports, spellings, argument counts and operation IDs from those declarations. Core independently owns numerical behavior in its operation registry. When adding a function, add its evaluator, display spec and Python export mapping. The function support contract reads every Python declaration from the installed wheel and exercises each spelling through capture, verification, rendering and export. It classifies display-only nodes separately and checks their rendering/export compatibility without requiring Python authoring syntax. Add an independent reference case there and domain/edge cases in the owning packages. Display-only or export-only operations do not need an authoring declaration.
Choose the evidence needed for the changed behavior before generating artifacts.
| Change | Primary checks | PDF work |
|---|---|---|
| Bindings, imports, documentation or runtime only | Execution, contracts, types and consumer tests | Only for a requested PDF deliverable |
| Calculation content or composition | Prepared content/identity assertions and affected HTML formulas | A targeted print check if pagination is affected |
| MathML, CSS or document layout | Screen and print-media browser checks; inspect affected HTML rows | Representative final pagination check |
| PDF pipeline or delivery | HTML diagnostics first | Print behavior checks; every-page inspection for a delivered PDF |
Use the actual prepared document renderer and captured assets. A fresh Python execution, a hand-built HTML approximation or the demo's screen layout does not establish the layout of the verified report being inspected.
After setup, generate a standalone report from the repository root:
node packages/cso-cli/dist/cli.js bindings examples/two-panel
node packages/cso-cli/dist/cli.js html examples/two-panel/estimate.cso.py \
--function estimate --input width=2 --out output/panels.html --format jsonOpen the file in a browser. It embeds the shared renderer's CSS and captured image
bytes, uses the 190 mm print content width on screen, and needs no preview server.
Generation verifies one execution and prepares its document without Chromium.
The report records browser rendering as not_applicable; it is not a layout pass.
Add --check-layout to check the same HTML in Chromium at screen and print media
settings before publication. The shared HTML/PDF check waits for fonts and images,
validates presentation, and checks MathML descendant bounds against the row and
sheet. Overflow diagnostics identify the source placement, selector, measured
bounds, media and overflow in CSS pixels. Inspect that row first; capture a
targeted screenshot when notation or spacing needs visual judgment.
For a failing layout, plain html export still produces an inspectable preview.
html --check-layout and pdf fail without replacing an existing output.
Browser geometry checks do not establish actual PDF pagination, font embedding,
independent numerical agreement or human visual acceptance.
Start with the authored table(...) call and its method(...) target. The
calculation's symbol metadata supplies descriptions, glyphs and units. The table
selects quantities, names cases and chooses cases_axis; CSS controls appearance.
| Change | Owning implementation |
|---|---|
| Cell markup and description/symbol/unit structure | case 'table' in PreparedFormulaSheet |
| Spacing, alignment, borders and group headings | .cso-comparison rules in styles.css |
| Case values, selected quantities and qualifications | comparisonPlacement in prepare-document |
| Measured print parts and repeated headings | partition-comparisons |
Inspect [data-comparison-id] in the generated HTML. It carries
data-source-placement and data-cases-axis. Each value cell carries
data-quantity, data-case, data-symbol-id and its unformatted data-value.
These identify the case and captured quantity independently of visible labels or
orientation. The description, notation and unit have separate
.cso-comparison-description, .cso-comparison-notation and
.cso-comparison-unit elements for targeted style changes.
Edit the source renderer or shared CSS, then rebuild React and regenerate the report. Generated HTML embeds the CSS; editing it alone will not fix the next report. Print parts clone the screen table and retain its classes and binding attributes. Inspect both orientations at report width and run the method/table integration checks after changes that affect cell size. They cover wide and tall tables, repeated headings, MathML units, checks and applicability. Keep the data attributes intact: print measurement and inspection use them.
For the maintained tapered comparison:
npm run build:cli
node packages/cso-cli/dist/cli.js html examples/section-properties/compare.cso.py \
--function compare_tapered --check-layout --out .scratch/tapered.html --format jsonThen follow the PDF inspection steps below if print layout changed.
Import @cs-object/react/style.css once. Browser printFormulaSheet accepts
a sheet target and waits for cloned images. Its boolean result means the request
was accepted; onError reports deferred failures. See the print implementation
and browser tests.
Verified PDF generation runs through the CLI. Content retention tests, rendering success and every-page inspection are separate. Prepared-document tests check retained fields and engineering presentation using synthetic inputs. Extracted text or a page count cannot establish visual acceptance.
Before delivering a PDF, inspect every page for missing content, unreadable
notation, clipping and pagination. Bind findings to the exact final PDF bytes.
Generated test artifacts can remain marked visualInspection: pending; running
an automated suite does not create a manual review queue for every test PDF.
For HTML work, inspect affected formulas at their intended width and keep
numerical, browser-layout and visual results separate. On-demand hosted downloads
follow the pending-review policy in ADR 0004.