@oxy.so/contracts 1.0.0

package/dist/types/updates.d.ts

@@ -0,0 +1,545 @@
+/**
+ * Oxy Updates (self-hosted expo-updates protocol) — publish/admin API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the AUTHENTICATED publish/admin
+ * surface that the `oxy-ship` CLI and the console Updates tab call. The PUBLIC
+ * manifest endpoint (`GET /updates/v1/apps/:clientId/manifest`) speaks the
+ * expo-updates v1 protocol verbatim (multipart/mixed, signed) and is therefore
+ * NOT modelled here — its shape is dictated by the Expo spec, not by us.
+ *
+ * The API validates its OUTPUT against these schemas; every consumer (the ship
+ * CLI, the console hook) validates its INPUT against the same definitions, so
+ * producer and consumers cannot drift.
+ *
+ * Domain model (mirrors the Mongoose models in `@oxy.so/api`):
+ *  - A `channel` (e.g. `production`, `preview`, `pr-123`) is a named release
+ *    track for one application.
+ *  - An `update` is one published bundle for a single `(channel, runtimeVersion,
+ *    platform)`. Its `updateId` is a UUIDv4 (the client parses it as a UUID).
+ *    The HEAD of a track is the newest `published` update for that tuple.
+ *  - An `asset` is content-addressed by its `sha256`; assets are shared across
+ *    updates and applications (an unchanged JS bundle is uploaded once).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/** The two platforms the expo-updates protocol addresses. */
+export declare const updatePlatformSchema: z.ZodEnum<["ios", "android"]>;
+export type UpdatePlatform = z.infer<typeof updatePlatformSchema>;
+/** Lifecycle of a single published update row. */
+export declare const updateStatusSchema: z.ZodEnum<["published", "superseded", "rolled_back"]>;
+export type UpdateStatus = z.infer<typeof updateStatusSchema>;
+/** Upload lifecycle of a content-addressed asset. */
+export declare const updateAssetStatusSchema: z.ZodEnum<["pending", "uploaded"]>;
+export type UpdateAssetStatus = z.infer<typeof updateAssetStatusSchema>;
+/** Lowercase-hex SHA-256 content hash (64 hex chars). */
+export declare const sha256HexSchema: z.ZodString;
+/**
+ * A channel name. Constrained to a URL/path-safe slug so it can appear in the
+ * `expo-channel-name` header and be used CI-friendly for `pr-<n>` tracks. No
+ * colon (BullMQ/id safety) and no slash (path safety).
+ */
+export declare const channelNameSchema: z.ZodString;
+/** A runtime version string (expo-updates `runtimeVersion`, e.g. an appVersion). */
+export declare const runtimeVersionSchema: z.ZodString;
+/** A rollout percentage: 0 rolls out to nobody, 100 to everybody. */
+export declare const rolloutPercentSchema: z.ZodNumber;
+/**
+ * One asset the client intends to upload as part of an update. `sha256` is the
+ * content hash (dedup key); `contentType` and `size` describe the object the
+ * server will accept at the presigned URL.
+ */
+export declare const assetInitItemSchema: z.ZodObject<{
+    sha256: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sha256: string;
+    contentType: string;
+    size: number;
+}, {
+    sha256: string;
+    contentType: string;
+    size: number;
+}>;
+export type AssetInitItem = z.infer<typeof assetInitItemSchema>;
+/**
+ * `POST /updates/v1/assets/init` request. Declares the full asset set of an
+ * update; the server replies with a presigned PUT for every asset it does NOT
+ * already hold (content-addressed dedup — unchanged assets are never re-uploaded).
+ */
+export declare const assetInitRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    assets: z.ZodArray<z.ZodObject<{
+        sha256: z.ZodString;
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        sha256: string;
+        contentType: string;
+        size: number;
+    }, {
+        sha256: string;
+        contentType: string;
+        size: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    assets: {
+        sha256: string;
+        contentType: string;
+        size: number;
+    }[];
+}, {
+    applicationId: string;
+    assets: {
+        sha256: string;
+        contentType: string;
+        size: number;
+    }[];
+}>;
+export type AssetInitRequest = z.infer<typeof assetInitRequestSchema>;
+/** One presigned upload the client must PUT its bytes to before completing. */
+export declare const assetUploadTicketSchema: z.ZodObject<{
+    sha256: z.ZodString;
+    /** Presigned S3 PUT URL. The client PUTs the exact bytes here. */
+    uploadUrl: z.ZodString;
+    /** The S3 key the object will live at (`public/updates/assets/<sha256>`). */
+    storageKey: z.ZodString;
+    /** The Content-Type the presigned URL was signed for; echo it on the PUT. */
+    contentType: z.ZodString;
+    /**
+     * The Cache-Control the presigned URL was signed for; the client MUST send it
+     * verbatim on the PUT so the SigV4 signature matches and the stored object
+     * carries the long immutable cache header (assets are content-addressed).
+     */
+    cacheControl: z.ZodString;
+    /** Base64 SHA-256 value required in the presigned PUT's checksum header. */
+    checksumSHA256: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sha256: string;
+    contentType: string;
+    uploadUrl: string;
+    storageKey: string;
+    cacheControl: string;
+    checksumSHA256: string;
+}, {
+    sha256: string;
+    contentType: string;
+    uploadUrl: string;
+    storageKey: string;
+    cacheControl: string;
+    checksumSHA256: string;
+}>;
+export type AssetUploadTicket = z.infer<typeof assetUploadTicketSchema>;
+/**
+ * `POST /updates/v1/assets/init` response. `missing` holds a presigned upload
+ * for each asset the server does not yet have; `existing` lists the sha256s it
+ * already holds (the client skips those).
+ */
+export declare const assetInitResponseSchema: z.ZodObject<{
+    missing: z.ZodArray<z.ZodObject<{
+        sha256: z.ZodString;
+        /** Presigned S3 PUT URL. The client PUTs the exact bytes here. */
+        uploadUrl: z.ZodString;
+        /** The S3 key the object will live at (`public/updates/assets/<sha256>`). */
+        storageKey: z.ZodString;
+        /** The Content-Type the presigned URL was signed for; echo it on the PUT. */
+        contentType: z.ZodString;
+        /**
+         * The Cache-Control the presigned URL was signed for; the client MUST send it
+         * verbatim on the PUT so the SigV4 signature matches and the stored object
+         * carries the long immutable cache header (assets are content-addressed).
+         */
+        cacheControl: z.ZodString;
+        /** Base64 SHA-256 value required in the presigned PUT's checksum header. */
+        checksumSHA256: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sha256: string;
+        contentType: string;
+        uploadUrl: string;
+        storageKey: string;
+        cacheControl: string;
+        checksumSHA256: string;
+    }, {
+        sha256: string;
+        contentType: string;
+        uploadUrl: string;
+        storageKey: string;
+        cacheControl: string;
+        checksumSHA256: string;
+    }>, "many">;
+    existing: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    missing: {
+        sha256: string;
+        contentType: string;
+        uploadUrl: string;
+        storageKey: string;
+        cacheControl: string;
+        checksumSHA256: string;
+    }[];
+    existing: string[];
+}, {
+    missing: {
+        sha256: string;
+        contentType: string;
+        uploadUrl: string;
+        storageKey: string;
+        cacheControl: string;
+        checksumSHA256: string;
+    }[];
+    existing: string[];
+}>;
+export type AssetInitResponse = z.infer<typeof assetInitResponseSchema>;
+/**
+ * `POST /updates/v1/assets/complete` request. Sent after the client has PUT
+ * every `missing` asset. The server HEADs each object and flips it to
+ * `uploaded`; an object that is absent or size-mismatched is rejected.
+ */
+export declare const assetCompleteRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    sha256s: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    sha256s: string[];
+}, {
+    applicationId: string;
+    sha256s: string[];
+}>;
+export type AssetCompleteRequest = z.infer<typeof assetCompleteRequestSchema>;
+/** Per-asset verification outcome from `assets/complete`. */
+export declare const assetCompleteResultItemSchema: z.ZodObject<{
+    sha256: z.ZodString;
+    status: z.ZodEnum<["pending", "uploaded"]>;
+    size: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "uploaded";
+    sha256: string;
+    size: number;
+}, {
+    status: "pending" | "uploaded";
+    sha256: string;
+    size: number;
+}>;
+export type AssetCompleteResultItem = z.infer<typeof assetCompleteResultItemSchema>;
+export declare const assetCompleteResponseSchema: z.ZodObject<{
+    assets: z.ZodArray<z.ZodObject<{
+        sha256: z.ZodString;
+        status: z.ZodEnum<["pending", "uploaded"]>;
+        size: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "uploaded";
+        sha256: string;
+        size: number;
+    }, {
+        status: "pending" | "uploaded";
+        sha256: string;
+        size: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    assets: {
+        status: "pending" | "uploaded";
+        sha256: string;
+        size: number;
+    }[];
+}, {
+    assets: {
+        status: "pending" | "uploaded";
+        sha256: string;
+        size: number;
+    }[];
+}>;
+export type AssetCompleteResponse = z.infer<typeof assetCompleteResponseSchema>;
+/**
+ * A single asset reference inside a create-update request. `key` is the
+ * expo-export asset key (the md5-basename the client uses to look the asset up
+ * and skip embedded ones); `fileExtension` is the suggested on-disk extension.
+ */
+export declare const updateAssetRefSchema: z.ZodObject<{
+    sha256: z.ZodString;
+    /** expo-export asset key (md5 basename) — how app code references the asset. */
+    key: z.ZodString;
+    contentType: z.ZodString;
+    /** Suggested file extension including the leading dot (e.g. `.js`, `.png`). */
+    fileExtension: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    sha256: string;
+    contentType: string;
+    fileExtension?: string | undefined;
+}, {
+    key: string;
+    sha256: string;
+    contentType: string;
+    fileExtension?: string | undefined;
+}>;
+export type UpdateAssetRef = z.infer<typeof updateAssetRefSchema>;
+/**
+ * `POST /updates/v1/updates` request. Publishes one bundle for one platform to a
+ * channel (the channel is created on demand — CI-friendly for `pr-<n>`). All
+ * referenced assets MUST already be `uploaded` (via init/complete). `extra`
+ * MUST carry `expoClient` so `Constants.expoConfig` works after an OTA update.
+ */
+export declare const createUpdateRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    channel: z.ZodString;
+    runtimeVersion: z.ZodString;
+    platform: z.ZodEnum<["ios", "android"]>;
+    /** The launch (entry-point) asset — its `fileExtension` is ignored by clients. */
+    launchAsset: z.ZodObject<{
+        sha256: z.ZodString;
+        /** expo-export asset key (md5 basename) — how app code references the asset. */
+        key: z.ZodString;
+        contentType: z.ZodString;
+        /** Suggested file extension including the leading dot (e.g. `.js`, `.png`). */
+        fileExtension: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }, {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }>;
+    assets: z.ZodArray<z.ZodObject<{
+        sha256: z.ZodString;
+        /** expo-export asset key (md5 basename) — how app code references the asset. */
+        key: z.ZodString;
+        contentType: z.ZodString;
+        /** Suggested file extension including the leading dot (e.g. `.js`, `.png`). */
+        fileExtension: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }, {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }>, "many">;
+    /**
+     * Opaque `extra` blob embedded verbatim in the signed manifest. MUST contain
+     * `expoClient` (the public expo config) so `Constants.expoConfig` resolves
+     * after an OTA update; MAY carry other third-party config.
+     */
+    extra: z.ZodObject<{
+        expoClient: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodUnknown, z.objectOutputType<{
+        expoClient: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodUnknown, "strip">, z.objectInputType<{
+        expoClient: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodUnknown, "strip">>;
+    /** String→string metadata dict; filtered client-side via manifest filters. */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Initial rollout percentage (default 100 — full rollout). */
+    rolloutPercent: z.ZodOptional<z.ZodNumber>;
+    /** Git commit the bundle was built from (audit / console display). */
+    gitCommit: z.ZodOptional<z.ZodString>;
+    /** Git branch the bundle was built from (audit / console display). */
+    gitBranch: z.ZodOptional<z.ZodString>;
+    /** Human-readable publish message (console display). */
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    channel: string;
+    applicationId: string;
+    assets: {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }[];
+    runtimeVersion: string;
+    platform: "ios" | "android";
+    launchAsset: {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    };
+    extra: {
+        expoClient: Record<string, unknown>;
+    } & {
+        [k: string]: unknown;
+    };
+    message?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    rolloutPercent?: number | undefined;
+    gitCommit?: string | undefined;
+    gitBranch?: string | undefined;
+}, {
+    channel: string;
+    applicationId: string;
+    assets: {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    }[];
+    runtimeVersion: string;
+    platform: "ios" | "android";
+    launchAsset: {
+        key: string;
+        sha256: string;
+        contentType: string;
+        fileExtension?: string | undefined;
+    };
+    extra: {
+        expoClient: Record<string, unknown>;
+    } & {
+        [k: string]: unknown;
+    };
+    message?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    rolloutPercent?: number | undefined;
+    gitCommit?: string | undefined;
+    gitBranch?: string | undefined;
+}>;
+export type CreateUpdateRequest = z.infer<typeof createUpdateRequestSchema>;
+/**
+ * A published update as returned by the read/admin endpoints. `id` is the
+ * update's UUIDv4 (the manifest `id`). Declared as an explicit interface (schema
+ * annotated `z.ZodType<Update>`) so the nested shape survives a consumer's
+ * `moduleResolution: "node"`, matching the convention in the other contracts.
+ */
+export interface Update {
+    id: string;
+    applicationId: string;
+    channel: string;
+    runtimeVersion: string;
+    platform: UpdatePlatform;
+    status: UpdateStatus;
+    rolloutPercent: number;
+    launchAssetSha256: string;
+    assetSha256s: string[];
+    gitCommit?: string;
+    gitBranch?: string;
+    message?: string;
+    /** The updateId this update was promoted from, when it is a promotion. */
+    promotedFromUpdateId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const updateSchema: z.ZodType<Update>;
+export declare const createUpdateResponseSchema: z.ZodObject<{
+    update: z.ZodType<Update, z.ZodTypeDef, Update>;
+}, "strip", z.ZodTypeAny, {
+    update: Update;
+}, {
+    update: Update;
+}>;
+export type CreateUpdateResponse = z.infer<typeof createUpdateResponseSchema>;
+/** One `rollBackToEmbedded` directive currently active on a channel. */
+export interface RollbackToEmbeddedEntry {
+    runtimeVersion: string;
+    platform: UpdatePlatform;
+    /** ISO 8601 datetime; the client rolls back updates created before this. */
+    commitTime: string;
+}
+export declare const rollbackToEmbeddedEntrySchema: z.ZodType<RollbackToEmbeddedEntry>;
+/** A release channel with its currently-active rollback-to-embedded directives. */
+export interface Channel {
+    id: string;
+    applicationId: string;
+    name: string;
+    rollbacksToEmbedded: RollbackToEmbeddedEntry[];
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const channelSchema: z.ZodType<Channel>;
+export declare const channelListResponseSchema: z.ZodObject<{
+    channels: z.ZodArray<z.ZodType<Channel, z.ZodTypeDef, Channel>, "many">;
+}, "strip", z.ZodTypeAny, {
+    channels: Channel[];
+}, {
+    channels: Channel[];
+}>;
+export type ChannelListResponse = z.infer<typeof channelListResponseSchema>;
+export declare const updateListResponseSchema: z.ZodObject<{
+    updates: z.ZodArray<z.ZodType<Update, z.ZodTypeDef, Update>, "many">;
+}, "strip", z.ZodTypeAny, {
+    updates: Update[];
+}, {
+    updates: Update[];
+}>;
+export type UpdateListResponse = z.infer<typeof updateListResponseSchema>;
+/**
+ * `POST /updates/v1/channels/:channel/rollback` request. Marks the current head
+ * for `(runtimeVersion, platform)` `rolled_back` so the previous published
+ * update (if any) becomes head again. Nothing is deleted.
+ */
+export declare const rollbackRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    runtimeVersion: z.ZodString;
+    platform: z.ZodEnum<["ios", "android"]>;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    runtimeVersion: string;
+    platform: "ios" | "android";
+}, {
+    applicationId: string;
+    runtimeVersion: string;
+    platform: "ios" | "android";
+}>;
+export type RollbackRequest = z.infer<typeof rollbackRequestSchema>;
+/**
+ * `POST /updates/v1/channels/:channel/rollback-to-embedded` request. Records a
+ * `rollBackToEmbedded` directive so clients on this `(runtimeVersion, platform)`
+ * fall back to the update embedded in their binary.
+ */
+export declare const rollbackToEmbeddedRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    runtimeVersion: z.ZodString;
+    platform: z.ZodEnum<["ios", "android"]>;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    runtimeVersion: string;
+    platform: "ios" | "android";
+}, {
+    applicationId: string;
+    runtimeVersion: string;
+    platform: "ios" | "android";
+}>;
+export type RollbackToEmbeddedRequest = z.infer<typeof rollbackToEmbeddedRequestSchema>;
+/**
+ * `POST /updates/v1/channels/:channel/promote` request. Promotes an existing
+ * update (by `updateId`) into the target channel by creating a NEW update (new
+ * UUID) pointing at the SAME assets. `toChannel` defaults to the path channel.
+ */
+export declare const promoteRequestSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    updateId: z.ZodString;
+    /** Target channel to promote into. Defaults to the path `:channel`. */
+    toChannel: z.ZodOptional<z.ZodString>;
+    /** Rollout percentage for the promoted update (default 100). */
+    rolloutPercent: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    updateId: string;
+    rolloutPercent?: number | undefined;
+    toChannel?: string | undefined;
+}, {
+    applicationId: string;
+    updateId: string;
+    rolloutPercent?: number | undefined;
+    toChannel?: string | undefined;
+}>;
+export type PromoteRequest = z.infer<typeof promoteRequestSchema>;
+/** `PATCH /updates/v1/updates/:updateId` request — adjust a rollout in place. */
+export declare const updateRolloutPatchSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    rolloutPercent: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    applicationId: string;
+    rolloutPercent: number;
+}, {
+    applicationId: string;
+    rolloutPercent: number;
+}>;
+export type UpdateRolloutPatch = z.infer<typeof updateRolloutPatchSchema>;

package/dist/types/userInvalidation.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Canonical contract for the Oxy user-invalidation broadcast.
+ *
+ * Oxy owns identity, but consumers cache it: Mention keeps a Redis summary per
+ * post author, and every backend using `@oxy.so/core` holds the SDK's own GET
+ * response cache. Both go stale the moment a profile is edited, and neither has
+ * any way to find out — the writer is a different process in a different repo.
+ * This is the signal that tells them.
+ *
+ * The channel name and the payload shape are wire contracts between oxy-api (the
+ * publisher) and every consuming backend (the subscribers), so they live here
+ * rather than in either side. A hand-typed copy of the channel name fails as
+ * "the invalidation never arrives" — silently, because pub/sub has no delivery
+ * receipt and a message nobody is listening for is indistinguishable from a
+ * message nobody sent.
+ *
+ * DELIVERY IS AT-MOST-ONCE, AND THAT IS THE DESIGN. Every consumer's cache still
+ * carries its own TTL, so a dropped message degrades to exactly the behaviour
+ * before this signal existed and never to something worse. That property is what
+ * makes a bare Redis PUBLISH sufficient here and an outbox, retries, delivery
+ * receipts and payload signatures unnecessary. Do not treat a received event as
+ * authoritative for anything except "re-read this user from Oxy".
+ *
+ * PRIVACY — the payload carries NO user data, only an id, a reason and a
+ * timestamp. The channel rides the shared Valkey that every Oxy backend can
+ * subscribe to, so anything placed on it is readable by every service in the
+ * ecosystem. Never add a name, handle, email, avatar or any profile field: a
+ * subscriber that wants the new values re-reads them from Oxy through its normal
+ * authenticated path, where the usual authorization applies.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Redis pub/sub channel carrying user-invalidation events. */
+export declare const OXY_USER_INVALIDATION_CHANNEL = "oxy:user:invalidate";
+/**
+ * Why a user record changed, as classified by the writer in oxy-api.
+ *
+ * - `profile` — anything a consumer renders or caches as IDENTITY: display name,
+ *   username, avatar, bio, verification, federation fields, account status. This
+ *   is the DEFAULT for every writer, so a site that forgets to classify itself
+ *   over-invalidates (correct, marginally slower) rather than under-invalidates
+ *   (silently wrong). Keep that asymmetry if you add a reason.
+ * - `graph` — follow-edge churn only (follower/following counts). High frequency,
+ *   and bulk follow/unfollow moves up to 200 edges in one call. Nothing renders
+ *   identity from it and a stale count is harmless to ranking, so it is NOT
+ *   broadcast — see {@link OXY_PUBLISHED_USER_CHANGE_REASONS}.
+ */
+export declare const OXY_USER_CHANGE_REASONS: readonly ["profile", "graph"];
+export type OxyUserChangeReason = (typeof OXY_USER_CHANGE_REASONS)[number];
+/**
+ * The reasons that are actually put on the wire.
+ *
+ * A reason absent from this list is a local cache eviction in oxy-api and
+ * nothing more: no message is published at all, rather than a message every
+ * subscriber receives and discards. The distinction matters at bulk-follow
+ * scale, where the discarded variant is a 200-message burst on a channel every
+ * Oxy backend is subscribed to.
+ *
+ * This is deliberately a shared list rather than a check inside the publisher:
+ * a subscriber needs to know what it can receive, and the schema below rejects
+ * anything else, so publisher and subscriber cannot drift into disagreeing about
+ * which events exist. Adding a reason therefore forces an explicit decision about
+ * whether it broadcasts.
+ */
+export declare const OXY_PUBLISHED_USER_CHANGE_REASONS: readonly ["profile"];
+export type PublishedOxyUserChangeReason = (typeof OXY_PUBLISHED_USER_CHANGE_REASONS)[number];
+/** Whether a change of this kind is broadcast to consumers at all. */
+export declare function isPublishedOxyUserChangeReason(reason: OxyUserChangeReason): reason is PublishedOxyUserChangeReason;
+/**
+ * A single user-invalidation event.
+ *
+ * `at` is the publisher's epoch-ms clock, carried for diagnosis (measuring
+ * end-to-end propagation, spotting a wedged subscriber) — never for ordering or
+ * conflict resolution. Two Oxy tasks publish from unsynchronised clocks, and the
+ * event says only "re-read this user", which is idempotent and order-independent.
+ */
+export declare const oxyUserInvalidationEventSchema: z.ZodObject<{
+    /** The Oxy user whose record changed. */
+    userId: z.ZodString;
+    /** Why it changed. Only broadcast reasons appear on the wire. */
+    reason: z.ZodEnum<["profile"]>;
+    /** Publisher's epoch-ms timestamp. Diagnostic only. */
+    at: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    at: number;
+    reason: "profile";
+    userId: string;
+}, {
+    at: number;
+    reason: "profile";
+    userId: string;
+}>;
+export type OxyUserInvalidationEvent = z.infer<typeof oxyUserInvalidationEventSchema>;