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.

Canon demand (T07, does not block T01–T06) is
`docs/demand-capability-consumption-lineage.md`, filed at
`info-tech-canon/demand/CapabilityConsumptionLineage.md`, and sent as
message `8b0fd492-dac1-4fbe-bebb-efd52c601773`.