jBOKResearch compendium
Work in developmentPublic revision

Draft contract concepts

These concepts organize the information that simulations, models, agents, and their reviewers may need to exchange. They are a developing vocabulary for implementation and evaluation, not a finished interoperability standard.

The original public overview reported five schema-backed seed families at v0.1.0, with security reserved as a sixth family. This revision clarifies that overview. The supporting repository schemas, fixtures, and test runs are maintained privately and are not provided here as an independently executable public verification package. No new conformance result is claimed in this release.

The compendium explains the reasoning, sources, alternatives, and limits behind the recommendations. These draft contracts explore how selected recommendations might become explicit records and checks.

Proposed families

Each family groups related obligations. A family name does not establish that implementations can exchange its records correctly, enforce its policies, or agree on their meaning. Those properties require versioned definitions and tests across implementations.

Family Information the concept is intended to capture Principal limitation
Agent Identity, role, authority, tools, supervision, and evidence duties A declared authority boundary does not enforce itself.
Model Intended use, units, assumptions, numerical methods, provenance, validation, and uncertainty A complete description does not establish physical fidelity or suitability.
Trust A bounded claim, its supporting evidence, review, and re-review conditions A record does not grant universal trust or substitute for an accountable decision.
Evidence graph Links among artifacts, activities, assumptions, decisions, and reviews Traceability does not establish that the linked evidence is sound.
Ontology and semantics Shared terms and relationships Vocabulary alignment does not define an executable protocol.
Security Access, authorization, confidentiality, integrity, and boundary obligations Reserved; no security-family schema is offered by this public overview.

Seed concepts

Agent contracts

An agent record is intended to declare identity, role, owner or steward, authority boundary, supervision model, permitted tools and data sources, inputs and outputs, evidence obligations, dependencies, policy constraints, escalation behavior, and monitoring requirements. Specialized profiles can constrain a role without creating a new family.

The distinction between a written charter and an enforced boundary matters. Runtime monitoring, escalation, and enforcement need explicit implementations and evidence. See ADR-0010.

Model contracts

A model record is intended to declare identity, scope, context of use, units, assumptions, dependencies, numerical methods, parameter origins, provenance completeness, validation evidence, uncertainty characterization, limitations, and revalidation triggers.

Missing parameter declarations should remain visible. Classification as measured, derived, calibrated, or assumed describes an asserted origin; it does not independently verify that origin. See ADR-0006.

Trust contracts

A trust record is intended to state a bounded claim about a capability, model, agent, workflow, evidence package, or decision. It links that claim to a context of use, verification and validation evidence, uncertainty, review scope, authority boundary, monitoring requirements, expiration or re-review triggers, and known limitations.

Here, “trust” means a reasoned judgment for a stated purpose. It is not a general score attached to a model. The historical use of “accreditation” describes a proposed review and acceptance process; it does not imply certification by an external institution.

Evidence graph

An evidence graph is intended to connect evidence artifacts, provenance, assumptions, models, agents, simulation runs, decisions, review actions, accreditation records, and trust claims. The v0.1.0 overview described recognition reports using existing evidence-artifact, agent, uncertainty-statement, and review-action vocabulary.

A useful graph lets a reader follow a claim to its support and identify missing links. Establishing artifact integrity, authentic authorship, or adequate scientific support requires additional checks. See ADR-0011.

Ontology and semantic contracts

The proposed shared vocabulary includes capability, agent, model, simulation, evidence artifact, trust claim, accreditation boundary, context of use, assumption, uncertainty statement, decision option, human authority boundary, interface contract, and recognition terms.

These concepts should support communication without requiring a single implementation technology. They do not yet establish a portable simulation-step API, plugin lifecycle, orchestration protocol, or replay format. The historical JWM mapping explicitly records several such gaps.

Security contracts: reserved

The sixth family is reserved for explicit access-control, authorization, confidentiality, integrity, and boundary obligations. The published overview contains no schema for this family. Reserving a family does not establish that the other contracts provide a complete security design. See ADR-0005.

Versioning and schema conventions

The original overview described the following project conventions. They remain draft design commitments here, rather than a promise of publicly available release assets:

Changing the wording of this overview does not revise a versioned schema or adopt a new normative requirement. Such changes require an explicit specification revision and recorded compatibility impact.

Conformance: scope and public evidence

The August 1, 2026 public snapshot reported the following repository test inventory. It is preserved as a dated, author-reported description, not a newly executed result or an independent assessment.

Seed family Reported version Reported schemas Reported tests
Agent contracts 0.1.0 1 13
Evidence graph 0.1.0 1 8
Model contracts 0.1.0 1 6
Ontology 0.1.0 1 4
Trust contracts 0.1.0 1 5
Total 5 36

That snapshot stated that CI validated schema documents, ran versioned family tests, accepted valid fixtures, rejected invalid fixtures for documented reasons, and failed on invalid schemas, unexpected fixture results, MUST-rule failures, or record/schema-version mismatches. Those statements are not independently reproducible from this page because the corresponding runnable artifacts and logs are not part of this public release.

Even a passing structural test establishes only the behavior it exercises. It does not establish physical accuracy, adequate uncertainty analysis, successful policy learning, or useful interchange between independently developed implementations.

A future public conformance package should include pinned schemas, a standalone runner, valid and invalid examples, expected outputs, and explicit limits. Broader claims will need tests of actual exchange or substitution between independent implementations. These are planned evidence requirements, not completed work. The research agenda sets out the proposed evaluations.