# Measurement Contract
#
# First-class treatment of subjective and objective measures on the site.
# This contract makes the % operator's dual nature (and similar measurement
# patterns) explicit, queryable, and consistently implemented.

#>measurement_contract
#:convention #!measurement #!operators
#:layer #!pragmatics

@operator_site_projection: ~"./operator-site-projection.spw#measure_operator"
@attention_field: ~"./attention-field.spw"
@planning_ecology: ~"./planning-ecology.spw#operational_semantics_template"
@workbench_claims: ~"../_workbench/.spw/harness/claim-protocol.spw"
@designer_conversation: ~"./designer-conversation-canvas.spw"
@pretext_measurement_bus: ~"../../public/js/semantic/pretext-measurement-bus.js"

^"core_distinction"{
  objective: .{
    definition: "Measurements produced by instrumentation, plugins, runtime counters, or deterministic calculation."
    capture: "Workbench plugins, performance observers, math libraries, audit scripts."
    data_attributes: #[`data-spw-measure-kind="objective"`, `data-spw-measure-source`, `data-spw-measure-scale`, `data-spw-measure-unit`][reg=set]
    examples: "divergence at a point, approximation error, layout shift, repaint cost, parse time"
  }[reg=facet]

  subjective: .{
    definition: "Measurements produced by practitioner judgment, felt state, or annotated evaluation."
    capture: "Annotation layers, cauldron captures, wonder notes, charge annotations, explicit % judgments during practice or review."
    data_attributes: #[`data-spw-measure-kind="subjective"`, `data-spw-measure-source` (usually includes practitioner/context), `data-spw-measure-scale`][reg=set]
    examples: "felt resonance intensity, wonder quality of a frame, perceived stability of an approximation, deviation salience"
  }[reg=facet]
}

^"integration_rules"{
  both_kinds_must_be_queryable: "Objective and subjective measures of the same underlying phenomenon should be discoverable together (via design catalog, state inspector, or future query surfaces) while remaining distinguishable by kind."
  field_participation: "Both kinds of measures should be able to contribute to the attention field when they represent attentional or resonance phenomena."
  export_together: "Proof artifacts, tending notes, and slice exports should be able to carry mixed objective + subjective % measures without loss of provenance."
}

^"workbench_responsibilities"{
  objective_capture: "Provide plugins and instrumentation surfaces that can emit well-formed objective % measures with full source and unit information."
  subjective_capture: "Provide annotation, cauldron, and claim surfaces that allow practitioners to record subjective judgments as first-class % measures (with kind, source/context, and scale)."
  cross_kind_comparison: "Support side-by-side viewing and analysis of objective and subjective measures of related phenomena."
}

^"claims"{
  measurement_kind_is_declared: {
    claim_id: "measurement-kind-001"
    layer: "pragmatic"
    hypothesis: "Every visible or exported measurement that participates in the % / measure pattern must declare its kind (subjective or objective) via data-spw-measure-kind."
    spec_ref: ".spw/conventions/measurement-contract.spw"
    impl_ref: "Any element or artifact carrying measurement data (labs, ornaments, proof cards, exports)"
    probe_ref: "Design catalog or direct inspection can distinguish subjective from objective measures on any surface that uses them."
    falsification: "A numeric or scaled value appears in a measurement context without a declared kind."
    status: "active"
  }

  subjective_measures_are_capturable: {
    claim_id: "measurement-subjective-capture-001"
    layer: "semantic"
    hypothesis: "Practitioner subjective judgments about attention, wonder, resonance, or stability must be capturable as durable, queryable % measures using workbench tooling."
    spec_ref: ".spw/conventions/measurement-contract.spw + operator-site-projection.spw#measure_operator"
    impl_ref: "annotation layers, cauldron, claim protocol surfaces"
    probe_ref: "A human can record a subjective % judgment during practice or review; it appears with proper kind, source, and scale alongside objective measurements."
    falsification: "Important subjective evaluations remain only in prose or private notes and cannot be captured or compared using the measurement machinery."
    status: "active"
  }
}[reg=facet]

validation: #[
  `Any new measurement surface must declare data-spw-measure-kind on relevant elements.`
  `Workbench plugins and annotation surfaces must be able to produce well-formed measures of both kinds.`
  `Design catalog and state inspection surfaces can surface and filter by measure kind.`
][reg=set]