fin-hub/docs/ai-plan-token-effectiveness.md

AI plan cost, token estimates, and effectiveness

Status: fin-hub design note for FIN-WP-0007-T00 Checked against: resource-control SCOPE.md, INTENT.md, docs/TermsOfResourceProcurement.md §4.1 and §6, docs/fin-hub-resource-control-contract-v0.1.md, docs/evidence-basis.md, data/capability/platform-audit-storage.json (2026-08-15), and the ratified fin-hub contract docs/fin-resource-authority-contract-v0.1.md.

This note records the authority split. It does not amend contract v0.1. A proposed addendum is at the end for resource-control to accept or reject.

Why a second check was required

FIN-WP-0007 first treated resource-control as the wrong producer for any AI-token number. That is too coarse.

Resource-control already names intelligence as a Railiance-procured resource class — “commercial model APIs, reserved weights, inference hosts” — and records class I consumption on a provision as their gap (owner: resource-control), with unknown never stored as zero. They do not yet inventory any AI plan, and they do not parse coding sessions. Those two facts have to stay separate.

Four quantities, four writers

Quantity	Native unit	Authoritative writer	Fin-hub may
Booked plan / API invoice	currency	fin-hub	Book once as booked_cost
Recurring plan as commitment	currency / period	fin-hub	Record; not usage
Plan entitlement (included tokens or plan label)	token or declared capacity	fin-hub	Commercial fact, same discipline as engagement prices
Intelligence resource identity	resource:…	resource-control	Join when present; never invent
Provision-level class I usage	token	resource-control, when they meter a named provision	Consume via FIN-WP-0004 usage_observation
Session token evidence	token	State Hub (STATE-WP-0045)	Join as session-token evidence
Technical allocation of a portfolio resource	share of a referenced fact	resource-control	Consume AllocationEvidence; do not emit it
Work done	task / outcome	State Hub / domain repos	Join key, not a cost driver
Reporting allocation of a plan invoice across work	share of a referenced fact	fin-hub	Local reporting derivation (FIN-WP-0002 family)
Implied €/token and work-per-token / work-per-euro	derived	fin-hub	Overlay only; inherit the weakest input basis

Session telemetry is not platform telemetry. Contract v0.1 says technical usage is sourced from platform telemetry and written by resource-control. Agent-session counts from State Hub therefore must not be stored as resource-control usage_observation.

Reporting allocation of an invoice across workplans is not technical allocation of a portfolio resource. Contract v0.1 keeps allocation method and driver with resource-control. Fin-hub already has a reporting-only consumer for that evidence (FIN-WP-0002-T03). Work effectiveness uses a local reporting allocation and must not be posted as AllocationEvidence.

When a resource_id exists

If resource-control later inventories a Railiance-procured intelligence resource (API account, reserved weights, inference host, or license):

• fin-hub books the invoice and may attach the resource-control resource_id they published;
• resource-control owns usage and technical allocation on that resource, including class I tokens against the provision;
• fin-hub still owns entitlement, burn, runway, and the work-effectiveness report.

Until that inventory row exists, resource_id stays null. A null join is a visible gap, not a license to mint resource:anthropic:claude-max.

Financial entity

Resource-control requires every expense, estimate, and usage observation to carry exactly one financial_entity_id, or an explicit null with a named gap. Founder-private cards and uncleared Auslagen stay outside their terms until booked to an entity and a resource.

Fin-hub may still book those invoices for runway. It must not silent-default the entity to Railiance or Binky, and it must not pretend a private plan is a Railiance-procured resource.

Measurement layers and estimates

Keep these records separate, joined by period, provider/plan, and optional workplan/repo/resource_id:

1. booked plan cost
2. entitlement (or explicit unknown capacity)
3. consumption of class I, each row marked with how it was obtained
4. work done

Reuse resource-control’s evidence-basis vocabulary rather than inventing a dialect: invoiced, measured, quoted, derived, projected, estimated, assumed, unknown. Unknown carries no quantity. Zero means measured and none.

State Hub measurement_kind maps as:

State Hub	Evidence basis used here
measured	measured
allocated	derived (from a measured parent; method required)
estimated	estimated
superseded	excluded from totals
no events	unknown residual, not a zero observation

A derived overlay (implied €/token, work per token) is only as strong as its weakest input. Coverage is measured / (measured + estimated). A month whose coverage is below 0.50 is unfit for token-series trend comparison, not interpolated. The effectiveness report publishes three series — work per measured token, work per measured+estimated token, and work per euro — and never a blended efficiency number.

What fin-hub will not do

• Invent resource identity or provider-resource identity.
• Meter tokens against a portfolio provision.
• Parse Codex, Claude, Cursor, or Grok session files.
• Emit usage_observation or AllocationEvidence as if it were resource-control.
• Collapse tokens into euros at capture time.
• Store missing tokens as 0.
• Treat a plan entitlement as an invoice, or an implied €/token as a price.

Proposed contract addendum (not ratified)

Offer to resource-control, without changing v0.1 until they accept:

1. Intelligence resources remain in their portfolio when Railiance procures them. Class I on a provision stays their meter.
2. Agent-session token events stay with State Hub. Fin-hub may join them for financial reporting; that join is not technical usage.
3. Work-effectiveness allocation of a booked AI-plan fact is a fin-hub reporting derivation and is not technical allocation.
4. A booked AI-plan fact may carry resource_id=null until they publish one. Fin-hub will not mint a surrogate.

FIN-WP-0004-T05 (Scaleway platform:audit-storage booked-cost round trip) is unchanged and is class S, not class I.

Offered to resource-control on 2026-08-15 as State Hub message 4e75cd00-87f1-46e1-8d17-9169289640a2. Not assumed until they accept, reject, or name a conflict.