demand: fin-hub CapabilityConsumption lineage and entitlement structure

Inbound consumer demand from FIN-WP-0007. Asks for a lineage qualifier
on CapabilityConsumption, commerce.entitlement/metering structure, and
dropping cost as an intelligence quality. No model change.

demand/CapabilityConsumptionLineage.md

@@ -0,0 +1,142 @@
+# Demand: Capability consumption lineage, plan entitlement structure, and intelligence cost quality
+
+**Status:** inbound demand (un-reviewed)
+**Date:** 2026-08-15
+**Source:** fin-hub (consumer), domain `financials`
+**Target artifacts:** `ITC-CAP` §4.12 `CapabilityConsumption`; `commerce.entitlement`, `commerce.metering` (OQ-5); `intelligence.generation` quality dimensions
+**Consumer evidence:** `FIN-WP-0007` T00–T06; `fin-hub/docs/ai-plan-token-effectiveness.md`
+**Consumer copy:** `fin-hub/docs/demand-capability-consumption-lineage.md`
+**Does not block:** `FIN-WP-0007` T01–T06 (already implemented against the current proposed model)
+
+---
+
+## Demand signal
+
+Consumer **fin-hub** owns booked financial facts, plan entitlements, and
+reporting overlays for AI-plan spend. It has just built a working dataset
+that joins:
+
+1. booked monthly plan invoices,
+2. entitled capacity (or explicit unknown),
+3. State Hub session-token aggregates (`measured` / `derived` / `estimated`
+   / excluded / unknown residual),
+4. work outcomes,
+
+without treating missing tokens as zero and without posting estimates as
+booked spend.
+
+ITC-CAP 0.2.0 / canon 0.3.0 was the vocabulary that made this possible:
+class `I` native unit `token`, unknown is never zero, currency is an
+overlay, no H↔I exchange rate. This demand is a request to refine a
+model that is already in use, not to replace one that is not.
+
+The three gaps below showed up the moment the dataset had to distinguish
+*how a token quantity was obtained* and *what a plan entitles*.
+
+---
+
+## Finding A — `CapabilityConsumption` has a quantity or `unknown`, and no lineage
+
+ITC-CAP §4.12 records one native-unit row on a provision. Unknown is
+allowed. That is necessary and not sufficient.
+
+Fin-hub now stores the same token total as:
+
+- measured (State Hub `measured`),
+- derived (State Hub `allocated`, method required),
+- estimated,
+- unknown residual (no includable events),
+- or a declared plan label with no quantity (Claude “Max 20×”).
+
+Those are different claims. A number without a qualifier cannot be
+compared across months: an effectiveness trend that mixes them is
+estimator drift. ITC-DATA already has the lineage states
+`declared / inferred / observed / verified / unknown` (and
+`conflicting`). Capability consumption should reuse that scale, not
+grow a local dialect.
+
+resource-control independently converged on an ordered evidence-basis
+(`invoiced` … `unknown`) for the same reason. Fin-hub maps State Hub
+kinds onto that basis. The canon should name the qualifier on the
+consumption row so both consumers point at one vocabulary.
+
+**Proposed:** every `CapabilityConsumption` carries a lineage or
+evidence-basis qualifier drawn from ITC-DATA (or an explicit mapping to
+it). Unknown remains a missing quantity, never zero. A declared plan
+capacity without a token ceiling is `declared` plus a label, not an
+invented integer.
+
+---
+
+## Finding B — `commerce.entitlement` and `commerce.metering` are still unanchored
+
+OQ-5 remains open for invoices and entitlements. Fin-hub had to invent
+a local plan-entitlement record (`token` / `multiplier` / `plan`,
+append-only revisions, unknown requires a label) because the catalog
+names the abilities and gives them no structure.
+
+What we needed, and implemented privately:
+
+- a plan-period entitlement that is not an invoice,
+- a meter that can be incomplete (coverage < 1 is a first-class
+  state, not a failed month),
+- a join of booked euros to entitled capacity that does not silently
+  cross currencies.
+
+That is `commerce.entitlement` (profiles `plan`, `capacity`) and
+`commerce.metering` (quality dimensions `accuracy`, `completeness`).
+Without an owning model, every financial consumer will grow a private
+entitlement schema.
+
+**Proposed:** enough structure — not a billing system — for plan
+capacity, incomplete meters, and the rule that a meter gap is not a
+zero reading. Invoices stay with fin-hub. This is OQ-5 firing for
+entitlements and meters, not for payments.
+
+---
+
+## Finding C — `intelligence.generation` lists `cost` as a quality dimension
+
+ITC-CAP §4.12 says currency is not a resource class and not a native
+unit. Collapsing tokens into euros at capture time is the defect the
+class set exists to prevent.
+
+`intelligence.generation` still declares quality dimension `cost`.
+That invites a provision to treat euros as a quality of generation,
+which fights §4.12 and `intelligence_intensity` (tokens per unit of
+output). Fin-hub’s effectiveness report keeps implied €/token as an
+*inferred overlay*, labelled as such, and refuses a blended
+efficiency number.
+
+**Proposed:** drop `cost` from `intelligence.generation` (and any
+sibling that copied it), or re-home it as a non-normative reporting
+overlay owned outside ITC-CAP. Keep `intelligence_intensity` as the
+quality of a provision that consumes `I`.
+
+---
+
+## What this demand is not
+
+- A request that InfoTechCanon own booked-cost semantics or ledgers.
+- A canonical token↔euro or token↔hour rate.
+- Vendor plan names, context windows, or list prices.
+- A patch from this repository. T01–T06 shipped against the current
+  proposed model and stay done regardless of this demand.
+
+---
+
+## Success criteria
+
+1. `CapabilityConsumption` can say how a native-unit quantity was
+   obtained, using ITC-DATA lineage states or a published mapping.
+2. A plan entitlement and an incomplete meter can be expressed in
+   canon terms without a private fin-hub schema.
+3. `intelligence.*` quality dimensions no longer name `cost` as if it
+   were a native quality of generation.
+4. Fin-hub can restate one AI-plan month — booked fact, entitlement,
+   measured/estimated/unknown tokens, work, three effectiveness
+   series — entirely in canon terms.
+
+Criterion 4 is offered as a second real-provision proof, this time
+for class `I`, alongside resource-control’s backup restatement for
+class `S`.