Skip to content

v5.09 — Usage is counted once per response and stated in one unit, so a release's cost can be recorded

Choose a tag to compare

@cody-hutson cody-hutson released this 16 Nov 22:51
Immutable release. Only release title and notes can be modified.
v5.09
1c2130c

Usage is counted once per response and stated in one unit, so a release's cost can be recorded

2026-11-16 · v5.09

The usage extractor now counts each API response once instead of once per transcript line, and flags a response whose output was only partly written. Usage is converted to one unit — weekly points of one account — through a single conversion, so the usage report, the release-cost row and the command-template ranking all state cost the same way.

Skip the rest unless you read the FinOps usage report, record or compare what a release cost, or run the usage scripts in your own sessions.

Who this affects

  • Operators who read usage figures from the FinOps usage extractor or its report
  • Anyone who records or compares what a release cost
  • Operators whose sessions run the new conversion or ranking scripts, which the script guard allows only after the next update (see Known limits)

What changed for everyone using the platform

  • Each API response is counted once. The extractor used to count every assistant line in a transcript, which over-counted responses by 1.8 to 3.4 times. It now counts one row per response. Why it matters: usage figures are no longer inflated by how a response happened to be split across lines.

  • A partly written response is flagged, not quietly under-counted. When only part of a response's output count was written, the response is marked incomplete and the report says how many responses could not be fully read. Why it matters: a low output figure is shown as a lower bound rather than passed off as exact.

  • The usage report reads real stores. The report used to reject every real store because of how it checked start times. Why it matters: the report now runs on the data it was written for.

  • Cost is stated in one unit. Token usage converts to weekly points of one account through one conversion, at both ends of the cache-read weight range, and the decision is recorded in ADR-240. Why it matters: two figures from different tools can be compared, because they are the same unit computed the same way.

  • Each release can carry its own cost row. The release velocity tool builds a usage row by stage, role and token type through that one conversion. Why it matters: what a release cost can be recorded beside how long it took, instead of being estimated after the fact.

  • Retyped command templates are ranked by cost. A new ranking script lists the commands sessions retype most, with their cost in the same unit, as input for deciding which to turn into scripts. It keeps transcript text out of its output. Why it matters: the most expensive repeated work is visible without exposing what the sessions said.

Known limits

  • The two new scripts — the usage conversion and the command-template ranking — are refused by the script guard until a workspace runs ./update.sh, which refreshes the guard's allowlist and its shared resolver library.
  • Writing the release-cost row automatically at close-out is not part of this release; until #9004 lands, the row is written by hand into the install's usage-telemetry home.
  • The extractor does not yet count advisor and fallback sub-call usage (#9032), and a response repeated in a resumed or forked transcript file is counted again (#9033). The report does not yet show the lower-bound label or the count of unread responses (#9035), and thinking is counted inside output with no separate figure (#9036).
  • The model-use decision and the probes it rests on moved to the next milestone with their two cards, #7935 and #8041, after the probe window read degraded.
  • The usage store's schema moved to a new major version; an existing store is rebuilt the next time the extractor runs, because rebuilding is its default.

Report issues at https://github.com/cody-hutson/pmo-platform/issues, and report a suspected vulnerability privately as the Security Policy describes.

Reversibility

MODERATE / MEDIUM. Reverting the single release merge and rebuilding the usage store restores the previous counting, because the store is a derived cache; ADR-240 would be superseded rather than deleted, and the version tag is kept as the record that the version was claimed.


Operator and engineering detail

Counting (#7937, #7938). extract-usage.sh keys each row on the response's message identifier, so a response written across several assistant lines is one row, and it marks a response incomplete when its final output count was never written. The store schema's major version advanced, with the measured corpus factors cited in core/schemas/finops-usage-store-schema.md.

The report (#7939). report-usage.sh accepts start times with fractional seconds, which every real store carries.

The unit (#7940, ADR-240). One account's weekly points, counted once per API response and attributed to the release run graph's four elements. convert-usage.sh is the one conversion from per-response token totals to weekly points, and it states both ends of the cache-read weight bracket. The release's first calibration revisit re-confirmed Decisions 1 and 3 and moved no calibrated value. ADR-240 was ratified at this release's Stage 13.

The cost row (#7943). compute-release-velocity.sh gains a cost-row mode built on convert-usage.sh. Under the Stage 9 Operator Override Record, the automatic write at close-out and its stage text moved to #9004, which is blocked by #8019 and #8022.

The ranking (#7945). rank-command-templates.sh ranks retyped command templates by cost. Its privacy controls run first: planted-leak fixtures in its self-test fail every privacy arm, and its report stays under the analysis home.

How it shipped. Six cards on one branch. Two further cards, the model-use decision (#8041) and its probe card (#7935), moved to the next milestone at Engineering when the probe window read degraded. A sibling release merged first and took ADR-239 and v5.08, so this release's decision record was renumbered to ADR-240, its provisional version stamps moved to v5.09, and the branch merged main twice before its merge at 1c2130c5. The release claimed v5.09 with a signed annotated tag, and the FinOps skill was deployed under the release's identity. The operator ran ./update.sh to publish the allowlist and the shared resolver to the guard tier.

For full implementation detail see the Deployment Log v5.09 entry in the release log, and the release plan.

References