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.

workplans/FIN-WP-0007-ai-plan-token-effectiveness.md

@@ -4,7 +4,7 @@ type: workplan
 title: "AI plan cost, token estimates, and effectiveness"
 domain: financials
 repo: fin-hub
-status: proposed
+status: active
 owner: grok
 topic_slug: financials
 created: "2026-08-15"
@@ -12,7 +12,9 @@ updated: "2026-08-15"
 related:
   - FIN-WP-0002
   - FIN-WP-0004
+  - FIN-WP-0006
   - STATE-WP-0045
+  - RESOURCE-WP-0003
   - ITC-CAP-0.2.0
 origin: assessment
 origin_ref: "info-tech-canon 0.3.0 review — AI token data-gap"
@@ -44,22 +46,34 @@ wait for a new commerce or intelligence domain model.
 
 ## Boundaries
 
+Checked 2026-08-15 against resource-control SCOPE, INTENT, procurement
+terms §4.1/§6, their v0.1 ratification, evidence-basis vocabulary, and
+the backup capability restatement. Design note:
+`docs/ai-plan-token-effectiveness.md`. Contract v0.1 is not silently
+amended; the addendum in that note is offered, not assumed.
+
 | Concept | Authoritative writer | Fin-hub role |
 | --- | --- | --- |
 | Provider invoice / plan subscription charge | fin-hub | Book once as `booked_cost` |
 | Recurring plan as a financial commitment | fin-hub | Record cadence and amount; not usage |
 | Plan entitlement (included tokens or plan capacity) | fin-hub | Commercial fact, same discipline as engagement prices |
-| Session token evidence (`measured` / `allocated` / `estimated` / `superseded`) | State Hub (`STATE-WP-0045`) | Consume aggregates; do not re-parse sessions |
-| Technical infrastructure usage and resource identity | resource-control | Out of scope here (class `S`/`C`/`P`, `FIN-WP-0004`) |
+| Intelligence / infrastructure `resource_id` | resource-control | Join when they publish one; never invent |
+| Provision-level class `I` usage | resource-control (gap they already own) | Consume via `FIN-WP-0004` when emitted |
+| Session token evidence (`measured` / `allocated` / `estimated` / `superseded`) | State Hub (`STATE-WP-0045`) | Join as session-token evidence; do not store as `usage_observation` |
+| Technical allocation of a portfolio resource | resource-control | Consume `AllocationEvidence`; do not emit it |
 | Work done (tasks, progress, outcomes) | State Hub / domain repos | Join key for effectiveness; not a cost driver |
+| Reporting allocation of a plan invoice across work | fin-hub | Local `FIN-WP-0002`-family derivation |
 | Implied €/token and work-per-token / work-per-euro | fin-hub | Reporting overlay; never a booked price |
 | Vendor parsers, transcripts, model names, list prices | State Hub / llm-connect / operators | Not invented here |
 
-Reuse `docs/fin-resource-authority-contract-v0.1.md` shapes
-(`booked_cost`, `usage_observation`, `AllocationEvidence`). Resource-control
-is the wrong *producer* for AI-session usage; the *envelope* is the right
-one. A new AI-plan producer (State Hub aggregates, plus fin-hub's own
-entitlement and booked facts) fills that role.
+Reuse the *discipline* of contract v0.1 (unknown is not zero, residual
+visible, estimates are not booked). Do not impersonate resource-control
+record types for agent-session telemetry or work-effectiveness shares.
+
+Founder-private AI plans may be booked for runway. They stay
+`resource_id=null` and must not silent-default `financial_entity_id`
+until the spend is booked to an entity and, if Railiance-procured, a
+resource.
 
 ## Non-goals
 
@@ -67,6 +81,9 @@ entitlement and booked facts) fills that role.
 - Completing the Scaleway `platform:audit-storage` booked-cost round trip
   (`FIN-WP-0004-T05`). That is class `S`, not class `I`.
 - Owning session parsers or storing transcripts.
+- Inventing a `resource_id` or metering tokens against a provision.
+- Emitting `usage_observation` or `AllocationEvidence` as if this repo
+  were resource-control.
 - A canonical token↔hour or token↔euro exchange rate (ITC-CAP forbids
   asserting one; substitution is observed from the time series).
 - A new definition of “work” beyond joining to existing task / progress
@@ -99,7 +116,7 @@ estimator method starts a new series.
 
 ```task
 id: FIN-WP-0007-T00
-status: todo
+status: done
 priority: high
 state_hub_task_id: "5e9bccfd-569a-43a2-b016-afed760add49"
 ```
@@ -117,11 +134,21 @@ Done when the note is committed, `SCOPE.md` matches the boundary, and
 no task below has an ambiguous owner for booked cost, entitlement,
 session tokens, or work.
 
+Completed 2026-08-15: boundary-checked against resource-control SCOPE,
+INTENT, Terms §4.1/§6, their contract ratification, evidence-basis, and
+the backup restatement. They own intelligence *resource* identity and
+provision-level class `I` metering (not yet implemented). Session
+telemetry and work-effectiveness stay outside that. Note:
+`docs/ai-plan-token-effectiveness.md`. `SCOPE.md` and `INTENT.md`
+updated. T04/T05 rewritten so fin-hub does not impersonate
+`usage_observation` or `AllocationEvidence`. Proposed v0.1 addendum
+offered to resource-control; not assumed.
+
 ## Stop treating missing tokens as zero
 
 ```task
 id: FIN-WP-0007-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "aefa287e-0e4d-40b1-adf6-a8e6df7caeb2"
 ```
@@ -139,6 +166,11 @@ Done when the existing fixture still parses, a missing-token fixture
 does not emit zeros, and CAP-R8 (`unknown` never stored as zero) holds
 on the token path.
 
+Completed 2026-08-15: `parse_optional_token_count` treats empty as
+unknown and `0` as measured none. `TokenSpend.tokens_in/out` are
+nullable with no zero default. Ledger import of a cost-only Anthropic
+row still books the amount and does not invent token quantities.
+
 ## Book AI-plan invoices as facts and commitments
 
 ```task
@@ -186,7 +218,7 @@ invent a token ceiling.
 Done when a plan month can be reported as booked euros + entitled
 capacity (or explicit unknown) without reading session logs.
 
-## Consume State Hub token aggregates as usage observations
+## Join State Hub session-token aggregates
 
 ```task
 id: FIN-WP-0007-T04
@@ -195,21 +227,28 @@ priority: high
 state_hub_task_id: "29f1804f-a5ad-46b6-b9d7-8f074e31b04e"
 ```
 
-After T00, ingest State Hub token summaries as `usage_observation`
-records (or a compatible typed sibling). Preserve `measurement_kind`
-(`measured`, `allocated`, `estimated`, `superseded`), period, model,
-repo/workplan association, confidence, and coverage. Do not re-parse
-Codex/Claude/Cursor/Grok session files in this repo.
+After T00, ingest State Hub token summaries as **fin-hub session-token
+evidence**, not as resource-control `usage_observation`. Preserve
+`measurement_kind` (`measured`, `allocated`, `estimated`,
+`superseded`), period, model, repo/workplan association, confidence,
+and coverage. Map kinds onto the resource-control evidence-basis
+vocabulary (`measured` / `derived` / `estimated` / excluded /
+`unknown`). Do not re-parse Codex, Claude, Cursor, or Grok session
+files. Do not invent a `resource_id`.
+
+If resource-control later inventories a Railiance-procured
+intelligence resource and emits `usage_observation` for it, consume
+that through the existing `FIN-WP-0004` planning-evidence path.
 
 Superseded rows must not enter totals. Estimated and measured must
 remain separable. Months with no State Hub events produce an explicit
 unknown residual, not a zero-consumption observation.
 
 Done when a recorded fixture of mixed measured/estimated/superseded
-aggregates stores as usage evidence, reconciles by kind, and cannot be
-posted as booked spend.
+aggregates stores as session-token evidence, reconciles by kind, and
+cannot be posted as booked spend or as resource-control usage.
 
-## Allocate booked plan cost across work
+## Reporting-allocate booked plan cost across work
 
 ```task
 id: FIN-WP-0007-T05
@@ -219,17 +258,23 @@ state_hub_task_id: "db098143-90b7-475c-8846-e4c274e50b4a"
 ```
 
 After T02 and T04, allocate each AI-plan `financial_fact_id` across
-repos/workplans using `AllocationEvidence`: named method, shares, and
-explicit residual. Allowed first methods: measured-token share,
-measured+estimated-token share, session-count share, even split.
-Method and estimator version are part of the record identity.
+repos/workplans as a **fin-hub reporting allocation** (same family as
+`FIN-WP-0002` billing basis). This is not resource-control
+`AllocationEvidence` and must not be posted as technical allocation.
 
-Shares plus residual must equal 1. Unattributed and unmeasured shares
-stay visible. Allocation never writes a new booked fact.
+Allowed first methods: measured-token share, measured+estimated-token
+share, session-count share, even split. Method and estimator version
+are part of the record identity. Shares plus residual must equal 1.
+Unattributed and unmeasured shares stay visible. Allocation never
+writes a new booked fact.
+
+Technical allocation of a portfolio resource remains
+resource-control's job and only applies when they have published a
+`resource_id`.
 
 Done when a one-plan, two-workplan fixture reconciles to the booked
-effective amount, names its method, and keeps residual when coverage
-is incomplete.
+effective amount, names its method, keeps residual when coverage is
+incomplete, and is not stored as `AllocationEvidence`.
 
 ## Publish an effectiveness report