HF-307 PR 2: public API guards (ensureCapability) - #1729

Context

HF-307 (feature packages / entitlement gating). This is PR 2 of 4: guards on the public API. Stacked on hf-307-entitlement-gating-pr1 (#1728) - depends on CapabilityRegistry/allowsFeature/FeatureId/Config.licenseCapabilities from that PR. Mechanical, public-repo-only, no key-format knowledge needed.

New:

• src/errors.ts - LicenseCapabilityMissingError, mirroring the existing ~30 error classes.
• src/HyperFormula.ts - private ensureCapability(feature: FeatureId), mirroring ensureEvaluationIsNotSuspended: a single isLicenseGateActive boolean read on the fast path, then allowsFeature against the resolved entitlement.
• src/BuildEngineFactory.ts - private static ensureNamedExpressionsCapability(config, namedExpressions), the build-time counterpart (task 2.3).

Modified: ensureCapability wired as the first statement (before argument validation - a license error should beat a type error) in the ~20 methods from spec §05 task 2.2:

• NamedExpressions: addNamedExpression, changeNamedExpression, removeNamedExpression
• Clipboard: copy, cut, paste
• Crud: addRows, removeRows, addColumns, removeColumns, moveCells, moveRows, moveColumns, addSheet, removeSheet, clearSheet, setSheetContent, renameSheet, setCellContents, swapRowIndexes, setRowOrder, swapColumnIndexes, setColumnOrder
• UndoRedo: undo, redo
• Batching: batch, suspendEvaluation — but not resumeEvaluation, see finding 4 below

CustomFunctions is not gated anywhere, per HF-307 decision D1. ImportExport has no methods to gate yet (HF-107).

Where the line is drawn (written into the ensureCapability JSDoc so a later change has to move it on purpose):

• Gated — mutations that create value: the sheet, the clipboard, the undo history, the named-expression set.
• Not gated — reads (getCellValue, listNamedExpressions, getAllNamedExpressionsSerialized, the isItPossibleTo* predicates) and teardown that only ever removes state (clearClipboard, clearUndoStack, clearRedoStack, destroy). Gating cleanup would let a restricted entitlement strand an integration mid-teardown while giving a licensee nothing. This mirrors gate B, which blocks calling a function rather than reading an already-computed value. There is a test pinning this, because "we chose not to gate cleanup" is otherwise indistinguishable from "we forgot these" — which is exactly how the reordering gap below survived the first pass.

Open question resolved: the handoff left "is getAllNamedExpressions gated or read-only-exempt?" open. There's no such method today (it's listNamedExpressions, getNamedExpression, getAllNamedExpressionsSerialized) - I left all three ungated. This follows gate B's own precedent: it blocks calling a function, not reading a cell's already-computed value, so a restricted entitlement can still see named expressions that already exist. Flagging for reviewers in case the intended scope was broader.

Task 2.3: BuildEngineFactory.ensureNamedExpressionsCapability runs the same allowsFeature(FeatureId.NamedExpressions) check when the namedExpressions argument to buildFromSheets/buildFromSheet/buildEmpty (what buildFromArray/buildFromSheets/buildEmpty resolve to) is non-empty; an empty list is never checked. Deliberately not applied to rebuildWithConfig - that path re-serializes named expressions an already-built instance was already allowed to create (e.g. on updateConfig()), rather than accepting them fresh from a caller, so a later entitlement change must not retroactively break an existing instance's own state.

This ships without a real license-key payload adapter (PR 3), so every entitlement Config can produce today is unrestricted - ensureCapability and the build-time check are correct, independently-testable no-ops in production until that adapter lands, exactly like gate B in PR 1.

Self-review findings (after the PR was first opened)

Recording these in the open rather than quietly amending, since several are things a reviewer should get to disagree with. Findings 4 and 5 came from Cursor Bugbot's inline comments and were confirmed here before fixing.

1. The Crud gate was bypassable — fixed in 8a26e2be7. The first pass gated moveRows/moveColumns but missed four structurally identical methods: swapRowIndexes, setRowOrder, swapColumnIndexes, setColumnOrder. A restricted entitlement with no Crud grant could still permute every row and column in a sheet, which defeats the gate for a whole class of structural mutation. All four are now gated in their own right rather than relying on the swap* method that the set*Order pair delegates to — otherwise set*Order's own mappingFromOrder validation would run first and a type error would beat the license error, violating task 2.2's first-statement rule.

2. ensureCapability checks gate B only, never gate A — deliberate, and now an explicit invariant. Today a missing or invalid key yields #LIC! in cells while the CRUD API keeps working; this PR preserves that exactly. The risk is forward-looking: if PR 3's key adapter resolves an invalid key to a restricted entitlement rather than an unrestricted one, every gated method here starts throwing and that becomes a silent breaking API change. This PR is what makes that reachable, so the invariant is documented at the guard itself. Reviewers: worth confirming this is the intended split before PR 3 lands.

3. Known evidence gap in the task 2.3 tests. The BuildEngineFactory gate is exercised by calling the private static directly, because the public path (buildFromArray(sheet, config, namedExpressions) → throws) cannot be reached today — the factories construct their own Config, and every Config currently resolves unrestricted. So Codecov's 100% patch coverage overstates the evidence for that one check: the integration path is unproven until PR 3 makes a restricted Config constructible. Flagging rather than papering over it.

4. Gating resumeEvaluation could brick an engine — fixed in c29a9ba40. Raised by Bugbot, confirmed. resumeEvaluation is the only exit from a suspended engine, and _evaluationSuspended survives rebuildWithConfig. So: suspend while Batching is granted → updateConfig produces an entitlement without Batching → the instance is permanently unusable, because every read throws EvaluationSuspendedError and the sole recovery path threw LicenseCapabilityMissingError. It is now ungated. suspendEvaluation and batch stay gated — those are the entry points that make the feature worth licensing, and if you cannot enter batching you can never extract value from it. Generalised into a rule on ensureCapability so it does not get re-added: a capability check must never be reachable only on the way out of a state it let the caller into — the same reasoning that leaves teardown ungated.

5. One of PR 1's tests was vacuous — fixed in the paired tests PR. Also raised by Bugbot. PR 1's custom-function-exemption test built the sheet with '=CUSTOMFUNC()' already in it, so the formula was evaluated during buildFromArray while the entitlement was still unrestricted; restrictEngine then changed nothing that getCellValue would re-read, and the assertion passed against a cached value. I verified this rather than assuming it — deleting the exemption from Interpreter.ts outright left the test still passing. It now writes the formula via setCellContents after restricting, matching the shape its sibling tests already had, and the same mutation now correctly fails it. The two new resumeEvaluation regression tests were verified the same way (re-adding the gate fails them).

Process note, since it generalises: Bugbot's findings 4 and 5 were missed by the automated review tier that scrapes them (a regex looking for Severity: Medium against Bugbot's actual **Medium Severity**), which reported a clean PASS. Worth reading Bugbot's inline comments directly rather than trusting an aggregator.

How did you test your changes?

• tsc --noEmit and tsc -p tsconfig.test.json: clean.
• eslint on all changed files: 0 errors (pre-existing warning categories only, none introduced by this change - confirmed against a clean HyperFormula.ts run).
• Manual verification against the built engine (ts-node scratch script, not committed): every gated method throws LicenseCapabilityMissingError under a simulated restricted entitlement, an unrestricted entitlement (today's default) is unaffected, and buildFromArray with named expressions under the default unrestricted entitlement does not throw.
• Private test suite pushed: hyperformula-tests#31 - unit/license/public-api-guards.spec.ts (21 tests: one positive + one negative per feature group, a validation-order test, the build-time bypass pair, five covering the reordering gap, one pinning the ungated-cleanup rule, and two for the resumeEvaluation deadlock) plus fixes to PR 1's unit/licence.spec.ts (the test-helper interaction described in that PR, and the vacuous exemption test in finding 5).
• Mutation-checked, not just green: the two resumeEvaluation tests fail if the gate is re-added, and the repaired custom-function test fails if the exemption is removed. Both were run.
• Full suite against the paired branch: 506 suites / 6225 tests, 6222 passed, 3 pre-existing skips, 0 failures.

Types of changes

• Breaking change
• New feature or improvement
• Bug fix
• Additional language file, or a change to an existing language file (translations)
• Change to the documentation

Related issues:

1. HF-307 (internal tracker; no public GitHub issue for this one)

Checklist:

• I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
• I have signed the Contributor License Agreement. (please confirm/attach on your end - I can't verify this from here)
• My change is compliant with the OpenDocument standard. (N/A - no worksheet function behaviour changes in this PR)
• My change is compatible with Microsoft Excel. (N/A - same reason)
• My change is compatible with Google Sheets. (N/A - same reason)
• I described my changes in the CHANGELOG.md file. (intentionally not done - internal-only change, no user-visible behaviour yet; a CHANGELOG entry lands with the PR that actually activates the gates for customers)
• My changes require a documentation update. (no - nothing user-visible yet)
• My changes require a migration guide. (no)