API: Contracts

Contract generation and serialization.

Contract generation and serialization utilities.

This module is responsible for: - Creating a blank narrative contract from a parsed Novel. - Serializing that contract to YAML. - Loading a contract back from YAML.

The contract is the executable specification of narrative intent.

contract_from_novel

contract_from_novel(novel)

Build a blank narrative contract from a parsed Novel.

Each module in the novel becomes a ModuleContract with: - structural metadata - text anchors - empty reader states - no declared expectations

The resulting contract is syntactically complete but semantically empty. It is intended to be filled either manually or by an inference engine.

:param novel: Parsed Novel object. :return: List of ModuleContract instances.

dump_contract_yaml

dump_contract_yaml(contracts, *, source=None)

Serialize a list of ModuleContract objects to YAML.

The YAML output is the canonical external representation of a narrative contract. It is both human-editable and machine-consumable.

Optionally embeds source provenance metadata so that: - The exact Markdown input can be identified - Contract drift can be detected - Reproducibility is preserved

:param contracts: List of ModuleContract entries. :param source: Optional source metadata dictionary (fingerprint, paths, timestamps). :return: YAML string.

load_contract_yaml

load_contract_yaml(text)

Load ModuleContract objects from YAML text.

The YAML must define a top-level modules list, where each entry corresponds to one ModuleContract specification.

The expected_changes field is always normalized to List[str], even if missing or null in the source YAML.

:param text: YAML string. :return: List of ModuleContract entries.

This module creates the specification that everything else operates on.
The contract is the system.

Assessment Engine

Rule-based narrative validation.

Module contract assessment engine.

This module evaluates narrative module contracts using a configurable set of rule objects. Each rule inspects a ModuleContract and may emit a Finding describing a structural problem in the narrative.

The assessment process mirrors a unit-test runner: - Each module is evaluated independently. - Findings are collected. - A severity (PASS, WARN, FAIL) is assigned.

ModuleReport dataclass

Report describing the assessment outcome of a single narrative module.

:param module_id: Unique identifier of the module. :param title: Title of the module. :param chapter: Chapter in which the module appears. :param severity: Overall severity (PASS, WARN, FAIL). :param findings: List of findings emitted by rule evaluation.

assess_contract

assess_contract(contracts, rules=None)

Assess a sequence of ModuleContracts using a set of narrative rules.

Each module is evaluated independently. The resulting ModuleReport aggregates all findings and determines the highest severity:

• FAIL if any rule emits a FAIL finding
• WARN if no FAIL but at least one WARN
• PASS otherwise

:param contracts: Sequence of ModuleContract objects to assess. :param rules: Optional sequence of Rule objects. If not provided, the default rule set is used. :return: List of ModuleReport entries.

report_to_json

report_to_json(reports)

Serialize assessment reports to JSON.

All Findings are converted to plain dictionaries so the output is fully JSON serializable.

Narrative contract assessment rules.

Each Rule inspects a ModuleContract and optionally emits a Finding. Findings describe structural problems in narrative execution.

Rules are intentionally small, isolated, and composable.

Finding dataclass

A single assessment result emitted by a Rule.

:param rule: Name of the rule that emitted this finding. :param severity: PASS, WARN, or FAIL. :param message: Human-readable explanation.

MissingExpectedChangeRule

Warn when no narrative intent has been declared.

expected_changes is how the author declares what the passage is supposed to do.

NoChangeRule

Fail if expected changes are declared but: - state is missing, or - state exists but does not change.

Rule

Bases: Protocol

Protocol for all contract assessment rules.

Every rule must define: - a human-readable name - an evaluate() method returning an optional Finding

evaluate

evaluate(contract)

Evaluate a ModuleContract.

:param contract: ModuleContract to evaluate. :return: Finding if rule is violated, otherwise None.

UnspecifiedStateRule

Warn when no reader-state information has been provided.

Without state information, no meaningful narrative assessment is possible.

This is where narrative intent becomes falsifiable.
All future intelligence lives here.

Design Contract

This API reference is not documentation theater.

It is:

• mechanically generated
• version-controlled
• always consistent with the code

If the API changes, this page changes.
If this page is wrong, the code is wrong.