@velajs/studio-protocol 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,1285 @@
+//#region src/errors.d.ts
+/**
+ * Studio error wire shape + the closed catalog of Studio-specific error codes.
+ *
+ * `AdminErrorBody` is a STRUCTURAL MIRROR of `@velajs/errors` `WireErrorObject`
+ * (`errors/src/to-error-body.ts`), enriched with the `title` and `status` the
+ * UI renders directly off the error envelope. The server enriches a
+ * `WireErrorObject` (from `toErrorBody`) into this shape; a drift guard asserting
+ * field compatibility lives in the server package.
+ */
+/**
+ * The client-bound error body carried by a failed {@link AdminRpcResponse}.
+ *
+ * Shared fields (`code`, `message`, `hint`, `docsUrl`, `details`) mirror
+ * `WireErrorObject`; `title` and `status` are the Studio-facing enrichment.
+ */
+export interface AdminErrorBody {
+  /** Stable, dot/underscore-namespaced machine code (e.g. `STUDIO_DISABLED`). */
+  code: string;
+  /** Human-readable, catalog-sourced summary of the error class. */
+  title: string;
+  /** HTTP status this error maps to. */
+  status: number;
+  /** Redaction-safe message (unbranded errors carry only their status title). */
+  message: string;
+  /** Optional actionable remediation hint. */
+  hint?: string;
+  /** Optional link to documentation for this error class. */
+  docsUrl?: string;
+  /** Optional wire-encoded structured data (mirrors `WireErrorObject.details`). */
+  details?: unknown;
+}
+/**
+ * The structured payload carried on {@link AdminErrorBody.details} of a
+ * `STUDIO_CONFIRM_REQUIRED` (428) error — the server's challenge for a
+ * destructive op. The client re-sends the identical op args plus
+ * {@link StudioConfirmChallenge.confirmToken} to complete the op.
+ *
+ * The token is single-use and payload-bound (see the server confirm signer);
+ * `summary` is a human line the op handler supplies for the confirm dialog.
+ * This is the canonical wire shape for the challenge — producers (server,
+ * test fixtures) and consumers (UI decode) MUST use this type rather than
+ * re-declaring it, so the two ends cannot drift.
+ */
+export interface StudioConfirmChallenge {
+  /** Single-use, op+payload-bound token to echo back on the confirmed retry. */
+  confirmToken: string;
+  /** Epoch-ms after which the token is rejected. */
+  expiresAt: number;
+  /** Human-readable description of what the confirmed op will do. */
+  summary: string;
+}
+/**
+ * The closed set of Studio-specific error codes. `const` array + derived union
+ * so the compile-time type and any runtime membership check can never drift.
+ * Parenthetical statuses document the intended HTTP mapping (the wire carries
+ * the concrete status on {@link AdminErrorBody}).
+ */
+export declare const STUDIO_ERROR_CODES: readonly [
+/** Studio surface disabled (no token configured). */
+'STUDIO_DISABLED',
+/** Missing or invalid bearer token (401). */
+'STUDIO_UNAUTHORIZED',
+/** Dispatch target op is not registered (404). */
+'STUDIO_UNKNOWN_OP',
+/** Op recognized but forbidden for this principal/config (403). */
+'STUDIO_OP_FORBIDDEN',
+/** Ephemeral WS sub-token failed verification (401). */
+'STUDIO_SUB_TOKEN_INVALID',
+/** Per-IP token bucket exhausted (429). */
+'STUDIO_RATE_LIMITED',
+/** A confirmation token is required for this destructive op (428). */
+'STUDIO_CONFIRM_REQUIRED',
+/** Referenced data model is unknown (404). */
+'STUDIO_UNKNOWN_MODEL',
+/** Data editing is disabled (read-only Studio) (403). */
+'DATA_EDIT_DISABLED',
+/** Time travel is unavailable in this environment (409). */
+'TIMETRAVEL_UNAVAILABLE',
+/** Snapshot schema is incompatible with the current model (409). */
+'TIMETRAVEL_SCHEMA_MISMATCH',
+/** The backing feature/package is present but not configured (404). */
+'FEATURE_UNCONFIGURED'];
+/** Union of every Studio-specific error code. */
+export type StudioErrorCode = (typeof STUDIO_ERROR_CODES)[number];
+//#endregion
+//#region src/envelope.d.ts
+/** A dispatch request. `args` shape is the op's `req` type from the op catalog. */
+export interface AdminRpcRequest<A = unknown> {
+  args?: A;
+}
+/** Success metadata attached to every ok response. */
+export interface AdminResponseMeta {
+  /** Server-measured handling time in milliseconds. */
+  ms: number;
+  op: string;
+  mode: 'read' | 'write';
+}
+/**
+ * The dispatch response, discriminated on `ok`. Narrowing on `ok === true`
+ * exposes `data` + `meta`; `ok === false` exposes `error` + `status`.
+ */
+export type AdminRpcResponse<R = unknown> = {
+  ok: true;
+  op: string;
+  data: R;
+  meta: AdminResponseMeta;
+} | {
+  ok: false;
+  op: string;
+  error: AdminErrorBody;
+  status: number;
+};
+//#endregion
+//#region src/data.d.ts
+/**
+ * Data-browser wire contract. Model discovery + row access shapes.
+ *
+ * `StudioFilterOperator` is a compatible subset of `@velajs/crud`'s
+ * `FilterOperator` (`crud/packages/core/src/adapter/query-types.ts`), and
+ * `StudioPageInfo` is a structural mirror of crud's `PageInfo` (snake_case
+ * preserved). Drift guards against the real crud package land in the server
+ * package; see the report for mirror source paths.
+ */
+/**
+ * Grid filter operators — a subset of crud's `FILTER_OPERATORS`, chosen so every
+ * member is assignment-compatible with crud's `FilterOperator`. `const` array +
+ * derived union so compile-time type and runtime membership can't drift.
+ */
+export declare const STUDIO_FILTER_OPERATORS: readonly ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike', 'null', 'between'];
+/** Union of every supported grid filter operator. */
+export type StudioFilterOperator = (typeof STUDIO_FILTER_OPERATORS)[number];
+/** One grid filter clause. */
+export interface StudioGridFilter {
+  field: string;
+  operator: StudioFilterOperator;
+  value: unknown;
+}
+/** A single column in a model, derived from the model schema. */
+export interface StudioColumn {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'date' | 'json' | 'unknown';
+  pk: boolean;
+  nullable: boolean;
+  unique: boolean;
+  /** Foreign-key reference, from `model.relations` foreignKey. */
+  fk?: {
+    table: string;
+    relation: string;
+  };
+  /** Managed field: timestamps / soft-delete / tenant. */
+  managed: boolean;
+}
+/** Lightweight model listing entry. */
+export interface StudioModelInfo {
+  name: string;
+  table: string;
+  label: string;
+  /** Adapter capability names available for this model (e.g. `search`, `aggregate`). */
+  capabilities: string[];
+}
+/** Full descriptor for a single model. */
+export interface StudioModelDescriptor {
+  name: string;
+  table: string;
+  primaryKeys: string[];
+  columns: StudioColumn[];
+  relations: Array<{
+    name: string;
+    type: 'hasOne' | 'hasMany' | 'belongsTo';
+    target: string;
+    foreignKey: string;
+    cascade?: string;
+  }>;
+  flags: {
+    softDelete: boolean;
+    multiTenant: boolean;
+    versioning: boolean;
+    audit: boolean;
+  };
+  supports: {
+    bulkWrites: boolean;
+    facets: boolean;
+    search: boolean;
+    cascade: boolean;
+  };
+}
+/** Request to list rows of a model. */
+export interface ListRowsRequest {
+  model: string;
+  filters?: StudioGridFilter[];
+  sort?: {
+    field: string;
+    order: 'asc' | 'desc';
+  };
+  page?: number;
+  perPage?: number;
+  cursor?: string;
+  search?: string;
+  withDeleted?: boolean;
+}
+/**
+ * Pagination metadata — structural mirror of `@velajs/crud` `PageInfo`
+ * (snake_case field names preserved for faithful mirroring).
+ */
+export interface StudioPageInfo {
+  page: number;
+  per_page: number;
+  total_count?: number;
+  total_pages?: number;
+  has_next_page: boolean;
+  has_prev_page: boolean;
+  /** Next-page cursor (keyset pagination). Walks are next-only. */
+  next_cursor?: string;
+}
+/** A page of untyped rows plus pagination metadata. */
+export interface StudioRowPage {
+  rows: Array<Record<string, unknown>>;
+  info: StudioPageInfo;
+}
+/** Request to write (create or patch) a single row. */
+export interface WriteRowRequest {
+  model: string;
+  /** Present for an update; absent for a create. */
+  id?: string;
+  patch: Record<string, unknown>;
+  confirmToken?: string;
+}
+/** Request to delete rows (soft or hard). Destructive: `confirmToken` required. */
+export interface DeleteRowsRequest {
+  model: string;
+  ids: string[];
+  mode: 'soft' | 'hard';
+  confirmToken: string;
+}
+/** Request to clear an entire table. Destructive: `confirmToken` required. */
+export interface ClearTableRequest {
+  model: string;
+  confirmToken: string;
+}
+/** Request faceted counts for a field. */
+export interface FacetsRequest {
+  model: string;
+  field: string;
+  filters?: StudioGridFilter[];
+  limit?: number;
+}
+/** Faceted count buckets. */
+export interface FacetsResponse {
+  buckets: Array<{
+    value: unknown;
+    count: number;
+  }>;
+}
+/** Request a cascade-delete preview for the given rows. */
+export interface CascadePreviewRequest {
+  model: string;
+  ids: string[];
+}
+/** The relations a cascade delete would touch. */
+export interface CascadePreviewResponse {
+  relations: Array<{
+    relation: string;
+    target: string;
+    action: string;
+    affected: number;
+  }>;
+}
+/** Request to generate synthetic rows. */
+export interface GenerateRowsRequest {
+  model: string;
+  count: number;
+  overrides?: Record<string, unknown>;
+}
+/** Result of a generate-rows write. */
+export interface GenerateRowsResponse {
+  inserted: number;
+}
+//#endregion
+//#region src/app.d.ts
+/**
+ * Application-introspection wire contract (the `app.*` and `api.authorizeTryIt` ops).
+ *
+ * `RouteRow` mirrors `@velajs/cli` `introspect.ts` `RouteRow`, and `ModuleNode`
+ * mirrors vela's `ModuleDescription` (`vela/src/container/types.ts`) field-for-
+ * field. `EntrypointRow` intentionally carries `meta?: unknown` (the wire shape)
+ * rather than the CLI's serialized `meta: string`. See the report for sources.
+ */
+/** One row of the app route table. Mirrors `@velajs/cli` `RouteRow`. */
+export interface RouteRow {
+  method: string;
+  path: string;
+  /** `Controller#handler`, or `(mounted)` for routes vela did not compose itself. */
+  handler: string;
+  source: 'controller' | 'mounted';
+}
+/**
+ * One module instance in the loaded graph. Structural mirror of vela's
+ * `ModuleDescription` (`Container.getModuleDescriptions()`).
+ */
+export interface ModuleNode {
+  moduleId: string;
+  /** moduleIds this instance imports. */
+  imports: string[];
+  isGlobal: boolean;
+  lazy: boolean;
+  /** Token labels registered in this instance's bucket (registration order). */
+  providers: string[];
+  /** Token labels this instance exports. */
+  exports: string[];
+}
+/** One entrypoint entry (queue/cron/etc.). Wire shape: `meta` is optional/unknown. */
+export interface EntrypointRow {
+  kind: string;
+  target: string;
+  meta?: unknown;
+}
+/** An API "try it" request proxied against the app. */
+export interface TryItRequest {
+  method: string;
+  path: string;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+/** The response captured from a "try it" request. */
+export interface TryItResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+}
+/** Validate JSON from the local API explorer before any request can be sent. */
+export declare function parseTryItRequest(value: unknown): TryItRequest;
+export declare function parseTryItResponse(value: unknown): TryItResponse;
+//#endregion
+//#region src/panels.d.ts
+/**
+ * Read-panel row types for the package-backed op sets (auth / queue / schedule /
+ * flags / logs / live / presence / audit / transfer / overview).
+ *
+ * Kept MINIMAL and honest: only the fields the panels actually need. Field names
+ * are chosen to match the real backing services later ops call (`@velajs/auth`,
+ * `@velajs/feature-flags`, `vela/src/queue`, `vela/src/schedule*`) so they are
+ * not fantasy; the server package narrows them to concrete service reads.
+ */
+/** A user row for the auth users panel. */
+export interface AuthUserRow {
+  id: string;
+  email: string;
+  name?: string;
+  emailVerified: boolean;
+  image?: string;
+  role?: string;
+  banned?: boolean;
+  createdAt: number;
+}
+/** A session row for the auth sessions panel. */
+export interface AuthSessionRow {
+  id: string;
+  userId: string;
+  createdAt: number;
+  expiresAt: number;
+  ipAddress?: string;
+  userAgent?: string;
+}
+/** An organization row (better-auth organization plugin). */
+export interface AuthOrgRow {
+  id: string;
+  name: string;
+  slug?: string;
+  memberCount?: number;
+  createdAt: number;
+}
+/** The detail view for a single user. */
+export interface AuthUserDetail {
+  user: AuthUserRow;
+  sessions: AuthSessionRow[];
+  organizations: AuthOrgRow[];
+}
+/** A queue row for the queues panel. */
+export interface QueueRow {
+  name: string;
+  kind: string;
+  depth?: number;
+}
+/** A live queue-depth reading. */
+export interface QueueDepthRow {
+  name: string;
+  depth: number;
+  inFlight?: number;
+}
+/** A dead-letter-queue entry. */
+export interface DlqEntryRow {
+  id: string;
+  queue: string;
+  failedAt: number;
+  attempts: number;
+  error?: string;
+  payload?: unknown;
+}
+/**
+ * A scheduled job row. Mirrors vela's `ScheduleJobRef` (`kind` + `expression?` /
+ * `ms?`). `ScheduleJobRef` carries no name or run timestamps, so `name`,
+ * `lastRun`, and `nextRun` are all server-synthesized around the driver read.
+ */
+export interface ScheduleJobRow {
+  /** Server-synthesized display name (derived from the job's `methodName`). */
+  name: string;
+  kind: 'cron' | 'interval';
+  /** Cron expression (`kind: 'cron'`). */
+  expression?: string;
+  /** Interval period in ms (`kind: 'interval'`). */
+  ms?: number;
+  /** Server-synthesized: last fire time (epoch ms). */
+  lastRun?: number;
+  /** Server-synthesized: next scheduled fire time (epoch ms). */
+  nextRun?: number;
+}
+/** A declared cron trigger. */
+export interface CronTriggerRow {
+  name: string;
+  cron: string;
+  nextRun?: number;
+}
+/**
+ * A value a feature flag can resolve to. A local structural mirror of
+ * `@velajs/feature-flags`' `FlagValue` (`boolean | string | number | object`) —
+ * mirrored, never imported, so the wire contract is independent of that package.
+ */
+export type FlagValue = boolean | string | number | object;
+/**
+ * Why a flag evaluation returned the value it did. A local structural mirror of
+ * `@velajs/feature-flags`' `FlagEvaluationReason` union (its members, exactly).
+ */
+export type FlagEvaluationReason = 'STATIC' | 'DEFAULT' | 'ERROR';
+/**
+ * A feature-flag row. A flag resolves to a {@link FlagValue}, not a boolean —
+ * the driver has no `enabled`/`description` fields to back those, so the row
+ * carries only the key and its resolved value.
+ */
+export interface FlagRow {
+  key: string;
+  value: FlagValue;
+}
+/**
+ * The result of evaluating a flag against a context. Mirrors
+ * `@velajs/feature-flags`' `FlagEvaluationDetails`: `flagKey`, the resolved
+ * {@link FlagValue}, a required {@link FlagEvaluationReason}, and an optional
+ * `errorMessage` present only on `reason: 'ERROR'`.
+ */
+export interface FlagEvaluation {
+  flagKey: string;
+  value: FlagValue;
+  reason: FlagEvaluationReason;
+  errorMessage?: string;
+}
+/** A captured application log line. */
+export interface AdminLogEntry {
+  ts: number;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  msg: string;
+  source?: string;
+  fields?: Record<string, unknown>;
+}
+/** An active live subscription. */
+export interface LiveSubscriptionRow {
+  id: string;
+  room: string;
+  tags: string[];
+  connectedAt: number;
+  clientId?: string;
+}
+/** A presence room occupancy row. */
+export interface PresenceRoomRow {
+  room: string;
+  count: number;
+  members?: string[];
+}
+/** One recorded admin audit row (mirrors the server's `AdminAuditEntry`). */
+export interface AdminAuditEntry {
+  ts: number;
+  op: string;
+  mode: 'read' | 'write';
+  subject: string;
+  status: number;
+  ms: number;
+  ip: string | null;
+  detail?: {
+    target?: string;
+    summary?: string;
+    extra?: Record<string, unknown>;
+  };
+}
+/** The result of a transfer export (a downloadable NDJSON URL). */
+export interface TransferExportResult {
+  exportUrl: string;
+}
+/**
+ * A transfer import request. Destructive (bulk ingest): `confirmToken` required,
+ * so it satisfies the destructive-op contract.
+ */
+export interface TransferImportRequest {
+  model: string;
+  ndjson: string;
+  confirmToken: string;
+}
+/** The result of a transfer import. */
+export interface TransferImportResult {
+  imported: number;
+  errors: Array<{
+    line: number;
+    message: string;
+  }>;
+}
+/** A minimal health + counts summary for the overview panel. */
+export interface OverviewSummary {
+  status: 'ok' | 'degraded';
+  uptimeMs?: number;
+  counts: {
+    models?: number;
+    routes?: number;
+    modules?: number;
+    queues?: number;
+    scheduledJobs?: number;
+    flags?: number;
+  };
+}
+//#endregion
+//#region src/time-travel.d.ts
+/**
+ * Time-travel wire contract — adopted verbatim (in concept) from the
+ * `timetravel.contracts` design slice. Pure types only: the `TimeTravelPort`
+ * interface lives here, but its DI token is declared in the server package.
+ *
+ * Marks are opaque (a CF DO bookmark string, or a portable manifest id). The
+ * lifecycle is preview -> confirmToken -> arm -> undo; unavailable environments
+ * surface `TIMETRAVEL_UNAVAILABLE` (409).
+ */
+/** How precisely a port can address a point in time. */
+export type TimeTravelGranularity = 'bookmark' | 'snapshot' | 'snapshot+cdc';
+/**
+ * Capability negotiation shape the UI reads for defaults-shown / hide-on-disabled
+ * affordances. Both adapters expose their full power here rather than collapsing
+ * to a lowest common denominator.
+ */
+export interface TimeTravelCapabilities {
+  /** `getMarkForTime` supported. */
+  markByTime: boolean;
+  /** `listMarks` supported (portable: yes; CF DO: no). */
+  list: boolean;
+  /** `armRestore` returns an undo mark. */
+  undo: boolean;
+  /** Restore applies to the live store. */
+  inPlace: boolean;
+  /** CF DO: applies only on restart/abort. */
+  restartRequired: boolean;
+  /** A snapshot can be downloaded off-platform. */
+  portableExport: boolean;
+  /** `createSnapshot` supported. */
+  createOnDemand: boolean;
+  /** Addressing granularity of this port. */
+  granularity: TimeTravelGranularity;
+  /** Human, honest note on what a restore actually covers. */
+  scopeNote: string;
+}
+/** Selects the dataset / log-scope to operate on. */
+export interface TimeTravelScope {
+  /** Portable: a named table-group (`'default'` = all managed). CF: the DO room/name. */
+  dataset?: string;
+}
+/** An opaque, addressable point in time. */
+export interface TimeTravelMark {
+  /** Opaque id: a CF bookmark string or a portable manifest id. */
+  id: string;
+  kind: 'bookmark' | 'snapshot';
+  /** Epoch-ms when known. */
+  time?: number;
+  label?: string;
+  /** Portable snapshots only. */
+  schemaHash?: string;
+  sizeBytes?: number;
+  /** Portable: the tables captured by this mark. */
+  tables?: string[];
+}
+/** A page of marks (cursor pagination; next-only). */
+export interface TimeTravelMarkPage {
+  marks: TimeTravelMark[];
+  nextCursor?: string;
+}
+/** Addresses a restore target — an explicit mark id or a point in time. */
+export interface RestoreTarget {
+  /** Explicit mark id (e.g. an undo mark) — wins over `time`. */
+  bookmark?: string;
+  /** Epoch-ms or ISO string. */
+  time?: number | string;
+}
+/** The result of a restore preview; `confirmToken` must be echoed to `armRestore`. */
+export interface RestorePreview {
+  target: TimeTravelMark;
+  affectedTables: Array<{
+    table: string;
+    approxRows?: number;
+  }>;
+  /** `manifest.schemaHash === current`. */
+  schemaCompatible: boolean;
+  incompatibleTables: string[];
+  undoAvailable: boolean;
+  restartRequired: boolean;
+  /** Single-use token bound to (mark, tables, schemaHash); echo to `armRestore`. */
+  confirmToken: string;
+  /** Epoch-ms after which the `confirmToken` is rejected. */
+  expiresAt: number;
+}
+/** A confirmed restore request. */
+export interface RestoreRequest extends RestoreTarget {
+  scope?: TimeTravelScope;
+  /** CF: also `ctx.abort()` to apply now. */
+  restart?: boolean;
+  /** Override a schema mismatch (dev-host only). */
+  force?: boolean;
+  /** The token echoed from {@link RestorePreview}. */
+  confirmToken: string;
+}
+/** The outcome of an armed restore. */
+export interface RestoreOutcome {
+  /** Target mark id. */
+  restoredTo: string;
+  /** Restore to this mark to undo. */
+  undoMark?: TimeTravelMark;
+  /** `false` when armed-for-next-restart (CF, `restart: false`). */
+  applied: boolean;
+  restartRequested: boolean;
+}
+/** Snapshot retention policy for pruning. */
+export interface RetentionPolicy {
+  keepLast?: number;
+  maxAgeMs?: number;
+}
+/** A portable snapshot manifest (adapter B). */
+export interface SnapshotManifest {
+  id: string;
+  createdAt: number;
+  label?: string;
+  tables: Array<{
+    table: string;
+    rows: number;
+    schemaHash: string;
+    ndjsonKey: string;
+  }>;
+  /** Set when a change source captured a window. */
+  changeLog?: {
+    fromTs: number;
+    toTs: number;
+  };
+}
+/** A single CDC record kind. */
+export type StudioChangeKind = 'insert' | 'update' | 'delete';
+/** A single committed change (CDC replay input). */
+export interface StudioChange {
+  ts: number;
+  table: string;
+  kind: StudioChangeKind;
+  key: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+}
+/**
+ * The time-travel seam. Two adapters implement it: the portable NDJSON
+ * snapshot/replay adapter and the CF-native DO PITR bookmark adapter. Declared
+ * here as pure types; the `TIME_TRAVEL_PORT` DI token lives in the server package.
+ */
+export interface TimeTravelPort {
+  /** `'cf-do-pitr'` | `'portable-snapshot'`. */
+  readonly id: string;
+  capabilities(scope?: TimeTravelScope): TimeTravelCapabilities;
+  getCurrentMark(scope?: TimeTravelScope): Promise<TimeTravelMark>;
+  getMarkForTime?(time: number | string, scope?: TimeTravelScope): Promise<TimeTravelMark | null>;
+  listMarks?(scope?: TimeTravelScope, opts?: {
+    limit?: number;
+    before?: string;
+  }): Promise<TimeTravelMarkPage>;
+  preview(target: RestoreTarget, scope?: TimeTravelScope): Promise<RestorePreview>;
+  armRestore(req: RestoreRequest): Promise<RestoreOutcome>;
+  createSnapshot?(opts?: {
+    scope?: TimeTravelScope;
+    label?: string;
+  }): Promise<TimeTravelMark>;
+  exportSnapshot?(markId: string): Promise<ReadableStream<Uint8Array>>;
+  prune?(retention: RetentionPolicy, scope?: TimeTravelScope): Promise<{
+    pruned: number;
+  }>;
+}
+//#endregion
+//#region src/ops.d.ts
+/** A request that carries no arguments. */
+export type EmptyArgs = Record<string, never>;
+/**
+ * The closed catalog of every Studio op, keyed by op name. Each entry declares
+ * its `req` (dispatch args) and `res` (result) type.
+ */
+export interface StudioRpcMap {
+  'studio.capabilities': {
+    req: EmptyArgs;
+    res: StudioCapabilities;
+  };
+  'app.routes': {
+    req: EmptyArgs;
+    res: RouteRow[];
+  };
+  'app.modules': {
+    req: EmptyArgs;
+    res: ModuleNode[];
+  };
+  'app.entrypoints': {
+    req: EmptyArgs;
+    res: EntrypointRow[];
+  };
+  'app.openapi': {
+    req: EmptyArgs;
+    res: unknown;
+  };
+  'api.authorizeTryIt': {
+    req: TryItRequest;
+    res: {
+      authorized: true;
+    };
+  };
+  'data.listModels': {
+    req: EmptyArgs;
+    res: StudioModelInfo[];
+  };
+  'data.describeModel': {
+    req: {
+      model: string;
+    };
+    res: StudioModelDescriptor;
+  };
+  'data.listRows': {
+    req: ListRowsRequest;
+    res: StudioRowPage;
+  };
+  'data.readRow': {
+    req: {
+      model: string;
+      id: string;
+    };
+    res: Record<string, unknown> | null;
+  };
+  'data.facets': {
+    req: FacetsRequest;
+    res: FacetsResponse;
+  };
+  'data.cascadePreview': {
+    req: CascadePreviewRequest;
+    res: CascadePreviewResponse;
+  };
+  'data.writeRow': {
+    req: WriteRowRequest;
+    res: Record<string, unknown>;
+  };
+  'data.deleteRows': {
+    req: DeleteRowsRequest;
+    res: {
+      deleted: number;
+    };
+  };
+  'data.clearTable': {
+    req: ClearTableRequest;
+    res: {
+      deleted: number;
+    };
+  };
+  'data.generateRows': {
+    req: GenerateRowsRequest;
+    res: GenerateRowsResponse;
+  };
+  'timeTravel.capabilities': {
+    req: {
+      scope?: TimeTravelScope;
+    };
+    res: TimeTravelCapabilities;
+  };
+  'timeTravel.currentMark': {
+    req: {
+      scope?: TimeTravelScope;
+    };
+    res: TimeTravelMark;
+  };
+  'timeTravel.markForTime': {
+    req: {
+      time: number | string;
+      scope?: TimeTravelScope;
+    };
+    res: TimeTravelMark | null;
+  };
+  'timeTravel.listMarks': {
+    req: {
+      scope?: TimeTravelScope;
+      limit?: number;
+      before?: string;
+    };
+    res: TimeTravelMarkPage;
+  };
+  'timeTravel.preview': {
+    req: {
+      target: RestoreTarget;
+      scope?: TimeTravelScope;
+    };
+    res: RestorePreview;
+  };
+  'timeTravel.armRestore': {
+    req: RestoreRequest;
+    res: RestoreOutcome;
+  };
+  'timeTravel.undo': {
+    req: {
+      undoMark: string;
+      scope?: TimeTravelScope;
+      confirmToken: string;
+    };
+    res: RestoreOutcome;
+  };
+  'timeTravel.createSnapshot': {
+    req: {
+      scope?: TimeTravelScope;
+      label?: string;
+    };
+    res: TimeTravelMark;
+  };
+  'timeTravel.prune': {
+    req: {
+      retention: RetentionPolicy;
+      scope?: TimeTravelScope;
+      confirmToken: string;
+    };
+    res: {
+      pruned: number;
+    };
+  };
+  'transfer.export': {
+    req: {
+      model?: string;
+    };
+    res: TransferExportResult;
+  };
+  'transfer.import': {
+    req: TransferImportRequest;
+    res: TransferImportResult;
+  };
+  'auth.users': {
+    req: {
+      q?: string;
+      cursor?: string;
+    };
+    res: {
+      rows: AuthUserRow[];
+      nextCursor?: string;
+    };
+  };
+  'auth.userDetail': {
+    req: {
+      id: string;
+    };
+    res: AuthUserDetail;
+  };
+  'auth.sessions': {
+    req: {
+      userId?: string;
+    };
+    res: AuthSessionRow[];
+  };
+  'auth.revokeSession': {
+    req: {
+      sessionId: string;
+    };
+    res: {
+      ok: true;
+    };
+  };
+  'auth.organizations': {
+    req: EmptyArgs;
+    res: AuthOrgRow[];
+  };
+  'queue.list': {
+    req: EmptyArgs;
+    res: QueueRow[];
+  };
+  'queue.depths': {
+    req: EmptyArgs;
+    res: QueueDepthRow[];
+  };
+  'queue.dlq': {
+    req: {
+      queue: string;
+    };
+    res: DlqEntryRow[];
+  };
+  'queue.send': {
+    req: {
+      queue: string;
+      payload: unknown;
+    };
+    res: {
+      id: string;
+    };
+  };
+  'queue.replay': {
+    req: {
+      queue: string;
+      ids: string[];
+    };
+    res: {
+      replayed: number;
+    };
+  };
+  'schedule.jobs': {
+    req: EmptyArgs;
+    res: ScheduleJobRow[];
+  };
+  'schedule.triggers': {
+    req: EmptyArgs;
+    res: CronTriggerRow[];
+  };
+  'schedule.runNow': {
+    req: {
+      id: string;
+    };
+    res: {
+      ok: true;
+    };
+  };
+  'flags.list': {
+    req: EmptyArgs;
+    res: FlagRow[];
+  };
+  'flags.evaluate': {
+    req: {
+      key: string;
+      context?: Record<string, unknown>;
+    };
+    res: FlagEvaluation;
+  };
+  'logs.tail': {
+    req: {
+      level?: AdminLogEntry['level'];
+      limit?: number;
+    };
+    res: AdminLogEntry[];
+  };
+  'live.subscriptions': {
+    req: EmptyArgs;
+    res: LiveSubscriptionRow[];
+  };
+  'presence.rooms': {
+    req: EmptyArgs;
+    res: PresenceRoomRow[];
+  };
+  'audit.tail': {
+    req: {
+      limit?: number;
+    };
+    res: AdminAuditEntry[];
+  };
+}
+/** The union of every op name. */
+export type StudioOp = keyof StudioRpcMap;
+/** The `req` type for an op. */
+export type StudioOpReq<Op extends StudioOp> = StudioRpcMap[Op]['req'];
+/** The `res` type for an op. */
+export type StudioOpRes<Op extends StudioOp> = StudioRpcMap[Op]['res'];
+/**
+ * Runtime classification of a single op. Single source for dispatch
+ * (read/write), capability negotiation (`feature`), write-gating (`gate`), and
+ * destructive-confirm handling (`destructive`).
+ */
+export interface StudioOpMeta {
+  mode: 'read' | 'write';
+  feature: StudioFeatureKey;
+  gate?: keyof StudioWriteGates;
+  destructive?: true;
+}
+/**
+ * Op meta for every op. `as const satisfies` enforces total key coverage while
+ * preserving literal types (so `destructive` narrows exactly), which drives the
+ * type-level destructive-confirm guard in the tests.
+ */
+export declare const STUDIO_OP_META: {
+  readonly 'studio.capabilities': {
+    readonly mode: 'read';
+    readonly feature: 'app';
+  };
+  readonly 'app.routes': {
+    readonly mode: 'read';
+    readonly feature: 'app';
+  };
+  readonly 'app.modules': {
+    readonly mode: 'read';
+    readonly feature: 'app';
+  };
+  readonly 'app.entrypoints': {
+    readonly mode: 'read';
+    readonly feature: 'app';
+  };
+  readonly 'app.openapi': {
+    readonly mode: 'read';
+    readonly feature: 'openapi';
+  };
+  /** Authorizes a host HTTP request; server gates and audits this operational action. */
+  readonly 'api.authorizeTryIt': {
+    readonly mode: 'write';
+    readonly feature: 'openapi';
+    readonly gate: 'opsEditable';
+  };
+  readonly 'data.listModels': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.describeModel': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.listRows': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.readRow': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.facets': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.cascadePreview': {
+    readonly mode: 'read';
+    readonly feature: 'data';
+  };
+  readonly 'data.writeRow': {
+    readonly mode: 'write';
+    readonly feature: 'data';
+    readonly gate: 'dataEditable';
+  };
+  readonly 'data.deleteRows': {
+    readonly mode: 'write';
+    readonly feature: 'data';
+    readonly gate: 'dataEditable';
+    readonly destructive: true;
+  };
+  readonly 'data.clearTable': {
+    readonly mode: 'write';
+    readonly feature: 'data';
+    readonly gate: 'dataEditable';
+    readonly destructive: true;
+  };
+  readonly 'data.generateRows': {
+    readonly mode: 'write';
+    readonly feature: 'data';
+    readonly gate: 'dataEditable';
+  };
+  readonly 'timeTravel.capabilities': {
+    readonly mode: 'read';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.currentMark': {
+    readonly mode: 'read';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.markForTime': {
+    readonly mode: 'read';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.listMarks': {
+    readonly mode: 'read';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.preview': {
+    readonly mode: 'read';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.armRestore': {
+    readonly mode: 'write';
+    readonly feature: 'timeTravel';
+    readonly gate: 'timeTravelRestore';
+    readonly destructive: true;
+  };
+  readonly 'timeTravel.undo': {
+    readonly mode: 'write';
+    readonly feature: 'timeTravel';
+    readonly gate: 'timeTravelRestore';
+    readonly destructive: true;
+  };
+  readonly 'timeTravel.createSnapshot': {
+    readonly mode: 'write';
+    readonly feature: 'timeTravel';
+  };
+  readonly 'timeTravel.prune': {
+    readonly mode: 'write';
+    readonly feature: 'timeTravel';
+    readonly gate: 'timeTravelRestore';
+    readonly destructive: true;
+  };
+  readonly 'transfer.export': {
+    readonly mode: 'read';
+    readonly feature: 'transfer';
+  };
+  readonly 'transfer.import': {
+    readonly mode: 'write';
+    readonly feature: 'transfer';
+    readonly gate: 'transferImport';
+    readonly destructive: true;
+  };
+  readonly 'auth.users': {
+    readonly mode: 'read';
+    readonly feature: 'auth';
+  };
+  readonly 'auth.userDetail': {
+    readonly mode: 'read';
+    readonly feature: 'auth';
+  };
+  readonly 'auth.sessions': {
+    readonly mode: 'read';
+    readonly feature: 'auth';
+  };
+  readonly 'auth.revokeSession': {
+    readonly mode: 'write';
+    readonly feature: 'auth';
+    readonly gate: 'opsEditable';
+  };
+  readonly 'auth.organizations': {
+    readonly mode: 'read';
+    readonly feature: 'authOrganizations';
+  };
+  readonly 'queue.list': {
+    readonly mode: 'read';
+    readonly feature: 'queue';
+  };
+  readonly 'queue.depths': {
+    readonly mode: 'read';
+    readonly feature: 'queue';
+  };
+  readonly 'queue.dlq': {
+    readonly mode: 'read';
+    readonly feature: 'queue';
+  };
+  readonly 'queue.send': {
+    readonly mode: 'write';
+    readonly feature: 'queue';
+    readonly gate: 'opsEditable';
+  };
+  readonly 'queue.replay': {
+    readonly mode: 'write';
+    readonly feature: 'queue';
+    readonly gate: 'opsEditable';
+  };
+  readonly 'schedule.jobs': {
+    readonly mode: 'read';
+    readonly feature: 'schedule';
+  };
+  readonly 'schedule.triggers': {
+    readonly mode: 'read';
+    readonly feature: 'schedule';
+  };
+  readonly 'schedule.runNow': {
+    readonly mode: 'write';
+    readonly feature: 'schedule';
+    readonly gate: 'opsEditable';
+  };
+  readonly 'flags.list': {
+    readonly mode: 'read';
+    readonly feature: 'flags';
+  };
+  readonly 'flags.evaluate': {
+    readonly mode: 'read';
+    readonly feature: 'flags';
+  };
+  readonly 'logs.tail': {
+    readonly mode: 'read';
+    readonly feature: 'logs';
+  };
+  readonly 'live.subscriptions': {
+    readonly mode: 'read';
+    readonly feature: 'live';
+  };
+  readonly 'presence.rooms': {
+    readonly mode: 'read';
+    readonly feature: 'presence';
+  };
+  readonly 'audit.tail': {
+    readonly mode: 'read';
+    readonly feature: 'audit';
+  };
+};
+/**
+ * Every op name as a runtime const array. Kept as a literal tuple (via
+ * `as const satisfies`) so the exhaustiveness drift guard can compare its
+ * element union against `keyof StudioRpcMap` in both directions.
+ */
+export declare const STUDIO_OPS: readonly ["studio.capabilities", "app.routes", "app.modules", "app.entrypoints", "app.openapi", "api.authorizeTryIt", "data.listModels", "data.describeModel", "data.listRows", "data.readRow", "data.facets", "data.cascadePreview", "data.writeRow", "data.deleteRows", "data.clearTable", "data.generateRows", "timeTravel.capabilities", "timeTravel.currentMark", "timeTravel.markForTime", "timeTravel.listMarks", "timeTravel.preview", "timeTravel.armRestore", "timeTravel.undo", "timeTravel.createSnapshot", "timeTravel.prune", "transfer.export", "transfer.import", "auth.users", "auth.userDetail", "auth.sessions", "auth.revokeSession", "auth.organizations", "queue.list", "queue.depths", "queue.dlq", "queue.send", "queue.replay", "schedule.jobs", "schedule.triggers", "schedule.runNow", "flags.list", "flags.evaluate", "logs.tail", "live.subscriptions", "presence.rooms", "audit.tail"];
+/**
+ * The subset of ops flagged destructive (they carry a `confirmToken`). Derived
+ * from the op union so it can't drift from {@link STUDIO_OP_META}.
+ */
+export type DestructiveStudioOp = { [K in StudioOp]: (typeof STUDIO_OP_META)[K] extends {
+  destructive: true;
+} ? K : never; }[StudioOp];
+//#endregion
+//#region src/capabilities.d.ts
+/**
+ * The closed set of feature keys the UI navigates by. `const` array + derived
+ * union so a feature panel can light up iff the app actually wired that package.
+ */
+export declare const STUDIO_FEATURE_KEYS: readonly ['app', 'openapi', 'data', 'timeTravel', 'transfer', 'auth', 'authOrganizations', 'queue', 'schedule', 'flags', 'logs', 'audit', 'live', 'presence'];
+/** Union of every Studio feature key. */
+export type StudioFeatureKey = (typeof STUDIO_FEATURE_KEYS)[number];
+/**
+ * The derived, wire-facing write gates. Default all `false` -> read-only Studio.
+ * Op dispatch gates a write op against the gate named in its meta.
+ */
+export interface StudioWriteGates {
+  /** Data-row create/update/delete/generate is permitted. */
+  dataEditable: boolean;
+  /** Schema-level edits are permitted. */
+  schemaEditable: boolean;
+  /** Operational actions (queue send/replay, schedule run-now, session revoke). */
+  opsEditable: boolean;
+  /** Reads/writes may run as a supplied identity. */
+  runAsIdentity: boolean;
+  /** Time-travel restore/undo/prune is permitted. */
+  timeTravelRestore: boolean;
+  /** Transfer import (bulk NDJSON ingest) is permitted. */
+  transferImport: boolean;
+}
+/**
+ * The full capability descriptor returned by `studio.capabilities`.
+ * `timeTravel` is `null` when no {@link TimeTravelPort} is bound.
+ */
+export interface StudioCapabilities {
+  /** Registered operations with a usable implementation; write permission is separate. */
+  operations: StudioOp[];
+  features: Record<StudioFeatureKey, boolean>;
+  writes: StudioWriteGates;
+  timeTravel: TimeTravelCapabilities | null;
+}
+//#endregion
+//#region src/http.d.ts
+/**
+ * Transport constants shared by the server module, the UI, and the dev host.
+ * String literals + one integer version marker; zero runtime dependencies.
+ */
+/** Default reserved prefix the admin surface mounts under. */
+export declare const STUDIO_DEFAULT_PATH = "/_vela/admin";
+/** Unauthenticated health probe suffix (`GET {prefix}/health`). */
+export declare const STUDIO_HEALTH_SUFFIX = "/health";
+/** RPC dispatch suffix (`POST {prefix}/rpc/:op`). */
+export declare const STUDIO_RPC_SUFFIX = "/rpc/";
+/** Ephemeral WS sub-token mint suffix (`POST {prefix}/ws-token`). */
+export declare const STUDIO_WS_TOKEN_SUFFIX = "/ws-token";
+/** Snapshot/transfer export suffix (`GET {prefix}/export`). */
+export declare const STUDIO_EXPORT_SUFFIX = "/export";
+/** The header carrying the master bearer token (`Authorization: Bearer <token>`). */
+export declare const STUDIO_TOKEN_HEADER = "authorization";
+/** The wire protocol version. Bumped only on a breaking envelope change. */
+export declare const STUDIO_PROTOCOL_VERSION = 2;
+//#endregion
+//#region src/connection.d.ts
+/** Browser configuration emitted by the loopback host. Never contains the master token. */
+export interface StudioConnection {
+  protocolVersion: 2;
+  routerBasePath: string;
+  adminBasePath: string;
+  apiRequestPath: string;
+  sessionToken: string;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseStudioConnection(value: unknown): StudioConnection;
+//#endregion
+//#region src/responses.d.ts
+/** Every operation must supply a concrete validator for its declared output. */
+export declare const STUDIO_RESPONSE_PARSERS: { readonly [Op in StudioOp]: (value: unknown) => StudioOpRes<Op>; };
+/** The result type comes only from the selected operation and its validator. */
+export declare function parseStudioResponse<Op extends StudioOp>(op: Op, value: unknown): StudioOpRes<Op>;
+/** Validate the envelope, operation identity, and operation-specific payload. */
+export declare function parseStudioRpcResponse<Op extends StudioOp>(op: Op, value: unknown): AdminRpcResponse<StudioOpRes<Op>>;
+//#endregion
+//# sourceMappingURL=index.d.ts.map