HF-306/HF-307: resolve both capability-token dialects from one group registry (8/8)

[marcin-kordas-hoc]

8/8 of the HF-307 stack, stacked on #1740. Pairs with hyperformula-tests#42 — merge the tests PR first.

Why

Two capability-token vocabularies exist for HyperFormula and the business choice between them is still open (D8, asked on HF-307 on 13.08, unanswered):

• the key spec / generator vocabulary — functions_1..4 package slices plus the spreadsheet/import_export add-ons. This is what upstream license-key@4.0.0's own schema mints today;
• the packaging doc vocabulary (§6, 12.08, linked from HF-307 by its author as "the list of capability tokens") — fun:all, 21 group tokens fun:<family>.<A|B|C>, and a single-function token fun:<CANONICAL_NAME> for every catalog entry.

Rather than bet on one, the engine now resolves both (owner's decision, 20.08). This is spec-clean: T7 defines an unrecognized token as "a grant this version does not implement", so implementing a superset breaks nothing — and whichever dialect keys end up minted in, they work without another engine release.

Design: one source of truth, two dialects reading from it

• The 21 groups are transcribed 1:1 from the doc's §6 into FUNCTION_GROUPS (members verbatim, operators and protected built-ins included, so a drift check can compare against the doc's published counts).
• The functions_1..3 package slices are now DERIVED from the groups as the doc's own cumulative unions (.A / .A+.B / .A+.B+.C), minus the operators (granted by core) and the protected built-ins. The derived memberships are pinned by name by the pre-existing capability-table.spec.ts lists, which is the consistency proof: derivation reproduces the previously authored lists exactly.
• fun:all grants byte-for-byte what functions_4 grants; the excel-simulator tail stays an authored list (the doc does not itemize it, and deriving it from the registry would gate user-registered functions — D1).
• fun:info.A / fun:lookup.A / fun:OFFSET / fun:VERSION resolve to empty grants: their members are the protected built-ins, which are always available and must never become table-covered. Recognized bookkeeping, exactly as the doc frames them ("technical limitation").
• Token matching is case-insensitive (the doc states it outright for fun:*; the other tokens tolerate it for free — nothing collides under lowercasing). Normalization happens at lookup; entitlements keep the key's own spellings as diagnostics.
• Alias-named tokens stay unrecognized: tokens reference canonical names, and an alias travels with its canonical function because the gates canonicalize before consulting the table (fun:STDEV.S accepts =STDEV(...)).
• Table entry order is load-bearing for capabilityOf's first-wins reverse index: the package slices stay ahead of the new tokens, so its answers are unchanged.

⚠️ A pinned behaviour is deliberately inverted

The 18.08 test "a key in the published fun:* vocabulary grants zero functions, silently" pinned a measured outcome pending D9. This PR resolves it the way the pin's own comment anticipated ("translate the vocabulary, warn, or reject — it has to change this test"): the vocabulary is now implemented. The inversion is by the owner's 20.08 decision, not a regression, and the replacement tests say so in place.

Risks, stated

• The group registry is one more artifact to keep in sync with the packaging doc — mitigated by the drift check (per-group counts from §6) and the by-name membership pins.
• This does not resolve the commercial 3-vs-4 package split (upstream's default schema sells Essential/Pro/Complete; the packaging doc describes four packages). Packages are generator-side data — the engine only ever sees tokens — so that's a myHOT/business call, not an engine one.
• If the business ultimately picks a single dialect, the other one becomes dead code — cheap to keep (it's derived data, one source of truth) or to remove.

Testing

unit/license + unit/helpers/licenseKeyValidator: 16 suites / 266 tests green; dialect-equivalence pinned per package (functions_N ≡ fun:* union, fun:all ≡ functions_1..4); tsc --noEmit and ESLint clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_019pxNP45obT2LZfjitaCv9o

---

Note

High Risk
Changes commercial license entitlement resolution and feature gating predicates; incorrect grants or fallback logic would block or over-grant API areas and functions for paying customers.

Overview
This PR unifies two license capability vocabularies so keys minted with either functions_1–functions_4 (and add-ons) or the packaging doc’s fun:all, fun:<family>.<A|B|C>, and per-function fun:<NAME> tokens grant the same function sets. The packaging §6 groups live in FUNCTION_GROUPS; functions_1–functions_3 memberships are derived from those cumulative group unions instead of hand-maintained lists.

Lookup behavior now uses normalizeCapabilityToken (trim + lowercase) everywhere the table is consulted, including CapabilityRegistry.resolve, which also drops queue.shift() for a read cursor to avoid O(n²) expansion on huge token lists.

License resolution fixes two edge cases: an unrecognized feat:* token no longer suppresses the “grant all five feature areas” fallback (only recognized feature tokens opt into explicit feature gating), and padded tokens like ' feat:crud' vs 'feat:crud ' no longer disagree between the feature-prefix rule and table lookup.

fun:all matches functions_4; protected built-ins (OFFSET, VERSION) and their group tokens stay recognized but grant nothing; table entry order preserves prior capabilityOf answers for package slices.

^{Reviewed by Cursor Bugbot for commit 6b23a40. Bugbot is set up for automated code reviews on this repo. Configure here.}

Spec-to-ship review (2026-08-20): 3 findings fixed here

1. An unrecognized feat:* token revoked the whole gated API instead of being inert. The
   feature opt-in trigger was a purely syntactic prefix test, so a token this version does not
   implement suppressed the "this key does not talk about features" fallback and left the key with
   zero of the five areas. Measured:

   key's capabilities	feature areas granted
   functions_1	5 / 5
   functions_1, feat:crud	1 / 5 — correct
   functions_1, feat:teleport (unknown)	0 / 5
   functions_1, feat:cruds (typo at issuing time)	0 / 5

   That inverts the additive-safety rule for the two cases that matter — an older build meeting a
   key from a newer generator, and a one-character typo when a key is minted — and it contradicts
   D3, which makes an unrecognized token silently ignored. The trigger now requires a feature
   token this version recognizes. Four tests pin both directions.

   Scope note for the reviewer: the defect predates this PR (it came in with the opt-in rule in
   PR 3/9) — the adversarial verifier correctly flagged that. It is fixed here because this PR
   rewrites that exact predicate to add case-insensitivity, and because leaving a known revocation
   bug in place while touching the line would be the wrong call.

2. Group membership was pinned only by COUNT. FUNCTION_GROUPS is the single source of truth
   for both dialects, but only the doc's per-group sizes were checked — so moving a function
   between two groups of the same tier letter changed what a fun:<family>.<letter> key grants
   while leaving every count, every derived package union and every other assertion identical.
   Demonstrated live: with EXP and MEDIAN swapped between fun:math.C and fun:stat.C, the
   whole license suite stayed green at 272/272. The 21 memberships are now checked by name
   against §6 of the packaging doc (the expected literal was generated by parsing the doc itself),
   and that check catches the swap.

3. Token expansion was quadratic, and whitespace split a token's meaning in two.
   CapabilityRegistry.resolve drained its queue with Array.prototype.shift — O(n) per call, so
   O(n²) overall: 1.4 s inside the constructor for a key with 100 000 tokens. Now a read cursor.
   Separately, normalizeCapabilityToken lowercased but did not trim, and the two rules that read a
   token disagreed for a padded one: ' feat:crud' failed the prefix test and was granted all five
   areas, 'feat:crud ' passed it and was granted none — neither was "crud". Normalization now
   trims, pinned by a test.

[qunabu]

Task linked: HOT-15413 Pick function sets for each HF product package
Task linked: HF-307 Implement feature packages and add-ons in HF

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	6b23a40	Commit Preview URL Branch Preview URL	Aug 26 2026, 03:39 AM

[github-actions]

Performance comparison of head (6b23a40) vs base (a425d37)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |  503.79 |  512.67 | +1.76%
                                      Sheet B |  170.14 |  169.29 | -0.50%
                                      Sheet T |   144.4 |   149.1 | +3.25%
                                Column ranges |  546.63 |  541.78 | -0.89%
                                Sorted lookup | 16123.6 | 15982.7 | -0.87%
Sheet A:  change value, add/remove row/column |   18.44 |   17.64 | -4.34%
 Sheet B: change value, add/remove row/column |   157.3 |  152.94 | -2.77%
                   Column ranges - add column |  172.18 |   169.9 | -1.32%
                Column ranges - without batch |  520.38 |   541.3 | +4.02%
                        Column ranges - batch |   135.8 |  133.12 | -1.97%

[Tobiadefami]

Reviewed at 4c8258e together with the paired tests at e2a35206. I checked the 21 group memberships against the captured packaging source, package and single-function equivalence across both token dialects, case and whitespace normalization, unknown feature-token inertness, protected built-ins, reverse-index ordering, hostile-token-list performance, documentation, changelog, and current automated findings. The 16 focused license suites pass (278 tests), TypeScript passes, all current engine checks are green, and I found no material issue in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.39%. Comparing base (a425d37) to head (6b23a40).

Additional details and impacted files

@@                       Coverage Diff                        @@
##           hf-329-entitlement-key-envelope    #1741   +/-   ##
================================================================
  Coverage                            97.38%   97.39%           
================================================================
  Files                                  204      204           
  Lines                                16233    16255   +22     
  Branches                              3482     3484    +2     
================================================================
+ Hits                                 15809    15831   +22     
  Misses                                 424      424           

Files with missing lines	Coverage Δ
src/license/CapabilityRegistry.ts	100.00% <100.00%> (ø)
src/license/capabilities.ts	100.00% <100.00%> (ø)
src/license/licenseResolution.ts	98.66% <100.00%> (+0.03%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.