urpx.coverage — energy.grid-coordination/clj-urpx 0.36.0

Read what a version snapshot CLAIMS about its own coverage.

Every urpx:RatePlanVersion and urpx:RatePlanModifierVersion carries a urpx:CoverageClaim: a verdict on what can be answered from that snapshot under stated conditions. The verdict is the standard's own answer to "what am I holding?", and this library modeled it and read it nowhere until now.

NOT A JUDGEMENT OF THIS LIBRARY'S. Per the ontology, CoverageClaim instances "are produced by an implementation or publishing workflow", so a claim says what the PUBLISHER asserts about a snapshot, not what clj-urpx found. Nothing here re-derives a verdict or second-guesses one; reading is the whole job.

OPTIONAL BY CONSTRUCTION. This requires urpx.index and nothing else of the library: not urpx.price, not urpx.scenario-cost-model. Nothing in src/ requires it, which a test asserts over the whole source tree.

TWO FIELDS ARE EASY TO OVER-READ. selfContained is defined as "false iff any PriceDefinitionReference is referenceInclusion retrievedElsewhere", so true means "nothing here is fetched from elsewhere", which is not "complete" and must not be read as reassurance; on a snapshot with no PriceDefinitionReference it is vacuously true. And the CoverageClaim note says producers SHOULD attach a TemporalScope with scopeKind urpx:coverage, which no shape requires, so a verdict with no scope is conformant and a consumer publishing a horizon cannot assume a verdict covers it.

claim clj

(claim version)

(claim version doc)

The urpx:CoverageClaim on version, or ::absent.

doc is the document the version came from, needed only to follow a claim recorded as a bare @id reference; the schema admits that arm ([:or CoverageClaim ExclusiveRef]).

REFUSES :urpx.coverage/claim-ref-unresolved when the claim IS a bare reference and cannot be followed, because a reference that goes nowhere is not the same as no claim: one is a document that says something this reader cannot reach, the other a document that says nothing.

completeness-results clj

The six urpx:CompletenessResultValue members, from urpx-shacl:CompletenessResultValueShape's sh:in.

No ordering is stated among them and none is implied here. The absence is meaningful rather than an oversight: the same ontology uses skos:broader where it does mean a hierarchy. They are distinct KINDS, not degrees: partial asserts a gap in the snapshot while what is present is usable, unsupported that the source has it and the representation cannot express it, pending that the source has not published it yet, noCoverage that it was evaluated and nothing exists anywhere, and unknown that no evaluation has run at all.

coverage-interval clj

(coverage-interval version-report zone)

The window a verdict covers, as {:tick/beginning <ZonedDateTime> :tick/end <ZonedDateTime>} in zone, with either end nil when unbounded on that side.

ZONED, AND THE ZONE IS REQUIRED. A TemporalScope's bounds are usually written without an offset, so a bare bound is a wall-clock reading that means nothing until a zone is supplied. A bound written with an offset is moved to zone with its instant kept. Returning it unzoned looked like the honest choice and was the opposite: urpx.schedule emits {:tick/beginning :tick/end} carrying ZonedDateTimes, so an unzoned window is the same map with the same keys and an incompatible type, and the natural comparison does not fail loudly. Measured: tick.alpha.interval/relation throws a ClassCastException on the mixture, and contains? returns TRUE regardless of the values. A silently wrong answer about whether a verdict covers a published horizon is the worst thing this namespace could produce.

zone is a java.time.ZoneId. A rate plan usually declares one as urpx:timezoneIdentifier, which is what urpx.schedule resolves for the same purpose; a caller that has already built a horizon has it in hand. This namespace does not read it for you, because the plan carrying it is not always the document a version came from and guessing which is the caller's call rather than this reader's.

TICK INTERVALS IN FACT, not only in shape. tick.alpha.interval's functions read any map carrying those two keys, so (ti/relation window segment) answers with Allen's relations directly and (ti/contains? window interval) agrees with verdict-applies? case for case, with both sides now zoned. A caller wanting the richer relation should reach for tick rather than for another function here. This library requires tick nowhere.

The dateTime form is preferred and the date form read at start of day, the rule urpx.price/version-effective-at already gives the version shapes' own date-or-dateTime pair.

REFUSES :urpx.coverage/coverage-scope-absent and :urpx.coverage/coverage-scope-unbounded; see verdict-applies?.

descriptions clj

(descriptions model-report)

The Evaluation prose from an of-model report, in part order, as [{:role :version-id :description} ...].

THE PROSE IS THE ONLY PLACE A GAP IS NAMED. A completeness result says THAT something is missing; the linked Evaluation says WHAT, and that prose can be specific enough to act on, naming for instance the customer groups whose component exemptions a filing does not represent.

So a consumer deciding whether a partial snapshot is publishable is reading this, not the verdict keyword. Entries with no description are dropped; explainedBy is optional.

of-model clj

(of-model model)

What each part of model claims about its own coverage.

:urpx.coverage/parts [<of-version report> ...] in model order, base first, each carrying :urpx.coverage/role of :base or :modifier :urpx.coverage/completeness-counts {"urpx:partial" 2, ...} :urpx.coverage/unstated-count parts carrying no claim :urpx.coverage/every-part-stated? :urpx.coverage/every-part-complete? :urpx.coverage/every-part-self-contained? :urpx.coverage/any-part-scope-stated?

THERE IS NO MODEL-LEVEL VERDICT, and the absence is the design rather than an omission. A test pins the key set so that adding one fails.

Two reasons, the second decisive. No ordering is stated among the six completeness members, and the absence is meaningful: the same ontology uses skos:broader where it does mean a hierarchy. And every definition is relative to "the claimed scope" of its own snapshot, while no snapshot states one, so composing would require knowing each part's scope and that their union equals the model's. Neither is known. Composition is undefined at the DOMAIN level, not merely unranked, and would stay undefined even if URPX later imposed an order.

A minimum would also be positively wrong in a case the vocabulary allows: a modifier claiming urpx:noCoverage contributes nothing to the composition, so a complete base with a noCoverage modifier is not a noCoverage model.

EVERY DERIVED BOOLEAN NAMES THE PARTS, never the model. A conjunction of per-part facts needs no ordering; a verdict does, and the naming is what keeps the two from being confused at a call site. Note that every-part-complete? still does NOT mean the model is complete: each claim covers its own snapshot's required elements, and nothing claims the elements a composition needs and neither part carries.

Each part is read against ITS OWN document, the one the model bound to it, so a claim recorded as a bare reference resolves correctly rather than against whichever document happened to be at hand.

of-version clj

(of-version version)

(of-version version doc)

What version claims about its own coverage, as a report map.

:urpx.coverage/version-id the snapshot's @id :urpx.coverage/version-type its @type :urpx.coverage/stated? whether it carries a CoverageClaim at all :urpx.coverage/completeness one of completeness-results as the IRI STRING the document uses, or nil :urpx.coverage/self-contained true / false / nil :urpx.coverage/self-contained-source :claim, :version, or nil :urpx.coverage/self-contained-disagrees? the two places disagree :urpx.coverage/confidence IRI string or nil :urpx.coverage/stale true / false / nil :urpx.coverage/fallback-sourced true / false / nil :urpx.coverage/scope-stated? a urpx:coverage TemporalScope is present :urpx.coverage/coverage-window that scope node, raw, or nil :urpx.coverage/evaluations [{:kind :evaluated-on :description}], or {:unresolved-ref id} for one that cannot be followed. :evaluated-on is a ZonedDateTime when the document wrote an offset, else a LocalDateTime

ABSENT IS NOT UNKNOWN. A version with no claim reports stated? false and completeness nil, never "urpx:unknown". urpx:unknown is itself a verdict, meaning evaluated-nowhere, and a document that asserts it has said something a document that omits the claim has not. Conflating them would invent a claim on the publisher's behalf.

A missing claim is NOT refused either: urpx:hasCoverageClaim is optional in this library's schema for a recorded reason, that requiring it would reject every v0.2.x document, and v0.2.x acceptance is a contract this library advertises.

completeness is the IRI string as written, "urpx:partial", rather than a keyword of this library's invention. It maps 1:1 to what the document says and needs no translation table to compare against one.

SCOPE-STATED IS NOT WINDOW-STATED. urpx:scopeKind is the only required field on a TemporalScope, so a scope may name its role and give no bounds. A caller deciding whether a verdict covers a window must read coverage-window rather than trusting scope-stated?.

verdict-applies? clj

(verdict-applies? version-report zone interval)

True if the window version-report's verdict covers CONTAINS interval.

interval is {:tick/beginning <ZonedDateTime> :tick/end <ZonedDateTime>}, exactly what urpx.schedule's price-schedule and price-segments emit and what urpx.scenario-cost-model/segments-for hands back, so a caller asks this of a segment it is about to publish without converting anything.

zone interprets the scope's own bounds, which URPX states without one. See coverage-interval for why that is required rather than defaulted.

THE WINDOW IS [beginning, end), start inclusive and end exclusive, matching urpx.price/version-covers? exactly. URPX states no convention for a TemporalScope's bounds, and two readings of a window inside one library would be worse than either. An absent bound is unbounded on that side, so a scope stating only a start covers everything after it.

On bounded windows this is exactly tick.alpha.interval/contains?, which reads the same map; it exists as a named predicate because the refusals are the interesting part, not the comparison.

REFUSES :urpx.coverage/coverage-scope-absent for a claim with no urpx:coverage scope, which no shape requires, :urpx.coverage/coverage-scope-unbounded for a scope that names its role and bounds nothing, and :urpx.coverage/zone-required.

False would claim the verdict does not cover the window, which the document never said; true would be worse. The honest answer is that the question has none, which is what a refusal says. A caller that publishes anyway is choosing its own policy, and catching a named reason is how it says so.