feat: bound AI-plan work to resource-control and stop zeroing missing tokens

Record the FIN-WP-0007 split after checking resource-control: they keep
intelligence resource identity and provision-level class I metering;
session tokens stay with State Hub; work-effectiveness is a reporting
join. Missing token counts are now unknown, not zero.

docs/ai-plan-token-effectiveness.md

@@ -0,0 +1,142 @@
+# 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. A month whose coverage is incomplete is
+`insufficient` for trend comparison, not interpolated.
+
+## 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.