mova-contract-spec

mova-contract-spec defines how MOVA language entities are assembled into an executable contract package. This repository is the source of truth for the contract package canon.

Boundary:

• mova-spec = language and semantic building blocks
• mova-contract-spec = contract package canon and composition rules
• runtime / platform repos = execution, admission, access, verification, audit

This repository is intentionally narrow. It specifies:

• the canonical composition of an executable contract package
• the authoring -> classification -> contract -> runtime binding pipeline
• the minimal entities required for executability
• a reference package on invoice flow
• the boundary to MOVA State 1.5 without copying runtime code

This repository does not include:

• Engine 1.5 runtime code
• API, SDK, billing, dashboard, marketplace logic
• general AI framework abstractions

Package Layers

1. Authoring layer
   • ds.step_classification_policy_v0
   • ds.step_classification_option_set_v0
   • ds.step_classification_result_v0
2. Contract structure layer
   • ds.contract_step_v0
   • ds.contract_flow_v0
3. Runtime binding layer
   • env.runtime_execution_binding_v0
   • env.runtime_binding_set_v0
4. Package layer
   • package.contract_package_manifest_v0

Frozen Standard

Mandatory core

• manifest.json
• flow.json
• classification_results.json
• runtime_binding_set.json
• models/input_model_v0.json
• models/verification_model_v0.json
• README.md

Mandatory but support-level

• classification_policy.json

Conditional mandatory

• checks/ when any executable step uses binding_kind = "esm_function"

Optional

• option_sets.json
• fixtures/
• execution_note.md
• additional diagrams or notes

Deprecated legacy equivalents

• source_contract_package_v0.json
• runtime_manifest_v0.json
• policy_calibration_v0.json

Repository Layout

• docs/CONTRACT_PACKAGE_CANON_v0.md
• docs/LAYER_MODEL_v0.md
• docs/AUTHORING_TO_RUNTIME_MODEL_v0.md
• schemas
• policies/mova.step_classification_policy_v0.json
• examples/invoice_processing_v0

Core Invariants

1. A contract step without classification is invalid.
2. An executable step without runtime binding is invalid.
3. classification.execution_mode must equal binding.execution_mode.
4. Runtime does not choose step type; it executes already classified step type.
5. AI_ATOMIC cannot make final business decisions.
6. External calls must not hide decision logic.
7. DS layer does not depend on ENV layer.
8. PACKAGE layer binds DS and ENV without changing DS semantics.
9. A DETERMINISTIC step using esm_function must resolve to a package-local .mjs file under checks/.

Canon Sources

Source A:

• mova_contract_runtime_package_v0.zip
• provides the base schemas, package skeleton, and invoice example

Source B:

• mova-state-1.5
• provides package discipline, executable-form canon, and strict runtime boundary

mova-state-1.5 is used here as a source of package discipline and runtime boundary, not as the package canon. If older State 1.5 package artifacts differ from this repository, they are legacy forms to be aligned later.

The active rule inherited from State 1.5 is simple:

• calibrated intent is not directly executable
• candidate contract must be shaped into a package
• package must be validated and bound before runtime executes it

Canonical Reference Rules

• anything under examples must conform to this repository canon
• package-local refs are formalized:
  • classification://<step_id>
  • binding://<step_id>
• the only canonical manifest name is package.contract_package_manifest_v0
• the canonical package-local deterministic rule surface is checks/*.mjs
• canonical runtime binding kinds are:
  • esm_function
  • internal_handler
  • mcp_tool
  • human_gate_channel