Developer docs

From constrained Python to reviewable documents

Capture source and execution observations, check documented formulas, then prepare a document for review. Source-to-document consistency, independent numerical agreement and visual inspection each answer a different question. Human engineering approval remains separate.

Input

Python

Contract

CSO

Display

MathML

Step 1

Annotated Python

Author constrained Python with shared input metadata, formulas and public results.

Step 2

Capture and execute

Capture source bytes and execution observations. Produce a CalculationSourceObject plus evidence.

Step 3

verifyExecution

Core evaluates documented formulas and compares runtime observations to check source-to-document consistency.

Step 4

Optional independent references

Compare with separately established expected values bound to the source, function and inputs. Report agreement separately.

Step 5

Prepare and display

Use prepareExecutionDocument and PreparedFormulaSheet for ordered documents, or FormulaSheet for mathematical rows.

Motivation

Keep calculations inspectable

A CalculationSourceObject records formulas, symbols, units, explanations, ordered content and source metadata. FormulaSheet is its reviewable mathematical presentation, not the complete calculation source.

Authoring layer

Calculation inputs carry reusable metadata

Signature annotations define inputs. Shared Annotated aliases keep their metadata reusable. This panel-area fragment uses the maintained two-panel notation: pan means panel and rect means rectangle. It is illustration-only, not a captured execution or the full maintained calculation.

Annotated Python illustration

python

PanelWidth: TypeAlias = Annotated[
    float,
    symbol(
        glyph=r"w_{pan}",
        unit="m",
    ),
]
PanelHeight: TypeAlias = Annotated[
    float,
    symbol(
        glyph=r"h_{pan}",
        unit="m",
    ),
]

@calculation(
    id="panel-area-illustration",
    ...
)
@section(id="geometry", ...)
def panel_area(
    width: PanelWidth = 2,
    height: PanelHeight = 3,
) -> CalculationResults:
    area: Annotated[
        float,
        symbol(
            glyph=r"A_{rect}",
            unit="m^2",
            description="Panel area",
        ),
    ] = width * height
    return {"area": area}

Source object

Capture and execute produce CSO plus evidence

The captured execution pairs a CalculationSourceObject with source hashes, input bindings, assignment observations and public outputs. Core verifyExecution checks source-to-document consistency; execution success alone is not a verification pass. Legacy export and dev-export remain unverified development paths. The adjacent JSON is a formula fragment with illustrative values, not a complete CSO or execution record.

CSO fragment

json

{
  "sections": [{ "items": [
    { "kind": "symbol", "symbol": {
        "id": "width", "glyph": "w_{pan}",
        "unit": "m", "valueTree": { "result": {
          "kind": "number", "value": 2 }, ... }
    }},
    { "kind": "symbol", "symbol": {
        "id": "height", "glyph": "h_{pan}",
        "unit": "m", "valueTree": { "result": {
          "kind": "number", "value": 3 }, ... }
    }},
    { "kind": "symbol", "symbol": {
        "id": "area", "glyph": "A_{rect}",
        "description": "Panel area",
        "unit": "m^2", "comment": "...",
        "valueTree": {
          "result": { "kind": "number",
            "value": 6 },
          "nodes": [..., {
            "mode": "FUNCTION",
            "funcSpec": {
              "id": "fg.multiply" },
            "funcArgs": [
              { "key": "width" },
              { "key": "height" }] }]
        }
    }}
  ]}, ...]
}

FormulaSheet

The source object becomes a review sheet

FormulaSheet receives a sheet model derived from CalculationSourceObject. Its columns show descriptions, symbols, values, units and comments, with formula and substitution details. This mathematical projection omits figures and standalone prose; rendering does not verify supplied values.

Mathematical sheet rendering

tsx

import {
  parseCalculationSourceJson,
  createSheetFromCalculationSourceObject,
} from '@viktar-b/cso-core';
import { FormulaSheet } from '@viktar-b/cso-react';
import '@viktar-b/cso-react/style.css';

export function CalculationSheet({ json }: { json: unknown }) {
  const source = parseCalculationSourceJson(json);
  const calculation = createSheetFromCalculationSourceObject(source, {
    id: 'calculation-sheet',
    label: source.title,
  });
  return <FormulaSheet sheet={calculation.sheet} />;
}

Prepared documents

Preserve ordered engineering content

prepareExecutionDocument binds supplied execution and captured assets to a PreparedDocument. PreparedFormulaSheet displays its ordered inputs, formulas, prose, figures and results. The host captures assets; React does not fetch files or execute Python. The example checks consistency without supplying an independent reference case, so it establishes no independent agreement.

Prepare a supplied execution

tsx

import {
  type ExecutionPayload,
  type ResolvedAsset,
  verifyExecution,
} from '@viktar-b/cso-core';
import {
  prepareExecutionDocument,
  PreparedFormulaSheet,
} from '@viktar-b/cso-react';
import '@viktar-b/cso-react/style.css';

// The host supplies captured execution and validated assets.
export function ExecutionDocument({ execution, assets }: {
  execution: ExecutionPayload;
  assets: readonly ResolvedAsset[];
}) {
  const report = verifyExecution({ execution });
  if (!report.ok) throw new Error('Execution verification failed');
  const document = prepareExecutionDocument({ execution, assets });
  return <PreparedFormulaSheet document={document} />;
}

Printing and checks

Browser print and verified PDF publication

printFormulaSheet is development browser printing. Its boolean result means the print request was accepted; deferred failures use onError. It does not run verification or publish CLI evidence. cso pdf verifies a captured execution and uses that same execution for document preparation and PDF publication, with evidence by default.

Optional independent references compare separately established expected values bound to the source, function and resolved inputs. No matching case means not applicable, not a pass. Document preservation accounts for every input, formula, explanation, figure, unit and result. Inspect every PDF page for missing content, notation, clipping and pagination, and bind findings to the exact PDF bytes. Generation leaves inspection pending and establishes no human engineering approval.

Python code generation

Generate source from a validated sheet

Core createPythonFromSheetDocument orders assignments by dependency and generates Python. It does not execute or verify the generated code. C# and TypeScript export and package-manager hosting remain planned.

Core code generation

tsx

import {
  type SheetDocument,
  createPythonFromSheetDocument,
} from '@viktar-b/cso-core';

export function generatePython(sheet: SheetDocument) {
  return createPythonFromSheetDocument(sheet);
}

MathML notation

FormulaSheet renders notation with native MathML

Glyphs and units pass through the ASCII math parser, value-tree functions pass through structured renderers, and the row output uses MathML elements for notation that remains inspectable in HTML.

Rendered notation

A_{rect} = w_{pan} h_{pan}

MathML output

html

<math display="block">
  <mrow>
    <msub>
      <mi>A</mi>
      <mi>rect</mi>
    </msub>
    <mo>=</mo>
    <msub><mi>w</mi><mi>pan</mi></msub>
    <msub><mi>h</mi><mi>pan</mi></msub>
  </mrow>
</math>