@greatwait/contracts 0.1.0-alpha.1

package/dist/identifiers.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+/**
+ * Public identifiers.
+ *
+ * Every identifier a client sees is opaque, prefixed, and server-assigned.
+ * Clients must treat the part after the prefix as meaningless and compare
+ * identifiers only for equality.
+ *
+ * This is a deliberate break from the legacy scheduler, where the caller
+ * supplied `id` and tenancy travelled in the path as `:owner/:partition/:id`.
+ * Caller-chosen identifiers leak the caller's namespace into ours, make
+ * collision handling a client concern, and make it impossible to change
+ * internal representation later. See `docs/architecture/legacy-provenance.md`.
+ */
+/** The resource a prefix names. Extending this list is an additive change. */
+export declare const ID_PREFIXES: {
+    readonly apiCredential: "ak";
+    readonly apiCredentialEvent: "ake";
+    readonly attempt: "att";
+    readonly authorizationRequest: "oar";
+    readonly callbackSigningKey: "csk";
+    readonly delivery: "dlv";
+    readonly endpoint: "ep";
+    readonly environment: "env";
+    readonly event: "evt";
+    readonly oauthClient: "oc";
+    readonly oauthGrant: "og";
+    readonly oauthGrantEvent: "oge";
+    readonly occurrence: "occ";
+    readonly organization: "org";
+    readonly project: "proj";
+    readonly schedule: "sch";
+    readonly testSink: "tsk";
+    readonly testSinkDelivery: "tsd";
+};
+export type IdResource = keyof typeof ID_PREFIXES;
+export declare function idPattern(resource: IdResource): RegExp;
+/** Any well-formed public identifier, whatever it names. */
+export declare const ANY_ID_PATTERN: RegExp;
+export declare function idSchema(resource: IdResource): z.ZodString;
+export declare const apiCredentialIdSchema: z.ZodString;
+export declare const apiCredentialEventIdSchema: z.ZodString;
+export declare const authorizationRequestIdSchema: z.ZodString;
+export declare const callbackSigningKeyIdSchema: z.ZodString;
+export declare const oauthClientIdSchema: z.ZodString;
+export declare const oauthGrantIdSchema: z.ZodString;
+export declare const oauthGrantEventIdSchema: z.ZodString;
+export declare const scheduleIdSchema: z.ZodString;
+export declare const occurrenceIdSchema: z.ZodString;
+export declare const attemptIdSchema: z.ZodString;
+export declare const deliveryIdSchema: z.ZodString;
+export declare const endpointIdSchema: z.ZodString;
+export declare const organizationIdSchema: z.ZodString;
+export declare const projectIdSchema: z.ZodString;
+export declare const environmentIdSchema: z.ZodString;
+export declare const eventIdSchema: z.ZodString;
+export declare const testSinkIdSchema: z.ZodString;
+export declare const testSinkDeliveryIdSchema: z.ZodString;
+export type ApiCredentialId = z.infer<typeof apiCredentialIdSchema>;
+export type ApiCredentialEventId = z.infer<typeof apiCredentialEventIdSchema>;
+export type AuthorizationRequestId = z.infer<typeof authorizationRequestIdSchema>;
+export type CallbackSigningKeyId = z.infer<typeof callbackSigningKeyIdSchema>;
+export type OAuthClientId = z.infer<typeof oauthClientIdSchema>;
+export type OAuthGrantId = z.infer<typeof oauthGrantIdSchema>;
+export type OAuthGrantEventId = z.infer<typeof oauthGrantEventIdSchema>;
+export type ScheduleId = z.infer<typeof scheduleIdSchema>;
+export type OccurrenceId = z.infer<typeof occurrenceIdSchema>;
+export type AttemptId = z.infer<typeof attemptIdSchema>;
+export type DeliveryId = z.infer<typeof deliveryIdSchema>;
+export type EndpointId = z.infer<typeof endpointIdSchema>;
+export type OrganizationId = z.infer<typeof organizationIdSchema>;
+export type ProjectId = z.infer<typeof projectIdSchema>;
+export type EnvironmentId = z.infer<typeof environmentIdSchema>;
+export type TestSinkId = z.infer<typeof testSinkIdSchema>;
+export type TestSinkDeliveryId = z.infer<typeof testSinkDeliveryIdSchema>;
+/**
+ * Random bytes, as the generator needs them.
+ *
+ * Injectable so a test can pin an exact identifier, and defaulted so no ordinary
+ * caller has to think about it.
+ *
+ * The default is `crypto.getRandomValues`, which is Web Crypto — a standard, not
+ * a Cloudflare extension. It is present in Workers, in Node 18 and later, and in
+ * every browser, so one implementation serves every runtime this package is used
+ * from. `identifiers.worker.test.ts` proves it in the Workers runtime rather than
+ * assuming it.
+ *
+ * Typing it needs `lib: ["ES2023", "WebWorker"]` in this package's tsconfig.
+ * That adds no dependency — `lib` selects TypeScript's built-in typings — and
+ * `types` stays empty, so the contract layer still has none.
+ */
+export type RandomBytes = (length: number) => Uint8Array;
+/**
+ * Mint a public identifier.
+ *
+ * 26 characters of a 32-symbol alphabet is 130 bits, which is not a compromise
+ * between size and safety — identifiers appear in URLs and logs, and one that can
+ * be guessed is an enumeration oracle regardless of how well authorization works.
+ *
+ * `byte & 31` is unbiased because 256 is an exact multiple of 32. Using `%` on a
+ * non-power-of-two alphabet would skew the distribution toward its start, which is
+ * the classic way a generator quietly loses entropy; keeping the alphabet a power
+ * of two is what makes the cheap masking correct.
+ */
+export declare function newId(resource: IdResource, randomBytes?: RandomBytes): string;
+/** The generator's alphabet, exported so tests can pin it against `SUFFIX`. */
+export declare const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/** Which resource an identifier names, or undefined if it is not one of ours. */
+export declare function resourceOf(id: string): IdResource | undefined;

package/dist/identifiers.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+/**
+ * Public identifiers.
+ *
+ * Every identifier a client sees is opaque, prefixed, and server-assigned.
+ * Clients must treat the part after the prefix as meaningless and compare
+ * identifiers only for equality.
+ *
+ * This is a deliberate break from the legacy scheduler, where the caller
+ * supplied `id` and tenancy travelled in the path as `:owner/:partition/:id`.
+ * Caller-chosen identifiers leak the caller's namespace into ours, make
+ * collision handling a client concern, and make it impossible to change
+ * internal representation later. See `docs/architecture/legacy-provenance.md`.
+ */
+/** The resource a prefix names. Extending this list is an additive change. */
+export const ID_PREFIXES = {
+    apiCredential: "ak",
+    // One entry in a credential's audit trail. Its own prefix rather than
+    // `event`, which names the domain events in `events.ts` that consumers
+    // subscribe to — two different things called "event" sharing one namespace
+    // would make an identifier ambiguous about which stream it belongs to.
+    apiCredentialEvent: "ake",
+    attempt: "att",
+    // A pending OAuth authorization, alive only between the client's redirect and
+    // the member's answer. It is an identifier rather than an opaque blob because
+    // the consent screen has to fetch it by name, and a blob in a URL is a blob
+    // in a browser history entry.
+    authorizationRequest: "oar",
+    // One version of a callback endpoint's signing material. Public and
+    // non-secret: receivers use it to select a secret during bounded rotation.
+    callbackSigningKey: "csk",
+    delivery: "dlv",
+    endpoint: "ep",
+    environment: "env",
+    event: "evt",
+    oauthClient: "oc",
+    oauthGrant: "og",
+    // One entry in a grant's audit trail, named apart from `oauthGrant` for the
+    // reason `apiCredentialEvent` is named apart from `apiCredential`.
+    oauthGrantEvent: "oge",
+    occurrence: "occ",
+    organization: "org",
+    project: "proj",
+    schedule: "sch",
+    // A deterministic test-only callback receiver, and one delivery it recorded.
+    // The receipt has its own prefix rather than reusing `delivery`, which names
+    // the *sender's* identity for an attempt: one delivery id can produce a
+    // receipt at more than one sink, and a receipt exists even for a request that
+    // never authenticated and therefore has no trustworthy delivery id at all.
+    testSink: "tsk",
+    testSinkDelivery: "tsd",
+};
+/**
+ * Crockford base32 without padding, lowercase only: unambiguous when read
+ * aloud or transcribed, because it excludes I, L, O and U. Input is not
+ * case-folded — an uppercase identifier is refused rather than accepted, so
+ * there is exactly one spelling of any identifier.
+ */
+const SUFFIX = "[0-9abcdefghjkmnpqrstvwxyz]{26}";
+export function idPattern(resource) {
+    return new RegExp(`^${ID_PREFIXES[resource]}_${SUFFIX}$`, "u");
+}
+/** Any well-formed public identifier, whatever it names. */
+export const ANY_ID_PATTERN = new RegExp(`^(?:${Object.values(ID_PREFIXES).join("|")})_${SUFFIX}$`, "u");
+export function idSchema(resource) {
+    return z
+        .string()
+        .regex(idPattern(resource), `must be a ${resource} identifier: "${ID_PREFIXES[resource]}_" followed by 26 Crockford base32 characters`);
+}
+export const apiCredentialIdSchema = idSchema("apiCredential");
+export const apiCredentialEventIdSchema = idSchema("apiCredentialEvent");
+export const authorizationRequestIdSchema = idSchema("authorizationRequest");
+export const callbackSigningKeyIdSchema = idSchema("callbackSigningKey");
+export const oauthClientIdSchema = idSchema("oauthClient");
+export const oauthGrantIdSchema = idSchema("oauthGrant");
+export const oauthGrantEventIdSchema = idSchema("oauthGrantEvent");
+export const scheduleIdSchema = idSchema("schedule");
+export const occurrenceIdSchema = idSchema("occurrence");
+export const attemptIdSchema = idSchema("attempt");
+export const deliveryIdSchema = idSchema("delivery");
+export const endpointIdSchema = idSchema("endpoint");
+export const organizationIdSchema = idSchema("organization");
+export const projectIdSchema = idSchema("project");
+export const environmentIdSchema = idSchema("environment");
+export const eventIdSchema = idSchema("event");
+export const testSinkIdSchema = idSchema("testSink");
+export const testSinkDeliveryIdSchema = idSchema("testSinkDelivery");
+/**
+ * The alphabet the pattern above accepts, in order.
+ *
+ * Derived from nothing — written out — but `identifiers.test.ts` asserts every
+ * character satisfies `SUFFIX` and that the length is exactly 32. A generator and
+ * a validator that disagree would mint identifiers the product then refuses.
+ */
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/** How many characters follow the prefix. Matches `SUFFIX`. */
+const SUFFIX_LENGTH = 26;
+const defaultRandomBytes = (length) => crypto.getRandomValues(new Uint8Array(length));
+/**
+ * Mint a public identifier.
+ *
+ * 26 characters of a 32-symbol alphabet is 130 bits, which is not a compromise
+ * between size and safety — identifiers appear in URLs and logs, and one that can
+ * be guessed is an enumeration oracle regardless of how well authorization works.
+ *
+ * `byte & 31` is unbiased because 256 is an exact multiple of 32. Using `%` on a
+ * non-power-of-two alphabet would skew the distribution toward its start, which is
+ * the classic way a generator quietly loses entropy; keeping the alphabet a power
+ * of two is what makes the cheap masking correct.
+ */
+export function newId(resource, randomBytes = defaultRandomBytes) {
+    const bytes = randomBytes(SUFFIX_LENGTH);
+    if (bytes.length < SUFFIX_LENGTH) {
+        // A short read would silently shorten the identifier, and a short identifier
+        // still matches nothing else in the system — it would fail validation far
+        // from here, with no clue why.
+        throw new Error(`random source returned ${String(bytes.length)} bytes, needed ${String(SUFFIX_LENGTH)}`);
+    }
+    let suffix = "";
+    for (let index = 0; index < SUFFIX_LENGTH; index += 1) {
+        suffix += ALPHABET[bytes[index] & 31];
+    }
+    return `${ID_PREFIXES[resource]}_${suffix}`;
+}
+/** The generator's alphabet, exported so tests can pin it against `SUFFIX`. */
+export const ID_ALPHABET = ALPHABET;
+/** Which resource an identifier names, or undefined if it is not one of ours. */
+export function resourceOf(id) {
+    const prefix = id.slice(0, id.indexOf("_"));
+    return Object.keys(ID_PREFIXES).find((resource) => ID_PREFIXES[resource] === prefix && idPattern(resource).test(id));
+}

package/dist/identity.d.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+/**
+ * External identity, and what it projects into.
+ *
+ * Clerk is the authority for who a human is and which organizations they belong
+ * to. Greatwait keeps a projection of that so it can list and join, but the
+ * projection never authorizes on its own — a request carries current session
+ * claims, and a stale row must not outlive a removed membership. See
+ * `packages/domain/src/membership.ts` for the reconciliation rules.
+ */
+/**
+ * A Clerk organization identifier.
+ *
+ * **This is not one of our identifiers, despite sharing the `org_` prefix.**
+ * A real Clerk id — `org_2DKoiPJ56JpKrgPoKXTyo49GvE8` — fails
+ * `organizationIdSchema`, which requires exactly 26 characters of lowercase
+ * Crockford base32. That direction is pinned by test and is the one that
+ * matters in practice: it means a Clerk id can never be mistaken for, or stored
+ * as, a Greatwait identifier.
+ *
+ * The converse does **not** hold, and it would be dishonest to imply otherwise:
+ * our identifiers are alphanumeric and 26 characters long, so every Greatwait
+ * `org_…` also satisfies the pattern below. Tightening this schema to exclude
+ * them would trade a theoretical confusion for a real failure mode — a Clerk id
+ * that happened to collide would be refused, dropping a genuine membership
+ * event and leaving the projection stale.
+ *
+ * What actually keeps the two apart is structural, not lexical: external ids
+ * live in their own columns, are typed distinctly here, and are mapped to a
+ * server-assigned `org_…` of ours at the projection boundary. An external id
+ * never appears in a public response, because leaking one would make our public
+ * surface depend on our identity vendor and hand callers a second spelling of
+ * the same tenant.
+ */
+export declare const externalOrganizationIdSchema: z.ZodString;
+export declare const externalUserIdSchema: z.ZodString;
+/**
+ * A Clerk organization-membership identifier, and the projection's primary key.
+ *
+ * `(organization, user)` would be the obvious key and is the wrong one: it is
+ * not unique over time. Leaving and rejoining an organization mints a new
+ * membership, so keying on the pair would make a rejoin overwrite the record of
+ * the departure. Keyed on the id, the old membership stays as a removed row and
+ * the new one is a separate row, which is also what makes the two orderable
+ * independently.
+ */
+export declare const externalMembershipIdSchema: z.ZodString;
+export type ExternalOrganizationId = z.infer<typeof externalOrganizationIdSchema>;
+export type ExternalUserId = z.infer<typeof externalUserIdSchema>;
+export type ExternalMembershipId = z.infer<typeof externalMembershipIdSchema>;
+/**
+ * Product roles, projected from Clerk's `org:admin` and `org:member`.
+ *
+ * Named without the `org:` prefix because these are ours: W1-03 builds the
+ * role-to-scope matrix on them, and binding that matrix to a vendor's string
+ * format would make changing identity providers a contract change.
+ */
+export declare const MEMBERSHIP_ROLES: readonly ["admin", "member"];
+export declare const membershipRoleSchema: z.ZodEnum<{
+    admin: "admin";
+    member: "member";
+}>;
+export type MembershipRole = z.infer<typeof membershipRoleSchema>;
+/**
+ * Whether a membership currently grants anything.
+ *
+ * `suspended` is distinct from `removed` because they recover differently: a
+ * suspension is lifted and the same membership resumes, whereas a removal ends
+ * it and rejoining creates a new one. Both refuse access.
+ */
+export declare const MEMBERSHIP_STATUSES: readonly ["active", "suspended", "removed"];
+export declare const membershipStatusSchema: z.ZodEnum<{
+    removed: "removed";
+    active: "active";
+    suspended: "suspended";
+}>;
+export type MembershipStatus = z.infer<typeof membershipStatusSchema>;
+/** Whether a status grants any access at all. */
+export declare function grantsAccess(status: MembershipStatus): boolean;
+/** The role granting no more access than either argument. */
+export declare function leastRole(left: MembershipRole, right: MembershipRole): MembershipRole;
+/** The status granting no more access than either argument. */
+export declare function leastStatus(left: MembershipStatus, right: MembershipStatus): MembershipStatus;
+/**
+ * A membership as currently projected.
+ *
+ * `version` is Clerk's `updated_at` in milliseconds — the source's own notion of
+ * when the change happened, carried on every membership event. It is never a
+ * counter we increment on arrival and never the Svix delivery time: either
+ * would make whichever event arrived last win, which is precisely the bug
+ * acceptance criterion 2 is about.
+ *
+ * Every field here arrives together on every membership event, including
+ * deletion. That is worth stating because it is what makes the projection fully
+ * convergent: there is no event that updates the status while leaving the role
+ * behind at an older version, so one version orders the whole record.
+ */
+export declare const membershipSchema: z.ZodObject<{
+    id: z.ZodString;
+    organization: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>;
+    status: z.ZodEnum<{
+        removed: "removed";
+        active: "active";
+        suspended: "suspended";
+    }>;
+    user: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type Membership = z.infer<typeof membershipSchema>;
+/**
+ * One change, normalized by the adapter from a Clerk webhook payload.
+ *
+ * Identical in shape to a projected membership, because Clerk's
+ * `organizationMembership.created`, `.updated`, and `.deleted` all deliver the
+ * same full `OrganizationMembershipJSON` — deletion included. Verified against
+ * `@clerk/backend`'s own types rather than assumed; an earlier design here
+ * carried a second id-only variant for deletions, which no event actually
+ * produces.
+ *
+ * Normalizing at the adapter edge keeps every Clerk-shaped concern — the `org:`
+ * role prefix, `public_user_data` nesting, which event type implies which
+ * status — out of the domain, which sees only a membership asserted to hold at
+ * a version.
+ *
+ * `organization.deleted` is **not** a membership change and is modelled
+ * separately, as `organizationTombstoneSchema`: it carries a `DeletedObjectJSON`
+ * with no timestamp, and it withdraws every membership an organization held
+ * rather than one. See FXO-1377.
+ *
+ * `user.deleted` needs nothing. Measured against staging: deleting a user *does*
+ * emit `organizationMembership.deleted`, which arrives here like any other
+ * change. Deleting an organization does not. The asymmetry is real and is why
+ * only one of the two has a tombstone.
+ */
+export declare const membershipChangeSchema: z.ZodObject<{
+    id: z.ZodString;
+    organization: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>;
+    status: z.ZodEnum<{
+        removed: "removed";
+        active: "active";
+        suspended: "suspended";
+    }>;
+    user: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type MembershipChange = Membership;
+/**
+ * The membership a verified session asserts.
+ *
+ * Clerk is the identity authority, so this comes from signed session claims and
+ * never from the projection. `assertedAt` is the token's issued-at in
+ * milliseconds — when Clerk vouched for this membership — which is what makes it
+ * comparable against a projected `version` from the same clock.
+ */
+export declare const sessionMembershipSchema: z.ZodObject<{
+    assertedAt: z.ZodNumber;
+    organization: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>;
+    user: z.ZodString;
+}, z.core.$strip>;
+export type SessionMembership = z.infer<typeof sessionMembershipSchema>;
+/**
+ * A record that an organization was deleted.
+ *
+ * Kept rather than deleting its memberships, for two reasons. A membership event
+ * can arrive *after* the deletion — retries are unordered — and without a durable
+ * marker there would be nothing to stop it reinstating access. And a tombstone
+ * preserves who had access when the organization ended, which a cascade delete
+ * would destroy.
+ *
+ * `version` comes from the event envelope's `timestamp`, not from the payload:
+ * Clerk's `organization.deleted` carries a `DeletedObjectJSON` with no timestamp
+ * at all. The envelope value is still Clerk's own clock in milliseconds, so it is
+ * comparable with a membership's `updated_at`.
+ *
+ * Measured on 2026-07-29: deleting an organization emits **no** per-membership
+ * deletion, so without this the projection keeps its memberships reading `active`
+ * for an organization that no longer exists. Deleting a *user* does emit a
+ * membership deletion. That asymmetry is why this exists — see FXO-1377.
+ */
+export declare const organizationTombstoneSchema: z.ZodObject<{
+    organization: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type OrganizationTombstone = z.infer<typeof organizationTombstoneSchema>;

package/dist/identity.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+/**
+ * External identity, and what it projects into.
+ *
+ * Clerk is the authority for who a human is and which organizations they belong
+ * to. Greatwait keeps a projection of that so it can list and join, but the
+ * projection never authorizes on its own — a request carries current session
+ * claims, and a stale row must not outlive a removed membership. See
+ * `packages/domain/src/membership.ts` for the reconciliation rules.
+ */
+/**
+ * A Clerk organization identifier.
+ *
+ * **This is not one of our identifiers, despite sharing the `org_` prefix.**
+ * A real Clerk id — `org_2DKoiPJ56JpKrgPoKXTyo49GvE8` — fails
+ * `organizationIdSchema`, which requires exactly 26 characters of lowercase
+ * Crockford base32. That direction is pinned by test and is the one that
+ * matters in practice: it means a Clerk id can never be mistaken for, or stored
+ * as, a Greatwait identifier.
+ *
+ * The converse does **not** hold, and it would be dishonest to imply otherwise:
+ * our identifiers are alphanumeric and 26 characters long, so every Greatwait
+ * `org_…` also satisfies the pattern below. Tightening this schema to exclude
+ * them would trade a theoretical confusion for a real failure mode — a Clerk id
+ * that happened to collide would be refused, dropping a genuine membership
+ * event and leaving the projection stale.
+ *
+ * What actually keeps the two apart is structural, not lexical: external ids
+ * live in their own columns, are typed distinctly here, and are mapped to a
+ * server-assigned `org_…` of ours at the projection boundary. An external id
+ * never appears in a public response, because leaking one would make our public
+ * surface depend on our identity vendor and hand callers a second spelling of
+ * the same tenant.
+ */
+export const externalOrganizationIdSchema = z
+    .string()
+    .regex(/^org_[A-Za-z0-9]{1,64}$/u, 'must be a Clerk organization identifier: "org_" followed by alphanumerics');
+export const externalUserIdSchema = z
+    .string()
+    .regex(/^user_[A-Za-z0-9]{1,64}$/u, 'must be a Clerk user identifier: "user_" followed by alphanumerics');
+/**
+ * A Clerk organization-membership identifier, and the projection's primary key.
+ *
+ * `(organization, user)` would be the obvious key and is the wrong one: it is
+ * not unique over time. Leaving and rejoining an organization mints a new
+ * membership, so keying on the pair would make a rejoin overwrite the record of
+ * the departure. Keyed on the id, the old membership stays as a removed row and
+ * the new one is a separate row, which is also what makes the two orderable
+ * independently.
+ */
+export const externalMembershipIdSchema = z
+    .string()
+    .regex(/^orgmem_[A-Za-z0-9]{1,64}$/u, 'must be a Clerk membership identifier: "orgmem_" followed by alphanumerics');
+/**
+ * Product roles, projected from Clerk's `org:admin` and `org:member`.
+ *
+ * Named without the `org:` prefix because these are ours: W1-03 builds the
+ * role-to-scope matrix on them, and binding that matrix to a vendor's string
+ * format would make changing identity providers a contract change.
+ */
+export const MEMBERSHIP_ROLES = ["admin", "member"];
+export const membershipRoleSchema = z.enum(MEMBERSHIP_ROLES);
+/**
+ * Whether a membership currently grants anything.
+ *
+ * `suspended` is distinct from `removed` because they recover differently: a
+ * suspension is lifted and the same membership resumes, whereas a removal ends
+ * it and rejoining creates a new one. Both refuse access.
+ */
+export const MEMBERSHIP_STATUSES = ["active", "suspended", "removed"];
+export const membershipStatusSchema = z.enum(MEMBERSHIP_STATUSES);
+/** Whether a status grants any access at all. */
+export function grantsAccess(status) {
+    return status === "active";
+}
+/**
+ * How much access each role carries, most restrictive first. Used only to break
+ * ties between changes that claim the same instant — see
+ * `reconcileMembership`.
+ */
+const ROLE_RANK = {
+    admin: 1,
+    member: 0,
+};
+const STATUS_RANK = {
+    active: 2,
+    removed: 0,
+    suspended: 1,
+};
+/** The role granting no more access than either argument. */
+export function leastRole(left, right) {
+    return ROLE_RANK[left] <= ROLE_RANK[right] ? left : right;
+}
+/** The status granting no more access than either argument. */
+export function leastStatus(left, right) {
+    return STATUS_RANK[left] <= STATUS_RANK[right] ? left : right;
+}
+/**
+ * A membership as currently projected.
+ *
+ * `version` is Clerk's `updated_at` in milliseconds — the source's own notion of
+ * when the change happened, carried on every membership event. It is never a
+ * counter we increment on arrival and never the Svix delivery time: either
+ * would make whichever event arrived last win, which is precisely the bug
+ * acceptance criterion 2 is about.
+ *
+ * Every field here arrives together on every membership event, including
+ * deletion. That is worth stating because it is what makes the projection fully
+ * convergent: there is no event that updates the status while leaving the role
+ * behind at an older version, so one version orders the whole record.
+ */
+export const membershipSchema = z.object({
+    id: externalMembershipIdSchema,
+    organization: externalOrganizationIdSchema,
+    role: membershipRoleSchema,
+    status: membershipStatusSchema,
+    user: externalUserIdSchema,
+    version: z.number().int().nonnegative(),
+});
+/**
+ * One change, normalized by the adapter from a Clerk webhook payload.
+ *
+ * Identical in shape to a projected membership, because Clerk's
+ * `organizationMembership.created`, `.updated`, and `.deleted` all deliver the
+ * same full `OrganizationMembershipJSON` — deletion included. Verified against
+ * `@clerk/backend`'s own types rather than assumed; an earlier design here
+ * carried a second id-only variant for deletions, which no event actually
+ * produces.
+ *
+ * Normalizing at the adapter edge keeps every Clerk-shaped concern — the `org:`
+ * role prefix, `public_user_data` nesting, which event type implies which
+ * status — out of the domain, which sees only a membership asserted to hold at
+ * a version.
+ *
+ * `organization.deleted` is **not** a membership change and is modelled
+ * separately, as `organizationTombstoneSchema`: it carries a `DeletedObjectJSON`
+ * with no timestamp, and it withdraws every membership an organization held
+ * rather than one. See FXO-1377.
+ *
+ * `user.deleted` needs nothing. Measured against staging: deleting a user *does*
+ * emit `organizationMembership.deleted`, which arrives here like any other
+ * change. Deleting an organization does not. The asymmetry is real and is why
+ * only one of the two has a tombstone.
+ */
+export const membershipChangeSchema = membershipSchema;
+/**
+ * The membership a verified session asserts.
+ *
+ * Clerk is the identity authority, so this comes from signed session claims and
+ * never from the projection. `assertedAt` is the token's issued-at in
+ * milliseconds — when Clerk vouched for this membership — which is what makes it
+ * comparable against a projected `version` from the same clock.
+ */
+export const sessionMembershipSchema = z.object({
+    assertedAt: z.number().int().nonnegative(),
+    organization: externalOrganizationIdSchema,
+    role: membershipRoleSchema,
+    user: externalUserIdSchema,
+});
+/**
+ * A record that an organization was deleted.
+ *
+ * Kept rather than deleting its memberships, for two reasons. A membership event
+ * can arrive *after* the deletion — retries are unordered — and without a durable
+ * marker there would be nothing to stop it reinstating access. And a tombstone
+ * preserves who had access when the organization ended, which a cascade delete
+ * would destroy.
+ *
+ * `version` comes from the event envelope's `timestamp`, not from the payload:
+ * Clerk's `organization.deleted` carries a `DeletedObjectJSON` with no timestamp
+ * at all. The envelope value is still Clerk's own clock in milliseconds, so it is
+ * comparable with a membership's `updated_at`.
+ *
+ * Measured on 2026-07-29: deleting an organization emits **no** per-membership
+ * deletion, so without this the projection keeps its memberships reading `active`
+ * for an organization that no longer exists. Deleting a *user* does emit a
+ * membership deletion. That asymmetry is why this exists — see FXO-1377.
+ */
+export const organizationTombstoneSchema = z.object({
+    organization: externalOrganizationIdSchema,
+    version: z.number().int().nonnegative(),
+});