Home /Modules/impl/SST.SUBJECT.md

SST.SUBJECT.md

impl/nordshrift/SST.SUBJECT.md · 130 line(s) · markdown

.sst Semantic Subject Support โ€” NS-SST-SUB-0001

Nordshrift 2.0 .sst sheets have a first-class subject declaration block. A subject makes the semantic meaning of a computation explicit: what is modeled, in what units, under what assumptions, by what relation, with what provenance, and how completion will be validated. It fills a nordshrift::semantic::Subject (see subject_model.h) and is parsed by the same indentation-aware NS-SST parser as every other section.

A subject is metadata, not a program. It carries the semantic layer shared by the Math, Physics, Economics, Chemistry, and Financial libraries so a numeric result is not silently promoted to an empirical fact.

Canonical chain

Subject -> Quantity -> Unit -> Assumption -> Relation -> Formula ->
Transformation -> Result -> ComparativeNorm -> Evidence -> Explanation ->
Validation

Grammar

A subject is subject <Identity>: followed by scalar keys and repeatable nested blocks:

subject ProjectileRange:
  domain: physics
  depends: [ math ]

  quantity range:
    value:     "v0^2 * sin(2*theta) / g"
    unit:      meter
    dimension: length
    domain:    "0 <= theta <= pi/2"
    status:    modeled

  assumption noDrag:
    statement: "air resistance is neglected"
    scope:     "low-speed, short-range trajectories"
    source:    "modeling choice"
    status:    assumed

  relation rangeFormula:
    formula: "R = v0^2 * sin(2*theta) / g"
    inputs:  [ v0, theta, g ]
    outputs: [ range ]

  transformation deriveRange:
    source:      rangeFormula
    operation:   "evaluate at theta = 45deg"
    parameters:  "theta=pi/4"
    destination: range
    approximate: false

  comparison:
    prior:     ProjectileRangeVacuumBaseline
    current:   ProjectileRange
    reference: ProjectileRangeVacuumBaseline
    norm:      "ratio of modeled range to ideal vacuum range"

  evidence:
    status: modeled
    source: "closed-form kinematics under the noDrag assumption"
    note:   "result is a model output, not a measurement"

  explanation:
    subject: ProjectileRange
    steps: [ "identify subject and domain", "apply the range relation" ]

  todo validateAgainstMeasurement:
    priority:      1
    depends:       [ ProjectileRange ]
    preconditions: "a measured trajectory data set is available"
    action:        "compare modeled range to observed range"
    expected:      "relative error within stated tolerance"
    validation:    "residual analysis over the data set"
    status:        planned

Nested blocks (quantity, assumption, relation, transformation, comparison, evidence, explanation, todo) may each appear any number of times. quantity, assumption, relation, transformation, explanation, and todo accept an optional identity/name before the :; comparison and evidence are nameless.

Evidence status

A status records epistemic provenance and must be one of:

observed, specified, derived, modeled, inferred, assumed.

Unknown values are rejected with NSS-E-SUB-002.

Work status

A todo status must be one of:

planned, ready, active, blocked, validating, complete, deferred.

Unknown values are rejected with NSS-E-SUB-003.

Validation

nordshrift check prints each declared subject, its collection counts, and its canonical chain, and applies two provenance checks (warnings, so a subject sheet remains valid):

Build effect

On nordshrift build, declared subjects (alongside any network: / finance: series) are emitted into a component manifest artifact for the selected target. See SST.NETWORK.md and SST.FINANCE.md.

Diagnostics summary

CodeMeaning
NSS-E-SUB-001subject block without an identity
NSS-E-SUB-002unknown evidence status
NSS-E-SUB-003unknown work status
NSS-W-SUB-010dependency on an undeclared subject
NSS-W-SUB-011modeled/inferred/derived quantity without supporting provenance