tegwick
580b70df7e
File the consumption-lineage / entitlement / intelligence-cost demand for info-tech-canon. T01–T06 stay done; this does not patch the canon.
150 lines
6.8 KiB
Markdown
150 lines
6.8 KiB
Markdown
# 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`.
|