@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/spreadsheet-artifact-query.ts

@@ -1,8 +1,14 @@
 import { spreadsheetSheetId, type EditableArtifactStableId } from "./spreadsheet-artifact-commands";
+import { fnv1a64 } from "./editable-artifact-binary";
 import {
   canonicalSpreadsheetDateFromMilliseconds,
   canonicalSpreadsheetDateMilliseconds,
 } from "./spreadsheet-artifact-date";
+import {
+  SPREADSHEET_DEFAULT_ROW_HEIGHT,
+  SPREADSHEET_DEFAULT_COLUMN_WIDTH,
+  SPREADSHEET_MAX_DIMENSION_PIXELS,
+} from "./spreadsheet-artifact-commands";
 
 /** Canonical private kernel query/projection ABI shared by browser and native bindings. */
 export const SPREADSHEET_ARTIFACT_QUERY_VERSION = 1 as const;
@@ -24,10 +30,23 @@ const VIEWPORT_QUERY_PAYLOAD_BYTES = 32;
 const VIEWPORT_PROJECTION_PREFIX_BYTES = 48;
 const METADATA_PROJECTION_PREFIX_BYTES = 4;
 const GENERATIONS_FLAG = 1;
+const DIMENSIONS_FLAG = 2;
+const DIMENSION_KEYS = [
+  "defaultRowHeight",
+  "defaultColumnWidth",
+  "rowHeights",
+  "columnWidths",
+] as const;
+
+/** Sparse absolute zero-based indices; omitted only in pre-dimension private projections. */
+export type SpreadsheetArtifactDimensions = Readonly<{
+  defaultRowHeight?: number;
+  defaultColumnWidth?: number;
+  rowHeights?: readonly (readonly [number, number])[];
+  columnWidths?: readonly (readonly [number, number])[];
+}>;
 const UINT32_MAX = 0xffff_ffff;
 const UINT64_MAX = 0xffff_ffff_ffff_ffffn;
-const FNV_OFFSET = 0xcbf29ce484222325n;
-const FNV_PRIME = 0x100000001b3n;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder("utf-8", { fatal: true });
 
@@ -85,16 +104,17 @@ export type SpreadsheetArtifactProjectedCell = Readonly<{
 }>;
 
 /** Complete and non-truncated. A limit breach is an error, never a partial response. */
-export type SpreadsheetArtifactViewportProjection = Readonly<{
-  revision: bigint;
-  sheetId: EditableArtifactStableId;
-  generationId: EditableArtifactStableId | null;
-  startRow: number;
-  startColumn: number;
-  rowCount: number;
-  columnCount: number;
-  cells: readonly SpreadsheetArtifactProjectedCell[];
-}>;
+export type SpreadsheetArtifactViewportProjection = SpreadsheetArtifactDimensions &
+  Readonly<{
+    revision: bigint;
+    sheetId: EditableArtifactStableId;
+    generationId: EditableArtifactStableId | null;
+    startRow: number;
+    startColumn: number;
+    rowCount: number;
+    columnCount: number;
+    cells: readonly SpreadsheetArtifactProjectedCell[];
+  }>;
 
 export type SpreadsheetArtifactUsedBounds = Readonly<{
   startRow: number;
@@ -103,20 +123,21 @@ export type SpreadsheetArtifactUsedBounds = Readonly<{
   endColumn: number;
 }>;
 
-export type SpreadsheetArtifactSheetMetadata = Readonly<{
-  sheetId: EditableArtifactStableId;
-  generationId: EditableArtifactStableId | null;
-  name: string;
-  usedBounds: SpreadsheetArtifactUsedBounds | null;
-}>;
+export type SpreadsheetArtifactSheetMetadata = SpreadsheetArtifactDimensions &
+  Readonly<{
+    sheetId: EditableArtifactStableId;
+    generationId: EditableArtifactStableId | null;
+    name: string;
+    usedBounds: SpreadsheetArtifactUsedBounds | null;
+  }>;
 
 /**
- * Version 1 deliberately models no row/column dimensions, hidden state, or
- * merges. It also carries no style projection. These are false capability
- * facts, not omitted authoritative data.
+ * Dimensions are carried under the explicit dimensions flag. Hidden state,
+ * merges and styles remain unsupported. Pre-dimension private projections
+ * carry dimensions=false and round-trip without inventing geometry.
  */
 export type SpreadsheetArtifactModeledFeatures = Readonly<{
-  dimensions: false;
+  dimensions: boolean;
   hidden: false;
   merges: false;
 }>;
@@ -232,6 +253,8 @@ export function encodeSpreadsheetViewportKernelProjection(
   payload.u32(projection.startColumn);
   payload.u32(projection.rowCount);
   payload.u32(projection.columnCount);
+  const hasDimensions = projection.defaultRowHeight !== undefined;
+  if (hasDimensions) writeDimensions(payload, projection);
   for (const cell of projection.cells) {
     payload.u32(cell.row - projection.startRow);
     payload.u32(cell.column - projection.startColumn);
@@ -240,7 +263,8 @@ export function encodeSpreadsheetViewportKernelProjection(
   return encodeProjectionFrame(
     0,
     projection.revision,
-    projection.generationId === null ? 0 : GENERATIONS_FLAG,
+    (projection.generationId === null ? 0 : GENERATIONS_FLAG) |
+      (hasDimensions ? DIMENSIONS_FLAG : 0),
     projection.cells.length,
     payload.finish(),
     maximum,
@@ -257,7 +281,7 @@ export function encodeSpreadsheetMetadataKernelProjection(
     SPREADSHEET_ARTIFACT_METADATA_MIN_RESPONSE_BYTES,
   );
   const payload = new DynamicWriter(maximum - PROJECTION_HEADER_BYTES - CHECKSUM_BYTES);
-  payload.u32(0);
+  payload.u32(projection.modeledFeatures.dimensions ? 1 : 0);
   for (const sheet of projection.sheets) {
     payload.stableId(sheet.sheetId);
     payload.optionalStableId(sheet.generationId);
@@ -271,12 +295,14 @@ export function encodeSpreadsheetMetadataKernelProjection(
       payload.u32(sheet.usedBounds.endRow);
       payload.u32(sheet.usedBounds.endColumn);
     }
+    if (projection.modeledFeatures.dimensions) writeDimensions(payload, sheet);
   }
   const generations = projection.sheets.length > 0 && projection.sheets[0]!.generationId !== null;
   return encodeProjectionFrame(
     1,
     projection.revision,
-    generations ? GENERATIONS_FLAG : 0,
+    (generations ? GENERATIONS_FLAG : 0) |
+      (projection.modeledFeatures.dimensions ? DIMENSIONS_FLAG : 0),
     projection.sheets.length,
     payload.finish(),
     maximum,
@@ -498,7 +524,7 @@ function decodeProjectionFrame(bytes: Uint8Array): ProjectionFrame {
     throw projectionError(`unsupported spreadsheet projection version: ${version}`);
   }
   const flags = reader.u16();
-  if ((flags & ~GENERATIONS_FLAG) !== 0) {
+  if ((flags & ~(GENERATIONS_FLAG | DIMENSIONS_FLAG)) !== 0) {
     throw projectionError("spreadsheet projection flags are noncanonical");
   }
   const kindTag = reader.u8();
@@ -549,6 +575,8 @@ function decodeViewportPayload(frame: ProjectionFrame): SpreadsheetArtifactViewp
   const rowCount = reader.u32();
   const columnCount = reader.u32();
   validateViewportGeometry(startRow, startColumn, rowCount, columnCount);
+  const dimensions = (frame.flags & DIMENSIONS_FLAG) !== 0 ? readDimensions(reader) : {};
+  validateDimensionExtent(dimensions, startRow, rowCount, startColumn, columnCount);
   const cells: SpreadsheetArtifactProjectedCell[] = [];
   let previousOrdinal = -1;
   for (let index = 0; index < frame.itemCount; index += 1) {
@@ -579,6 +607,7 @@ function decodeViewportPayload(frame: ProjectionFrame): SpreadsheetArtifactViewp
   reader.done("viewport projection payload contains trailing bytes");
   return Object.freeze({
     revision: frame.revision,
+    ...dimensions,
     sheetId,
     generationId,
     startRow,
@@ -597,7 +626,8 @@ function decodeMetadataPayload(frame: ProjectionFrame): SpreadsheetArtifactMetad
     throw projectionError("metadata projection payload is truncated");
   }
   const reader = new Reader(frame.payload);
-  if (reader.u32() !== 0) {
+  const features = reader.u32();
+  if ((features & ~1) !== 0 || (features === 1) !== ((frame.flags & DIMENSIONS_FLAG) !== 0)) {
     throw projectionError("metadata projection contains unknown modeled feature bits");
   }
   const hasGenerations = (frame.flags & GENERATIONS_FLAG) !== 0;
@@ -631,12 +661,13 @@ function decodeMetadataPayload(frame: ProjectionFrame): SpreadsheetArtifactMetad
       }
       usedBounds = Object.freeze({ startRow, startColumn, endRow, endColumn });
     }
-    sheets.push(Object.freeze({ sheetId, generationId, name, usedBounds }));
+    const dimensions = (frame.flags & DIMENSIONS_FLAG) !== 0 ? readDimensions(reader) : {};
+    sheets.push(Object.freeze({ sheetId, generationId, name, usedBounds, ...dimensions }));
   }
   reader.done("metadata projection payload contains trailing bytes");
   return Object.freeze({
     revision: frame.revision,
-    modeledFeatures: MODELED_FEATURES_NONE,
+    modeledFeatures: Object.freeze({ dimensions: features === 1, hidden: false, merges: false }),
     sheets: Object.freeze(sheets),
   });
 }
@@ -694,7 +725,8 @@ function normalizeViewportProjection(input: unknown): SpreadsheetArtifactViewpor
       "sheetId",
       "startColumn",
       "startRow",
-    ],
+      ...(projection.defaultRowHeight === undefined ? [] : DIMENSION_KEYS),
+    ].sort(),
     "spreadsheet viewport projection",
   );
   const revision = uint64(projection.revision, "viewport revision");
@@ -705,6 +737,9 @@ function normalizeViewportProjection(input: unknown): SpreadsheetArtifactViewpor
   const rowCount = positiveUint32(projection.rowCount, "viewport rowCount");
   const columnCount = positiveUint32(projection.columnCount, "viewport columnCount");
   validateViewportGeometry(startRow, startColumn, rowCount, columnCount);
+  const dimensions =
+    projection.defaultRowHeight === undefined ? {} : normalizeDimensions(projection);
+  validateDimensionExtent(dimensions, startRow, rowCount, startColumn, columnCount);
   if (!Array.isArray(projection.cells)) throw projectionError("viewport cells must be an array");
   if (projection.cells.length > SPREADSHEET_ARTIFACT_VIEWPORT_MAX_CELLS) {
     throw projectionError("viewport projection exceeds its hard cell limit");
@@ -733,6 +768,7 @@ function normalizeViewportProjection(input: unknown): SpreadsheetArtifactViewpor
   }
   return Object.freeze({
     revision,
+    ...dimensions,
     sheetId,
     generationId,
     startRow,
@@ -753,8 +789,12 @@ function normalizeMetadataProjection(input: unknown): SpreadsheetArtifactMetadat
   const revision = uint64(projection.revision, "metadata revision");
   const features = exactRecord(projection.modeledFeatures, "metadata modeledFeatures");
   exactKeys(features, ["dimensions", "hidden", "merges"], "metadata modeledFeatures");
-  if (features.dimensions !== false || features.hidden !== false || features.merges !== false) {
-    throw projectionError("version 1 metadata modeled features must all be false");
+  if (
+    typeof features.dimensions !== "boolean" ||
+    features.hidden !== false ||
+    features.merges !== false
+  ) {
+    throw projectionError("metadata modeled features are invalid");
   }
   if (!Array.isArray(projection.sheets)) throw projectionError("metadata sheets must be an array");
   if (projection.sheets.length > SPREADSHEET_ARTIFACT_METADATA_MAX_SHEETS) {
@@ -769,7 +809,17 @@ function normalizeMetadataProjection(input: unknown): SpreadsheetArtifactMetadat
       ownArrayElement(projection.sheets, index, "metadata sheets"),
       "metadata sheet",
     );
-    exactKeys(value, ["generationId", "name", "sheetId", "usedBounds"], "metadata sheet");
+    exactKeys(
+      value,
+      [
+        "generationId",
+        "name",
+        "sheetId",
+        "usedBounds",
+        ...(features.dimensions ? DIMENSION_KEYS : []),
+      ].sort(),
+      "metadata sheet",
+    );
     const sheetId = spreadsheetSheetId(requireString(value.sheetId, "metadata sheetId"));
     if (ids.has(sheetId)) throw projectionError("metadata projection contains duplicate sheet ids");
     ids.add(sheetId);
@@ -789,15 +839,118 @@ function normalizeMetadataProjection(input: unknown): SpreadsheetArtifactMetadat
     }
     names.add(foldedName);
     const usedBounds = value.usedBounds === null ? null : normalizeUsedBounds(value.usedBounds);
-    sheets.push(Object.freeze({ sheetId, generationId, name, usedBounds }));
+    sheets.push(
+      Object.freeze({
+        sheetId,
+        generationId,
+        name,
+        usedBounds,
+        ...(features.dimensions ? normalizeDimensions(value) : {}),
+      }),
+    );
   }
   return Object.freeze({
     revision,
-    modeledFeatures: MODELED_FEATURES_NONE,
+    modeledFeatures: Object.freeze({
+      dimensions: features.dimensions,
+      hidden: false,
+      merges: false,
+    }),
     sheets: Object.freeze(sheets),
   });
 }
 
+function normalizeDimensions(input: Record<string, unknown>): SpreadsheetArtifactDimensions {
+  if (
+    input.defaultRowHeight !== SPREADSHEET_DEFAULT_ROW_HEIGHT ||
+    input.defaultColumnWidth !== SPREADSHEET_DEFAULT_COLUMN_WIDTH
+  ) {
+    throw projectionError("dimension defaults are invalid");
+  }
+  const normalizeEntries = (
+    value: unknown,
+    defaultPixels: number,
+  ): readonly (readonly [number, number])[] => {
+    if (!Array.isArray(value) || value.length > SPREADSHEET_ARTIFACT_PROJECTION_MAX_BYTES / 8)
+      throw projectionError("dimension entries exceed limits");
+    let previous = -1;
+    const entries: (readonly [number, number])[] = [];
+    for (let offset = 0; offset < value.length; offset += 1) {
+      const entry = ownArrayElement(value, offset, "dimension entries");
+      if (!Array.isArray(entry) || entry.length !== 2)
+        throw projectionError("dimension entry must be an index/pixels pair");
+      const index = uint32(ownArrayElement(entry, 0, "dimension index"), `dimension ${offset}`);
+      const pixels = positiveUint32(
+        ownArrayElement(entry, 1, "dimension pixels"),
+        "dimension pixels",
+      );
+      if (
+        index <= previous ||
+        pixels > SPREADSHEET_MAX_DIMENSION_PIXELS ||
+        pixels === defaultPixels
+      )
+        throw projectionError("dimensions must be sorted unique non-default entries within bounds");
+      previous = index;
+      entries.push(Object.freeze([index, pixels] as const));
+    }
+    return Object.freeze(entries);
+  };
+  return Object.freeze({
+    defaultRowHeight: SPREADSHEET_DEFAULT_ROW_HEIGHT,
+    defaultColumnWidth: SPREADSHEET_DEFAULT_COLUMN_WIDTH,
+    rowHeights: normalizeEntries(input.rowHeights, SPREADSHEET_DEFAULT_ROW_HEIGHT),
+    columnWidths: normalizeEntries(input.columnWidths, SPREADSHEET_DEFAULT_COLUMN_WIDTH),
+  });
+}
+
+function writeDimensions(writer: DynamicWriter, dimensions: SpreadsheetArtifactDimensions): void {
+  writer.u32(dimensions.defaultRowHeight!);
+  writer.u32(dimensions.defaultColumnWidth!);
+  for (const entries of [dimensions.rowHeights!, dimensions.columnWidths!]) {
+    writer.u32(entries.length);
+    for (const [index, pixels] of entries) {
+      writer.u32(index);
+      writer.u32(pixels);
+    }
+  }
+}
+
+function readDimensions(reader: Reader): SpreadsheetArtifactDimensions {
+  const defaultRowHeight = reader.u32();
+  const defaultColumnWidth = reader.u32();
+  const axes: (readonly [number, number])[][] = [];
+  for (let axis = 0; axis < 2; axis += 1) {
+    const count = reader.u32();
+    if (count > SPREADSHEET_ARTIFACT_PROJECTION_MAX_BYTES / 8)
+      throw projectionError("dimension entries exceed limits");
+    const entries: (readonly [number, number])[] = [];
+    for (let index = 0; index < count; index += 1) entries.push([reader.u32(), reader.u32()]);
+    axes.push(entries);
+  }
+  return normalizeDimensions({
+    defaultRowHeight,
+    defaultColumnWidth,
+    rowHeights: axes[0],
+    columnWidths: axes[1],
+  });
+}
+
+function validateDimensionExtent(
+  dimensions: SpreadsheetArtifactDimensions,
+  startRow: number,
+  rowCount: number,
+  startColumn: number,
+  columnCount: number,
+): void {
+  if (
+    dimensions.rowHeights?.some(([index]) => index < startRow || index - startRow >= rowCount) ||
+    dimensions.columnWidths?.some(
+      ([index]) => index < startColumn || index - startColumn >= columnCount,
+    )
+  )
+    throw projectionError("dimensions lie outside viewport");
+}
+
 function normalizeProjectedCell(input: unknown): SpreadsheetArtifactProjectedCell {
   const cell = exactRecord(input, "projected cell");
   exactKeys(cell, ["column", "formula", "row", "value"], "projected cell");
@@ -1036,15 +1189,6 @@ function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
   return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
 }
 
-function fnv1a64(bytes: Uint8Array): bigint {
-  let hash = FNV_OFFSET;
-  for (const byte of bytes) {
-    hash ^= BigInt(byte);
-    hash = BigInt.asUintN(64, hash * FNV_PRIME);
-  }
-  return hash;
-}
-
 function queryError(message: string): TypeError {
   return new TypeError(message);
 }
@@ -1053,12 +1197,6 @@ function projectionError(message: string): TypeError {
   return new TypeError(message);
 }
 
-const MODELED_FEATURES_NONE: SpreadsheetArtifactModeledFeatures = Object.freeze({
-  dimensions: false,
-  hidden: false,
-  merges: false,
-});
-
 const EMPTY_VALUE: SpreadsheetArtifactProjectedCellValue = Object.freeze({
   kind: "empty",
 });

package/src/subscription-account-actions.ts

@@ -0,0 +1,103 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/**
+ * Request bodies for subscription account actions (Codex, Claude, SuperGrok):
+ * renaming, pausing, rotation, extra credits and device sign-in. The routes
+ * validate with these, and the agent action catalog shows them as the input.
+ */
+
+/** Rename an account. An empty or null label goes back to the account's email. */
+export const SubscriptionAccountRenameRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    label: primitives.string.trim().max(200).nullable(),
+  }),
+);
+export type SubscriptionAccountRenameRequest = z.infer<typeof SubscriptionAccountRenameRequest>;
+
+/**
+ * Turn one account setting on or off: "used for new work" (allocator) or extra
+ * credits. expectedVersion is the account's current allocatorVersion or
+ * extraCreditsVersion; a stale version is refused so concurrent edits don't clash.
+ */
+export const SubscriptionAccountToggleRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    enabled: primitives.boolean,
+    expectedVersion: primitives.positiveInteger,
+  }),
+);
+export type SubscriptionAccountToggleRequest = z.infer<typeof SubscriptionAccountToggleRequest>;
+
+/** Account picking: true spreads work across every usable account, false uses the primary one only. */
+export const SubscriptionRotationSettingsRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    rotationEnabled: primitives.boolean,
+  }),
+);
+export type SubscriptionRotationSettingsRequest = z.infer<
+  typeof SubscriptionRotationSettingsRequest
+>;
+
+/** Check a device sign-in with the state returned by its connect/start call. */
+export const SubscriptionConnectPollRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    state: z.string().min(1).max(16_384),
+  }),
+);
+export type SubscriptionConnectPollRequest = z.infer<typeof SubscriptionConnectPollRequest>;
+
+/** Where a workspace SuperGrok sign-in lands: the shared workspace pool or only the person. */
+export const SupergrokConnectStartRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    scope: z.enum(["workspace", "user"]).default("workspace"),
+  }),
+);
+export type SupergrokConnectStartRequest = z.infer<typeof SupergrokConnectStartRequest>;
+
+/**
+ * A started device sign-in (Codex or SuperGrok): the person enters userCode at
+ * verificationUri (or opens verificationUriComplete), then the caller polls
+ * connect/poll with state every intervalSeconds.
+ */
+export const SubscriptionDeviceSignInStart = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    userCode: primitives.string,
+    verificationUri: primitives.string,
+    verificationUriComplete: primitives.string.nullable().optional(),
+    intervalSeconds: primitives.positiveInteger,
+    expiresInSeconds: primitives.positiveInteger.optional(),
+    scope: z.enum(["workspace", "user", "organization"]).optional(),
+    state: primitives.string,
+  }),
+);
+export type SubscriptionDeviceSignInStart = z.infer<typeof SubscriptionDeviceSignInStart>;
+
+/**
+ * Which Codex accounts a workspace uses: automatic (Opengeni picks from the
+ * workspace's and the organization's accounts), only the workspace's own, only
+ * the organization's, or none (Codex off for the workspace).
+ */
+export const CodexSourceRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    mode: z.enum(["automatic", "workspace", "organization", "disabled"]),
+  }),
+);
+export type CodexSourceRequest = z.infer<typeof CodexSourceRequest>;
+
+/** Choose the Codex account that serves Codex Apps; expectedVersion is the current designation version. */
+export const CodexAppsDesignationRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    accountId: primitives.uuid,
+    expectedVersion: primitives.nonnegativeInteger,
+  }),
+);
+export type CodexAppsDesignationRequest = z.infer<typeof CodexAppsDesignationRequest>;
+
+/** Pin one chat to a Codex account by id, or "auto" to let Opengeni pick again. */
+export const SessionCodexAccountPinRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    target: primitives.nonEmptyString.describe('"auto" or a Codex account id'),
+  }),
+);
+export type SessionCodexAccountPinRequest = z.infer<typeof SessionCodexAccountPinRequest>;

package/src/subscription-account-pools.ts

@@ -0,0 +1,74 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { ClaudeSubscriptionUsage } from "./claude-subscription-usage";
+
+/**
+ * Who an account in the organization's list reaches: the workspace that owns
+ * it (its own account, used only there), every workspace including new ones,
+ * chosen shared workspaces, Personal workspaces, or chosen people.
+ */
+export const SubscriptionAccountReach = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      ownerWorkspaceId: primitives.nullableUuid,
+      everyWorkspace: primitives.boolean,
+      workspaceIds: z.array(primitives.uuid),
+      personalWorkspaces: primitives.boolean,
+      people: z.number().int().nonnegative().nullable(),
+    })
+    .strict(),
+);
+export type SubscriptionAccountReach = z.infer<typeof SubscriptionAccountReach>;
+
+/** Shared, secret-free account list contract for native subscription pools. */
+export const SubscriptionAccountSummary = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    scope: z.enum(["organization", "workspace", "user"]),
+    subject: primitives.nonEmptyString,
+    email: z.string().email().nullable(),
+    label: primitives.nullableString,
+    plan: primitives.nullableString,
+    status: z.enum(["active", "needs_relogin", "error", "disabled"]),
+    active: primitives.boolean,
+    expiresAt: z.string().datetime().nullable(),
+    lastRefreshAt: z.string().datetime().nullable(),
+    lastError: primitives.nullableString,
+    allocatorEnabled: primitives.boolean,
+    allocatorVersion: primitives.positiveInteger,
+    allocatorUpdatedAt: z.string().datetime().nullable(),
+    /** The organization's list only. */
+    reach: SubscriptionAccountReach.optional(),
+  }),
+);
+export type SubscriptionAccountSummary = z.infer<typeof SubscriptionAccountSummary>;
+export const SubscriptionPoolSettings = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      rotationEnabled: primitives.boolean,
+      rotationStrategy: z.literal("sharded"),
+      activeCredentialId: primitives.nullableUuid,
+    })
+    .strict(),
+);
+export type SubscriptionPoolSettings = z.infer<typeof SubscriptionPoolSettings>;
+export const ClaudeSubscriptionAccount = /* @__PURE__ */ defineSchema(() =>
+  SubscriptionAccountSummary.extend({
+    version: primitives.positiveInteger,
+    usage: ClaudeSubscriptionUsage.optional(),
+  }).strict(),
+);
+export type ClaudeSubscriptionAccount = z.infer<typeof ClaudeSubscriptionAccount>;
+export const ClaudeSubscriptionAccountsResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      accounts: z.array(ClaudeSubscriptionAccount),
+      activeAccountId: primitives.nullableUuid,
+      source: z.enum(["organization", "workspace", "user"]),
+      organizationId: primitives.uuid,
+      settings: SubscriptionPoolSettings,
+    })
+    .strict(),
+);
+export type ClaudeSubscriptionAccountsResponse = z.infer<typeof ClaudeSubscriptionAccountsResponse>;

package/src/subscription-personal-authority-v2.ts

@@ -0,0 +1,69 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+const PositiveSafeInteger = /* @__PURE__ */ defineSchema(() =>
+  primitives.positiveInteger.max(Number.MAX_SAFE_INTEGER),
+);
+/**
+ * Canonical lowercase UUID, matching PostgreSQL uuid::text and the
+ * session_turns CHECK, so an accepted snapshot can never silently mismatch.
+ */
+const CanonicalUuid = /* @__PURE__ */ defineSchema(() =>
+  primitives.string.regex(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  ),
+);
+
+/**
+ * Immutable personal authority for accepted subscription work. Shared pool
+ * eligibility is live and deliberately absent from this snapshot.
+ */
+export const SubscriptionPersonalAuthorityV2 = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(2),
+      personal: z
+        .array(
+          z
+            .object({
+              provider: z.enum(["codex", "claude", "xai"]),
+              ownerMembershipId: CanonicalUuid,
+              authorityGeneration: PositiveSafeInteger,
+              /**
+               * Explicit personal consent accepted in a shared chat. Unlike the
+               * historical private-work pool, this authorizes only this connection
+               * in this session. Copies retain the restriction verbatim.
+               */
+              sharedSessionChoice: z
+                .object({ sessionId: CanonicalUuid, connectionId: CanonicalUuid })
+                .strict()
+                .optional(),
+            })
+            .strict(),
+        )
+        .max(3),
+    })
+    .strict()
+    .superRefine((snapshot, ctx) => {
+      const providers = snapshot.personal.map((authority) => authority.provider);
+      if (new Set(providers).size !== providers.length) {
+        ctx.addIssue({ code: "custom", message: "Duplicate provider personal authority" });
+      }
+    }),
+);
+
+export type SubscriptionPersonalAuthorityV2 = z.infer<typeof SubscriptionPersonalAuthorityV2>;
+
+/** Return one provider's immutable personal authority from a parsed snapshot. */
+export function subscriptionPersonalAuthorityForProviderV2(
+  snapshot: SubscriptionPersonalAuthorityV2,
+  provider: SubscriptionPersonalAuthorityV2["personal"][number]["provider"],
+): SubscriptionPersonalAuthorityV2["personal"][number] | null {
+  return snapshot.personal.find((authority) => authority.provider === provider) ?? null;
+}
+
+export const EMPTY_SUBSCRIPTION_PERSONAL_AUTHORITY_V2 = {
+  version: 2,
+  personal: [],
+} as const satisfies SubscriptionPersonalAuthorityV2;