###########################################################################

#

# SSTIM SHACL Shapes — sstim-shapes.ttl

#

# Namespace: https://w3id.org/sstim/shapes#

# Version: 0.17.0-dev

# Date: 2026-08-18

# Author: Renato Fabbri <renato@junto.space>

# License: CC BY 4.0

#

# SHACL validation shapes for presets, evidence claims, session

# specifications, and voice specifications. The pre-commit hook and

# the export pipeline run these shapes before any preset is committed

# or exported to dist/presets.json.

#

# Protected file — do not modify without explicit maintainer instruction.

#

###########################################################################

@prefix sstim: <https://w3id.org/sstim#> .

@prefix sstim-v: <https://w3id.org/sstim/vocab#> .

@prefix sstim-sh: <https://w3id.org/sstim/shapes#> .

@prefix sstim-ex: <https://w3id.org/sstim/exposure#> .

@prefix sstim-eco: <https://w3id.org/sstim/ecosystem#> .

@prefix owl: <http://www.w3.org/2002/07/owl#> .

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

@prefix sh: <http://www.w3.org/ns/shacl#> .

@prefix dct: <http://purl.org/dc/terms/> .

@prefix prov: <http://www.w3.org/ns/prov#> .

@prefix foaf: <http://xmlns.com/foaf/0.1/> .

@prefix schema: <https://schema.org/> .

@prefix org: <http://www.w3.org/ns/org#> .

###########################################################################

# Module metadata

###########################################################################

<https://w3id.org/sstim/shapes> a owl:Ontology ;

owl:versionInfo "0.17.0-dev" ;

dct:title "SSTIM SHACL Validation Shapes"@en ;

dct:description "SHACL Core and SHACL-SPARQL constraints for SSTIM ontology metadata, controlled vocabularies, presets, techniques, evidence claims, safety tags, exposure models, protocols, sessions, references, and qualified public ecosystem records."@en ;

dct:isPartOf <https://w3id.org/sstim> ;

dct:requires <https://w3id.org/sstim>, <https://w3id.org/sstim/common>, <https://w3id.org/sstim/configuration>, <https://w3id.org/sstim/ecosystem>, <https://w3id.org/sstim/evidence>, <https://w3id.org/sstim/exposure>, <https://w3id.org/sstim/neuromodulation>, <https://w3id.org/sstim/patch-studio>, <https://w3id.org/sstim/session>, <https://w3id.org/sstim/stimulus>, <https://w3id.org/sstim/technique>, <https://w3id.org/sstim/vocab> ;

dct:creator <https://orcid.org/0000-0002-9699-629X> ;

dct:publisher <https://github.com/laBioSynCare> ;

dct:created "2026-04-12"^^xsd:date ;

dct:issued "2026-08-18"^^xsd:date ;

dct:modified "2026-08-18"^^xsd:date ;

dct:license <https://creativecommons.org/licenses/by/4.0/> ;

rdfs:seeAlso <https://github.com/laBioSynCare/laBioSynCare.github.io/blob/main/docs/decisions/0031-qualified-ecosystem-records.md> .

###########################################################################

# Ontology module metadata shape

###########################################################################

sstim-sh:OntologyMetadataShape a sh:NodeShape ;

sh:targetClass owl:Ontology ;

sh:name "OWL ontology module metadata"@en ;

sh:property [

sh:path owl:versionInfo ; sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:string ;

sh:message "Every SSTIM ontology module must declare one owl:versionInfo value."@en ;

] ;

sh:property [

sh:path dct:title ; sh:minCount 1 ;

sh:message "Every SSTIM ontology module must declare dct:title."@en ;

] ;

sh:property [

sh:path dct:description ; sh:minCount 1 ;

sh:message "Every SSTIM ontology module must declare dct:description."@en ;

] ;

sh:property [

sh:path dct:creator ; sh:minCount 1 ; sh:nodeKind sh:IRI ;

sh:message "Every SSTIM ontology module must identify an IRI-valued dct:creator."@en ;

] ;

sh:property [

sh:path dct:publisher ; sh:minCount 1 ; sh:nodeKind sh:IRI ;

sh:message "Every SSTIM ontology module must identify an IRI-valued dct:publisher."@en ;

] ;

sh:property [

sh:path dct:created ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:date ;

sh:message "Every SSTIM ontology module must declare one xsd:date dct:created value."@en ;

] ;

sh:property [

sh:path dct:issued ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:date ;

sh:message "Every SSTIM ontology module must declare one xsd:date dct:issued value."@en ;

] ;

sh:property [

sh:path dct:modified ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:date ;

sh:message "Every SSTIM ontology module must declare one xsd:date dct:modified value."@en ;

] ;

sh:property [

sh:path dct:license ; sh:minCount 1 ; sh:nodeKind sh:IRI ;

sh:message "Every SSTIM ontology module must declare an IRI-valued dct:license."@en ;

] .

###########################################################################

# Preset Shape

###########################################################################

sstim-sh:BscCatalogPresetShape a sh:NodeShape ;

# Targets anything bearing a catalog-model predicate, rather than every

# sstim:Preset (ADR 0041): a configuration that uses the catalog vocabulary

# owes the catalog's curation metadata, and one that does not is not held to

# it. Several predicates rather than one, because targeting only

# sstim:composedOf would let a half-written catalog entry escape the profile

# by omitting its voices — the union closes that without needing SPARQL

# targets, which the browser validator does not implement, or a marker

# property on every published instance.

sh:targetSubjectsOf sstim:composedOf ;

sh:targetSubjectsOf sstim:inGroup ;

sh:targetSubjectsOf sstim:presetVersion ;

sh:targetSubjectsOf sstim:targetsFrequencyBand ;

sh:targetSubjectsOf sstim:hasBreathGuide ;

sh:name "BSC catalog preset"@en ;

sh:property [

sh:path rdfs:label ;

sh:minCount 1 ;

sh:datatype xsd:string ;

sh:message "Preset must have at least one rdfs:label."@en ;

] ;

sh:property [

sh:path dct:description ;

sh:minCount 1 ;

sh:message "Preset must have a dct:description with conservative scope and use context."@en ;

] ;

sh:property [

sh:path sstim:targetsFrequencyBand ;

sh:minCount 1 ;

sh:maxCount 2 ;

sh:class sstim:FrequencyBand ;

sh:message "Preset must target 1–2 frequency bands from sstim:FrequencyBand."@en ;

] ;

sh:property [

sh:path sstim:primaryFrequencyBand ;

sh:maxCount 1 ;

sh:class sstim:FrequencyBand ;

sh:message "primaryFrequencyBand, if present, must be a single sstim:FrequencyBand."@en ;

] ;

# RDF-08 (2026-07-24 audit): primaryFrequencyBand must be one of the

# preset's own targetsFrequencyBand values, not an unrelated band.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "primaryFrequencyBand must be one of the preset's own targetsFrequencyBand values."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#primaryFrequencyBand> ?primary .

FILTER NOT EXISTS {

$this <https://w3id.org/sstim#targetsFrequencyBand> ?primary .

}

}

""" ;

] ;

sh:property [

sh:path sstim:inGroup ;

sh:minCount 1 ;

sh:maxCount 1 ;

sh:class sstim:PresetGroup ;

sh:message "Preset must belong to exactly one group from sstim:PresetGroup."@en ;

] ;

sh:property [

sh:path sstim:hasBreathGuide ;

sh:minCount 1 ;

sh:maxCount 1 ;

sh:datatype xsd:boolean ;

sh:message "Preset must declare hasBreathGuide as a boolean."@en ;

] ;

sh:property [

sh:path sstim:presetVersion ;

sh:minCount 1 ;

sh:maxCount 1 ;

sh:datatype xsd:string ;

sh:pattern "^\\d+\\.\\d+\\.\\d+$" ;

sh:message "presetVersion must be a semantic version string X.Y.Z."@en ;

] ;

# KR-07: the class definition caps a preset at six voices and the format

# specification says 1-6, but nothing enforced the ceiling.

sh:property [

sh:path sstim:composedOf ;

sh:minCount 1 ; sh:maxCount 6 ;

sh:class sstim:Voice ;

sh:message "Preset must be composed of 1-6 Voices."@en ;

] ;

sh:property [

sh:path sstim:forImplementation ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:class sstim:SensoryStimulationImplementation ;

sh:message "Preset must identify exactly one implementation whose parameter model it configures."@en ;

] ;

sh:property [

sh:path sstim:followsProtocol ;

sh:minCount 1 ;

sh:class sstim:SensoryStimulationProtocol ;

sh:message "Preset must follow at least one declared sensory stimulation protocol."@en ;

] ;

sh:property [

sh:path sstim:hasPublicClaimLevel ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:class sstim:PublicClaimLevel ;

sh:message "Preset must declare exactly one public claim level."@en ;

] ;

# CLAUDE.md §4.5: hasBreathGuide is true iff exactly one composed voice is the

# breathing reference (isBreathReference = true); at most one voice may be.

# SHACL-SPARQL is required because the rule counts across the preset's voices —

# a per-voice property shape cannot express it. Full IRIs avoid an sh:prefixes

# block.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "hasBreathGuide must be true iff exactly one composed voice has isBreathReference=true (found {?n} breathing-reference voice(s) for hasBreathGuide={?guide})."@en ;

sh:select """

SELECT $this ?guide (COUNT(?v) AS ?n) WHERE {

$this <https://w3id.org/sstim#hasBreathGuide> ?guide .

OPTIONAL {

$this <https://w3id.org/sstim#composedOf> ?v .

?v <https://w3id.org/sstim#isBreathReference> true .

}

}

GROUP BY $this ?guide

HAVING ( ( ?guide && COUNT(?v) != 1 ) || ( !?guide && COUNT(?v) != 0 ) )

""" ;

] ;

# KR-07: the binaural beat frequency is |fl - fr| and the format

# specification caps it at 35 Hz, with one exception — exactly 40 Hz for a

# deliberate gamma-40 design, which must then declare gamma-40 as a target

# band. Neither the cap nor the exception was enforced, so a voice whose

# carriers were each individually legal could produce any beat at all.

#

# This has to be a preset-level constraint: the exception depends on the

# preset's targetsFrequencyBand, which the voice cannot see. It covers both

# carrier-pair subtypes, since both derive the beat the same way.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "Binaural beat frequency |fl - fr| must not exceed 35 Hz, unless it is exactly 40 Hz in a preset that declares gamma-40 as a target band."@en ;

sh:select """

SELECT $this ?beat WHERE {

$this <https://w3id.org/sstim#composedOf> ?voice .

?voice <https://w3id.org/sstim#carrierFreqLeft> ?fl ;

<https://w3id.org/sstim#carrierFreqRight> ?fr .

BIND( ABS( ?fl - ?fr ) AS ?beat )

FILTER( ?beat > 35 )

FILTER( ! ( ?beat = 40 && EXISTS {

$this <https://w3id.org/sstim#targetsFrequencyBand> <https://w3id.org/sstim/vocab#gamma40> .

} ) )

}

""" ;

] ;

# P7.2 (ADR 0018), hardened for audit finding KR-04 (ADR 0050): the

# public-claim applicability contract.

#

# A preset asserting a public claim level whose requiresEvidenceTierRank >= 1

# must be authorized by at least one EvidenceAssessmentClaim that satisfies

# EVERY clause below. C0/C1/C2 (requires 0) need no evidence; C4 medical

# (sentinel 7, above max tier 6) can never be satisfied, so asserting it

# publicly always fails.

#

# The original constraint required only a tier rank reached via the now

# deprecated sstim:supportsRelation. That accepted a *refuting* claim, a

# claim about a different preset, a claim in an unrelated modality, an

# unreviewed or withdrawn claim, and a claim citing a reference it never

# read. Each clause below closes one of those, and each has an adversarial

# negative fixture in scripts/public-claim-gate-negative.py proving it is

# load-bearing — a conjunct nobody can fail is a conjunct that is not there.

#

# Note the consequence, which is intended: no EvidenceReviewDecision exists

# in SSTIM yet, so no claim can currently authorize C3 or C5. That is the

# honest state of the evidence base, not a defect. The tier mapping remains

# the PROVISIONAL default in sstim-vocab (PublicClaimLevelScheme) —

# reconcile with the BioSynCare Reference enum and legal advice before

# launch. Full IRIs avoid an sh:prefixes block.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "No evidence assessment satisfies the public-claim applicability contract for this preset's claim level. An authorizing assessment must: support (not refute or leave inconclusive) the claim; reach the tier rank the level requires; be about this preset in both its proposition subject and its scope intervention/context; declare a population or model; declare a sensory modality this preset actually delivers; cite a public-safe reference it also used as an evidence basis; carry a confirming review decision with no reject or revision-request against the same revision; and be neither deprecated nor superseded. Medical/condition (C4) claims are never publicly assertable."@en ;

sh:select """

SELECT DISTINCT $this WHERE {

$this <https://w3id.org/sstim#hasPublicClaimLevel> ?level .

?level <https://w3id.org/sstim#requiresEvidenceTierRank> ?req .

FILTER( ?req >= 1 )

FILTER NOT EXISTS {

# Direction and strength. hasClaimDirection is where an

# assessment's direction lives; evaluatesSubject is neutral,

# which is exactly why the old gate could be satisfied by a

# well-evidenced refutation.

?claim a <https://w3id.org/sstim#EvidenceAssessmentClaim> ;

<https://w3id.org/sstim#evaluatesSubject> $this ;

<https://w3id.org/sstim#hasClaimDirection> <https://w3id.org/sstim/vocab#claimSupports> ;

<https://w3id.org/sstim#hasEvidenceTier> ?tier ;

<https://w3id.org/sstim#assessesProposition> ?proposition ;

<https://w3id.org/sstim#citesReference> ?reference .

?tier <https://w3id.org/sstim#tierRank> ?rank .

FILTER( ?rank >= ?req )

# Subject. The bounded proposition must itself be about this

# preset, not merely attached to a claim that points at it.

?proposition <https://w3id.org/sstim#propositionSubject> $this ;

<https://w3id.org/sstim#hasAssessmentScope> ?scope .

# Context and population. The scope must name this preset as

# the intervention it was established under, and must say in

# whom or in what model.

?scope <https://w3id.org/sstim#scopeInterventionOrContext> $this ;

<https://w3id.org/sstim#scopePopulationOrModel> ?population ;

<https://w3id.org/sstim#scopeSensoryModality> ?modality .

# Modality compatibility. The scope's modality must be one

# the preset actually delivers, derived through the protocol

# it follows and that protocol's techniques.

$this <https://w3id.org/sstim#followsProtocol> ?protocol .

?protocol <https://w3id.org/sstim#usesTechnique> ?technique .

?technique <https://w3id.org/sstim#techniqueModality> ?modality .

# Citation integrity. The cited reference must be public-safe

# (PublicSafeReferenceShape then forces title, creator, date

# and DOI) and must be a source the assessment actually used,

# not decoration borrowed from a stronger literature.

?reference a <https://w3id.org/sstim#PublicSafeReference> .

?claim <https://w3id.org/sstim#hasEvidenceBasis> ?basis .

?basis <https://w3id.org/sstim#basisSource> ?reference .

# Review state. ADR 0027 derives review state from immutable

# decision records, never from the deprecated mutable

# hasReviewStatus. Decisions carry no date, so ordering them

# is not possible; instead any adverse decision against the

# same immutable revision blocks it. A revision that was

# confirmed and rejected is contradictory, not merely stale.

?decision a <https://w3id.org/sstim#EvidenceReviewDecision> ;

<https://w3id.org/sstim#reviewsAssessment> ?claim ;

<https://w3id.org/sstim#hasReviewDecision> <https://w3id.org/sstim/vocab#reviewConfirm> .

FILTER NOT EXISTS {

?adverseDecision <https://w3id.org/sstim#reviewsAssessment> ?claim ;

<https://w3id.org/sstim#hasReviewDecision> ?adverse .

FILTER( ?adverse IN ( <https://w3id.org/sstim/vocab#reviewReject>,

<https://w3id.org/sstim/vocab#reviewRequestRevision> ) )

}

# Currency. Withdrawn or superseded evidence authorizes

# nothing, in either direction the supersession was written.

FILTER NOT EXISTS { ?claim <http://www.w3.org/2002/07/owl#deprecated> true }

FILTER NOT EXISTS { ?claim <http://purl.org/dc/terms/isReplacedBy> ?successor }

FILTER NOT EXISTS { ?replacement <http://purl.org/dc/terms/replaces> ?claim }

}

}

""" ;

] .

###########################################################################

# Voice Shapes

###########################################################################

sstim-sh:VoiceShape a sh:NodeShape ;

sh:targetClass sstim:Voice ;

sh:name "Voice"@en ;

# A Voice must be exactly one of the four disjoint subtypes. sh:xone enforces

# this at the data level (pyshacl runs without OWL inference, so the

# owl:AllDisjointClasses axiom alone would not be checked).

sh:xone (

[ sh:class sstim:BinauralVoice ]

[ sh:class sstim:MartigliVoice ]

[ sh:class sstim:MartigliBinauralVoice ]

[ sh:class sstim:SymmetryVoice ]

) ;

sh:message "Voice must be typed as exactly one of the four subtypes: Binaural, Martigli, Martigli-Binaural, or Symmetry."@en ;

# KR-07: the shape admitted any volume below 1.0, while the format

# specification caps the conservative default at 0.30 and requires an

# explicit rationale above it. A hard ceiling would forbid a legitimately

# louder design outright, so the requirement is the rationale, not the

# ceiling: above 0.30 the voice must carry an rdfs:comment saying why.

# 1.0 stays invalid outright via the per-subtype sh:maxExclusive.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "A voice louder than iniVolume 0.30 must record why in an rdfs:comment (format specification, conservative volume limits)."@en ;

sh:select """

SELECT $this ?volume WHERE {

$this <https://w3id.org/sstim#initialVolume> ?volume .

FILTER( ?volume > 0.30 )

FILTER NOT EXISTS { $this <http://www.w3.org/2000/01/rdf-schema#comment> ?rationale }

}

""" ;

] .

sstim-sh:BinauralVoiceShape a sh:NodeShape ;

sh:targetClass sstim:BinauralVoice ;

sh:name "BinauralVoice"@en ;

sh:property [

sh:path sstim:carrierFreqLeft ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ; sh:maxInclusive 1000 ;

sh:message "fl must be a decimal in [80, 1000] Hz."@en ;

] ;

sh:property [

sh:path sstim:carrierFreqRight ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ; sh:maxInclusive 1000 ;

sh:message "fr must be a decimal in [80, 1000] Hz."@en ;

] ;

sh:property [

sh:path sstim:initialVolume ;

sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0 ; sh:maxExclusive 1 ;

sh:message "iniVolume must be in [0, 1)."@en ;

] .

sstim-sh:SymmetryVoiceShape a sh:NodeShape ;

sh:targetClass sstim:SymmetryVoice ;

sh:name "SymmetryVoice"@en ;

sh:property [

sh:path sstim:baseFrequency ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ;

sh:message "f0 must be >= 80 Hz."@en ;

] ;

sh:property [

sh:path sstim:noteCount ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:integer ;

sh:minInclusive 2 ;

sh:message "nnotes must be an integer >= 2."@en ;

] ;

sh:property [

sh:path sstim:octaveSpan ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0 ;

sh:message "noctaves must be a non-negative decimal."@en ;

] ;

sh:property [

sh:path sstim:cycleDuration ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minExclusive 0 ;

sh:message "d must be a positive decimal (seconds)."@en ;

] ;

sh:property [

sh:path sstim:permutationFunction ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:integer ;

sh:minInclusive 0 ; sh:maxInclusive 4 ;

sh:message "permfunc must be 0, 1, 2, 3, or 4."@en ;

] ;

# KR-07: the pulse rate is nnotes/d Hz and the engine supports at most 50 Hz

# (onset interval >= 20 ms). Nothing enforced it, so nnotes and d could each

# be individually legal and jointly produce a rate the engine cannot deliver.

# This is the constraint CLAUDE.md §4.7 states and the one an isochronic

# design is validated by.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "Symmetry pulse rate (nnotes / d) must not exceed 50 Hz — the onset interval d/nnotes must stay at or above 20 ms."@en ;

sh:select """

SELECT $this ?rate WHERE {

$this <https://w3id.org/sstim#noteCount> ?nnotes .

$this <https://w3id.org/sstim#cycleDuration> ?d .

FILTER( ?d > 0 )

BIND( ?nnotes / ?d AS ?rate )

FILTER( ?rate > 50 )

}

""" ;

] .

# Martigli & Martigli-Binaural voice parameter properties live in

# sstim-patch-studio.ttl (domain sstim:Voice); these shapes enforce which subtype

# requires which parameter. See ADR 0012 and docs/technical/{BREATHING_MODEL,

# MARTIGLI_BINAURAL}.md for parameter ranges.

sstim-sh:MartigliVoiceShape a sh:NodeShape ;

sh:targetClass sstim:MartigliVoice ;

sh:name "MartigliVoice"@en ;

sh:property [

sh:path sstim:martigliCenterFreq ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ; sh:maxInclusive 400 ;

sh:message "mf0 must be a decimal in [80, 400] Hz."@en ;

] ;

sh:property [

sh:path sstim:martigliAmplitude ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 1 ; sh:maxInclusive 400 ;

sh:message "ma must be a decimal in [1, 400] Hz."@en ;

] ;

sh:property [

sh:path sstim:martigliPeriodInitial ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 120 ;

sh:message "mp0 must be a decimal in [0.1, 120] s."@en ;

] ;

sh:property [

sh:path sstim:martigliPeriodFinal ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 240 ;

sh:message "mp1 must be a decimal in [0.1, 240] s."@en ;

] ;

sh:property [

sh:path sstim:martigliTransitionDuration ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 3600 ;

sh:message "md must be a decimal in [0.1, 3600] s."@en ;

] ;

sh:property [

sh:path sstim:isBreathReference ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:boolean ;

sh:message "isOn must be a boolean."@en ;

] ;

sh:property [

sh:path sstim:initialVolume ;

sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0 ; sh:maxExclusive 1 ;

sh:message "iniVolume must be in [0, 1)."@en ;

] ;

# A Martigli voice is a single tone — the carrier pair belongs to Martigli-Binaural.

sh:property [

sh:path sstim:carrierFreqLeft ; sh:maxCount 0 ;

sh:message "Martigli voice must not declare carrierFreqLeft (use Martigli-Binaural)."@en ;

] ;

sh:property [

sh:path sstim:carrierFreqRight ; sh:maxCount 0 ;

sh:message "Martigli voice must not declare carrierFreqRight (use Martigli-Binaural)."@en ;

] ;

# CLAUDE.md §4.5: when this voice is the breathing reference, mp0 must be >= 3 s.

sh:or (

[ sh:not [ sh:path sstim:isBreathReference ; sh:hasValue true ] ]

[ sh:path sstim:martigliPeriodInitial ; sh:minInclusive 3 ]

) ;

sh:message "When isOn=true (breathing reference), mp0 must be >= 3 s."@en .

sstim-sh:MartigliBinauralVoiceShape a sh:NodeShape ;

sh:targetClass sstim:MartigliBinauralVoice ;

sh:name "MartigliBinauralVoice"@en ;

sh:property [

sh:path sstim:carrierFreqLeft ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ; sh:maxInclusive 1000 ;

sh:message "fl must be a decimal in [80, 1000] Hz."@en ;

] ;

sh:property [

sh:path sstim:carrierFreqRight ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 80 ; sh:maxInclusive 1000 ;

sh:message "fr must be a decimal in [80, 1000] Hz."@en ;

] ;

sh:property [

sh:path sstim:martigliAmplitude ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 1 ; sh:maxInclusive 400 ;

sh:message "ma must be a decimal in [1, 400] Hz."@en ;

] ;

sh:property [

sh:path sstim:martigliPeriodInitial ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 120 ;

sh:message "mp0 must be a decimal in [0.1, 120] s."@en ;

] ;

sh:property [

sh:path sstim:martigliPeriodFinal ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 240 ;

sh:message "mp1 must be a decimal in [0.1, 240] s."@en ;

] ;

sh:property [

sh:path sstim:martigliTransitionDuration ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0.1 ; sh:maxInclusive 3600 ;

sh:message "md must be a decimal in [0.1, 3600] s."@en ;

] ;

sh:property [

sh:path sstim:isBreathReference ;

sh:minCount 1 ; sh:maxCount 1 ;

sh:datatype xsd:boolean ;

sh:message "isOn must be a boolean."@en ;

] ;

sh:property [

sh:path sstim:initialVolume ;

sh:maxCount 1 ;

sh:datatype xsd:decimal ;

sh:minInclusive 0 ; sh:maxExclusive 1 ;

sh:message "iniVolume must be in [0, 1)."@en ;

] ;

# Martigli-Binaural uses the carrier pair (fl/fr), not a single-tone center.

sh:property [

sh:path sstim:martigliCenterFreq ; sh:maxCount 0 ;

sh:message "Martigli-Binaural voice must not declare martigliCenterFreq (uses the fl/fr carrier pair)."@en ;

] ;

# CLAUDE.md §4.5: when this voice is the breathing reference, mp0 must be >= 3 s.

sh:or (

[ sh:not [ sh:path sstim:isBreathReference ; sh:hasValue true ] ]

[ sh:path sstim:martigliPeriodInitial ; sh:minInclusive 3 ]

) ;

sh:message "When isOn=true (breathing reference), mp0 must be >= 3 s."@en .

###########################################################################

# Evidence Assessment Shapes (ADR 0027)

###########################################################################

# EvidenceClaim is only a compatibility superclass: every instance must carry

# the concrete EvidenceAssessmentClaim subtype. A bare EvidenceClaim is rejected.

sstim-sh:EvidenceClaimShape a sh:NodeShape ;

sh:targetClass sstim:EvidenceClaim ;

sh:name "EvidenceClaim"@en ;

sh:class sstim:EvidenceAssessmentClaim ;

sh:message "A bare sstim:EvidenceClaim is not allowed: it must carry the concrete sstim:EvidenceAssessmentClaim subtype (ADR 0027)."@en .

sstim-sh:EvidenceAssessmentClaimShape a sh:NodeShape ;

sh:targetClass sstim:EvidenceAssessmentClaim ;

sh:name "EvidenceAssessmentClaim"@en ;

sh:property [

sh:path rdfs:label ; sh:minCount 1 ;

sh:message "EvidenceAssessmentClaim must have a human-readable rdfs:label."@en ;

] ;

sh:property [

sh:path dct:description ; sh:minCount 1 ;

sh:message "EvidenceAssessmentClaim must describe the exact scoped assessment and its limits."@en ;

] ;

sh:property [

sh:path sstim:evaluatesSubject ; sh:minCount 1 ; sh:maxCount 1 ;

# Widened by ADR 0049 alongside sstim:propositionSubject, for the same

# reason: an assessment of what an endogenous rhythm covaries with is

# not an assessment of anything BSC delivers, and the alternative was

# leaving those associations as unsourced prose.

sh:or (

[ sh:class sstim:Preset ]

[ sh:class sstim:SensoryStimulationTechnique ]

[ sh:class sstim:NeuralOscillationType ]

) ;

sh:message "EvidenceAssessmentClaim must evaluate exactly one Preset, Technique or NeuralOscillationType (ADR 0013 range, widened by ADR 0049)."@en ;

] ;

# supportsRelation, when present as the 0.7 compatibility alias, must equal evaluatesSubject.

sh:property [

sh:path sstim:supportsRelation ; sh:equals sstim:evaluatesSubject ;

sh:message "Deprecated supportsRelation must materialize the same object as evaluatesSubject."@en ;

] ;

sh:property [

sh:path sstim:hasEvidenceTier ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:EvidenceTierValue ;

sh:message "EvidenceAssessmentClaim must have exactly one evidence tier."@en ;

] ;

sh:property [

sh:path sstim:hasClaimDirection ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:ClaimDirection ;

sh:message "EvidenceAssessmentClaim must have exactly one claim direction."@en ;

] ;

sh:property [

sh:path sstim:assessesProposition ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:AssessmentProposition ;

sh:message "EvidenceAssessmentClaim must assess exactly one AssessmentProposition."@en ;

] ;

sh:property [

sh:path sstim:hasEvidenceBasis ; sh:minCount 1 ; sh:class sstim:EvidenceBasis ;

sh:message "EvidenceAssessmentClaim must have at least one qualified evidence basis (ADR 0027 retires the rank-conditional citation exception)."@en ;

] ;

sh:property [

sh:path prov:wasAttributedTo ; sh:minCount 1 ; sh:nodeKind sh:IRI ;

sh:message "EvidenceAssessmentClaim must identify at least one IRI-valued responsible agent."@en ;

] ;

sh:property [

sh:path dct:modified ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:date ;

sh:message "EvidenceAssessmentClaim must declare one xsd:date dct:modified value."@en ;

] ;

# A node cannot be both an evidence assessment and a non-evidence statement role.

sh:not [ sh:class sstim-ex:ExposureHypothesis ] ;

sh:not [ sh:class sstim-ex:ResearchQuestion ] ;

sh:not [ sh:class sstim-ex:BoundaryApplicabilityStatement ] ;

sh:not [ sh:class sstim-ex:ProtocolRequirement ] ;

sh:not [ sh:class sstim-ex:ExposureDesignObjective ] ;

sh:not [ sh:class sstim-ex:PlannedOutcomeSpecification ] ;

sh:not [ sh:class sstim-ex:KnowledgeStatusAssertion ] ;

# For each bibliographic basis source, a matching citesReference must exist.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "Every bibliographic-reference evidence basis must be mirrored by a matching sstim:citesReference triple (ADR 0027)."@en ;

sh:select """

SELECT DISTINCT $this WHERE {

$this <https://w3id.org/sstim#hasEvidenceBasis> ?basis .

?basis <https://w3id.org/sstim#basisSource> ?ref .

?ref a <https://w3id.org/sstim#BibliographicReference> .

FILTER NOT EXISTS { $this <https://w3id.org/sstim#citesReference> ?ref . }

}

""" ;

] ;

# The assessment's proposition must be about the same subject it evaluates.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "The assessed proposition's propositionSubject must equal the assessment's evaluatesSubject (ADR 0027)."@en ;

sh:select """

SELECT DISTINCT $this WHERE {

$this <https://w3id.org/sstim#assessesProposition> ?prop ;

<https://w3id.org/sstim#evaluatesSubject> ?subject .

?prop <https://w3id.org/sstim#propositionSubject> ?psubject .

FILTER( ?subject != ?psubject )

}

""" ;

] .

sstim-sh:AssessmentPropositionShape a sh:NodeShape ;

sh:targetClass sstim:AssessmentProposition ;

sh:name "AssessmentProposition"@en ;

sh:property [

sh:path sstim:propositionSubject ; sh:minCount 1 ; sh:maxCount 1 ;

# ADR 0049 widened this to admit a named neural oscillation. The evidence

# machinery was built to assess what BSC delivers — a preset or a

# technique — but the associations moved off the frequency-band scope

# notes are about the endogenous rhythm, not about anything delivered.

# Refusing them here would have forced them back into unqualified prose,

# which is the defect ADR 0049 exists to remove. The same widening ADR

# 0034 made for non-sensory techniques, for the same reason.

sh:or (

[ sh:class sstim:Preset ]

[ sh:class sstim:SensoryStimulationTechnique ]

[ sh:class sstim:NeuralOscillationType ]

) ;

sh:message "AssessmentProposition must have exactly one Preset, Technique or NeuralOscillationType subject."@en ;

] ;

sh:property [

sh:path sstim:propositionOutcome ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:EvidenceOutcomeConcept ;

sh:message "AssessmentProposition must identify exactly one outcome concept."@en ;

] ;

sh:property [

sh:path sstim:hasAssessmentScope ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:AssessmentScope ;

sh:message "AssessmentProposition must have exactly one explicit scope."@en ;

] ;

sh:property [

sh:path sstim:hasPropositionForm ; sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:EvidencePropositionForm ;

sh:message "AssessmentProposition must have exactly one proposition form."@en ;

] ;

sh:or (

[ sh:path sstim:propositionText ; sh:minCount 1 ]

[ sh:path sstim:propositionDigest ; sh:minCount 1 ]

) ;

sh:message "AssessmentProposition must carry exact text or an immutable digest."@en ;

# Universal-absence propositions never conform.

sh:not [ sh:path sstim:hasPropositionForm ; sh:hasValue sstim-v:formUniversalAbsence ] .

sstim-sh:AssessmentScopeShape a sh:NodeShape ;

sh:targetClass sstim:AssessmentScope ;

sh:name "AssessmentScope"@en ;

sh:property [

sh:path sstim:scopeSensoryModality ; sh:minCount 1 ;

sh:message "AssessmentScope must state a sensory modality or an explicit scope marker."@en ;

] ;

sh:property [

sh:path sstim:scopePopulationOrModel ; sh:minCount 1 ;

sh:message "AssessmentScope must state a population/model or an explicit scope marker."@en ;

] ;

sh:property [

sh:path sstim:scopeInterventionOrContext ; sh:minCount 1 ;

sh:message "AssessmentScope must state an intervention/context or an explicit scope marker."@en ;

] ;

sh:property [

sh:path sstim:scopeComparator ; sh:minCount 1 ;

sh:message "AssessmentScope must state a comparator or an explicit scope marker."@en ;

] .

sstim-sh:EvidenceBasisShape a sh:NodeShape ;

sh:targetClass sstim:EvidenceBasis ;

sh:name "EvidenceBasis"@en ;

sh:property [

sh:path sstim:basisSource ; sh:minCount 1 ; sh:maxCount 1 ;

sh:message "EvidenceBasis must have exactly one basisSource."@en ;

] ;

# Zero canonical sensory modalities is allowed only with an explicit

# modality-applicability value (ADR 0027): never a silent gap.

sh:or (

[ sh:path sstim:basisSensoryModality ; sh:minCount 1 ]

[ sh:path sstim:basisModalityApplicability ; sh:minCount 1 ]

) ;

sh:message "EvidenceBasis must state at least one canonical sensory modality or an explicit modality-applicability value."@en .

sstim-sh:GovernedResearchOutputShape a sh:NodeShape ;

sh:targetClass sstim:GovernedResearchOutput ;

sh:name "GovernedResearchOutput"@en ;

sh:property [

sh:path sstim:hasSourceGovernanceRecord ; sh:minCount 1 ; sh:maxCount 1 ;

sh:class sstim:SourceGovernanceRecord ;

sh:message "GovernedResearchOutput must have exactly one immutable source-governance record."@en ;

] .

sstim-sh:EvidenceSearchRecordShape a sh:NodeShape ;

sh:targetClass sstim:EvidenceSearchRecord ;

sh:name "EvidenceSearchRecord"@en ;

sh:property [

sh:path sstim:searchQuery ; sh:minCount 1 ; sh:maxCount 1 ;

sh:message "EvidenceSearchRecord must record the exact query."@en ;

] ;

sh:property [

sh:path sstim:searchCoverageEnd ; sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:date ;

sh:message "EvidenceSearchRecord must record its as-of coverage-end date."@en ;

] .

# The public-claim gate (BscCatalogPresetShape, ADR 0050) reads

# requiresEvidenceTierRank to decide whether a preset needs evidence at all, and

# tierRank to decide whether a claim is strong enough. Neither was mandatory.

#

# A PublicClaimLevel missing requiresEvidenceTierRank matches nothing in the

# gate's WHERE clause, so the entire constraint passes vacuously for every preset

# declaring that level — a safety gate failing open on an omission, which is the

# worst way for one to fail. Adding a seventh claim level and forgetting one

# triple would have disabled it silently.

#

# A tier missing tierRank fails closed instead (no claim can reach the

# requirement), which is safe but still leaves the vocabulary incomplete.

# ADR 0052. Two constraints here are the ones that stop the signal layer being

# decoration: a signal must state a frequency extent that runs the right way, and

# a sampled signal must identify what it was sampled from — without which it is

# not reproducible, which is the whole reason the shape is distinguished.

sstim-sh:StimulationSignalShape a sh:NodeShape ;

sh:targetClass sstim:StimulationSignal ;

sh:name "StimulationSignal"@en ;

sh:property [

sh:path sstim:hasSignalShape ;

sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:SignalShape ;

sh:message "A stimulation signal must state its shape."@en ;

] ;

sh:property [

sh:path sstim:hzMin ;

sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:decimal ; sh:minInclusive 0 ;

sh:message "A stimulation signal must state the lower bound of its frequency extent; a point signal states the same value twice."@en ;

] ;

sh:property [

sh:path sstim:hzMax ;

sh:minCount 1 ; sh:maxCount 1 ; sh:datatype xsd:decimal ; sh:minInclusive 0 ;

sh:message "A stimulation signal must state the upper bound of its frequency extent."@en ;

] ;

# A point signal is the degenerate interval, exactly as sstim-v:alpha10 and

# sstim-v:gamma40 already are; an inverted one is never meaningful.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "A signal's frequency extent must not run backwards: hzMin may equal hzMax, which is a point signal, but may not exceed it."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#hzMin> ?low ;

<https://w3id.org/sstim#hzMax> ?high .

FILTER( ?low > ?high )

}

""" ;

] ;

# The three band-interval relations are derivable from the two extents, and

# were assertable independently of them — a signal spanning 4-8 Hz could

# claim signalWithinBand alpha (8-13 Hz) and conform. Every ingredient for

# the check was already present, and ADR 0049 had added exactly this

# containment check for oscillations six weeks earlier.

#

# Asserted rather than inferred, deliberately: which relation holds is a

# design statement about what the signal is aimed at, and stating it lets

# this catch the case where the aim and the arithmetic disagree.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "signalWithinBand requires the signal's whole extent to lie inside the band: check hzMin/hzMax against the band's."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#signalWithinBand> ?band ;

<https://w3id.org/sstim#hzMin> ?low ;

<https://w3id.org/sstim#hzMax> ?high .

?band <https://w3id.org/sstim#hzMin> ?bandLow ;

<https://w3id.org/sstim#hzMax> ?bandHigh .

FILTER( ?low < ?bandLow || ?high > ?bandHigh )

}

""" ;

] ;

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "signalCoversBand requires the signal's extent to contain the whole band; a signal narrower than the band overlaps it at most."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#signalCoversBand> ?band ;

<https://w3id.org/sstim#hzMin> ?low ;

<https://w3id.org/sstim#hzMax> ?high .

?band <https://w3id.org/sstim#hzMin> ?bandLow ;

<https://w3id.org/sstim#hzMax> ?bandHigh .

FILTER( ?low > ?bandLow || ?high < ?bandHigh )

}

""" ;

] ;

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "signalOverlapsBand requires the extents to intersect with neither containing the other; use signalWithinBand or signalCoversBand for containment, and neither when they are disjoint."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#signalOverlapsBand> ?band ;

<https://w3id.org/sstim#hzMin> ?low ;

<https://w3id.org/sstim#hzMax> ?high .

?band <https://w3id.org/sstim#hzMin> ?bandLow ;

<https://w3id.org/sstim#hzMax> ?bandHigh .

FILTER( ?high < ?bandLow || ?low > ?bandHigh

|| ( ?low >= ?bandLow && ?high <= ?bandHigh )

|| ( ?low <= ?bandLow && ?high >= ?bandHigh ) )

}

""" ;

] ;

# The sampled shape is an asset, not a function. Without its source the

# signal cannot be reproduced, and reproducibility is why it is a shape of

# its own rather than an unnamed special case.

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "A sampled signal must identify the material it was sampled from (sstim:signalSourceAsset); a sampled signal without its source is not reproducible."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#hasSignalShape> <https://w3id.org/sstim/vocab#shapeSampled> .

FILTER NOT EXISTS { $this <https://w3id.org/sstim#signalSourceAsset> ?asset }

}

""" ;

] .

# Two carrier properties exist on purpose, one per layer (ADR 0041): emission on

# the channel, binding on the rendering. Two names for one quantity is only

# defensible if they cannot disagree, so this is what makes it defensible.

sstim-sh:ChannelCarrierAgreementShape a sh:NodeShape ;

sh:targetClass sstim-ex:StimulusChannel ;

sh:name "StimulusChannel carrier agreement"@en ;

sh:sparql [

a sh:SPARQLConstraint ;

sh:message "A channel's carrier frequency and the carrier of a rendering it presents state the same quantity at two layers and must agree."@en ;

sh:select """

SELECT $this WHERE {

$this <https://w3id.org/sstim#hasSignalRendering> ?rendering ;

<https://w3id.org/sstim/exposure#hasCarrierFrequencyHz> ?channelCarrier .

?rendering <https://w3id.org/sstim#renderingCarrierHz> ?renderingCarrier .

FILTER( ?channelCarrier != ?renderingCarrier )

}

""" ;

] .

sstim-sh:SignalRenderingShape a sh:NodeShape ;

sh:targetClass sstim:SignalRendering ;

sh:name "SignalRendering"@en ;

sh:property [

sh:path sstim:rendersSignal ;

sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:StimulationSignal ;

sh:message "A rendering must name the single signal it delivers."@en ;

] ;

sh:property [

sh:path sstim:rendersOntoParameter ;

sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:RenderableParameter ;

sh:message "A rendering must name the parameter the signal drives."@en ;

] ;

sh:property [

sh:path sstim:hasRenderingMechanism ;

sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:RenderingMechanism ;

sh:message "A rendering must name its mechanism."@en ;

] ;

sh:property [

sh:path sstim:hasRenderingPresence ;

sh:minCount 1 ; sh:maxCount 1 ; sh:class sstim:RenderingPresence ;

sh:message "A rendering must state whether the signal is physically present or perceptually constructed: evidence does not transfer freely between the two."@en ;

] ;

sh:property [

sh:path sstim:renderingCarrierHz ;