@suluk/journeys 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/journeys",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Intuitive, runnable BDD over a v4 'Suluk' contract. Projects a deterministic Gherkin step VOCABULARY from the contract (Given from x-suluk-access, When from each operation, Then from declared statuses + x-suluk-store + x-suluk-cost), binds authored .feature stories EXACT-or-UNBOUND with outcome steps resolved relative to the scenario's When-subject, and emits a BIDIRECTIONAL tri-state gap report (PARAPHRASE / NEEDS-DEV-GLUE / NEEDS-CONTRACT) + contract->authored coverage holes. A pure function of the document. CANDIDATE tooling.",
   "publishConfig": {
     "access": "public"

package/src/hatch/index.ts

@@ -13,6 +13,7 @@
  *
  * Runtime IO only — provably outside the deterministic core (bind.ts / vocabulary.ts), enforced by hatch-wall.test.ts.
  */
+export { runScope, type RunScope, type RunScopeOptions } from "./runscope";
 export { resolveBackend, localD1, remoteD1, type BackendSpec } from "./backends";
 export { stateHatch, type StateHatchOptions } from "./state";
 export { signInAs, type SignInAsOptions, type SignedInSession, type CleanupTarget } from "./auth";

package/src/hatch/runscope.ts

@@ -0,0 +1,40 @@
+/**
+ * runScope (C039) — a per-process RUN SCOPE so parallel git worktrees / CI shards / agents can run the SAME BDD suite
+ * without clashing. The only things that clash are SHARED mutable state with a FIXED name; this makes both unique:
+ *
+ *  - `d1Path` is a unique file in the OS temp dir (NOT in the repo), so git/worktrees/.wrangler never see or contend
+ *    on it — each run opens its own local sqlite.
+ *  - `scopeId`/`email` are unique, so even against a SHARED backend (prod-as-test-users) the hatch's test-user scoping
+ *    means a run only ever seeds/cleans ITS OWN rows.
+ *
+ * `runId = <pid>_<uuid8>` is globally unique across processes and worktrees. Pair it with a hatch `scope: { value:
+ * scopeId }` (state hatch) and the `email` (auth hatch) for a fully isolated, parallel-safe run.
+ */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface RunScope {
+  runId: string;
+  /** the test-user id — the state hatch forces every seeded row's owner to this; cleanup deletes only these rows. */
+  scopeId: string;
+  email: string;
+  /** an isolated local sqlite path in the OS temp dir (outside any worktree). */
+  d1Path: string;
+}
+
+export interface RunScopeOptions {
+  /** filename prefix for the temp DB (default "suluk-bdd"). */
+  prefix?: string;
+  /** email domain for the synthetic test user (default "example.test"). */
+  emailDomain?: string;
+}
+
+export function runScope(opts: RunScopeOptions = {}): RunScope {
+  const runId = `${process.pid}_${crypto.randomUUID().slice(0, 8)}`;
+  return {
+    runId,
+    scopeId: `testuser_${runId}`,
+    email: `bdd+${runId}@${opts.emailDomain ?? "example.test"}`,
+    d1Path: join(tmpdir(), `${opts.prefix ?? "suluk-bdd"}-${runId}.sqlite`),
+  };
+}

package/test/hatch-auth.test.ts

@@ -0,0 +1,53 @@
+import { test, expect, describe } from "bun:test";
+import { localD1 } from "../src/hatch/backends";
+import { stateHatch } from "../src/hatch/state";
+import { signInAs } from "../src/hatch/auth";
+import type { TestUser } from "../src/hatch/types";
+
+/**
+ * Durable package witness for the AUTH HATCH contract (C039) — the orchestration + the FAIL-CLOSED guarantee, proven
+ * without any real Better Auth (the consumer supplies mintSession/verify; here they are stubs). The end-to-end mint
+ * against toolfactory's real Better Auth is witnessed separately by toolfactory's local self-test
+ * (scripts/journeys-hatch-selftest.ts). This pins the property that matters most: signInAs NEVER returns a session the
+ * app rejected — it can never manufacture a false green — and teardown is test-user-scoped.
+ */
+async function fixture() {
+  const d1 = await localD1(":memory:");
+  await d1.run("CREATE TABLE user (id TEXT PRIMARY KEY, email TEXT)");
+  await d1.run("CREATE TABLE session (id TEXT PRIMARY KEY, userId TEXT, token TEXT)");
+  const state = stateHatch(d1, { write: true, scope: { value: "testuser_1" } });
+  return { d1, state };
+}
+const ensureUser = async (state: Awaited<ReturnType<typeof fixture>>["state"], user: TestUser) => {
+  await state.d1.seed("user", "id", [{ email: user.email }], { kind: "auth", because: "OAuth-only; no API seeds a verified user", userPathChecked: true });
+  return "testuser_1"; // seed forced user.id = the scope value
+};
+const mintSession = async (userId: string) => ({ cookie: `better-auth.session_token=${userId}.sig` });
+
+describe("auth hatch — signInAs (fail-closed, never a false green)", () => {
+  test("returns the session + seeds the user when the app ACCEPTS the minted cookie", async () => {
+    const { state } = await fixture();
+    const s = await signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => true });
+    expect(s.userId).toBe("testuser_1");
+    expect(s.cookie).toBe("better-auth.session_token=testuser_1.sig");
+    expect(await state.d1.get("SELECT id FROM user WHERE id = ?", ["testuser_1"])).toEqual({ id: "testuser_1" });
+  });
+
+  test("THROWS when the app REJECTS the minted session — fails closed, never returns an unverified credential", async () => {
+    const { state } = await fixture();
+    await expect(
+      signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => false }),
+    ).rejects.toThrow(/REJECTED|fails closed/);
+  });
+
+  test("teardown scoped-deletes only the test user's user + session rows", async () => {
+    const { d1, state } = await fixture();
+    await d1.run("INSERT INTO session (id, userId, token) VALUES (?,?,?)", ["s1", "testuser_1", "t"]);
+    await d1.run("INSERT INTO user (id, email) VALUES (?,?)", ["real_1", "real@customer.com"]); // a co-resident real user
+    const s = await signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => true });
+    await s.teardown(); // default targets: session.userId + user.id
+    expect(await state.d1.select("SELECT id FROM user WHERE id = ?", ["testuser_1"])).toEqual([]);
+    expect(await state.d1.select("SELECT id FROM session WHERE userId = ?", ["testuser_1"])).toEqual([]);
+    expect(await state.d1.select("SELECT id FROM user WHERE id = ?", ["real_1"])).toEqual([{ id: "real_1" }]); // untouched
+  });
+});

package/test/hatch-runscope.test.ts

@@ -0,0 +1,28 @@
+import { test, expect, describe } from "bun:test";
+import { tmpdir } from "node:os";
+import { runScope } from "../src/hatch/runscope";
+
+/**
+ * runScope is the parallel-safety primitive (C039): every call yields a UNIQUE test-user identity + an isolated temp DB
+ * path, so parallel worktrees / CI shards running the same BDD suite never clash.
+ */
+describe("runScope — unique-per-call, isolated, parallel-safe", () => {
+  test("each call is globally unique (id, scopeId, email, d1Path)", () => {
+    const a = runScope();
+    const b = runScope();
+    expect(a.runId).not.toBe(b.runId);
+    expect(a.scopeId).not.toBe(b.scopeId);
+    expect(a.email).not.toBe(b.email);
+    expect(a.d1Path).not.toBe(b.d1Path);
+    // 50 calls → 50 distinct ids
+    expect(new Set(Array.from({ length: 50 }, () => runScope().runId)).size).toBe(50);
+  });
+
+  test("the DB path is in the OS temp dir (outside any worktree/repo) and the scope ties everything to one test user", () => {
+    const s = runScope({ prefix: "tf-bdd" });
+    expect(s.d1Path.startsWith(tmpdir())).toBe(true);
+    expect(s.d1Path).toContain("tf-bdd-");
+    expect(s.scopeId).toBe(`testuser_${s.runId}`);
+    expect(s.email).toContain(s.runId);
+  });
+});