diff --git a/demand/EvidenceBasis.md b/demand/EvidenceBasis.md new file mode 100644 index 0000000..9e8ffce --- /dev/null +++ b/demand/EvidenceBasis.md @@ -0,0 +1,191 @@ +# Demand: Evidence Basis — how a quantity was obtained, and how far a conclusion may be trusted + +**Status:** inbound demand (un-reviewed) +**Date:** 2026-08-15 +**Source:** resource-control (consumer), domain `financials` +**Proposed owner:** **ITC-GOV** (Evidence), imported by `ITC-CAP` `CapabilityConsumption` +**Requested by:** info-tech-canon, in reply to the ITC-CAP restatement, 2026-08-15 +**Consumer implementation:** `resource-control/tools/basis.py`, `docs/evidence-basis.md` +**Proposed workplan:** new; ITC-GOV owning change with an ITC-CAP import + +--- + +## Demand signal + +ITC-GOV §11.34 defines **Evidence** as "information used to support a claim", +with examples that are all *artifact kinds*: a log extract, a scan result, a +test result, a deployment record. §11.35 defines an **Assertion** as a claim +that something is true, supported by evidence. + +Nothing in the canon says **how a quantity was obtained**, and therefore nothing +bounds how far a conclusion computed from it may be trusted. + +That is a different question from which artifact supports a claim. An artifact +can be impeccable while the number inside it is a guess. A consumer reading two +numbers of the same shape — `7.35` and `60.00` — cannot tell that one is a +published price and the other is an assumed hour count multiplied by an assumed +rate, and the canon currently gives it no way to say so. + +## Why this cannot stay private to one consumer + +`resource-control` has implemented and is running this. We are filing rather +than keeping it because the same argument info-tech-canon accepted for +`CapabilityConsumption` applies unchanged: a private vocabulary diverges the +moment a second repository reports evidence-bearing quantities. + +It is already wanted in three places on the consumer side alone — capability +consumption rows, monthly actual observations, and threshold evaluations. That +breadth is also why the concept should **not** live in ITC-CAP: it is not about +capabilities. It is about quantities, wherever they occur. + +--- + +## Proposed concepts + +### `EvidenceBasis` + +A closed, ordered vocabulary naming how a single quantity was obtained. + +| Basis | Meaning | +|---|---| +| `invoiced` | Taken from an authoritative financial record | +| `measured` | Directly observed from the authoritative system | +| `quoted` | Stated by a provider or counterparty in a citable source | +| `derived` | Computed from other values by a stated rule | +| `projected` | Interpolated between, or extrapolated beyond, observations | +| `estimated` | Human judgement, neither observed nor computed | +| `assumed` | A modelling constant chosen by the author | +| `unknown` | No value exists | + +`invoiced`, `measured`, and `quoted` are **evidenced**: they assert an observed +or contracted fact. Everything below is inference. + +**On `invoiced`.** Per info-tech-canon's own instruction, this names a fin-hub +fact rather than originating one. The basis says only *where a value came from*; +it does not define booked-cost, tax, or currency semantics, which stay with the +financial authority under its own exchange contract. + +**Strength is a tier, not a total order.** `invoiced` and `measured` are peers. +An invoice is authoritative for a payment and a measurement is authoritative for +a quantity; neither outranks the other outside its own domain. The consumer's +first implementation got this wrong by using a strict list order, and corrected +it — `weakest(["invoiced", "measured"])` must not imply a difference that does +not exist. + +### `derived_from` and the propagation rule + +> **A derived value is only as strong as the weakest value it was computed from.** + +This is the rule that earns the vocabulary its place. Without it, arithmetic +launders assumptions: a two-decimal euro figure reads like a measurement when it +is an assumed hour count times an assumed rate. + +A `derived` value carries `derived_from`, the values it was computed from, and +resolves to the weakest of them, recursively. Derivation is not penalised in +itself: GB computed from measured bytes resolves to `measured`. + +### `unknown` carries no quantity + +A value with basis `unknown` MUST NOT carry a quantity, and MUST name the gap +and the party who owns it. A value with any other basis MUST carry a quantity. +Zero means "measured and none"; unknown means "not measured". Both directions +should be enforced, because the failure mode runs both ways — a missing amount +silently read as zero, and a zero mistaken for an absence. + +### `proxy_for` + +An orthogonal qualifier: the value is a genuine measurement of a *different* +quantity than the one being reasoned about. It does not weaken the measurement; +it weakens the inference drawn from it. A shared-database allocation driver may +measure bytes precisely while one of those databases has never recorded a +transaction. + +### `DecisionGrade` + +A rollup over the values a conclusion rests on — an **Assertion** whose strength +is bounded by its weakest supporting value. + +| Grade | Condition | +|---|---| +| `evidenced` | Every load-bearing value is invoiced, measured, or quoted | +| `projected` | The conclusion rests on values projected from observations | +| `indicative` | The conclusion is no stronger than an estimated or assumed value | +| `insufficient` | At least one load-bearing value is unknown | + +This is the seam to existing ITC-GOV vocabulary: Evidence supports an Assertion; +a DecisionGrade states how far that support actually reaches. + +--- + +## Worked evidence from the consumer + +The mechanism was applied to the consumer's own most consequential decision — +the provider selection that produced its backup resource, a €29.14 per month +difference stated to the cent: + +``` +by_basis {quoted: 1, projected: 1, assumed: 2} +weakest assumed +evidenced_ratio 0.25 +grade indicative +``` + +One of four load-bearing values is evidenced. The two labour figures — the ones +that actually inverted the provider ranking — are each `derived` from an +`assumed` hour count and an `assumed` rate, so both resolve to `assumed`. + +The finding did not overturn the decision: the direction is robust under any +plausible rate. It did establish that the *magnitude* is a model output rather +than a measurement, and it identified the cheapest way to strengthen it — +record real operator hours, not refine the arithmetic. + +A mechanism whose first act is to qualify its author's own headline number is +behaving correctly. + +--- + +## Proposed placement + +**Owner: ITC-GOV.** `EvidenceBasis`, `derived_from` and its propagation rule, +the unknown rule, `proxy_for`, and `DecisionGrade` sit beside Evidence, +Assertion, and Attestation in §11.34–11.36. They describe the epistemic status +of information, which is ITC-GOV's ground. + +**Import: ITC-CAP.** `CapabilityConsumption` gains an evidence basis per row. +It already distinguishes unknown from zero, which is the same discipline applied +to presence; basis applies it to the values that *are* present. `CAP-R8` would +be joined by a rule that a consumption row declares its basis. + +**Also imports:** ITC-OBS (a measurement is `measured`; a modelled series is +`projected`), and any model carrying quantities that consumers compare. + +**Avoid:** defining this only in ITC-CAP. It is not about capabilities, and +scoping it there would force a second, incompatible vocabulary the first time a +non-capability quantity needs grading. + +--- + +## Success criteria + +1. A closed basis vocabulary with tiers, not a spurious total order. +2. A stated propagation rule for derived values, computable and testable. +3. Unknown carries no quantity and names its gap and owner; zero is a + measurement. +4. `proxy_for` expressible and orthogonal to strength. +5. Decision grades defined against existing Assertion semantics. +6. `CapabilityConsumption` imports the basis without ITC-CAP owning it. +7. `resource-control` can drop its private vocabulary in favour of the canon's + without changing any recorded value. + +--- + +## Non-goals + +- Booked-cost, tax, or currency semantics. `invoiced` names a financial fact; + it does not define one. +- A confidence interval, probability, or statistical error model. Basis is + categorical provenance, not quantified uncertainty. A value may be `measured` + and still be a single noisy sample — age and sample size are separate + qualifiers and the canon should not conflate them with basis. +- A data-quality scoring or maturity scheme for datasets. +- An automated inference of basis. It is declared by the author of the value. diff --git a/demand/ProvisionRelationships.md b/demand/ProvisionRelationships.md new file mode 100644 index 0000000..0199986 --- /dev/null +++ b/demand/ProvisionRelationships.md @@ -0,0 +1,120 @@ +# Demand: Provision-to-provision relationships — which provision satisfies a dependency + +**Status:** inbound demand (un-reviewed) +**Date:** 2026-08-15 +**Source:** resource-control (consumer), domain `financials` +**Proposed owner:** `ITC-CAP` (§4.7 CapabilityProvision, §7 Relationships) +**Requested by:** info-tech-canon, in reply to the ITC-CAP restatement, 2026-08-15 +**Consumer evidence:** `resource-control/data/capability/platform-audit-storage.json` +**Proposed workplan:** `ITC-WP-0014` follow-on + +--- + +## Demand signal + +`ITC-CAP` §7 declares relationships at two levels: + +- capability to capability — `depends_on`, `may_use`, `composes`; +- landscape or consumer to capability — `requires`, `provides`, `implements`, + `consumes`. + +There is no relationship **between provisions**. The catalog can say that +`data.backup` `depends_on` `data.object`, but a provision cannot say *which +provision of `data.object` satisfies that dependency for it*. + +That matters because the dependency is where the operational and economic facts +live. `data.backup depends_on data.object` is a statement about abilities. +"This backup provision depends on the Scaleway bucket in nl-ams, and would be a +different risk and a different cost against a different one" is a statement +about the world, and it is the one a consumer needs. + +## How the gap surfaced + +info-tech-canon found it while reviewing the consumer's restatement, and named +it precisely: + +> The `P` row for credential custody is the wrong kind. `P` is purchased +> platform. What you needed is a provision naming that it uses +> `security.secrets` / depends on another provision. `depends_on_provision` is +> the right idea for the object-store layering; stuffing secrets into +> `consumes:P` is the leftover. + +That is an accurate diagnosis of a consumer error. The backup provision uses +`security.secrets` — an OpenBao `ClusterSecretStore` and a synced +`ExternalSecret` — and the consumer recorded it as one unit of class `P` +consumption. Nothing is purchased there. Using another capability is not +consuming platform capacity, and the record said it was because the model +offered no other place to put it. + +The consumer has removed that row. The relationship is currently held in a field +marked explicitly as **not canon**, pending this demand. + +## Why it will recur + +The mis-recording is the predictable result of the gap, not a one-off slip. Any +provision that uses another capability without buying capacity — secrets, +scheduling, observability, identity — has the same problem, and `consumes` is +the only structured list available. Left unaddressed, `P` slowly becomes a +dumping ground for "depends on something", and the class that finding C just +narrowed to purchased platform services widens again by usage. + +--- + +## Proposed shape + +A provision may declare which provisions it relies on: + +```yaml +provision: + provider: backup.barman.prod + capability: data.backup + uses_provisions: + - capability: data.object + provider: object.scaleway.nl-ams + relation: depends_on + - capability: security.secrets + provider: openbao.reef-railiance + relation: uses +``` + +- `relation` reuses the existing capability-to-capability vocabulary — + `depends_on` and `may_use` (or `uses` as its provision-level spelling). No new + relationship semantics are introduced. +- A `depends_on` entry SHOULD correspond to a `depends_on` declared between the + two capabilities in the catalog; a `may_use`/`uses` entry SHOULD correspond to + a declared `may_use`. This makes the provision graph checkable against the + capability graph rather than free-form. +- Naming the provider makes maturity traversable: a provision cannot honestly + claim reliability above that of a provision it depends on, which is a rule the + canon may or may not want to state. + +## What it is not + +It is not consumption. `consumes` records resource classes drawn in native +units; `uses_provisions` records which other provision supplies an ability. The +distinction is exactly the one that CAP-R8 and finding C established for classes, +applied one level up. + +--- + +## Success criteria + +1. A provision can name the provisions it depends on or uses, with a relation + drawn from the existing capability-to-capability vocabulary. +2. The provision graph is checkable against the capability graph. +3. Using another capability is expressible without a consumption row, so `P` + stays purchased platform capacity. +4. `resource-control` can drop the `proposed_extensions` marker from + `data/capability/platform-audit-storage.json` and record both the object-store + dependency and the secrets usage in canon terms. + +--- + +## Non-goals + +- Provider or service identity semantics — ITC-LAND owns those; this names them + by reference. +- A deployment or topology model. +- Automatic maturity derivation across a dependency chain. Whether a provision's + maturity is capped by its dependencies is a separate question, raised here only + because this relationship is what would make it askable.