The public API is frozen. A breaking change waits for 2.0. This is the last release in which anything can change shape without a major.
VERSIONING.md now states what that covers and, as importantly, what it does not — and it states the deprecation procedure rather than leaving it to be decided case by case:
@deprecatedin the JSDoc, naming the replacement. That is the strike-through in an editor, which is the only warning most people will ever see.- A Deprecated section in that release's changelog, with the migration written out — the actual before-and-after, not "use the new thing".
- Continues working for at least two minors and six months, whichever is longer. Deprecating and removing in consecutive releases is a breaking change wearing a notice.
- Removed only in a major, whose changelog repeats the migration.
A deprecated export never starts warning at runtime. A library that prints to somebody else's stderr because we changed our mind is a library people vendor to make quiet.
Newly named as covered, because they were being depended on either way: the
--json shape and units, the CLI's exit codes, @trazum/core/node as a real
entry point, and the trazum.config.json and pricing-overlay schemas. Newly named
as not covered: the prose and layout of the human reports — parse --json, not
the table.
Publishable#
Both packages would previously have shipped something wrong. Now asserted by
tests in publish.test.js, because a published package is the one artefact this
repository cannot take back:
- A
LICENSEfile, not just a"license"field. The field is metadata; the tarball has to carry the terms or nobody who installs it has been given them. - A README. The npm page is the README, and both were empty.
engines. Without it npm installs silently on a Node too old to run the code, and the failure surfaces as a syntax error in somebody else's build.prepublishOnly, which builds and tests.files: ["dist"]means the tarball is whatever happens to be on disk, so publishing without building would have shipped the previous version's code under the new version's number — completely silently, and the worst possible outcome.src. Every emitted source map references../src/*.tsand carries no inlined content, so shipping the maps without the sources gave a debugger a file it could not load. That is worse than no map, which would simply step through the compiled output. It also means you can read exactly what runs on your prompts, which for a zero-dependency library is rather the point.
Publishing itself stays manual. It is the one action here that cannot be undone after 72 hours.
A rule can be contributed without reading the engine#
New docs/authoring-rules.md: the four-line rule
contract, what the masking pass already guarantees (a rule cannot break code,
URLs or placeholders because those characters are not in the string it receives),
why safe is a promise rather than a default, and the three tests a rule
needs — the third being the false-positive case nearly everyone skips.
It also documents the ReDoS fixture shape that finds real bugs. Repeated tokens do not: both bugs found in this repository needed a prefix plus a long non-terminating run, and the fixtures that missed them were all repeated words.
CONTRIBUTING.md's security-invariant list said "four things" and had drifted to
eight. Corrected, with the import-graph invariant and the two Actions ones added.
Pricing came off the release cycle#
Prices change on someone else's schedule, and until now correcting one meant upgrading the library — which is backwards: a stale price is a wrong number in a budget decision.
A pricing overlay is a JSON file layered over the bundled catalogue:
{ "lastReviewed": "2027-01-15",
"models": { "claude-opus-5": { "inputPerMTok": 6 } } }Point at it with pricing in trazum.config.json or --pricing <file>. The
bundled catalogue stays the default, so Trazum is still correct out of the box
and needs no setup.
- A separate
@trazum/pricingpackage would not have solved this. You would still need to install something to get current numbers. A JSON file in your own repository actually decouples it, and keeps both properties that matter: the core still makes no network call, and it still has no dependencies. - The catalogue is a value, not module state.
applyPricingOverlayreturns a new catalogue; nothing mutates. A caller who overlays prices does not change what any other caller sees, which is what stops one consumer's local prices leaking into another's report — and what makes it testable at all. - Every report says when overlaid prices were used, and for which models.
Without that, a figure from the bundled catalogue and a figure from somebody's
JSON file look identical.
OptimizationResultgainspricingSource. lastReviewedis required in an overlay, and becomes the catalogue's date. An overlay of unknown age is worse than the bundled catalogue, whose age is printed on every report; and claiming the bundled date over corrected prices would be a lie about provenance.- Overriding a known model needs only the fields that changed. Introducing a
model needs all of them, because a half-defined model would price at nothing
and report a saving that does not exist.
"promo": nullwithdraws a promotion that ended early. withExactTokenCountsthrows if a result was priced against an overlay and the same catalogue is not passed back. Silently reverting to bundled prices would make the token counts and the money come from different sources, with nothing in the report to show why.cheapestOfTierInranks a tier on the effective price, so a model inside a promotional window is compared at what it actually costs today.- Validation is as strict as the config parser's, same reasoning: a typo'd
inputPerMtokwould silently price against the bundled number, and a budget decision made on a price nobody applied is the whole failure being prevented. usage.modelvalidation moved fromparseConfigtoloadConfig. An overlay can introduce a model, and the path to the overlay is a key of the very document being parsed — so the parser cannot know the catalogue yet. The check is still loud, just raised where "unknown model" can be answered truthfully.- Tests grow from 390 to 406, including a new
publish.test.jssuite.
Every third-party GitHub Action is now pinned to a commit SHA. SECURITY.md
listed this as a known limit; it no longer is. A tag can be moved and a branch
moves by design, so @v3 means "whatever that publisher pushes there next", with
the caller's token and secrets in scope.
- The sharpest case was
actions/dependency-review-action@v5, whose majors are published as branches rather than tags — a reference that is designed to move. (Worth recording: I first read the tag list and concluded@v5did not resolve at all. It does —refs/heads/v5— and the branch is the point.) - Pinning only freezes a version if nothing bumps it.
.github/dependabot.ymlalready has agithub-actionsentry, and the trailing# vNcomment is what it matches on. - Two new invariants: every
uses:outside this repository must be a 40-character commit SHA, and every pin must carry a version comment. A pin with no comment is a line nobody can review and nothing will ever update.