Recording, serialization, and replay

The declarative workflow records public compatibility operations in a GraphSession. It preserves more state than the compact native Graph, including typed operation nodes, result roots, semantic data, and external-source information.

@model

import cadflow as cad

@cad.model(graph_id="bracket")
def bracket(width: float, height: float):
    base = cad.make_box_rsolid(width, 30.0, 4.0)
    rib = cad.make_box_rsolid(4.0, 30.0, height)
    return cad.union_rsolid(base, rib)

result = bracket(60.0, 25.0)
shape = result.value
model_json = result.model_json

The decorator owns one graph session per invocation, records returned graph-backed values as result nodes, and returns ModelResult. export_dir additionally writes configured artifacts and exposes their paths in artifact_paths.

ModelResult

Field	Meaning
value	Original function return value
session	Completed recording session
result_node_ids	Explicit terminal graph roots
model_json	Portable model document
session_json	Session-oriented diagnostic document
artifact_paths	Files written by the decorator

The function return determines graph roots. Return every result that must remain reachable; intermediate nodes may be omitted by canonical export rules.

Export and import

export_model_json(session, indent=2, result_node_ids=None) serializes a canonical model document. import_model_json(json_str) parses and validates the document into structured data. Graph/session JSON helpers serve lower-level tooling and should not be substituted when a complete model contract is required.

Model JSON stores operations and dependencies, not arbitrary executable Python. Imported source files and external resources remain explicit dependencies and must be made available under the expected policy.

Strict replay

values = cad.replay_model_json(model_json, strict=True)

Strict replay rejects unsupported operations, invalid schema state, non-canonical dependencies, graph ownership errors, and other contract violations. Non-strict replay is useful for controlled inspection or migration but must not silently become the release default.

Replay success means the graph executed. For equivalence claims, compare terminal geometry, topology, dimensions, semantic assignments, and exported artifact metadata against expected evidence.

Determinism rules

• Give graphs, parts, components, connectors, and semantic entities stable IDs.
• Pass explicit parameters instead of relying on ambient state.
• Keep source resources addressable and hash them when reproducibility matters.
• Record CadFlow version and capability data with delivered artifacts.
• Canonicalize JSON only through public serialization helpers.
• Validate and bound untrusted input before replay.

The exhaustive functions and graph data types are in the graph/replay catalog.