fin-hub/docs/demand-capability-consumption-lineage.md

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; docs/ai-plan-token-effectiveness.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.