Scientific Model Extension Contract

Status: current reference extension contract
Scope: provider selection, typed scientific decisions, validation, provenance, and commit authority

Stable Boundary

flowchart LR
    OP["validated operation contract"] --> Author{"authored decision?"}
    Author -->|"yes"| Decision["typed decision"]
    Author -->|"no"| Selection["provider selection"]
    Selection --> Provider["selected provider"]
    Provider --> Result["typed proposed decision + provenance"]
    Result --> Validate["kernel validation"]
    Validate --> Decision
    Decision --> Candidate["candidate material state"]
    Candidate --> CommitValidate["conservation + state + capacity"]
    CommitValidate --> Commit["atomic commit"]

Boundary	Owns	Must not own
Operation contract	Program kind, declared arguments, output roles, effect kind	Scientific resolution
Provider selection	Capability binding and selected-provider identity	Scientific rules, state mutation
Provider	Typed proposed decision, assumptions, uncertainty, provenance	Runtime scheduling, candidate commit
Result validator	Request membership, result shape, bounds, allowed effects	Scientific inference
Candidate validator	State validity, quantities, conservation, capacity	Provider selection
Commit	Authoritative material-state mutation	Scientific inference

Extension Units

Unit	Stable identity	Versioned contract
Capability	capability	Request payload + result schema
Provider	provider_id	Supported capability versions + behavior specification
Binding	capability → provider	Run configuration + provenance
Composite provider	one provider_id	Internal chain/fallback/ensemble policy

Capability Contract

Required field	Rule
capability	Globally stable semantic name
contract_version	Version of typed request/result schema
lifecycle	Decision point such as runtime_precommit; request and selected capability declaration must match exactly before provider invocation
Request schema	Immutable semantic facts only
Result schema	Closed typed decisions only
Validation	Kernel-enforced acceptance conditions
Unresolved behavior	not_applicable, failed, or capability-specific UNRESOLVED

Current material capabilities:

Capability	Contract	Decision
material.separation_fate	1.0	Per-component output fractions
material.state_transition	1.0	Per-component next relationship/state

Provider Contract

Required declaration	Rule
provider_id	Stable provider identity
provider_version	Recorded with every accepted decision
Supported capabilities	Exact capability + contract-version pairs
Determinism	Declared deterministic behavior or runtime-provided seed policy
Assumptions	Explicit structured facts; no hidden source-name inference
Uncertainty	Typed when produced
Failure	Returned as provider status; never committed directly
State access	Immutable request only; no runtime state or commit handle

Request Record

request {
  request_id,
  capability,
  contract_version,
  lifecycle,
  seed?,
  payload
}

Result Record

result {
  status: resolved | not_applicable | failed,
  proposed_decision?,
  provenance,
  assumptions,
  uncertainty?,
  diagnostics
}

rejected is a kernel validation result, not a provider status.

Provider Selection

flowchart TD
    Request["capability request"] --> Binding{"explicit custom binding?"}
    Binding -->|"no"| Builtin["official built-in provider"]
    Binding -->|"yes"| Custom["external or composite provider"]
    Builtin --> Response["one provider response"]
    Custom --> Response
    Response --> Record["record provider ID + version + configuration"]

Rule	Required behavior
Default material binding	Official built-in Rulebook provider
External provider	Explicitly replaces the default binding
Fallback	Implemented by an explicitly selected composite provider
Implicit provider chain	Forbidden
Environment-dependent discovery	Forbidden in the semantic execution path
Run reproduction	Provider identity, version, binding, and decision provenance recorded

Built-in Provider

Provider	Capabilities	Specification
culsma.builtin.material_rulebook	material.separation_fate, material.state_transition	Built-in Material Separation Rulebook

The built-in provider uses the same extension contract and result validation as an external provider. Its default status does not grant state-mutation or validation bypass authority.

Provider-Specification Form

Provider specification
├── identity and version
├── supported capability contracts
├── closed input vocabulary
├── decision tables or model definition
├── unresolved outcomes
├── provenance requirements
└── conformance cases

Reference Change Boundary

Change	Required Reference edit
Add provider for an existing capability	Add independent provider specification
Update provider rules without changing capability schema	Update that provider specification
Replace default provider binding	Update extension binding declaration + compatibility note
Add capability	Add capability contract + conformance mapping
Change request/result schema	Version capability contract + conformance mapping
Change kernel validation or commit authority	Update core operational semantics

Provider additions and provider-internal rule changes do not require edits to core Reference chapters while the stable capability and kernel boundaries remain unchanged.

Kernel Invariants

Invariant	Required
Author decision validated before use	Yes
Provider result validated before candidate construction	Yes
Provider receives mutable runtime state	No
Provider commits material state	No
Unknown result silently becomes an equal split	No
Unconfigured fallback provider executes implicitly	No
Accepted provider decision records provenance	Yes
Decision provenance differs from its result envelope	Reject before candidate construction
Invalid candidate mutates committed state	No