akeso-check 0.1.0

package/src/snapshot.mjs

@@ -0,0 +1,97 @@
+/* The live snapshot: compare who Stripe says is paying against who the app
+ * says is entitled, and price the disagreement.
+ *
+ * This produces the sales line — "3 canceled users still have Pro, $87 a
+ * month" — from the founder's own data, on the founder's own machine. Akeso
+ * never holds a key: the Stripe key and database connection come from the
+ * project's env, are used read-only, and are never stored or transmitted.
+ *
+ * The comparison core is pure and fully tested. The two fetchers at the bottom
+ * talk to the real world and can only be proven against a real account — that
+ * limit is stated here and in the report, not discovered later.
+ */
+
+/* Which Stripe subscription statuses mean "this customer is paying and should
+   have access" under the default policy. past_due sits in the grace period:
+   still entitled, flagged separately so the founder sees it. */
+const PAYING = new Set(["active", "trialing", "past_due"]);
+
+/* stripeSide: [{ account, status, priceMonthly, subscriptionId }]
+   appSide:    [{ account, billingEntitled }]
+   Returns every disagreement, priced. */
+export function compareEntitlements(stripeSide, appSide) {
+  const app = new Map(appSide.map((row) => [String(row.account), Boolean(row.billingEntitled)]));
+  const seenInStripe = new Set();
+
+  const payingButLockedOut = [];
+  const canceledButEntitled = [];
+
+  for (const sub of stripeSide) {
+    const account = String(sub.account);
+    seenInStripe.add(account);
+    const paying = PAYING.has(sub.status);
+    const entitled = app.get(account);
+
+    if (entitled === undefined) continue; /* unmatched accounts are reported separately, never guessed at */
+
+    if (paying && !entitled) {
+      payingButLockedOut.push({ account, status: sub.status, priceMonthly: sub.priceMonthly ?? null, subscriptionId: sub.subscriptionId });
+    } else if (!paying && entitled) {
+      canceledButEntitled.push({ account, status: sub.status, priceMonthly: sub.priceMonthly ?? null, subscriptionId: sub.subscriptionId });
+    }
+  }
+
+  /* Entitled in the app with no Stripe subscription at all. Could be a leak,
+     could be complimentary access — the Check reports, it does not accuse. */
+  const entitledWithNoSubscription = [...app.entries()]
+    .filter(([account, entitled]) => entitled && !seenInStripe.has(account))
+    .map(([account]) => ({ account }));
+
+  const monthlyExposure = canceledButEntitled
+    .reduce((sum, row) => sum + (row.priceMonthly || 0), 0);
+
+  return {
+    payingButLockedOut,      /* the customer-hurting direction: paid, locked out */
+    canceledButEntitled,     /* the money-leaking direction */
+    entitledWithNoSubscription,
+    monthlyExposure,         /* list-price dollars leaking per month, only from rows with a known price */
+    counts: {
+      stripeSubscriptions: stripeSide.length,
+      appAccounts: appSide.length,
+      matched: [...seenInStripe].filter((account) => app.has(account)).length,
+    },
+    clean: payingButLockedOut.length === 0 && canceledButEntitled.length === 0,
+  };
+}
+
+/* ---- Real-world fetchers. Only proven against a real Stripe account. ---- */
+
+/* Read-only: lists subscriptions with their price. Works with a restricted or
+   test key; refuses nothing here because GETs cannot change anything. */
+export async function fetchStripeSubscriptions(stripeKey, { accountField = "client_reference_id" } = {}) {
+  const rows = [];
+  let startingAfter = null;
+  for (let page = 0; page < 20; page += 1) {
+    const params = new URLSearchParams({ status: "all", limit: "100", "expand[]": "data.items.data.price" });
+    if (startingAfter) params.set("starting_after", startingAfter);
+    const response = await fetch(`https://api.stripe.com/v1/subscriptions?${params}`, {
+      headers: { Authorization: `Bearer ${stripeKey}` },
+    });
+    if (!response.ok) throw new Error(`Stripe answered ${response.status}: ${(await response.text()).slice(0, 200)}`);
+    const body = await response.json();
+    for (const sub of body.data) {
+      const price = sub.items?.data?.[0]?.price;
+      rows.push({
+        subscriptionId: sub.id,
+        account: sub.metadata?.[accountField] || sub.metadata?.account || sub.customer,
+        status: sub.status,
+        priceMonthly: price?.recurring?.interval === "month" && typeof price.unit_amount === "number"
+          ? price.unit_amount / 100
+          : null,
+      });
+    }
+    if (!body.has_more) break;
+    startingAfter = body.data.at(-1)?.id;
+  }
+  return rows;
+}

package/src/stripe-events.mjs

@@ -0,0 +1,190 @@
+import { createHmac, randomUUID } from "node:crypto";
+
+/* Builds and signs the lifecycle events the Check delivers to the app.
+ *
+ * These are real Stripe-shaped events with real Stripe signatures — the HMAC
+ * scheme Stripe documents, computed with the app's own webhook secret, which
+ * the Check reads locally and never transmits. The app under test cannot tell
+ * these from Stripe's own deliveries unless it re-fetches objects from the
+ * Stripe API. Apps that do re-fetch need the sandbox driver (their own test
+ * key + the Stripe CLI); that limit is stated in the report, never papered over.
+ */
+
+export function signPayload(rawBody, webhookSecret, timestamp = Math.floor(Date.now() / 1000)) {
+  /* Stripe's SDKs use the signing secret VERBATIM as the HMAC key — the
+     whsec_ prefix is part of the key, not packaging. Stripping it made every
+     real stripe-node app reject our deliveries with 400 (proven against a
+     deployed app, Aug 30 2026). */
+  const signature = createHmac("sha256", webhookSecret).update(`${timestamp}.${rawBody}`).digest("hex");
+  return `t=${timestamp},v1=${signature}`;
+}
+
+let counter = 0;
+function eventId() {
+  counter += 1;
+  return `evt_akeso_${Date.now()}_${counter}_${randomUUID().slice(0, 8)}`;
+}
+
+/* One event, Stripe-shaped. `created` is controllable because out-of-order
+   delivery is one of the scenarios. */
+export function makeEvent({ type, account, created, id, object = {} }) {
+  return {
+    id: id || eventId(),
+    object: "event",
+    api_version: "2026-08-27.basil",
+    created: created ?? Math.floor(Date.now() / 1000),
+    type,
+    livemode: false,
+    data: {
+      object: {
+        id: object.id || `${type.startsWith("charge") ? "ch" : type.startsWith("invoice") ? "in" : type.startsWith("checkout") ? "cs" : "sub"}_akeso_${account}`,
+        customer: `cus_akeso_${account}`,
+        client_reference_id: account,
+        metadata: { account },
+        ...object,
+      },
+    },
+  };
+}
+
+/* The ten lifecycle scenarios from the master doc, each on its own account so
+   one scenario's state cannot bleed into another. `expect` is the billing
+   entitlement the app must report after the last event; null means reported,
+   not graded (refunds follow the app's own policy). `critical` marks the
+   failures that force an F: canceled customers keeping access. */
+export function scenarios({ accountFor } = {}) {
+  /* accountFor maps a scenario's default account ("s1".."s10") onto a real
+     account id — needed on deployed apps where rows for made-up accounts
+     don't exist and grading their absence would blame the app for our
+     harness. Without it, defaults stand. */
+  const acct = accountFor || ((id) => id);
+  const t = Math.floor(Date.now() / 1000);
+  const list = [
+    {
+      id: "checkout-grants",
+      name: "New payment unlocks access",
+      account: acct("s1"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s1"), created: t }),
+      ],
+      expect: true,
+    },
+    {
+      id: "trial-converts",
+      name: "Trial ends, subscription becomes active",
+      account: acct("s2"),
+      events: [
+        makeEvent({ type: "customer.subscription.created", account: acct("s2"), created: t, object: { status: "trialing" } }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s2"), created: t + 10, object: { status: "active" } }),
+      ],
+      expect: true,
+    },
+    {
+      id: "renewal-succeeds",
+      name: "Monthly renewal payment keeps access",
+      account: acct("s3"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s3"), created: t }),
+        makeEvent({ type: "invoice.paid", account: acct("s3"), created: t + 10 }),
+      ],
+      expect: true,
+    },
+    {
+      id: "payment-fails",
+      name: "Card fails, retries exhaust: access ends",
+      account: acct("s4"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s4"), created: t }),
+        makeEvent({ type: "invoice.payment_failed", account: acct("s4"), created: t + 10 }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s4"), created: t + 20, object: { status: "past_due" } }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s4"), created: t + 30, object: { status: "unpaid" } }),
+      ],
+      expect: false,
+    },
+    {
+      id: "cancel-at-period-end",
+      name: "Customer cancels; period ends: access ends",
+      account: acct("s5"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s5"), created: t }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s5"), created: t + 10, object: { status: "active", cancel_at_period_end: true } }),
+        makeEvent({ type: "customer.subscription.deleted", account: acct("s5"), created: t + 20, object: { status: "canceled" } }),
+      ],
+      expect: false,
+      critical: true,
+    },
+    {
+      id: "immediate-cancel",
+      name: "Immediate cancellation removes access",
+      account: acct("s6"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s6"), created: t }),
+        makeEvent({ type: "customer.subscription.deleted", account: acct("s6"), created: t + 10, object: { status: "canceled" } }),
+      ],
+      expect: false,
+      critical: true,
+    },
+    {
+      id: "reactivation",
+      name: "Customer un-cancels before the period ends",
+      account: acct("s7"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s7"), created: t }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s7"), created: t + 10, object: { status: "active", cancel_at_period_end: true } }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s7"), created: t + 20, object: { status: "active", cancel_at_period_end: false } }),
+      ],
+      expect: true,
+    },
+    {
+      id: "refund",
+      name: "Latest charge refunded (follows the app's own policy)",
+      account: acct("s8"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s8"), created: t }),
+        makeEvent({ type: "charge.refunded", account: acct("s8"), created: t + 10 }),
+      ],
+      expect: null,
+    },
+    (() => {
+      const dup = makeEvent({ type: "customer.subscription.deleted", account: acct("s9"), created: t + 10, object: { status: "canceled" } });
+      return {
+        id: "duplicate-delivery",
+        name: "The same event delivered twice",
+        account: acct("s9"),
+        events: [
+          makeEvent({ type: "checkout.session.completed", account: acct("s9"), created: t }),
+          dup,
+          { ...dup }, /* identical id: must not error or flip state back */
+        ],
+        expect: false,
+      };
+    })(),
+    {
+      id: "out-of-order",
+      name: "An old 'still active' event arrives after cancellation",
+      account: acct("s10"),
+      events: [
+        makeEvent({ type: "checkout.session.completed", account: acct("s10"), created: t }),
+        makeEvent({ type: "customer.subscription.deleted", account: acct("s10"), created: t + 20, object: { status: "canceled" } }),
+        makeEvent({ type: "customer.subscription.updated", account: acct("s10"), created: t + 10, object: { status: "active" } }),
+      ],
+      expect: false,
+    },
+  ];
+
+  /* Re-time: every scenario gets its own 10-second slice of the recent past,
+     ordered like the scenarios themselves. On a shared real account, an app
+     with a correct out-of-order guard keeps a per-account high-water mark —
+     if scenarios overlapped in event time, scenario 5's events would be
+     "older" than scenario 4's mark and silently ignored, and we would grade
+     the app on our own collision. resetCreated sits just before each slice so
+     a reset delivery lands inside the guard, not behind it. (Runs less than
+     ~2 minutes apart can still collide with their own previous marks; the
+     not_provable guard reports that honestly instead of passing vacuously.) */
+  list.forEach((scenario, i) => {
+    const base = t - 120 + i * 10;
+    for (const event of scenario.events) event.created = base + Math.round((event.created - t) / 10);
+    scenario.resetCreated = base - 2;
+  });
+  return list;
+}

package/tests/adapter.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { renderAdapter, renderReferenceAdapter } from "../src/adapter.mjs";
+
+/* The contract itself gets proven here, against the runnable reference
+   implementation — so the rules exist as executed behaviour, not just as
+   comments in generated code a founder might delete. */
+
+async function loadReference(initialStore) {
+  const dir = await mkdtemp(path.join(tmpdir(), "akeso-adapter-"));
+  const dbFile = path.join(dir, "store.json");
+  await writeFile(dbFile, JSON.stringify(initialStore));
+  const moduleFile = path.join(dir, "adapter.mjs");
+  await writeFile(moduleFile, renderReferenceAdapter());
+  process.env.AKESO_REF_DB = dbFile;
+  const adapter = await import(moduleFile);
+  return { adapter, dbFile };
+}
+
+test("the generated TS adapter carries the six fields and both functions", () => {
+  const source = renderAdapter({ tableName: "profiles", entitledColumn: "is_pro" });
+  for (const field of ["billingEntitled", "manualComplimentaryAccess", "manualBillingOverride",
+    "administrativeBlock", "securityOrAbuseBlock", "finalAccessDecision"]) {
+    assert.ok(source.includes(field), `missing ${field}`);
+  }
+  assert.match(source, /getBillingEntitlement/);
+  assert.match(source, /restoreBillingEntitlement/);
+  assert.match(source, /NEVER overridden/);
+});
+
+test("restore applies, verifies by re-read, and is honest in its receipt", async () => {
+  const { adapter } = await loadReference({ a1: { billing_entitled: false } });
+  const out = await adapter.restoreBillingEntitlement(
+    "a1", { billingEntitled: false }, { billingEntitled: true }, "1", "idem-1", "stripe_says_active");
+  assert.equal(out.result, "applied");
+  assert.equal(out.verified, true);
+  assert.equal(out.before.billingEntitled, false);
+  assert.equal(out.after.billingEntitled, true);
+});
+
+test("a blocked account is never restored, whatever Stripe says", async () => {
+  const { adapter } = await loadReference({ banned: { billing_entitled: false, abuse_block: true } });
+  const out = await adapter.restoreBillingEntitlement(
+    "banned", { billingEntitled: false }, { billingEntitled: true }, "1", "idem-2", "stripe_says_active");
+  assert.equal(out.result, "unsupported");
+  assert.match(out.reason, /block/);
+  const after = await adapter.getBillingEntitlement("banned");
+  assert.equal(after.billingEntitled, false, "the write must not have happened");
+});
+
+test("a restore racing a newer change loses loudly, not wins silently", async () => {
+  const { adapter } = await loadReference({ r1: { billing_entitled: true } });
+  /* prepared believing entitled=false; reality moved on */
+  const out = await adapter.restoreBillingEntitlement(
+    "r1", { billingEntitled: false }, { billingEntitled: true }, "1", "idem-3", "reconcile");
+  assert.equal(out.result, "no_op" /* already at target */);
+
+  const conflicting = await adapter.restoreBillingEntitlement(
+    "r1", { billingEntitled: false }, { billingEntitled: false }, "1", "idem-4", "reconcile");
+  assert.equal(conflicting.result, "conflict");
+  assert.match(conflicting.reason, /changed since/);
+});
+
+test("a rule-version mismatch refuses before touching anything", async () => {
+  const { adapter, dbFile } = await loadReference({ v1: { billing_entitled: false } });
+  const out = await adapter.restoreBillingEntitlement(
+    "v1", { billingEntitled: false }, { billingEntitled: true }, "999", "idem-5", "stale_plan");
+  assert.equal(out.result, "conflict");
+  assert.equal(JSON.parse(await readFile(dbFile, "utf8")).v1.billing_entitled, false);
+});

package/tests/lifecycle-acceptance.test.mjs

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { runLifecycle } from "../src/lifecycle.mjs";
+
+/* THE acceptance test from the master doc: the Check must catch the broken app
+   (F, with the cancel scenario failing) and clear the fixed one (A). If either
+   half fails, the Check is not ready — a checker that misses the bug it was
+   built for, or that alarms on a healthy app, is worse than no checker. */
+
+async function withFixture(name, port, run) {
+  const server = spawn(process.execPath, ["server.mjs"], {
+    cwd: path.resolve("fixtures", name),
+    env: { ...process.env, PORT: String(port) },
+    stdio: "ignore",
+  });
+  try {
+    for (let i = 0; i < 50; i += 1) {
+      try { await fetch(`http://localhost:${port}/__akeso_probe?account=warmup`); break; }
+      catch { await new Promise((r) => setTimeout(r, 100)); }
+    }
+    return await run({
+      webhookUrl: `http://localhost:${port}/api/stripe/webhook`,
+      probeUrl: `http://localhost:${port}/__akeso_probe`,
+      webhookSecret: "whsec_fixturefixturefixture5678",
+    });
+  } finally {
+    server.kill();
+  }
+}
+
+test("the broken app grades F, and for the right reason", async () => {
+  const outcome = await withFixture("broken-app", 4101, runLifecycle);
+  assert.equal(outcome.grade.letter, "F");
+  const cancel = outcome.results.find((r) => r.id === "cancel-at-period-end");
+  assert.equal(cancel.outcome, "fail", "the money-leaking scenario must be the one that fails");
+  assert.equal(cancel.observed, true, "canceled customer still shows entitled — that is the bug");
+  assert.equal(outcome.results.find((r) => r.id === "checkout-grants").outcome, "pass");
+});
+
+test("the fixed app grades A — no alarms on a healthy app", async () => {
+  const outcome = await withFixture("fixed-app", 4102, runLifecycle);
+  assert.equal(outcome.grade.letter, "A", JSON.stringify(outcome.results.filter(r => r.outcome !== "pass"), null, 2));
+});
+
+test("shared real account: grants after the first are not provable, never vacuous passes", async () => {
+  /* Deployed apps have no rows for made-up accounts, so every scenario maps
+     onto one real account. On a grant-only broken app that account stays
+     entitled forever — later grant scenarios must refuse to claim a pass. */
+  const outcome = await withFixture("broken-app", 4103, (opts) =>
+    runLifecycle({ ...opts, accountFor: () => "shared-real-account" }));
+  assert.equal(outcome.grade.letter, "F");
+  assert.equal(outcome.results.find((r) => r.id === "checkout-grants").outcome, "pass");
+  assert.equal(outcome.results.find((r) => r.id === "trial-converts").outcome, "not_provable");
+  assert.equal(outcome.results.find((r) => r.id === "reactivation").outcome, "not_provable");
+  assert.equal(outcome.results.find((r) => r.id === "cancel-at-period-end").outcome, "fail");
+});
+
+test("shared account + reset on the FIXED app: one real account proves everything", async () => {
+  /* The real-world mode: a deployed app has one usable account. Resetting it
+     between scenarios (with a cancellation the app understands) must make
+     every scenario provable — grade A, nothing vacuous, nothing skipped. */
+  const account = `shared-${Date.now()}`; /* fixture state persists on disk across runs */
+  const outcome = await withFixture("fixed-app", 4104, (opts) =>
+    runLifecycle({ ...opts, accountFor: () => account, resetBeforeEach: true }));
+  assert.equal(outcome.grade.letter, "A", JSON.stringify(outcome.results.filter(r => r.outcome !== "pass"), null, 2));
+  assert.equal(outcome.results.filter((r) => r.outcome === "not_provable").length, 0);
+});
+
+test("a dead server is our failure, never the app's grade", async () => {
+  const outcome = await runLifecycle({
+    webhookUrl: "http://localhost:59999/api/stripe/webhook",
+    probeUrl: "http://localhost:59999/__akeso_probe",
+    webhookSecret: "whsec_nothing",
+  });
+  assert.equal(outcome.grade.letter, "?");
+  assert.ok(outcome.results.every((r) => r.outcome === "could_not_test"));
+});

package/tests/probe.test.mjs

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { chooseProbeTarget, findAccessExports, installProbe, removeProbe } from "../src/probe.mjs";
+import { detect } from "../src/detect.mjs";
+
+test("recognises the shapes access functions actually take", () => {
+  assert.deepEqual(
+    findAccessExports(`export async function isPro(userId: string) { return true; }`),
+    [{ name: "isPro", paramCount: 1, firstParam: "userId: string" }],
+  );
+  assert.deepEqual(
+    findAccessExports(`export const hasAccess = async (id) => db.check(id);`),
+    [{ name: "hasAccess", paramCount: 1, firstParam: "id" }],
+  );
+  /* an explicit entitlement function outranks a generic isPro downstream */
+  const both = findAccessExports(`
+    export function isPro(u) { return true; }
+    export function getBillingEntitlement(accountId) { return {}; }
+  `);
+  assert.equal(both.length, 2);
+});
+
+test("refuses to wire a function it would have to guess at", async () => {
+  const root = path.resolve("fixtures");
+  await writeFile(path.join(root, "_tmp_multi.mjs"),
+    "export async function hasAccess(userId, feature, ctx) { return true; }");
+  const target = await chooseProbeTarget(root, [{ file: "_tmp_multi.mjs", score: 5, clientSideOnly: false }]);
+  assert.equal(target.chosen, null);
+  assert.match(target.reason, /guess/);
+  const { rm } = await import("node:fs/promises");
+  await rm(path.join(root, "_tmp_multi.mjs"));
+});
+
+test("a client-side gate is never offered as the server's answer", async () => {
+  const target = await chooseProbeTarget(path.resolve("fixtures/broken-app"), [
+    { file: "lib/handler.mjs", score: 4, clientSideOnly: true },
+  ]);
+  assert.equal(target.chosen, null);
+});
+
+test("install wires the real function, the probe executes, removal cleans up", async () => {
+  const root = path.resolve("fixtures/broken-app");
+  const detection = await detect(root);
+  /* force the runnable target and a runnable template */
+  detection.framework = { framework: "node-other" };
+  detection.accessDecisionSites = [{ file: "lib/handler.mjs", score: 9, clientSideOnly: false }];
+
+  const install = await installProbe(root, detection);
+  try {
+    assert.equal(install.wired, true, install.reason);
+    assert.equal(install.target.name, "isPro");
+
+    const written = await readFile(install.routeFile, "utf8");
+    assert.match(written, /AKESO PROBE/);
+    assert.match(written, /from "\.\.\/\.\.\/\.\.\/lib\/handler\.mjs"/);
+
+    /* the generated route must actually run and give the app's own answer */
+    await writeFile(path.join(root, "data", "profiles.json"),
+      JSON.stringify({ probed: { is_pro: true }, other: { is_pro: false } }));
+    const routeModule = await import(`${install.routeFile}?v=${Date.now()}`);
+    const yes = await (await routeModule.GET(new Request("http://x/api/__akeso_probe?account=probed"))).json();
+    const no = await (await routeModule.GET(new Request("http://x/api/__akeso_probe?account=other"))).json();
+    assert.equal(yes.billingEntitled, true);
+    assert.equal(no.billingEntitled, false);
+  } finally {
+    const removal = await removeProbe(install.routeFile);
+    assert.equal(removal.removed, true);
+  }
+});
+
+test("removal refuses a file that lost the Akeso marker", async () => {
+  const root = path.resolve("fixtures/broken-app");
+  const file = path.join(root, "app", "api", "__akeso_probe", "route.mjs");
+  const { mkdir } = await import("node:fs/promises");
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, "// the founder kept and edited this file\nexport const theirs = true;\n");
+  const removal = await removeProbe(file);
+  assert.equal(removal.removed, false);
+  assert.match(removal.reason, /marker/);
+  const { rm } = await import("node:fs/promises");
+  await rm(path.dirname(file), { recursive: true });
+});

package/tests/snapshot.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { compareEntitlements } from "../src/snapshot.mjs";
+
+test("finds the money leak: canceled in Stripe, entitled in the app", () => {
+  const out = compareEntitlements(
+    [
+      { account: "a1", status: "canceled", priceMonthly: 29, subscriptionId: "sub_1" },
+      { account: "a2", status: "canceled", priceMonthly: 29, subscriptionId: "sub_2" },
+      { account: "a3", status: "canceled", priceMonthly: 29, subscriptionId: "sub_3" },
+      { account: "a4", status: "active", priceMonthly: 29, subscriptionId: "sub_4" },
+    ],
+    [
+      { account: "a1", billingEntitled: true },
+      { account: "a2", billingEntitled: true },
+      { account: "a3", billingEntitled: true },
+      { account: "a4", billingEntitled: true },
+    ],
+  );
+  assert.equal(out.canceledButEntitled.length, 3);
+  assert.equal(out.monthlyExposure, 87); /* the sales line: "$87 a month" */
+  assert.equal(out.clean, false);
+});
+
+test("finds the customer-hurting direction: paying but locked out", () => {
+  const out = compareEntitlements(
+    [{ account: "b1", status: "active", priceMonthly: 49, subscriptionId: "sub_b" }],
+    [{ account: "b1", billingEntitled: false }],
+  );
+  assert.equal(out.payingButLockedOut.length, 1);
+  assert.equal(out.canceledButEntitled.length, 0);
+});
+
+test("past_due is grace, not a leak", () => {
+  const out = compareEntitlements(
+    [{ account: "c1", status: "past_due", priceMonthly: 19, subscriptionId: "sub_c" }],
+    [{ account: "c1", billingEntitled: true }],
+  );
+  assert.equal(out.clean, true);
+});
+
+test("reports, never guesses: unmatched accounts are listed separately", () => {
+  const out = compareEntitlements(
+    [{ account: "known", status: "active", priceMonthly: 9, subscriptionId: "sub_k" }],
+    [
+      { account: "known", billingEntitled: true },
+      { account: "mystery", billingEntitled: true }, /* entitled, no subscription anywhere */
+    ],
+  );
+  assert.equal(out.clean, true, "a possible comp account is not a confirmed leak");
+  assert.deepEqual(out.entitledWithNoSubscription, [{ account: "mystery" }]);
+});
+
+test("a subscription with no priced row adds nothing to the exposure figure", () => {
+  const out = compareEntitlements(
+    [{ account: "d1", status: "canceled", priceMonthly: null, subscriptionId: "sub_d" }],
+    [{ account: "d1", billingEntitled: true }],
+  );
+  assert.equal(out.canceledButEntitled.length, 1);
+  assert.equal(out.monthlyExposure, 0, "never invent a dollar figure");
+});