gatefit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-All notable Gatefit changes are listed here. The heading version matches `package.json`. Tag `v0.4.0` is not cut in this change.
+All notable Gatefit changes are listed here. The version heading matches `package.json`. Tag `v0.5.0` is not cut in this change.
+
+## [0.5.0] - 2026-10-16
+
+### Added
+
+- Chaos mode, a Pro pack. `gatefit run --suite chaos` replays every golden under seeded perturbations and compares the access row to the in-order replay. It requires `GATEFIT_LICENSE_KEY`.
+- License gate (`GATEFIT_LICENSE_KEY`), first shipped in 0.4.0.
+- Token-free npm trusted publishing. An annotated tag `vX.Y.Z` runs `.github/workflows/publish.yml` with GitHub OIDC. The publish job uses the GitHub environment `npm`. Provenance is automatic.
+
+### Not in this version
+
+- Provider packs.
+- A monthly plan.
 
 ## [0.4.0] - 2026-10-16
 

package/README.md

@@ -9,7 +9,7 @@ Fixture-first S1–S6 goldens, an `npx gatefit` CLI, and a GitHub Action. Node 2
 The CLI and GitHub Action in this repository stay free. The docs site is live. npm is live: `npx gatefit` ([gatefit](https://www.npmjs.com/package/gatefit)). Polar checkout is.
 
 - **Docs site:** live at https://gatefit.io. Cloudflare Pages project `gatefit`, hostname `gatefit-bdu.pages.dev`. From `site/`: `npm run build`, then `npx wrangler@4 pages deploy dist --project-name gatefit`. `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` come from the environment. GitHub Pages needs a public repository or a paid plan and is not the live host. `scripts/deploy-site.sh` can copy `site/dist` locally or deploy that Cloudflare target.
-- **npm:** live. `npx gatefit` is `gatefit@0.4.0` at https://www.npmjs.com/package/gatefit. CI runs `npm publish --dry-run` only.
+- **npm:** live. `npx gatefit` is the last published tarball (`gatefit@0.4.0` until tag `v0.5.0`) at https://www.npmjs.com/package/gatefit. This repo is `0.5.0`. The named gate runs `npm publish --dry-run` only. A `v*` tag publishes with OIDC. See [Releasing](#releasing).
 - **Polar checkout:** live. Gatefit Indie License is **$49** one-time at `https://buy.polar.sh/polar_cl_biyvx7HYtN2u19tUJCCkIuGOc98uVv7IG3gcB04eIJ0`. A plain `site` build and `scripts/deploy-site.sh` use that committed link. `PUBLIC_POLAR_CHECKOUT_URL` may override it. Any other value fails closed.
 
 ## Install / run
@@ -20,7 +20,7 @@ npx gatefit adapter-check
 npx gatefit run --suite paid_grants_access --adapter ./src/your-access-adapter.ts
 ```
 
-`gatefit@0.4.0`: https://www.npmjs.com/package/gatefit
+This repo is `0.5.0`. Registry: https://www.npmjs.com/package/gatefit
 
 From a clone:
 
@@ -41,13 +41,13 @@ Bring your own AccessAdapter in ≤30 minutes: [docs/bring-your-adapter.md](docs
 
 ## GitHub Action
 
-Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.4.0` is not cut yet. After a human tags the release commit:
+Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.5.0` is not cut yet. After a human pushes the annotated tag:
 
 ```yaml
 - uses: actions/setup-node@v4
   with:
     node-version: "22"
-- uses: gatefit/gatefit@v0.4.0
+- uses: gatefit/gatefit@v0.5.0
   with:
     adapter: src/your-access-adapter.ts
 ```
@@ -55,22 +55,43 @@ Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.4.0` is
 Nested path still works:
 
 ```yaml
-- uses: gatefit/gatefit/.github/actions/gatefit@v0.4.0
+- uses: gatefit/gatefit/.github/actions/gatefit@v0.5.0
   with:
     adapter: src/your-access-adapter.ts
 ```
 
-The Action wraps `gatefit run`. Adapter path is in *your* repo; goldens default to Gatefit’s S1–S6 pack. See [docs/publish.md](docs/publish.md) and the release draft [docs/release-v0.4.0.md](docs/release-v0.4.0.md).
+The Action wraps `gatefit run`. Adapter path is in *your* repo; goldens default to Gatefit’s S1–S6 pack. See [docs/publish.md](docs/publish.md) and the release notes [docs/release-v0.5.0.md](docs/release-v0.5.0.md).
 
 Do not set `GATEFIT_LIVE_CLOCK` for the named gate. Do not use `sk_live`. Never treat Stripe HTTP 200 as proof of access.
 
 Opt-in live Test Clocks (not default CI): [docs/live-clock.md](docs/live-clock.md).
 
+## Releasing
+
+Bump `version` in `package.json` and the lockfile `version` field, and add the matching `CHANGELOG.md` heading, in a pull request. Merge to `main`. Then push an annotated tag whose name is `v` plus that version:
+
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+The tag must match `v*`. The workflow fails when the tag without the leading `v` is not `package.json` `version`. That push runs `.github/workflows/publish.yml`: unit tests (`npm test`), the tarball checks (bin present, no `site/`, no secrets), then `npm publish --access public`. Provenance is automatic. The publish job requires the GitHub environment `npm`, so a required reviewer can be added there. `workflow_dispatch` runs the checks and does not publish. Do not set a registry token.
+
+One-time setup on npmjs.com for package `gatefit`: open Package settings, Trusted Publisher, GitHub Actions. Organization or user `gatefit`, repository `gatefit`, workflow filename `publish.yml`, environment name `npm`, and allow `npm publish`. Then set Publishing access to **Require two-factor authentication and disallow tokens**.
+
+`./ci-local.sh` stays the merge gate. It runs `npm publish --dry-run` and does not push tags.
+
 ## License
 
 S1–S6, seats/races, dispute/unpaid, and live Test Clocks stay free. Those packs do not read `GATEFIT_LICENSE_KEY` and do not call Polar.
 
-The $49 Gatefit Indie License unlocks Pro packs. Chaos mode is coming and is not in this release. Provider packs are not in this release. A missing, invalid, or revoked key exits non-zero and points at https://gatefit.io/#pricing.
+The $49 Gatefit Indie License unlocks Pro packs. Chaos mode is live. Provider packs are not in this release. A missing, invalid, or revoked key exits non-zero and points at https://gatefit.io/#pricing.
+
+```bash
+gatefit run --suite chaos --adapter src/adapters/hardened.ts --seed 1
+```
+
+Chaos mode replays every golden under a seeded set of delivery perturbations and compares the access row to the in-order replay. The perturbations are duplicated deliveries, reordered events, stale events, late events, dropped-then-replayed events, and the checkout-return page loading before the webhook. HTTP 200 is not access. The seed defaults to `1`. `--seed` wins over `GATEFIT_CHAOS_SEED`. The same seed prints the same bytes. A failure prints that seed and the perturbed events. Details: [docs/chaos.md](docs/chaos.md).
 
 ```bash
 export GATEFIT_LICENSE_KEY='GATEFIT-…'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatefit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Stripe Entitlement Edge Pack — CI that asserts the access DB survives ugly billing transitions",
   "type": "module",
   "license": "MIT",

package/src/access-adapter.ts

@@ -25,6 +25,8 @@ export type BillingEvent = {
   cancel_at_period_end?: boolean;
   period_end?: number;
   now?: number;
+  /** Original timeline position. Chaos folds on this so arrival order is not access. */
+  created?: number;
 };
 
 export type AccessAdapter = {

package/src/access-rules.ts

@@ -3,10 +3,12 @@ import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
 export type AccessStore = {
   rows: Map<string, AccessSnapshot>;
   seen: Set<string>;
+  events: BillingEvent[];
+  arrival: number;
 };
 
 export function emptyStore(): AccessStore {
-  return { rows: new Map(), seen: new Set() };
+  return { rows: new Map(), seen: new Set(), events: [], arrival: 0 };
 }
 
 export function isPaid(event: BillingEvent): boolean {
@@ -96,9 +98,26 @@ export function nextSnapshot(current: AccessSnapshot, event: BillingEvent): Acce
   return current;
 }
 
+function foldCustomer(store: AccessStore, customerId: string): void {
+  const ordered = store.events.filter((event) => event.customerId === customerId);
+  ordered.sort((a, b) => {
+    const byCreated = (a.created ?? 0) - (b.created ?? 0);
+    if (byCreated !== 0) return byCreated;
+    if (a.id < b.id) return -1;
+    if (a.id > b.id) return 1;
+    return 0;
+  });
+  let snapshot: AccessSnapshot = { locked: true };
+  for (const event of ordered) snapshot = nextSnapshot(snapshot, event);
+  store.rows.set(customerId, snapshot);
+}
+
 export function applyBillingEvent(store: AccessStore, event: BillingEvent): void {
   if (store.seen.has(event.id)) return;
   store.seen.add(event.id);
-  const current = store.rows.get(event.customerId) ?? { locked: true };
-  store.rows.set(event.customerId, nextSnapshot(current, event));
+  const stamped: BillingEvent = { ...event };
+  if (stamped.created === undefined) stamped.created = store.arrival;
+  store.arrival += 1;
+  store.events.push(stamped);
+  foldCustomer(store, event.customerId);
 }

package/src/adapters/hardened.ts

@@ -13,6 +13,8 @@ export function createAdapter(): AccessAdapter {
     reset() {
       store.rows.clear();
       store.seen.clear();
+      store.events.length = 0;
+      store.arrival = 0;
     },
   };
 }

package/src/chaos.ts

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
+import { loadAdapter } from "./access-adapter.ts";
+import { listGoldens, loadGolden } from "./fixture-driver.ts";
+import type { GoldenSuite } from "./fixture-driver.ts";
+import { registerProPack } from "./packs.ts";
+import { goldenDir, resolveUserOrPackage } from "./paths.ts";
+
+export const CHAOS_DEFAULT_SEED = "1";
+
+const PERTURBATIONS = [
+  "duplicate",
+  "reorder",
+  "stale",
+  "late",
+  "dropped_replay",
+  "checkout_return",
+] as const;
+
+type Perturbation = (typeof PERTURBATIONS)[number];
+
+export function resolveChaosSeed(flag: string | undefined, envValue: string | undefined): string {
+  const raw = flag !== undefined ? flag : envValue;
+  const trimmed = (raw ?? "").trim();
+  return trimmed.length > 0 ? trimmed : CHAOS_DEFAULT_SEED;
+}
+
+function pickIndex(seed: string, goldenId: string, kind: string, salt: string, n: number): number {
+  const digest = createHash("sha256").update(`${seed}\0${goldenId}\0${kind}\0${salt}`).digest();
+  return digest.readUInt32BE(0) % n;
+}
+
+function cloneEvents(events: BillingEvent[]): BillingEvent[] {
+  return events.map((event) => ({ ...event }));
+}
+
+function stamp(suite: GoldenSuite): BillingEvent[] {
+  return suite.steps.map((step, index) => ({ ...step.event, created: index }));
+}
+
+function duplicate(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "duplicate", "i", next.length);
+  next.push({ ...next[index]! });
+  return next;
+}
+
+function reorder(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  if (next.length < 2) return next;
+  const left = pickIndex(seed, goldenId, "reorder", "a", next.length);
+  let right = pickIndex(seed, goldenId, "reorder", "b", next.length);
+  if (left === right) right = (right + 1) % next.length;
+  const swap = next[left]!;
+  next[left] = next[right]!;
+  next[right] = swap;
+  return next;
+}
+
+function moveToEnd(events: BillingEvent[], index: number): BillingEvent[] {
+  const next = cloneEvents(events);
+  const [picked] = next.splice(index, 1);
+  next.push(picked!);
+  return next;
+}
+
+function stale(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "stale", "i", events.length - 1);
+  return moveToEnd(events, index);
+}
+
+function late(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "late", "i", events.length);
+  return moveToEnd(events, index);
+}
+
+function droppedReplay(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "dropped_replay", "i", next.length);
+  next.splice(index, 1);
+  return [...next, ...cloneEvents(events)];
+}
+
+function checkoutReturn(suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  const page: BillingEvent = {
+    id: `evt_chaos_checkout_${suite.id}`,
+    type: "checkout.session.completed",
+    customerId: suite.subject,
+    httpStatus: 200,
+    stripeHttpStatus: 200,
+    created: -1,
+  };
+  return [page, ...cloneEvents(events)];
+}
+
+function perturb(kind: Perturbation, seed: string, suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  if (kind === "duplicate") return duplicate(seed, suite.id, events);
+  if (kind === "reorder") return reorder(seed, suite.id, events);
+  if (kind === "stale") return stale(seed, suite.id, events);
+  if (kind === "late") return late(seed, suite.id, events);
+  if (kind === "dropped_replay") return droppedReplay(seed, suite.id, events);
+  return checkoutReturn(suite, events);
+}
+
+function stableSnapshot(snapshot: AccessSnapshot): string {
+  const keys = (Object.keys(snapshot) as (keyof AccessSnapshot)[])
+    .filter((key) => snapshot[key] !== undefined)
+    .sort();
+  const ordered: Record<string, unknown> = {};
+  for (const key of keys) ordered[key] = snapshot[key];
+  return JSON.stringify(ordered);
+}
+
+async function replay(
+  adapter: { apply: (event: BillingEvent) => void | Promise<void>; snapshot: (id: string) => AccessSnapshot | Promise<AccessSnapshot>; reset?: () => void | Promise<void> },
+  subject: string,
+  events: BillingEvent[],
+): Promise<AccessSnapshot> {
+  if (adapter.reset) await adapter.reset();
+  for (const event of events) await adapter.apply(event);
+  return adapter.snapshot(subject);
+}
+
+function fail(seed: string, goldenId: string, kind: Perturbation, events: BillingEvent[], expected: string, actual: string): void {
+  console.error(`gatefit: FAIL chaos ${goldenId} perturbation ${kind}`);
+  console.error(`seed: ${seed}`);
+  console.error("repro:");
+  for (const event of events) console.error(JSON.stringify(event));
+  console.error(`access: expected ${expected} got ${actual}`);
+}
+
+export async function runChaos(adapterPath: string, seed: string): Promise<number> {
+  console.error(`gatefit chaos: seed ${seed}`);
+  if (process.env.GATEFIT_LIVE_CLOCK) {
+    console.error("gatefit chaos: refuses GATEFIT_LIVE_CLOCK; fixture order only");
+    return 1;
+  }
+  const adapter = await loadAdapter(resolveUserOrPackage(adapterPath));
+  if (typeof adapter.reset !== "function") {
+    console.error("gatefit chaos: adapter.reset is required");
+    return 1;
+  }
+  const files = listGoldens(goldenDir());
+  for (const file of files) {
+    const suite = loadGolden(file);
+    const ordered = stamp(suite);
+    const expected = stableSnapshot(await replay(adapter, suite.subject, ordered));
+    for (const kind of PERTURBATIONS) {
+      const events = perturb(kind, seed, suite, ordered);
+      const actual = stableSnapshot(await replay(adapter, suite.subject, events));
+      if (actual !== expected) {
+        fail(seed, suite.id, kind, events, expected, actual);
+        return 1;
+      }
+    }
+    console.error(`gatefit: PASS chaos ${suite.id}`);
+  }
+  console.error("gatefit: PASS chaos");
+  return 0;
+}
+
+registerProPack({
+  id: "chaos",
+  run({ adapterPath, seed }) {
+    return runChaos(adapterPath, seed);
+  },
+});

package/src/cli.ts

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { loadAdapter } from "./access-adapter.ts";
 import { listGoldens, loadGolden, requireReset, runGolden } from "./fixture-driver.ts";
 import { LIVE_SCENARIO_IDS, runLiveLane, type LiveScenarioId } from "./live-scenarios.ts";
+import { resolveChaosSeed } from "./chaos.ts";
 import { ensureProLicense } from "./license.ts";
 import { getProPack, isProPack } from "./packs.ts";
 import { goldenDir, packageRoot, readPackageVersion, resolveUserOrPackage, userCwd } from "./paths.ts";
@@ -21,6 +22,7 @@ function usage(): string {
   return [
     "Usage:",
     "  gatefit run --suite <dir|file|id> --adapter <path>",
+    "  gatefit run --suite chaos --adapter <path> [--seed <value>]",
     "  gatefit adapter-check",
     "  gatefit live --adapter <path> [--scenario <id>]",
     "  gatefit --version",
@@ -41,7 +43,7 @@ function resolveSuiteFiles(suite: string): string[] {
   throw new Error(`suite not found: ${suite}`);
 }
 
-async function cmdRun(suite: string, adapterPath: string): Promise<number> {
+async function cmdRun(suite: string, adapterPath: string, seed: string): Promise<number> {
   if (isProPack(suite)) {
     const gate = await ensureProLicense();
     if (!gate.ok) {
@@ -50,7 +52,7 @@ async function cmdRun(suite: string, adapterPath: string): Promise<number> {
     }
     if (gate.warning) console.error(gate.warning);
     const pack = getProPack(suite);
-    if (pack?.run) return pack.run({ adapterPath });
+    if (pack?.run) return pack.run({ adapterPath, seed });
     console.error(`gatefit: PASS ${suite}`);
     return 0;
   }
@@ -109,13 +111,14 @@ async function main(argv: string[]): Promise<number> {
       options: {
         suite: { type: "string" },
         adapter: { type: "string" },
+        seed: { type: "string" },
       },
     });
     if (!values.suite || !values.adapter) {
       console.error(usage());
       return 1;
     }
-    return cmdRun(values.suite, values.adapter);
+    return cmdRun(values.suite, values.adapter, resolveChaosSeed(values.seed, process.env.GATEFIT_CHAOS_SEED));
   }
   if (command === "live") {
     const { values } = parseArgs({

package/src/packs.ts

@@ -1,10 +1,10 @@
 /**
- * Pro pack registry. H17 plugs chaos mode in by calling `registerProPack`
- * with a `run` function. The stub has no runner and is not a user-facing feature.
+ * Pro pack registry. Chaos mode registers here and runs only after the license gate.
+ * The stub has no runner and is not a user-facing feature.
  */
 export type ProPack = {
   id: string;
-  run?: (ctx: { adapterPath: string }) => Promise<number>;
+  run?: (ctx: { adapterPath: string; seed: string }) => Promise<number>;
 };
 
 const proPacks = new Map<string, ProPack>();