@nxgt/janus 0.1.0

package/dist/conformance/index.js

@@ -0,0 +1,1113 @@
+import {
+  mintId2,
+  createMemoryStores2
+} from "../chunks/index-658b6mr2.js";
+import {
+  JanusError2,
+  StoreFailure2,
+  StoreConflict2,
+  NotFoundError2,
+  formatSubject2
+} from "../chunks/index-6p56fpbe.js";
+import {
+  createMemoryRelations2
+} from "../chunks/index-fgb3t64y.js";
+
+// src/conformance/assert.ts
+function equal(actual, expected, what) {
+  const difference = differ(actual, expected, "");
+  if (difference !== null) {
+    throw new Error(`${what}
+  at ${difference.path || "(root)"}: expected ${show(difference.expected)}, got ${show(difference.actual)}`);
+  }
+}
+function isNull(actual, what) {
+  if (actual !== null) {
+    throw new Error(`${what}
+  expected null, got ${actual === undefined ? "undefined — an absence is null; undefined is a store that forgot to answer" : show(actual)}`);
+  }
+}
+function ok(condition, what) {
+  if (!condition)
+    throw new Error(what);
+}
+function rejects(promise, what) {
+  return promise.then((answer) => {
+    throw new Error(`${what}
+  expected a rejection, got ${show(answer)}`);
+  }, (error) => error);
+}
+function isOurs(error, cls, what) {
+  if (error instanceof cls)
+    return;
+  if (error?.name === cls.name) {
+    throw new Error(`${what}
+  the error is named ${cls.name} but is not @nxgt/janus's ${cls.name}: two copies of @nxgt/janus are installed. The adapter must list it as a peer dependency, never a dependency`);
+  }
+  throw new Error(`${what}
+  expected ${cls.name}, got ${show(error)}`);
+}
+function differ(actual, expected, path) {
+  if (expected instanceof Date || actual instanceof Date) {
+    return actual instanceof Date && expected instanceof Date && actual.getTime() === expected.getTime() ? null : { path, expected, actual };
+  }
+  if (Array.isArray(expected) || Array.isArray(actual)) {
+    if (!Array.isArray(expected) || !Array.isArray(actual)) {
+      return { path, expected, actual };
+    }
+    if (expected.length !== actual.length) {
+      return {
+        path: `${path}.length`,
+        expected: expected.length,
+        actual: actual.length
+      };
+    }
+    for (let i = 0;i < expected.length; i += 1) {
+      const inner = differ(actual[i], expected[i], `${path}[${i}]`);
+      if (inner !== null)
+        return inner;
+    }
+    return null;
+  }
+  if (typeof expected === "object" && expected !== null && typeof actual === "object" && actual !== null) {
+    const keys = new Set([...Object.keys(expected), ...Object.keys(actual)]);
+    for (const key of keys) {
+      const inner = differ(actual[key], expected[key], path === "" ? key : `${path}.${key}`);
+      if (inner !== null)
+        return inner;
+    }
+    return null;
+  }
+  return Object.is(actual, expected) ? null : { path, expected, actual };
+}
+function show(value) {
+  if (value instanceof Error)
+    return `${value.name}: ${value.message}`;
+  if (value instanceof Date)
+    return value.toISOString();
+  if (value === undefined)
+    return "undefined";
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  try {
+    const json = JSON.stringify(value);
+    return json.length > 200 ? `${json.slice(0, 200)}…` : json;
+  } catch {
+    return String(value);
+  }
+}
+
+// src/conformance/fixtures.ts
+var at = (iso) => new Date(iso);
+var fresh = () => `user-${mintId2()}@example.test`;
+function userRecord(overrides = {}) {
+  const email = fresh();
+  return {
+    id: mintId2(),
+    type: "user",
+    schemaVersion: "1",
+    active: true,
+    fields: { email, name: { first: "Ada", last: "Lovelace" } },
+    logins: [email],
+    password: {
+      hash: "$scrypt$ln=17,r=8,p=1$c2FsdA==$a2V5",
+      updatedAt: at("2026-01-01T00:00:00.000Z")
+    },
+    emailVerifiedAt: null,
+    version: 0,
+    createdAt: at("2026-01-01T00:00:00.000Z"),
+    updatedAt: at("2026-01-01T00:00:00.000Z"),
+    ...overrides
+  };
+}
+function sessionRecord(overrides = {}) {
+  return {
+    id: mintId2(),
+    tokenHash: hexOf(mintId2()),
+    userId: mintId2(),
+    authenticatedAt: at("2026-01-01T00:00:00.000Z"),
+    expiresAt: at("2099-01-01T00:00:00.000Z"),
+    revokedAt: null,
+    createdAt: at("2026-01-01T00:00:00.000Z"),
+    ...overrides
+  };
+}
+function tokenRecord(overrides = {}) {
+  return {
+    tokenHash: hexOf(mintId2()),
+    kind: "resetPassword",
+    userId: mintId2(),
+    address: fresh(),
+    expiresAt: at("2099-01-01T00:00:00.000Z"),
+    spentAt: null,
+    createdAt: at("2026-01-01T00:00:00.000Z"),
+    ...overrides
+  };
+}
+function hexOf(seed) {
+  return seed.replace(/-/g, "").padEnd(64, "0").slice(0, 64);
+}
+
+// src/conformance/cases/outage.ts
+function outage(slot, method, call, seed) {
+  return {
+    id: `outage.${method}`,
+    group: "outage",
+    name: `${slot}.${method} rejects when the store cannot answer — never null, false, 0 or an empty page`,
+    needs: "faults",
+    async run(context) {
+      await seed(context);
+      await context.faults?.fail(slot, method);
+      const error = await rejects(call(context), `${slot}.${method} under an outage should reject: answering an absence turns an outage into a silent lockout`);
+      if (error instanceof JanusError2 || error?.name === "StoreFailure") {
+        isOurs(error, StoreFailure2, `${slot}.${method} under an outage`);
+      }
+      ok(error?.code !== "NOT_FOUND", `${slot}.${method} under an outage rejected with NOT_FOUND: an outage is never an absence`);
+    }
+  };
+}
+var user = userRecord();
+var session = sessionRecord({ userId: user.id });
+var token = tokenRecord({ userId: user.id });
+var now = at("2026-02-01T00:00:00.000Z");
+var seed = async ({ stores }) => {
+  await stores.users.insertUser(user);
+  await stores.sessions.insertSession(session);
+  await stores.tokens.insertToken(token);
+};
+var outageCases = [
+  outage("users", "findUser", ({ stores }) => stores.users.findUser(user.id), seed),
+  outage("users", "findUserByLogin", ({ stores }) => stores.users.findUserByLogin(user.type, user.logins[0] ?? ""), seed),
+  outage("users", "listUsers", ({ stores }) => stores.users.listUsers({ type: user.type, after: null, limit: 10 }), seed),
+  outage("sessions", "findSessionByTokenHash", ({ stores }) => stores.sessions.findSessionByTokenHash(session.tokenHash), seed),
+  outage("sessions", "extendSession", ({ stores }) => stores.sessions.extendSession(session.id, at("2099-06-01T00:00:00.000Z")), seed),
+  outage("sessions", "revokeSession", ({ stores }) => stores.sessions.revokeSession(session.id, now), seed),
+  outage("sessions", "revokeUserSessions", ({ stores }) => stores.sessions.revokeUserSessions(user.id, now), seed),
+  outage("tokens", "consumeToken", ({ stores }) => stores.tokens.consumeToken(token.tokenHash, "resetPassword", now), seed),
+  outage("users", "deleteUser", ({ stores }) => stores.users.deleteUser(user.id), seed),
+  outage("sessions", "deleteUserSessions", ({ stores }) => stores.sessions.deleteUserSessions(user.id), seed),
+  outage("tokens", "deleteUserTokens", ({ stores }) => stores.tokens.deleteUserTokens(user.id), seed)
+];
+// src/conformance/cases/sessions.ts
+var group = "sessions";
+var sessionStoreCases = [
+  {
+    id: "sessions.verbatim",
+    group,
+    name: "answers a stored session verbatim — revoked or lapsed — or null once lapsed, and never a changed record",
+    async run({ stores }) {
+      const standing = sessionRecord();
+      const revoked = sessionRecord({
+        revokedAt: at("2026-01-02T00:00:00.000Z")
+      });
+      const lapsed = sessionRecord({
+        expiresAt: at("2020-01-01T00:00:00.000Z")
+      });
+      for (const record of [standing, revoked, lapsed]) {
+        await stores.sessions.insertSession(record);
+      }
+      equal(await stores.sessions.findSessionByTokenHash(standing.tokenHash), standing, "findSessionByTokenHash for a standing session");
+      equal(await stores.sessions.findSessionByTokenHash(revoked.tokenHash), revoked, "findSessionByTokenHash for a revoked session should answer it verbatim — revocation is the core’s to read");
+      const found = await stores.sessions.findSessionByTokenHash(lapsed.tokenHash);
+      if (found !== null) {
+        equal(found, lapsed, "findSessionByTokenHash for a lapsed session should answer it verbatim, or null");
+      }
+      isNull(await stores.sessions.findSessionByTokenHash("f".repeat(64)), "findSessionByTokenHash for an unknown hash");
+    }
+  },
+  {
+    id: "sessions.idempotentInsert",
+    group,
+    name: "is idempotent under retry: inserting an existing session id writes nothing",
+    async run({ stores }) {
+      const record = sessionRecord();
+      await stores.sessions.insertSession(record);
+      await stores.sessions.insertSession({
+        ...record,
+        expiresAt: new Date("2099-06-01T00:00:00.000Z")
+      });
+      equal(await stores.sessions.findSessionByTokenHash(record.tokenHash), record, "insertSession retried with the same id should write nothing");
+    }
+  },
+  {
+    id: "sessions.extend",
+    group,
+    name: "extends a standing session, and never brings back a revoked one",
+    async run({ stores }) {
+      const standing = sessionRecord();
+      const revoked = sessionRecord({
+        revokedAt: at("2026-01-02T00:00:00.000Z")
+      });
+      await stores.sessions.insertSession(standing);
+      await stores.sessions.insertSession(revoked);
+      const later = at("2099-06-01T00:00:00.000Z");
+      equal(await stores.sessions.extendSession(standing.id, later), { ...standing, expiresAt: later }, "extendSession should answer the session with its new expiresAt");
+      isNull(await stores.sessions.extendSession(revoked.id, later), "extendSession on a revoked session — an extension racing a revocation must never bring it back");
+      equal(await stores.sessions.findSessionByTokenHash(revoked.tokenHash), revoked, "extendSession refused on a revoked session should have written nothing");
+      isNull(await stores.sessions.extendSession(mintId2(), later), "extendSession on an unknown session");
+    }
+  },
+  {
+    id: "sessions.revoke",
+    group,
+    name: "revokes once and keeps the first revokedAt; answers false only when there is no session",
+    async run({ stores }) {
+      const record = sessionRecord();
+      await stores.sessions.insertSession(record);
+      const first = at("2026-02-01T00:00:00.000Z");
+      equal(await stores.sessions.revokeSession(record.id, first), true, "revokeSession on a standing session");
+      equal(await stores.sessions.revokeSession(record.id, at("2026-03-01T00:00:00.000Z")), true, "revokeSession on a revoked session still answers true: the session exists");
+      equal((await stores.sessions.findSessionByTokenHash(record.tokenHash))?.revokedAt, first, "revokeSession twice should keep the first revokedAt");
+      equal(await stores.sessions.revokeSession(mintId2(), first), false, "revokeSession on an unknown session");
+    }
+  },
+  {
+    id: "sessions.revokeUser",
+    group,
+    name: "revokes every standing session of one user but the one excepted, and counts only what it revoked",
+    async run({ stores }) {
+      const userId = mintId2();
+      const current = sessionRecord({ userId });
+      const other = sessionRecord({ userId });
+      const already = sessionRecord({
+        userId,
+        revokedAt: at("2026-01-02T00:00:00.000Z")
+      });
+      const stranger = sessionRecord();
+      for (const record of [current, other, already, stranger]) {
+        await stores.sessions.insertSession(record);
+      }
+      const now = at("2026-02-01T00:00:00.000Z");
+      equal(await stores.sessions.revokeUserSessions(userId, now, current.id), 1, "revokeUserSessions with except: how many this call revoked");
+      isNull((await stores.sessions.findSessionByTokenHash(current.tokenHash))?.revokedAt ?? null, "revokeUserSessions should spare the excepted session");
+      equal((await stores.sessions.findSessionByTokenHash(already.tokenHash))?.revokedAt, already.revokedAt, "revokeUserSessions should keep an earlier revokedAt");
+      equal(await stores.sessions.findSessionByTokenHash(stranger.tokenHash), stranger, "revokeUserSessions should not touch another user");
+      equal(await stores.sessions.revokeUserSessions(userId, now), 1, "revokeUserSessions without except");
+      equal(await stores.sessions.revokeUserSessions(mintId2(), now), 0, "revokeUserSessions for a user with none answers 0, not a failure");
+    }
+  },
+  {
+    id: "sessions.deleteUser",
+    group,
+    name: "deletes every session of one user — standing, revoked or lapsed — and counts them",
+    async run({ stores }) {
+      const userId = mintId2();
+      const records = [
+        sessionRecord({ userId }),
+        sessionRecord({ userId, revokedAt: at("2026-01-02T00:00:00.000Z") }),
+        sessionRecord({ userId, expiresAt: at("2026-01-02T00:00:00.000Z") })
+      ];
+      const stranger = sessionRecord();
+      for (const record of [...records, stranger]) {
+        await stores.sessions.insertSession(record);
+      }
+      equal(await stores.sessions.deleteUserSessions(userId), 3, "deleteUserSessions: how many it deleted, revoked and lapsed ones included");
+      for (const record of records) {
+        isNull(await stores.sessions.findSessionByTokenHash(record.tokenHash), "findSessionByTokenHash after deleteUserSessions");
+      }
+      equal(await stores.sessions.findSessionByTokenHash(stranger.tokenHash), stranger, "deleteUserSessions should not touch another user");
+      equal(await stores.sessions.deleteUserSessions(userId), 0, "deleteUserSessions for a user with none answers 0, not a failure");
+    }
+  },
+  {
+    id: "sessions.deleteExpired",
+    group,
+    name: "deletes sessions whose expiry is at or before the instant, and only those",
+    needs: "deleteExpiredSessions",
+    async run({ stores }) {
+      const collect = stores.sessions.deleteExpiredSessions;
+      ok(collect !== undefined, "deleteExpiredSessions should be present");
+      const lapsed = sessionRecord({
+        expiresAt: at("2026-01-10T00:00:00.000Z")
+      });
+      const living = sessionRecord({
+        expiresAt: at("2026-01-10T00:00:00.001Z")
+      });
+      await stores.sessions.insertSession(lapsed);
+      await stores.sessions.insertSession(living);
+      equal(await collect?.call(stores.sessions, at("2026-01-10T00:00:00.000Z")), 1, "deleteExpiredSessions: how many it deleted");
+      isNull(await stores.sessions.findSessionByTokenHash(lapsed.tokenHash), "findSessionByTokenHash after deleteExpiredSessions");
+      equal(await stores.sessions.findSessionByTokenHash(living.tokenHash), living, "deleteExpiredSessions should keep a session one millisecond short of lapsing");
+    }
+  }
+];
+// src/conformance/cases/tokens.ts
+var group2 = "tokens";
+var tokenStoreCases = [
+  {
+    id: "tokens.consume",
+    group: group2,
+    name: "answers the token as it was before the call: spentAt null means this call spent it",
+    async run({ stores }) {
+      const record = tokenRecord();
+      await stores.tokens.insertToken(record);
+      const first = at("2026-02-01T00:00:00.000Z");
+      equal(await stores.tokens.consumeToken(record.tokenHash, "resetPassword", first), record, "consumeToken the first time should answer the token as it was — spentAt null");
+      equal(await stores.tokens.consumeToken(record.tokenHash, "resetPassword", at("2026-02-02T00:00:00.000Z")), { ...record, spentAt: first }, "consumeToken the second time should answer it spent at the first call’s instant, and change nothing");
+    }
+  },
+  {
+    id: "tokens.concurrency",
+    group: group2,
+    name: "lets exactly one of twenty concurrent redemptions spend a token — one conditional write, never a read then a write",
+    async run({ stores }) {
+      const record = tokenRecord();
+      await stores.tokens.insertToken(record);
+      const now = at("2026-02-01T00:00:00.000Z");
+      const answers = await Promise.all(Array.from({ length: 20 }, () => stores.tokens.consumeToken(record.tokenHash, "resetPassword", now)));
+      equal(answers.filter((answer) => answer !== null && answer.spentAt === null).length, 1, "consumeToken: of twenty concurrent calls, exactly one should see spentAt null — a reset code redeemed twice is an account takeover");
+    }
+  },
+  {
+    id: "tokens.kind",
+    group: group2,
+    name: "does not know, and does not spend, a token of the other kind",
+    async run({ stores }) {
+      const record = tokenRecord({ kind: "verifyEmail" });
+      await stores.tokens.insertToken(record);
+      isNull(await stores.tokens.consumeToken(record.tokenHash, "resetPassword", at("2026-02-01T00:00:00.000Z")), "consumeToken for a verifyEmail token redeemed as resetPassword");
+      const own = await stores.tokens.consumeToken(record.tokenHash, "verifyEmail", at("2026-02-02T00:00:00.000Z"));
+      equal(own, record, "consumeToken of the other kind should not have spent the token: redeemed as its own kind, it is still unspent");
+      isNull(await stores.tokens.consumeToken("0".repeat(64), "resetPassword", at("2026-02-01T00:00:00.000Z")), "consumeToken for an unknown hash");
+    }
+  },
+  {
+    id: "tokens.lapsed",
+    group: group2,
+    name: "spends a lapsed token all the same: expiry is compared by the core, after the call",
+    async run({ stores }) {
+      const record = tokenRecord({ expiresAt: at("2020-01-01T00:00:00.000Z") });
+      await stores.tokens.insertToken(record);
+      const now = at("2026-02-01T00:00:00.000Z");
+      const first = await stores.tokens.consumeToken(record.tokenHash, "resetPassword", now);
+      if (first !== null) {
+        equal(first, record, "consumeToken on a lapsed token should answer it as it was");
+        equal((await stores.tokens.consumeToken(record.tokenHash, "resetPassword", now))?.spentAt, now, "consumeToken should have spent the lapsed token, so it can never be retried");
+      }
+    }
+  },
+  {
+    id: "tokens.idempotentInsert",
+    group: group2,
+    name: "is idempotent under retry: inserting an existing token hash writes nothing",
+    async run({ stores }) {
+      const record = tokenRecord();
+      await stores.tokens.insertToken(record);
+      await stores.tokens.insertToken({
+        ...record,
+        address: "other@example.test"
+      });
+      equal(await stores.tokens.consumeToken(record.tokenHash, "resetPassword", at("2026-02-01T00:00:00.000Z")), record, "insertToken retried with the same hash should write nothing");
+    }
+  },
+  {
+    id: "tokens.deleteUser",
+    group: group2,
+    name: "deletes every token of one user, spent or not, of either kind, and counts them",
+    async run({ stores }) {
+      const userId = mintId2();
+      const records = [
+        tokenRecord({ userId }),
+        tokenRecord({ userId, kind: "verifyEmail" }),
+        tokenRecord({ userId, spentAt: at("2026-01-02T00:00:00.000Z") })
+      ];
+      const stranger = tokenRecord();
+      for (const record of [...records, stranger]) {
+        await stores.tokens.insertToken(record);
+      }
+      const now = at("2026-02-01T00:00:00.000Z");
+      equal(await stores.tokens.deleteUserTokens(userId), 3, "deleteUserTokens: how many it deleted");
+      for (const record of records) {
+        isNull(await stores.tokens.consumeToken(record.tokenHash, record.kind, now), "consumeToken after deleteUserTokens");
+      }
+      equal(await stores.tokens.consumeToken(stranger.tokenHash, stranger.kind, now), stranger, "deleteUserTokens should not touch another user");
+      equal(await stores.tokens.deleteUserTokens(userId), 0, "deleteUserTokens for a user with none answers 0, not a failure");
+    }
+  }
+];
+// src/conformance/cases/users.ts
+var group3 = "users";
+var userStoreCases = [
+  {
+    id: "users.roundTrip",
+    group: group3,
+    name: 'round-trips a record byte for byte: nested fields, a 1 that stays a number, a "1" that stays a string',
+    async run({ stores }) {
+      const record = userRecord({
+        fields: {
+          email: "Ada@Example.test",
+          name: { first: "Ada", last: "Lovelace" },
+          count: 1,
+          code: "1",
+          zero: 0,
+          flags: [true, false, null],
+          note: "  spaced  ",
+          unicode: "Ｂob — ÿ",
+          nested: { deep: { deeper: [1, { two: 2 }] } },
+          tags: ["a", "b"]
+        },
+        emailVerifiedAt: at("2026-01-02T00:00:00.000Z")
+      });
+      equal(await stores.users.insertUser(record), record, "insertUser should answer the record as stored");
+      equal(await stores.users.findUser(record.id), record, "findUser should answer the record exactly as it was written");
+    }
+  },
+  {
+    id: "users.absence",
+    group: group3,
+    name: "answers null for an absence, never undefined, and an empty page for an empty store",
+    async run({ stores }) {
+      isNull(await stores.users.findUser(mintId2()), "findUser for an unknown id");
+      isNull(await stores.users.findUserByLogin("user", "nobody@example.test"), "findUserByLogin for an unknown login");
+      equal(await stores.users.listUsers({ type: "user", after: null, limit: 10 }), { items: [], nextCursor: null }, "listUsers on an empty store should answer an empty page");
+    }
+  },
+  {
+    id: "users.loginBytes",
+    group: group3,
+    name: "compares logins as bytes, within one type: no case folding, no trimming, no collation",
+    async run({ stores }) {
+      const upper = userRecord({ logins: ["Ada@Example.test"] });
+      const lower = userRecord({ logins: ["ada@example.test"] });
+      const staff = userRecord({ type: "staff", logins: ["ada@example.test"] });
+      for (const record of [upper, lower, staff]) {
+        await stores.users.insertUser(record);
+      }
+      equal((await stores.users.findUserByLogin("user", "Ada@Example.test"))?.id, upper.id, "findUserByLogin should find the login with its exact bytes");
+      equal((await stores.users.findUserByLogin("user", "ada@example.test"))?.id, lower.id, 'findUserByLogin should tell "Ada@…" from "ada@…": normalisation is the core’s');
+      equal((await stores.users.findUserByLogin("staff", "ada@example.test"))?.id, staff.id, "uniqueness is of (type, login): the same login under another type is another account");
+    }
+  },
+  {
+    id: "users.idempotentInsert",
+    group: group3,
+    name: "is idempotent under retry: inserting an existing id answers the stored record and writes nothing",
+    async run({ stores }) {
+      const record = userRecord();
+      await stores.users.insertUser(record);
+      const retried = await stores.users.insertUser({
+        ...record,
+        fields: { email: "changed@example.test" }
+      });
+      equal(retried, record, "insertUser retried with the same id should answer the stored record");
+      equal(await stores.users.findUser(record.id), record, "insertUser retried should write nothing");
+    }
+  },
+  {
+    id: "users.uniqueness",
+    group: group3,
+    name: "lets exactly one of twenty concurrent inserts hold a login: uniqueness is a constraint, not a read",
+    async run({ stores }) {
+      const records = Array.from({ length: 20 }, () => userRecord({ logins: ["contested@example.test"] }));
+      const outcomes = await Promise.allSettled(records.map((record) => stores.users.insertUser(record)));
+      const accepted = outcomes.filter((o) => o.status === "fulfilled");
+      const refused = outcomes.flatMap((o) => o.status === "rejected" ? [o.reason] : []);
+      equal(accepted.length, 1, "insertUser: of twenty concurrent inserts of one login, exactly one should be accepted — a read followed by a write lets several through");
+      for (const error of refused) {
+        isOurs(error, StoreConflict2, "insertUser should refuse a taken login with StoreConflict");
+        equal(error.code, "LOGIN_TAKEN", "insertUser: the conflict code");
+        equal(error.login, "contested@example.test", "insertUser: the conflict should name the login");
+      }
+      let stored = 0;
+      for (const record of records) {
+        if (await stores.users.findUser(record.id) !== null)
+          stored += 1;
+      }
+      equal(stored, 1, "insertUser: a refused insert should write nothing");
+    }
+  },
+  {
+    id: "users.versionIncrements",
+    group: group3,
+    name: "applies an update at the expected version, and answers the record written with its version one higher",
+    async run({ stores }) {
+      const record = userRecord();
+      await stores.users.insertUser(record);
+      const written = await stores.users.updateUser(record.id, { updatedAt: at("2026-02-01T00:00:00.000Z"), active: false }, 0);
+      const expected = {
+        ...record,
+        active: false,
+        version: 1,
+        updatedAt: at("2026-02-01T00:00:00.000Z")
+      };
+      equal(written, expected, "updateUser should answer the record as written");
+      equal(await stores.users.findUser(record.id), expected, "findUser after updateUser");
+    }
+  },
+  {
+    id: "users.versionConflict",
+    group: group3,
+    name: "refuses a stale version with both versions, and leaves the record identical byte for byte",
+    async run({ stores }) {
+      const record = userRecord();
+      await stores.users.insertUser(record);
+      await stores.users.updateUser(record.id, { updatedAt: at("2026-02-01T00:00:00.000Z"), active: false }, 0);
+      const before = await stores.users.findUser(record.id);
+      const error = await rejects(stores.users.updateUser(record.id, {
+        updatedAt: at("2026-03-01T00:00:00.000Z"),
+        active: true,
+        fields: { email: "overwritten@example.test" }
+      }, 0), "updateUser at a stale version should reject");
+      isOurs(error, StoreConflict2, "updateUser at a stale version should reject with StoreConflict");
+      equal(error.code, "VERSION_CONFLICT", "updateUser: the conflict code");
+      equal(error.expectedVersion, 0, "updateUser: expectedVersion");
+      equal(error.actualVersion, 1, "updateUser: actualVersion");
+      equal(await stores.users.findUser(record.id), before, "updateUser refused for its version should have written nothing");
+    }
+  },
+  {
+    id: "users.unknownUpdate",
+    group: group3,
+    name: "refuses an update to an unknown id with NotFoundError, told apart from a version conflict",
+    async run({ stores }) {
+      const error = await rejects(stores.users.updateUser(mintId2(), { updatedAt: at("2026-02-01T00:00:00.000Z") }, 0), "updateUser on an unknown id should reject");
+      isOurs(error, NotFoundError2, "updateUser on an unknown id should reject with NotFoundError, not a version conflict");
+    }
+  },
+  {
+    id: "users.omission",
+    group: group3,
+    name: "omission — the Kratos PUT trap: an update leaves every field it does not name exactly as it was",
+    async run({ stores }) {
+      const record = userRecord({
+        fields: { email: "kept@example.test", plan: "pro" },
+        emailVerifiedAt: at("2026-01-02T00:00:00.000Z")
+      });
+      await stores.users.insertUser(record);
+      const written = await stores.users.updateUser(record.id, { updatedAt: at("2026-02-01T00:00:00.000Z"), schemaVersion: "2" }, 0);
+      equal(written, {
+        ...record,
+        schemaVersion: "2",
+        version: 1,
+        updatedAt: at("2026-02-01T00:00:00.000Z")
+      }, "updateUser naming only schemaVersion should leave active, fields, logins, password and emailVerifiedAt untouched");
+    }
+  },
+  {
+    id: "users.passwordSlot",
+    group: group3,
+    name: "keeps a password the patch does not name, and removes one the patch names null",
+    async run({ stores }) {
+      const record = userRecord();
+      await stores.users.insertUser(record);
+      const kept = await stores.users.updateUser(record.id, { updatedAt: at("2026-02-01T00:00:00.000Z") }, 0);
+      equal(kept.password, record.password, "updateUser not naming password should keep it");
+      const removed = await stores.users.updateUser(record.id, { updatedAt: at("2026-02-02T00:00:00.000Z"), password: null }, 1);
+      isNull(removed.password, "updateUser with password: null should remove the password");
+    }
+  },
+  {
+    id: "users.loginsMove",
+    group: group3,
+    name: "moves logins on update: the old one is free, the new one found, one held elsewhere refused",
+    async run({ stores }) {
+      const record = userRecord();
+      const other = userRecord();
+      await stores.users.insertUser(record);
+      await stores.users.insertUser(other);
+      const [old] = record.logins;
+      const moved = "moved@example.test";
+      await stores.users.updateUser(record.id, { updatedAt: at("2026-02-01T00:00:00.000Z"), logins: [moved] }, 0);
+      isNull(await stores.users.findUserByLogin("user", old ?? ""), "findUserByLogin for a login the update replaced");
+      equal((await stores.users.findUserByLogin("user", moved))?.id, record.id, "findUserByLogin for the login the update wrote");
+      const error = await rejects(stores.users.updateUser(other.id, { updatedAt: at("2026-02-02T00:00:00.000Z"), logins: [moved] }, 0), "updateUser onto a login another user holds should reject");
+      isOurs(error, StoreConflict2, "updateUser onto a held login should reject with StoreConflict");
+      equal(error.code, "LOGIN_TAKEN", "updateUser: the conflict code");
+      equal(await stores.users.findUser(other.id), other, "updateUser refused for a login should have written nothing");
+    }
+  },
+  {
+    id: "users.pagination",
+    group: group3,
+    name: "pages 25 users of one type by 10 in ascending id order, with no gap, no repeat and no other type, and ends on a null cursor",
+    async run({ stores }) {
+      const records = Array.from({ length: 25 }, () => userRecord());
+      const others = Array.from({ length: 5 }, () => userRecord({ type: "staff" }));
+      for (const [index, record] of [...records].reverse().entries()) {
+        await stores.users.insertUser(record);
+        const other = others[index];
+        if (other !== undefined)
+          await stores.users.insertUser(other);
+      }
+      const expected = records.map((record) => record.id).sort();
+      const seen = [];
+      const sizes = [];
+      let after = null;
+      for (let page = 0;page < 10; page += 1) {
+        const answer = await stores.users.listUsers({
+          type: "user",
+          after,
+          limit: 10
+        });
+        seen.push(...answer.items.map((item) => item.id));
+        sizes.push(answer.items.length);
+        after = answer.nextCursor;
+        if (after === null)
+          break;
+      }
+      equal(sizes, [10, 10, 5], "listUsers: page sizes for 25 users by 10");
+      equal(seen, expected, "listUsers: every id of the type once, in ascending order");
+      const between = await stores.users.listUsers({
+        type: "user",
+        after: "00000000-0000-7000-8000-000000000000",
+        limit: 3
+      });
+      ok(between.items[0]?.id === expected[0], "listUsers: a cursor naming no stored user should start after it, not fail");
+    }
+  },
+  {
+    id: "users.delete",
+    group: group3,
+    name: "deletes a user and frees their logins, answers false for nobody, and touches no other user",
+    async run({ stores }) {
+      const record = userRecord();
+      const other = userRecord();
+      await stores.users.insertUser(record);
+      await stores.users.insertUser(other);
+      const [login] = record.logins;
+      equal(await stores.users.deleteUser(record.id), true, "deleteUser for a stored user should answer true");
+      isNull(await stores.users.findUser(record.id), "findUser after deleteUser");
+      isNull(await stores.users.findUserByLogin(record.type, login ?? ""), "findUserByLogin for a deleted user’s login");
+      equal(await stores.users.deleteUser(record.id), false, "deleteUser replayed should answer false, not fail: a deletion interrupted half-way is replayed");
+      equal(await stores.users.findUser(other.id), other, "deleteUser should not touch another user");
+      const successor = userRecord({ logins: [login ?? ""] });
+      equal(await stores.users.insertUser(successor), successor, "insertUser onto a deleted user’s login should succeed");
+    }
+  }
+];
+// src/conformance/describe.ts
+var allCases = [
+  ...userStoreCases,
+  ...sessionStoreCases,
+  ...tokenStoreCases,
+  ...outageCases
+];
+var SKIP_REASONS = {
+  faults: "faults not provided: the outage invariant is not proven for this adapter",
+  deleteExpiredSessions: "stores.sessions does not implement the optional deleteExpiredSessions"
+};
+async function runCase(conformanceCase, harness) {
+  const opened = await harness.open();
+  try {
+    if (conformanceCase.needs === "faults" && opened.faults === undefined) {
+      return { skipped: SKIP_REASONS.faults };
+    }
+    if (conformanceCase.needs === "deleteExpiredSessions" && opened.stores.sessions.deleteExpiredSessions === undefined) {
+      return { skipped: SKIP_REASONS.deleteExpiredSessions };
+    }
+    await conformanceCase.run({
+      stores: opened.stores,
+      faults: opened.faults ?? null
+    });
+    return { passed: true };
+  } finally {
+    await opened.close?.();
+  }
+}
+function describeJanusStores(options) {
+  describeSuite({
+    title: `${options.name} — @nxgt/janus conformance`,
+    cases: allCases,
+    run: (conformanceCase) => runCase(conformanceCase, options.harness),
+    runner: options.runner ?? fromGlobals("describeJanusStores"),
+    skip: options.skip ?? {},
+    faults: options.faults
+  });
+}
+function describeSuite(options) {
+  const { runner, skip, cases } = options;
+  const groups = [...new Set(cases.map((c) => c.group))];
+  const title = options.faults === false ? `${options.title} (WITHOUT faults: ${SKIP_REASONS.faults})` : options.title;
+  runner.describe(title, () => {
+    for (const group of groups) {
+      runner.describe(group, () => {
+        for (const conformanceCase of cases.filter((c) => c.group === group)) {
+          const reason = skip[conformanceCase.id];
+          if (reason !== undefined) {
+            runner.it.skip(`${conformanceCase.name} — skipped: ${reason}`, async () => {});
+            continue;
+          }
+          if (conformanceCase.needs === "faults" && options.faults === false) {
+            runner.it.skip(`${conformanceCase.name} — skipped: ${SKIP_REASONS.faults}`, async () => {});
+            continue;
+          }
+          runner.it(conformanceCase.name, async () => {
+            const outcome = await options.run(conformanceCase);
+            if ("skipped" in outcome) {
+              process.emitWarning(`${conformanceCase.id} skipped: ${outcome.skipped}`, { code: "JANUS_CONFORMANCE_SKIPPED" });
+            }
+          });
+        }
+      });
+    }
+  });
+}
+function fromGlobals(where) {
+  const globals = globalThis;
+  if (typeof globals.describe !== "function" || typeof globals.it !== "function") {
+    throw new TypeError(`${where}: no test runner on globalThis — pass runner: { describe, it } (under bun test: import them from 'bun:test')`);
+  }
+  return { describe: globals.describe, it: globals.it };
+}
+// src/conformance/reference.ts
+function referenceHarness() {
+  return {
+    async open() {
+      const failing = new Set;
+      const stores = withFaults(createMemoryStores2(), failing);
+      const faults = {
+        async fail(slot, method) {
+          failing.add(`${slot}.${method}`);
+        }
+      };
+      return { stores, faults };
+    }
+  };
+}
+function withFaults(stores, failing) {
+  const wrap = (slot, store) => {
+    const wrapped = {};
+    for (const [method, fn] of Object.entries(store)) {
+      wrapped[method] = (...args) => {
+        if (failing.has(`${slot}.${method}`)) {
+          return Promise.reject(new StoreFailure2(`${slot}.${method}: the store could not answer`, {
+            slot,
+            operation: method
+          }));
+        }
+        return fn.apply(store, args);
+      };
+    }
+    return wrapped;
+  };
+  return {
+    users: wrap("users", stores.users),
+    sessions: wrap("sessions", stores.sessions),
+    tokens: wrap("tokens", stores.tokens)
+  };
+}
+// src/conformance/relations.ts
+var entity = (type, id = mintId2()) => ({ type, id });
+var set = (type, id, relation) => ({
+  type,
+  id,
+  relation
+});
+var tuple = (object, relation, subject) => ({ object, relation, subject });
+var sorted = (subjects) => subjects.map(formatSubject2).sort();
+var group4 = "relations";
+var relationStoreCases = [
+  {
+    id: "relations.roundTrip",
+    group: group4,
+    name: "holds exactly the tuples written, byte for byte: staff:u1 is not patient:u1, and a set is not its entity",
+    async run({ store }) {
+      const record = entity("record", "Ｒ:1 — ÿ");
+      const direct = tuple(record, "viewer", entity("staff", "u1"));
+      const inherited = tuple(record, "viewer", set("team", "t1", "member"));
+      await store.write({ add: [direct, inherited] });
+      equal(await store.has(direct), true, "has for a written tuple");
+      equal(await store.has(inherited), true, "has for a written subject set");
+      equal(await store.has(tuple(record, "viewer", entity("patient", "u1"))), false, "has for the same id under another subject type: types are part of the subject");
+      equal(await store.has(tuple(record, "viewer", entity("team", "t1"))), false, "has for the entity of a stored subject set: a set is not its entity");
+      equal(await store.has(tuple(entity("record", "r:1 — ÿ"), "viewer", direct.subject)), false, "has for an id differing in one character: ids are compared as written");
+    }
+  },
+  {
+    id: "relations.undefinedRelation",
+    group: group4,
+    name: "reads a subject whose relation is undefined as its entity, not as a set",
+    async run({ store }) {
+      const record = entity("record");
+      const staff = entity("staff");
+      const spread = { ...staff, relation: undefined };
+      await store.write({ add: [tuple(record, "viewer", spread)] });
+      equal(await store.has(tuple(record, "viewer", staff)), true, "has for the entity, after writing it with relation: undefined");
+      equal(await store.findEntities(record, "viewer"), [staff], "findEntities: the tuple names an entity");
+      equal(await store.findSubjectSets(record, "viewer"), [], "findSubjectSets: relation: undefined is no set");
+      equal(await store.findObjects({
+        type: "record",
+        relation: "viewer",
+        subject: spread,
+        after: null,
+        limit: 10
+      }), { items: [record.id], nextCursor: null }, "findObjects for the subject written with relation: undefined");
+      equal(await store.findObjects({
+        type: "record",
+        relation: "viewer",
+        subject: set("staff", staff.id, "x"),
+        after: null,
+        limit: 10
+      }), { items: [], nextCursor: null }, "findObjects for a set of that entity: the entity is not a set");
+      await store.write({ remove: [tuple(record, "viewer", spread)] });
+      equal(await store.has(tuple(record, "viewer", staff)), false, "has after removing it with relation: undefined");
+    }
+  },
+  {
+    id: "relations.absence",
+    group: group4,
+    name: "answers false, [], an empty page and 0 for an empty store — never null or undefined",
+    async run({ store }) {
+      const record = entity("record");
+      const staff = entity("staff");
+      equal(await store.has(tuple(record, "viewer", staff)), false, "has");
+      equal(await store.findSubjectSets(record, "viewer"), [], "findSubjectSets");
+      equal(await store.findEntities(record, "viewer"), [], "findEntities");
+      equal(await store.findObjects({
+        type: "record",
+        relation: "viewer",
+        subject: staff,
+        after: null,
+        limit: 10
+      }), { items: [], nextCursor: null }, "findObjects on an empty store");
+      equal(await store.deleteEntity(staff), 0, "deleteEntity");
+    }
+  },
+  {
+    id: "relations.idempotentWrite",
+    group: group4,
+    name: "is idempotent under retry: adding a stored tuple and removing an absent one write nothing",
+    async run({ store }) {
+      const record = entity("record");
+      const viewer = tuple(record, "viewer", entity("team"));
+      await store.write({ add: [viewer] });
+      await store.write({ add: [viewer] });
+      await store.write({ remove: [tuple(record, "viewer", entity("team"))] });
+      equal((await store.findEntities(record, "viewer")).length, 1, "findEntities after the same tuple was added twice");
+    }
+  },
+  {
+    id: "relations.uniqueness",
+    group: group4,
+    name: "keeps one tuple when twenty concurrent writes add it: uniqueness is a constraint, not a read",
+    async run({ store }) {
+      const record = entity("record");
+      const parent = entity("folder");
+      await Promise.all(Array.from({ length: 20 }, () => store.write({ add: [tuple(record, "parent", parent)] })));
+      equal(await store.findEntities(record, "parent"), [parent], "findEntities after twenty concurrent adds of one tuple");
+    }
+  },
+  {
+    id: "relations.removeThenAdd",
+    group: group4,
+    name: "applies one write’s removals and additions together",
+    async run({ store }) {
+      const record = entity("record");
+      const before = tuple(record, "owner", entity("staff", "a"));
+      const after = tuple(record, "owner", entity("staff", "b"));
+      await store.write({ add: [before] });
+      await store.write({ remove: [before], add: [after] });
+      equal(await store.has(before), false, "the removed tuple");
+      equal(await store.has(after), true, "the added tuple");
+    }
+  },
+  {
+    id: "relations.oneHop",
+    group: group4,
+    name: "answers one hop: the subject sets and the entities holding one relation on one object, and nothing else",
+    async run({ store }) {
+      const record = entity("record");
+      const staff = entity("staff");
+      const team = entity("team");
+      const members = set("team", team.id, "member");
+      const leads = set("team", team.id, "lead");
+      await store.write({
+        add: [
+          tuple(record, "viewer", staff),
+          tuple(record, "viewer", team),
+          tuple(record, "viewer", members),
+          tuple(record, "viewer", leads),
+          tuple(record, "editor", set("team", team.id, "admin")),
+          tuple(entity("record"), "viewer", set("team", "other", "member"))
+        ]
+      });
+      equal(sorted(await store.findSubjectSets(record, "viewer")), sorted([members, leads]), "findSubjectSets: the sets only, of this object and this relation");
+      equal(sorted(await store.findEntities(record, "viewer")), sorted([staff, team]), "findEntities: the single entities only, of this object and this relation");
+    }
+  },
+  {
+    id: "relations.objects",
+    group: group4,
+    name: "pages 25 objects by 10 in ascending id order, for one type, relation and exact subject, and ends on a null cursor",
+    async run({ store }) {
+      const staff = entity("staff");
+      const ids = Array.from({ length: 25 }, (_, n) => `r${String(n).padStart(2, "0")}`);
+      for (const id of [...ids].reverse()) {
+        await store.write({
+          add: [
+            tuple(entity("record", id), "viewer", staff),
+            tuple(entity("record", `${id}x`), "editor", staff),
+            tuple(entity("folder", id), "viewer", staff),
+            tuple(entity("record", `${id}y`), "viewer", set("staff", staff.id, "x"))
+          ]
+        });
+      }
+      const seen = [];
+      const sizes = [];
+      let after = null;
+      for (let page = 0;page < 10; page += 1) {
+        const answer = await store.findObjects({
+          type: "record",
+          relation: "viewer",
+          subject: staff,
+          after,
+          limit: 10
+        });
+        seen.push(...answer.items);
+        sizes.push(answer.items.length);
+        after = answer.nextCursor;
+        if (after === null)
+          break;
+      }
+      equal(sizes, [10, 10, 5], "findObjects: page sizes for 25 objects by 10");
+      equal(seen, ids, "findObjects: every id once, in ascending order");
+      const between = await store.findObjects({
+        type: "record",
+        relation: "viewer",
+        subject: staff,
+        after: "r04a",
+        limit: 2
+      });
+      equal(between.items, ["r05", "r06"], "findObjects: a cursor naming no stored object should start after it");
+    }
+  },
+  {
+    id: "relations.deleteEntity",
+    group: group4,
+    name: "deletes every tuple naming an entity — as object, as subject, as a set’s entity — and counts them",
+    async run({ store }) {
+      const team = entity("team");
+      const other = entity("team");
+      const kept = [
+        tuple(other, "member", entity("staff")),
+        tuple(entity("record"), "viewer", set("team", other.id, "member"))
+      ];
+      await store.write({
+        add: [
+          tuple(team, "member", entity("staff")),
+          tuple(entity("record"), "team", team),
+          tuple(entity("record"), "viewer", set("team", team.id, "member")),
+          ...kept
+        ]
+      });
+      equal(await store.deleteEntity(team), 3, "deleteEntity: how many it deleted");
+      for (const survivor of kept) {
+        equal(await store.has(survivor), true, "deleteEntity should not touch another entity");
+      }
+      equal(await store.deleteEntity(team), 0, "deleteEntity replayed answers 0, not a failure");
+    }
+  }
+];
+function outage2(method, call, after) {
+  return {
+    id: `outage.${method}`,
+    group: "outage",
+    name: `relations.${method} rejects when the store cannot answer — never false, [], an empty page or 0`,
+    needs: "faults",
+    async run({ store, faults }) {
+      await store.write({ add: [seeded] });
+      await faults?.fail(method);
+      const error = await rejects(call(store), `relations.${method} under an outage should reject`);
+      if (error instanceof JanusError2 || error?.name === "StoreFailure") {
+        isOurs(error, StoreFailure2, `relations.${method} under an outage`);
+      }
+      ok(error?.code !== "NOT_FOUND", `relations.${method} under an outage rejected with NOT_FOUND: an outage is never an absence`);
+      await after?.(store);
+    }
+  };
+}
+var seededObject = { type: "record", id: "seeded" };
+var seededSubject = { type: "staff", id: "seeded" };
+var seeded = tuple(seededObject, "viewer", seededSubject);
+var relationOutageCases = [
+  outage2("write", (store) => store.write({
+    remove: [seeded],
+    add: [tuple(seededObject, "owner", seededSubject)]
+  }), async (store) => {
+    equal(await store.has(seeded), true, "relations.write rejected, and still removed a tuple: a write is all or nothing");
+    equal(await store.has(tuple(seededObject, "owner", seededSubject)), false, "relations.write rejected, and still added a tuple: a write is all or nothing");
+  }),
+  outage2("has", (store) => store.has(seeded)),
+  outage2("findSubjectSets", (store) => store.findSubjectSets(seededObject, "viewer")),
+  outage2("findEntities", (store) => store.findEntities(seededObject, "viewer")),
+  outage2("findObjects", (store) => store.findObjects({
+    type: "record",
+    relation: "viewer",
+    subject: seededSubject,
+    after: null,
+    limit: 10
+  })),
+  outage2("deleteEntity", (store) => store.deleteEntity(seededSubject))
+];
+var allRelationCases = [
+  ...relationStoreCases,
+  ...relationOutageCases
+];
+async function runRelationCase(relationCase, harness) {
+  const opened = await harness.open();
+  try {
+    if (relationCase.needs === "faults" && opened.faults === undefined) {
+      return { skipped: SKIP_REASONS.faults };
+    }
+    await relationCase.run({
+      store: opened.store,
+      faults: opened.faults ?? null
+    });
+    return { passed: true };
+  } finally {
+    await opened.close?.();
+  }
+}
+function describeRelationStores(options) {
+  describeSuite({
+    title: `${options.name} — @nxgt/janus relation conformance`,
+    cases: allRelationCases,
+    run: (relationCase) => runRelationCase(relationCase, options.harness),
+    runner: options.runner ?? fromGlobals("describeRelationStores"),
+    skip: options.skip ?? {},
+    faults: options.faults
+  });
+}
+function referenceRelationHarness() {
+  return {
+    async open() {
+      const failing = new Set;
+      const inner = createMemoryRelations2();
+      const store = Object.fromEntries(Object.entries(inner).map(([method, fn]) => [
+        method,
+        (...args) => failing.has(method) ? Promise.reject(new StoreFailure2(`relations.${method}: the store could not answer`, {
+          slot: "relations",
+          operation: method
+        })) : fn.apply(inner, args)
+      ]));
+      return {
+        store,
+        faults: {
+          async fail(method) {
+            failing.add(method);
+          }
+        }
+      };
+    }
+  };
+}
+export {
+  SKIP_REASONS,
+  allCases,
+  allRelationCases,
+  describeJanusStores,
+  describeRelationStores,
+  outageCases,
+  referenceHarness,
+  referenceRelationHarness,
+  relationOutageCases,
+  relationStoreCases,
+  runCase,
+  runRelationCase,
+  sessionStoreCases,
+  tokenStoreCases,
+  userStoreCases
+};
+
+//# debugId=26762626E8104F4164756E2164756E21
+//# sourceMappingURL=index.js.map