urpx.arrangements — energy.grid-coordination/clj-urpx 0.30.0

Enumerate the service arrangements a set of URPX documents expresses.

A SERVICE ARRANGEMENT is one urpx:RatePlanVersion, plus every urpx:RatePlanModifierVersion compatible with it, plus one urpx:ProfileAlternative for each dimension any of them leaves open. Fully determined: given an instant inside its window it resolves to prices with no further input. If a choice is still outstanding it is not one arrangement but several, and each of those is an arrangement in its own right.

urpx:ServiceArrangement IS NOT A URPX CLASS. It occurs zero times in the ontology and zero times in the SHACL shapes. It is a name for a thing the standard describes the parts of and does not name the whole of, and nothing here writes it into a document or claims a urpx: prefix for it. The concept and its evidence are set out in urpx-rate-plans doc/service-arrangements.md; the cardinalities this namespace relies on were checked against the shapes graph rather than recalled.

WHAT THIS CAN AND CANNOT ENUMERATE. Which compatible modifiers a given CUSTOMER has is a fact about the customer, and URPX places customer data outside its scope: urpx:AccountServiceAgreement carries the skos:note "Service account and agreement data lives in customer data, not URPX." So this enumerates the arrangements the DOCUMENTS EXPRESS, every combination the filings say is permitted. That set is larger than any one customer's and is what a price server can publish.

OPTIONAL BY CONSTRUCTION. This namespace requires urpx.price; urpx.price does not require this. A consumer that wants prices for a composition it already knows how to assemble uses urpx.price directly and never loads this file. Nothing here changes an existing arity or return shape.

applicable-modifiers clj

(applicable-modifiers documents base-version)

(applicable-modifiers documents base-version opts)

The urpx:RatePlanModifierVersions in documents that MAY apply to base-version.

This is the query a consumer actually wants, and it is the half URPX can answer. urpx:applicableToRatePlan states compatibility with a plan identity; urpx:applicableToRatePlanVersion states it against a specific version. Where a modifier names any versions, those are taken to be exhaustive, because the version-level statement is the more specific.

WHICH READING applies is a caller policy, :compatibility, defaulting to named-versions-narrow. URPX does not settle whether naming a version narrows the plan-level statement or adds to it, so this library does not settle it either; see the policies for the evidence on each side.

Counts below are AS MEASURED AT ONE CORPUS REVISION, urpx-rate-plans 9deae4dbaa8b, because a bare "37 of 37" is a claim with no stated conditions and this one had already drifted twice before it was pinned: 40 distinct modifier version nodes, applicableToRatePlan on 40 of 40 naming 3.40 plans on average, applicableToRatePlanVersion on 7 of 40.

WHAT THIS DOES NOT ANSWER, deliberately. Which of these a given customer HAS is a fact about the customer, and URPX places customer data outside its scope: urpx:AccountServiceAgreement carries the skos:note "Service account and agreement data lives in customer data, not URPX." Nor does URPX say which modifiers may be held TOGETHER: there is no property anywhere in the ontology expressing exclusivity or combinability between modifiers, and urpx:modifierCategory and urpx:modifierType, which might have served as a signal, are unset on all 40. So CARE and FERA are both returned for SCE Schedule D and nothing in the documents says a customer has at most one. Choosing among them is the caller's, which is why arrangements takes a combining policy rather than inventing one.

Options: :at a ZonedDateTime. Restricts to modifier versions current then. :repeated-ids fn from {kind -> [[identity-id version document] ...]} to the same, deciding what one @id naming several distinct snapshots means. Defaults to repeated-ids-refuse; repeated-ids-union merges them, which is what a corpus whose own SHACL gate validates a merged graph already assumes. A THIRD POLICY for the same reason as the other two: URPX does not say, and a client reading one filing and a client merging a corpus want different answers. Over the production corpus the default refuses and the union yields 137 pairs, or 144 paired with named-versions-add. :compatibility fn [modifier-version base-version plan-id] -> boolean. Defaults to named-versions-narrow; named-versions-add is the monotone alternative.

arrangement-id clj

(arrangement-id arrangement)

The intrinsic identity of arrangement:

[base-version-iri [modifier-version-iris sorted] [[container alternative] sorted]]

Computable from the documents alone, stable across regeneration, external nothing. Two arrangements are the same when this matches and different otherwise, INCLUDING when they resolve to the same price: a bundled customer and one buying generation elsewhere may pay the same delivery rate and are on different arrangements.

arrangement-pairs clj

(arrangement-pairs documents)

(arrangement-pairs documents opts)

Every (base version, modifier set) pair documents expresses, as a set:

#{[base-version-iri #{modifier-version-iri ...}] ...}

The enumeration collapsed to one row per composition, with any ProfileAlternative choices NOT expanded. That is a coarser question than arrangements answers and a deliberately different one: an arrangement with an open dimension is several arrangements and one pair.

FOR COMPARING TWO IMPLEMENTATIONS. A consumer cross-checking an independent enumerator against this one should compare pair SETS rather than arrangement counts, because the two sides can legitimately disagree about whether a pending choice is one row or several while agreeing completely about what composes with what.

opts is what arrangements takes. PIN EVERY POLICY EXPLICITLY when the result is an expected value in a gate: :at, :combine, :compatibility and :repeated-ids each change the answer, and matching defaults across two implementations is agreement by coincidence rather than by construction.

arrangements clj

(arrangements documents)

(arrangements documents opts)

Every service arrangement documents expresses, as a vector.

documents is a seq of coerced urpx:RatePlan and urpx:RatePlanModifier documents, the same values urpx.price takes.

Options: :at a ZonedDateTime. Restricts to arrangements whose every component is CURRENT at that instant: the latest version of each identity to have taken effect and not expired. Omit to enumerate the whole expressed space across every version, a different and larger question. :combine fn from the compatible modifier versions of one base version to a seq of the modifier SETS a customer might hold. Defaults to one-modifier-at-most. :compatibility fn [modifier-version base-version plan-id] -> boolean deciding which modifiers MAY apply. Defaults to named-versions-narrow; named-versions-add is the monotone alternative. TWO POLICIES, not one, because URPX does not say whether naming a urpx:applicableToRatePlanVersion narrows urpx:applicableToRatePlan or adds to it. They are indistinguishable on the corpus this namespace can enumerate today; see the policies for where that stops being true.

THE COMBINING POLICY IS THE CALLER'S BECAUSE URPX CANNOT STATE IT. Nothing in the ontology expresses exclusivity or combinability between modifiers, and urpx:modifierCategory and urpx:modifierType, the only properties that might have served, are unset on all 40 modifier version nodes at urpx-rate-plans 9deae4dbaa8b. So CARE and FERA are both compatible with SCE Schedule D and no document says a customer has at most one. The default is conservative and knowingly incomplete; every-subset is complete and knowingly wrong; a caller holding its own program rules should pass those instead. Use applicable-modifiers to see what it is choosing among.

Each arrangement is a map: :urpx.arrangement/rate-plan the coerced base document :urpx.arrangement/version the base version snapshot :urpx.arrangement/version-id its @id :urpx.arrangement/plan-id the plan identity @id :urpx.arrangement/modifiers coerced modifier documents, in order :urpx.arrangement/modifier-versions their snapshots :urpx.arrangement/modifier-version-ids their @ids :urpx.arrangement/selections {container-@id alternative-@id}

Deterministic: sorted by arrangement-id, so regenerating the same documents gives the same order. Nothing here consults wall-clock time.

every-subset clj

(every-subset modifier-versions)

A combining policy yielding every subset, including the empty one.

Complete and unfiltered: it will pair mutually exclusive programs, since nothing in the documents marks them exclusive. 2^n per base version, so use it on a narrowed modifier list rather than a whole corpus.

named-versions-add clj

(named-versions-add mv bv plan-id)

The monotone policy: a version statement ADDS to urpx:applicableToRatePlan and never removes from it.

Sound under RDF, which is what URPX documents denote: merging graphs adds triples and never retracts, so a larger corpus can only ever yield more compatibility. It also stops the plan-level statement being cancelled by triples that never mention the plan it names.

KNOWN COST. It leaves urpx:applicableToRatePlanVersion with almost nothing to do: it can only widen, and only to a version whose plan is not already named. A publisher wanting to say "this modifier applies only to version X of plan P" has no way to say it under this reading.

named-versions-narrow clj

(named-versions-narrow mv bv plan-id)

The default policy: naming any urpx:applicableToRatePlanVersion means those versions and no others, overriding urpx:applicableToRatePlan.

Reads with the ontology's own wording, "Defines which SPECIFIC rate plan versions are compatible with this modifier version", and it is the only reading under which the property can express a restriction at all: under named-versions-add a version statement can only widen, and then only to a version whose plan is not already named, which no modifier in the production corpus does.

KNOWN COST, stated because it is not small. The rule is NON-MONOTONIC. Merging a document that adds a version statement REMOVES compatibility with a plan named only by urpx:applicableToRatePlan, and RDF merge never retracts. A partial view of a corpus can therefore yield MORE arrangements than the whole of it. It is the default because it is what the corpus and the peer reference implementation both assume today, not because it is known right.

offered-by clj

(offered-by versions)

Group version snapshots by the urpx:Organization @id that offers them, for a broader search than one plan at a time.

urpx:offeredBy is populated on all 40 modifier version nodes at urpx-rate-plans 9deae4dbaa8b.

This used to add that urpx:applicableToRateGroup and urpx:hasServiceClass "would also serve this purpose and are unset on all 37", which was wrong in kind rather than in degree: both appear ZERO times in RatePlanModifierVersionShape, so they cannot be set on a modifier version at all and there was never anything to be unset. Asserting a mechanism that is not in the ontology.

one-modifier-at-most clj

(one-modifier-at-most modifier-versions)

The default combining policy: the empty set, and each modifier on its own.

Conservative because URPX cannot state which modifiers combine. Every arrangement it yields is one the documents support, and it is knowingly INCOMPLETE: real multi-overlay arrangements exist, and California publishes identifiers for some of them, so a caller that knows its own program rules should pass its own policy rather than accept this one.

plan-versions clj

(plan-versions documents)

(plan-versions documents opts)

Every urpx:RatePlanVersion in documents, as a vector of snapshots.

:at restricts to the version of each plan identity in force at that instant. Omit it for every version the documents carry.

repeated-ids-refuse clj

(repeated-ids-refuse by-kind)

The default policy for one @id naming more than one distinct snapshot: refuse, naming every offending @id at once.

An @id identifies a thing, so two different things under one is a contradiction rather than a choice. Where urpx.price refuses two DIFFERENT snapshots tied on an effective instant it can say "pass :version to choose", because the caller has two distinguishable things to choose between; here both carry the same @id and there is nothing to name.

Every conflicting @id is named in one refusal, across every kind. Called once per kind this threw on the base versions before the modifier versions were ever examined, so a corpus with three conflicting @ids reported one.

Byte-identical repeats are NOT a conflict. One version published in two filings is one version, and it is deduplicated.

repeated-ids-union clj

(repeated-ids-union by-kind)

A policy that MERGES snapshots sharing one @id rather than refusing them.

The reading a corpus whose own SHACL gate validates a merged graph already assumes: several documents describing one IRI contribute the union of their statements, and absence of a property is not a negative assertion.

KNOWN COST, and it is not small. RDF MERGES TRIPLES, NOT MEANINGS. Merging a copy that states urpx:applicableToRatePlanVersion with one that omits it yields a node that HAS the property, which under named-versions-narrow restricts the modifier to exactly those versions. The omitting copy meant the opposite: no version restriction at all. So the union of the triples narrows where the union of the meanings would widen. On the production corpus that difference is 7 of 166 base/modifier pairs, all of one modifier losing one plan. Pair this with named-versions-add if the widening reading is what you want.

It also SILENTLY RECONCILES a case that is a defect on any reading: a version @id whose option list differs between filings because the list is time-varying and the @id is not. cpau:e-1-2025-07-01 offers [e-hra] in the July filing and [e-hra, e-eec-1, e-nse-1] in the September one, and the two additions are September versions that did not exist in July. The union asserts that a version effective in July offered them. Merging makes that enumerable; it does not make it true.

Refuses :urpx.arrangement/unmergeable-property when occurrences disagree about a non-collection property, which cannot be combined.

resolve-at clj

(resolve-at arrangement zdt)

(resolve-at arrangement zdt opts)

Resolve arrangement at zdt, returning what urpx.price/resolve-prices-with-modifiers returns.

A convenience over urpx.price, not a replacement: it binds each document to its own version and hands the arrangement's selections through as :profile-alternatives, so the opts cannot reach a document they do not belong to. Both :version defects fixed in 0.28.0 were an opt and a document failing to line up: one applied the base plan's snapshot to every modifier, the other re-derived the snapshot on the holiday path and ignored the opt entirely. An arrangement makes both unrepresentable rather than repeatedly fixable.

The binding does more than choose. Handed a document carrying several version snapshots, urpx.price refuses outright rather than picking one, so this is what makes such a document resolvable at all.

Extra opts merge over the arrangement's own, except :version and :profile-alternatives, which are refused. See bound-opts.

schedule-for clj

(schedule-for arrangement start end)

(schedule-for arrangement start end zone)

(schedule-for arrangement start end zone opts)

A stepped price schedule for arrangement across [start, end), as urpx.schedule/price-schedule-with-modifiers returns them.

Walks a grid, default hourly, merging adjacent steps whose resolution is equal. Use it when a caller genuinely wants a fixed cadence; use segments-for when they want the truth about where prices change, which for a price server is almost always the question.

Same zone and opts handling as segments-for.

segments-for clj

(segments-for arrangement start end)

(segments-for arrangement start end zone)

(segments-for arrangement start end zone opts)

Exact price segments for arrangement across [start, end), as urpx.schedule/price-segments returns them.

PREFER THIS over schedule-for for publishing. Boundaries are derived from the documents rather than discovered by sampling, so a segment ends where the tariff actually changes and not where a step grid happened to land. For a consumer handing intervals to an optimizer that is the difference between a schedule that is right and one that is right only because every bracket in that plan sits on an hour.

A resolution that throws inside the window becomes a segment carrying :urpx.interval/refused rather than aborting the horizon, and equal refusals merge, so a stretch the arrangement does not cover is one segment and not one per candidate instant. That is what lets a publisher emit the part of a window it can price and say plainly what it cannot.

zone may be nil when the plan declares urpx:timezoneIdentifier. Extra opts are as resolve-at: merged, except the two the arrangement determines, which are refused.