Contract version 1

Lab Contract reference

A Lab Contract is small JSON guidance embedded in a lab. Its reader is a person or model adapting the learning experience. The core describes learning; an optional implementation map records how the current lab realises it. Neither is a contribution specification or runtime API.

Purpose

State the relationship that makes the lab educationally useful, then describe the learner’s loop: what they do, what changes, what evidence they receive, and what they decide next. This is the minimum information an adaptation should understand before changing the file.

Keep the core learning statements conceptual. “Changing the clock advances one CPU micro-operation and exposes its effect” describes the relationship. Put revision-specific selectors and mechanics in the optional implementation map.

Authoring sidecar

Author the contract once at lab-contracts/<subject>/<slug>.lab.json. Do not copy it into lab.html; the publication compiler owns the embedded block.

{
  "schemaVersion": 1,
  "relationship": "…",
  "learnerLoop": {
    "action": "…",
    "modelChange": "…",
    "evidence": "…",
    "nextDecision": "…"
  },
  "invariants": ["…"],
  "safeAdaptations": ["…"]
}

Field	Status	Use
`schemaVersion`	Required	Sidecar format version. Version 1 is the only supported value.
`relationship`	Required	The learning relationship between learner action, the model, and resulting understanding.
`learnerLoop`	Required	Four short statements: action, modelChange, evidence, and nextDecision.
`invariants`	Optional	Learning properties worth preserving. Keep them conceptual, not tied to DOM structure.
`safeAdaptations`	Optional	Changes that can vary while retaining the learning relationship.
`nonGoals`	Optional	Nearby scope the lab deliberately does not teach.
`implementation`	Optional	Revision-bound map of current surfaces, quantities, input slots, modes and completion dependencies.
`curriculum`	Optional	Profiles and feature IDs only when one lab genuinely varies by curriculum.
`developerGuide`	Optional	Canonical link to this reference.

Unknown top-level fields are allowed in version 1 so the format can learn from real adaptations. When an optional field is present, its documented shape is validated. See the JSON Schema for the machine-readable form.

Lifecycle and validation

lab-contracts/<subject>/<slug>.lab.json (authoritative)
          | validate + compile
          v
generated LAB_CONTRACT block in public/labs HTML
          | package download
          v
contract preserved in standalone HTML

npm run labs:contract:check verifies that each published lab has one valid contract and that its meaning is unchanged in the compiled and standalone artifacts. The embedded JSON escapes unsafe script text but parses back to the sidecar value. This catalogue-wide check also runs during labs:sync:check.

Semantic locators

A few data-lab-* attributes let an adapting model locate educationally meaningful parts of the HTML. They are annotations, not a runtime API.

data-lab-role: model, working, or evidence.
data-lab-action="reset": The control that restores the initial lab state.
data-lab-manipulative: Optional stable ID for a direct-manipulation surface.
data-lab-feature: Optional stable ID connecting a surface to a declared curriculum feature.

Labs mark meaningful model, working, and evidence surfaces, with reset and manipulative locators where applicable. These annotations preserve existing behaviour and do not add runtime controls.

Optional implementation map

Record what the inspected source actually implements. The map does not establish exam alignment, prescribe a redesign, or add controls. reviewedRevision identifies the inspected Git revision; update the map when the corresponding behaviour changes.

surfaces: Stable names for coherent task, model, working, input, evidence and completion areas. Each has selectors, a kind, a description and visibility conditions.
quantities: Mathematical or domain quantities with description, domain and units, source, and output conditions. Optional inputSlots locate physical controls; several boxes can compose one answer, and one box can hold several values.
modes: Current settings and the actual differences in supplied working, learner entries and evidence. Record when None/Some/All is absent.
dependencies / completion: What must happen before later evidence, inputs or progression become available, and what the implementation accepts as completion.
limitations: Optional caveats about heuristics, conditional controls and unresolved interpretation.

Prefer existing IDs and stable data attributes. Selectors may identify controls generated only in a later state; describe that condition instead of assuming every selector matches at startup. Use ordinary role annotations for structure. Reserve data-lab-feature for declared curriculum features. The compiler preserves the map in standalone downloads alongside the core.

Optional curriculum envelope

Use curriculum only when one lab contains meaningful syllabus-dependent capabilities. A feature names a teaching capability. A profile records syllabus and qualification alignment, enables declared feature IDs, and may carry subject-specific parameters. Curriculum determines the permitted content; cases and difficulty vary the challenge within that content; assistance changes the scaffolding and supplied working. Making a case harder does not introduce content from another curriculum.

Binary Number Practice uses its contract profiles to select the existing IGCSE and AS question features. Its question-range and help controls remain separate from curriculum selection. Other labs may have their own modes; there is no shared profile-selection runtime API yet.

Publication checks verify profile syllabus references against the catalogue and validate declared feature references. They do not establish that a feature teaches a syllabus objective correctly. That requires source review and behavioural verification.