@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/src/prompt.ts

@@ -1,5 +1,19 @@
-import type { JSONObject, JSONSchema, PromptRole } from '@llumiverse/common';
-import type { ProjectRef } from './project.js';
+import type { JSONSchema, PromptRole } from '@llumiverse/common';
+import type { z } from 'zod';
+import type {
+    PromptTemplateCreatePayloadSchema,
+    PromptTemplateRefSchema,
+    PromptTemplateSchema,
+    PromptTemplateUpdatePayloadSchema,
+} from './api-schemas/interaction.js';
+import type {
+    PromptTemplateForkPayloadSchema,
+    PromptTemplateInteractionsResponseSchema,
+    PromptTemplateInteractionUsageSchema,
+    PromptTemplateInteractionVersionSchema,
+    RenderPromptPayloadSchema,
+    RenderPromptResponseSchema,
+} from './api-schemas/prompt.js';
 
 export interface ChatPromptSchema {
     role: PromptRole.user | PromptRole.assistant;
@@ -38,18 +52,7 @@ export interface ExecutablePromptSegmentDef extends Omit<PromptSegmentDef, 'temp
     template?: ExecutablePromptTemplate;
 }
 
-export interface PromptTemplateRef {
-    id: string;
-    name: string;
-    description?: string;
-    role: PromptRole;
-    version: number;
-    status: PromptStatus;
-    content_type?: TemplateType;
-    tags?: string[];
-    created_at: Date;
-    updated_at: Date;
-}
+export type PromptTemplateRef = z.infer<typeof PromptTemplateRefSchema>;
 
 export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
     inputSchema?: JSONSchema;
@@ -66,56 +69,26 @@ export interface ExecutablePromptTemplate {
     content_type: TemplateType;
     inputSchema?: JSONSchema;
 }
-export interface PromptTemplate extends ExecutablePromptTemplate {
-    id: string;
-    name: string;
-    status: PromptStatus;
-    version: number;
-    // only to be used by published versions
-    // the id draft version which is the source of this published version (only when published)
-    parent?: string;
-    description?: string;
-    test_data?: JSONObject; // optional test data satisfying the schema
-    script?: string; // cache the template output
-    project: string | ProjectRef; // or projectRef? ObjectIdType;
-    // The name of a field in the input data that is of the specified schema and on each the template will iterate.
-    // If not specified then the schema will define the whole input data
-    tags?: string[];
-    // only for drafts - when it was last published
-    last_published_at?: Date;
-    created_by: string;
-    updated_by: string;
-    created_at: Date;
-    updated_at: Date;
-}
+export type PromptTemplate = z.infer<typeof PromptTemplateSchema>;
 
-export interface PromptTemplateForkPayload {
-    keepTags?: boolean;
-    targetProject?: string;
-}
+export type PromptTemplateForkPayload = z.infer<typeof PromptTemplateForkPayloadSchema>;
 
-export interface PromptTemplateCreatePayload
-    extends Omit<
-        PromptTemplate,
-        'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'status' | 'version'
-    > {}
+export type PromptTemplateCreatePayload = z.infer<typeof PromptTemplateCreatePayloadSchema>;
 
-export interface PromptTemplateUpdatePayload
-    extends Partial<
-        Omit<PromptTemplate, 'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'>
-    > {}
+export type PromptTemplateUpdatePayload = z.infer<typeof PromptTemplateUpdatePayloadSchema>;
 
-export interface PromptTemplateInteractionVersion {
-    version: number;
-}
+export type PromptTemplateInteractionVersion = z.infer<typeof PromptTemplateInteractionVersionSchema>;
 
-export interface PromptTemplateInteractionUsage {
-    id: string;
-    name: string;
-    versions: PromptTemplateInteractionVersion[];
-}
+export type PromptTemplateInteractionUsage = z.infer<typeof PromptTemplateInteractionUsageSchema>;
 
-export interface PromptTemplateInteractionsResponse {
-    prompt: string;
-    interactions: PromptTemplateInteractionUsage[];
-}
+export type PromptTemplateInteractionsResponse = z.infer<typeof PromptTemplateInteractionsResponseSchema>;
+
+export type RenderPromptPayload = z.infer<typeof RenderPromptPayloadSchema>;
+
+/**
+ * What `POST /prompts/:id/render` answers with: the segment identity plus the rendered body.
+ *
+ * Stated here for the first time — the endpoint declared its response inline, so there has never
+ * been a name for it on either side of the wire.
+ */
+export type RenderPromptResponse = z.infer<typeof RenderPromptResponseSchema>;

package/src/query.ts

@@ -1,8 +1,17 @@
+import type { z } from 'zod';
+import type {
+    ComplexCollectionSearchQuerySchema,
+    ComplexSearchQuerySchema,
+    dynamicScalingTypesSchema,
+    EmbeddingSearchConfigSchema,
+    scoreAggregationTypesSchema,
+    VectorSearchQuerySchema,
+} from './api-schemas/content.js';
+import type { InteractionSearchQuerySchema, RunSearchQuerySchema } from './api-schemas/interaction.js';
+import type { PromptSearchQuerySchema } from './api-schemas/prompt.js';
 import type { ExecutionRunStatus } from './interaction.js';
-import type { SearchTypes, SupportedEmbeddingTypes } from './project.js';
-import type { CollectionSearchPayload } from './store/collections.js';
 
-export type EmbeddingSearchConfig = Partial<Record<SupportedEmbeddingTypes, boolean>>;
+export type EmbeddingSearchConfig = z.infer<typeof EmbeddingSearchConfigSchema>;
 
 export interface RunListingQueryOptions {
     project?: string;
@@ -12,29 +21,33 @@ export interface RunListingQueryOptions {
     filters?: RunListingFilters;
 }
 
+/**
+ * The filters `RunsApi.list` puts on the query string of `GET /runs`.
+ *
+ * Kept as hand-written scalars-or-arrays rather than inferred from `RunListQuerySchema`: this is what
+ * a caller writes, and the published component is what goes over the wire after the client serializes
+ * it. A single value and a one-element array are the same request.
+ */
 export interface RunListingFilters {
     interaction?: string | string[];
-    status?: ExecutionRunStatus;
-    model?: string;
-    environment?: string;
-    tag?: string;
+    status?: ExecutionRunStatus | ExecutionRunStatus[];
+    model?: string | string[];
+    environment?: string | string[];
+    tag?: string | string[];
+    /** @deprecated Never applied by `GET /runs`. Sent and ignored; use `POST /runs/search` for a date range. */
     fromDate?: string;
+    /** @deprecated Never applied by `GET /runs`. Sent and ignored; use `POST /runs/search` for a date range. */
     toDate?: string;
     parent?: string | string[];
     is_root?: boolean;
     workflow_run_ids?: string[];
+    workflow_ids?: string[];
 }
 
-export type scoreAggregationTypes = 'rrf' | 'rsf' | 'smart';
-export type dynamicScalingTypes = 'off' | 'on';
+export type scoreAggregationTypes = z.infer<typeof scoreAggregationTypesSchema>;
+export type dynamicScalingTypes = z.infer<typeof dynamicScalingTypesSchema>;
 
-export interface VectorSearchQuery {
-    objectId?: string;
-    values?: number[];
-    text?: string;
-    image?: string;
-    config?: EmbeddingSearchConfig;
-}
+export type VectorSearchQuery = z.infer<typeof VectorSearchQuerySchema>;
 
 export interface SimpleSearchQuery {
     name?: string;
@@ -62,52 +75,11 @@ export interface ObjectTypeSearchQuery extends SimpleSearchQuery {
     chunkable?: boolean;
 }
 
-export interface PromptSearchQuery extends SimpleSearchQuery {
-    role?: string;
-    tags?: string[];
-    matchInteractions?: boolean;
-}
+export type PromptSearchQuery = z.infer<typeof PromptSearchQuerySchema>;
 
-export interface InteractionSearchQuery extends SimpleSearchQuery {
-    prompt?: string;
-    tags?: string[];
-    version?: string;
-    model?: string;
-    environment?: string;
-    is_agent?: boolean;
-    is_tool?: boolean;
-    is_skill?: boolean;
-    is_basic?: boolean;
-    is_sub_agent?: boolean;
-}
+export type InteractionSearchQuery = z.infer<typeof InteractionSearchQuerySchema>;
 
-export interface RunSearchQuery extends SimpleSearchQuery {
-    offset?: number;
-    interaction?: string;
-    environment?: string;
-    model?: string;
-    status?: ExecutionRunStatus;
-    tags?: string[];
-    /**
-     * Tags to exclude. Runs carrying any of these tags are filtered out of the results,
-     * counts, and facet buckets. Combined with `tags` (which requires all of the listed
-     * tags) as an additional `$nin` constraint on the same field.
-     */
-    exclude_tags?: string[];
-    query?: string;
-    default_query_path?: string;
-    parent?: string[];
-    is_root?: boolean;
-    object?: string;
-    start?: string;
-    end?: string;
-    finish_reason?: string;
-    created_by?: string;
-    workflow_run_ids?: string[];
-    workflow_ids?: string[];
-    run_ids?: string[];
-    is_agent?: boolean;
-}
+export type RunSearchQuery = z.infer<typeof RunSearchQuerySchema>;
 
 export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {
     documentId?: string;
@@ -118,37 +90,6 @@ export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {
     status?: string;
 }
 
-/**
- * ComplexSearchQuery is used for full-text search and vector embedding search.
- */
-export interface ComplexSearchQuery extends ObjectSearchQuery {
-    vector?: VectorSearchQuery;
-
-    /**
-     * If present, do a full text search (snake_case version).
-     */
-    full_text?: string;
-
-    weights?: Record<SearchTypes, number>;
+export type ComplexSearchQuery = z.infer<typeof ComplexSearchQuerySchema>;
 
-    /**
-     * dynamicScaling rescales the weights when a particular search type is not present in the results, per object.
-     * e.g. Weights of 5,3,2 will be treated as 0,3,2 if the first search type is not present in the results.
-     * Ignored when scoreAggregation is 'smart'
-     * Default is 'on'
-     */
-    dynamic_scaling?: dynamicScalingTypes; // Move to top level
-
-    /**
-     * rrf: Reciprocal Rank Fusion
-     * rsf: Reciprocal Score Fusion
-     * smart: Our own algorithm (default and recommended)
-     */
-    score_aggregation?: scoreAggregationTypes;
-
-    match?: Record<string, unknown>;
-}
-
-export interface ComplexCollectionSearchQuery extends CollectionSearchPayload {
-    match?: Record<string, unknown>;
-}
+export type ComplexCollectionSearchQuery = z.infer<typeof ComplexCollectionSearchQuerySchema>;

package/src/rate-limiter.ts

@@ -1,7 +1,17 @@
+import type { z } from 'zod';
 /**
  * Rate Limiter Types
  */
 
+import type {
+    QuotaEffectiveTierSchema,
+    QuotaStandingAdmissionClassSchema,
+    QuotaStandingResourceSchema,
+    QuotaStandingResponseSchema,
+    QuotaStandingWindowSchema,
+    QuotaTierResponseSchema,
+} from './api-schemas/quota.js';
+
 export interface RateLimiterCapacity {
     current: number;
     base: number;
@@ -34,79 +44,21 @@ export interface RateLimiterStatus {
 export type RateLimiterStatusResponse = RateLimiterStatus[];
 
 /**
- * A caller's own quota standing (GET /api/v1/quota/standing) — "where am I".
- * API rate limits are genuinely per-tenant; workflow admission and the LLM limiter are
- * global/discovered, so they are reported as posture, not per-tenant numbers.
+ * The quota contract as it crosses the wire, served by `GET /api/v1/quota/standing` and
+ * `GET /api/v1/quota/tier`.
+ *
+ * Derived from the schemas in `./api-schemas/quota.js`, not written alongside them: those schemas
+ * are what OpenAPI publishes and what AJV compiles, so a hand-written twin here could only ever
+ * drift from the contract actually being enforced. The documentation lives with the schemas too —
+ * zod reads `.meta()`, not TSDoc, so a comment here would describe the type while the published
+ * description came from somewhere else.
+ *
+ * `import type` erases at compile time, so nothing here pulls zod into a browser or SDK bundle;
+ * runtime consumers reach the schemas through the `@vertesia/common/api-schemas` entry point.
  */
-export interface QuotaStandingWindow {
-    /** Effective limit for this window (after effective account tier + per-tenant override). */
-    limit: number;
-    /** Requests used in the current window. */
-    used: number;
-    /** Requests remaining (max(0, limit - used)). */
-    remaining: number;
-    window_ms: number;
-}
-
-export interface QuotaStandingResource {
-    resource: string;
-    name: string;
-    burst: QuotaStandingWindow;
-    quota: QuotaStandingWindow;
-}
-
-export interface QuotaStandingAdmissionClass {
-    /** Workflow class (e.g. ExecuteConversationWorkflow). */
-    class: string;
-    /** This tenant's currently active (leased) slots for the class. */
-    tenant_active: number;
-}
-
-/**
- * Effective quota tier name after account-level overrides and account-type derivation.
- * Code-defined tier names are currently `QuotaTier`, but this remains a string because deployments
- * can introduce quota tiers through configuration.
- */
-export type QuotaEffectiveTier = string;
-
-export interface QuotaStandingResponse {
-    tenant_id: string;
-    /**
-     * False when the limiter store (Redis) was unavailable, so `api`/`admission` are empty because
-     * standing could not be read — NOT because there are no limits. Limiters fail open in this case.
-     */
-    available: boolean;
-    /** Deployment base tier (env QUOTA_BASE_TIER); `default` = the static limits stand. */
-    base_tier: string;
-    /**
-     * Tier used to compute the API limits below: explicit account `quota_tier`, else account_type
-     * derived tier, else `base_tier` when the account tier could not be resolved.
-     */
-    effective_tier: QuotaEffectiveTier;
-    /** Per-resource API rate-limit standing (effective limits + current usage). */
-    api: QuotaStandingResource[];
-    /**
-     * Workflow admission: per-tenant active slots per probed class. The budget itself is global and
-     * discovered (AIMD), not a per-tenant number — this is occupancy, not a limit.
-     */
-    admission: {
-        classes: QuotaStandingAdmissionClass[];
-        note: string;
-    };
-    /** The LLM interaction limiter is shared per environment/model, not per tenant. */
-    llm: {
-        note: string;
-    };
-}
-
-/**
- * Lightweight per-account quota tier for the calling account — served by `GET /api/v1/quota/tier`.
- * A cheap, cacheable read that lets another service (e.g. zeno-server's API rate limiter) resolve
- * the caller's tier through studio-server instead of reaching into the account store directly.
- * `tier` is the SAME value {@link QuotaStandingResponse.effective_tier} reports: the account's
- * explicit `quota_tier`, else its account_type-derived tier, else the deployment base tier when the
- * account tier cannot be resolved.
- */
-export interface QuotaTierResponse {
-    tier: QuotaEffectiveTier;
-}
+export type QuotaStandingWindow = z.infer<typeof QuotaStandingWindowSchema>;
+export type QuotaStandingResource = z.infer<typeof QuotaStandingResourceSchema>;
+export type QuotaStandingAdmissionClass = z.infer<typeof QuotaStandingAdmissionClassSchema>;
+export type QuotaEffectiveTier = z.infer<typeof QuotaEffectiveTierSchema>;
+export type QuotaStandingResponse = z.infer<typeof QuotaStandingResponseSchema>;
+export type QuotaTierResponse = z.infer<typeof QuotaTierResponseSchema>;

package/src/refs.ts

@@ -1,3 +1,6 @@
+import type { z } from 'zod';
+import type { ResourceRefSchema } from './api-schemas/agent-runs.js';
+
 export enum ResolvableRefType {
     project = 'Project',
     projects = 'Projects',
@@ -17,14 +20,4 @@ export interface RefResolutionRequest {
     refs: ResolvableRef[];
 }
 
-export interface ResourceRef {
-    id: string;
-    name: string;
-    type: string;
-    email?: string;
-    description?: string;
-    version?: number;
-    status?: string;
-    tags?: string[];
-    endpoint?: string;
-}
+export type ResourceRef = z.infer<typeof ResourceRefSchema>;

package/src/roles/types.ts

@@ -1,23 +1,35 @@
-import type { Permission } from '../access-control.js';
+import type { z } from 'zod';
+import type {
+    AbacScopeSchema,
+    RoleDefinitionSchema,
+    RoleDomainSchema,
+    SystemRoleDefinitionSchema,
+} from '../api-schemas/access-control.js';
 
 /**
  * Pure types & constants for the role system. This file is intentionally
  * `class`-free — it is what stays in `@vertesia/common` when the class
  * hierarchy (`classes.ts`) eventually moves to `studio-utils`. Client SDKs
  * depend ONLY on these types, never on the registry runtime.
+ *
+ * The wire shapes below are inferred from `../api-schemas/access-control.js`, which is what OpenAPI
+ * publishes and AJV compiles. `AbacScopes` and `RoleDomains` are the runtime lists those schemas
+ * enumerate; they live in `../access-control-values.js` so the schemas can read them without
+ * importing this module back.
  */
 
+export { AbacScopes, RoleDomains } from '../access-control-values.js';
+
 /**
  * Kind of object a ResourceSet's `resource_props` matches at query time. Used
  * in `AceConditions.scope` (validated at runtime against this list) and as
  * the prefix in JWT `content_security` keys (e.g. `collection:read`).
  *
  * Each scope is owned by exactly one partition. When adding a new partition
- * (e.g. tasks), extend this list with the new scope(s) AND extend `RoleDomain`
- * with the new domain.
+ * (e.g. tasks), extend `AbacScopes` with the new scope(s) AND extend
+ * `RoleDomains` with the new domain.
  */
-export const AbacScopes = ['document', 'collection', 'task'] as const;
-export type AbacScope = (typeof AbacScopes)[number];
+export type AbacScope = z.infer<typeof AbacScopeSchema>;
 
 /**
  * Logical grouping of roles by the service area that owns them. One domain may
@@ -26,7 +38,7 @@ export type AbacScope = (typeof AbacScopes)[number];
  * domain owns the built-in foundational roles (currently exposed as
  * `SystemRoles`) — registered first so domain partitions cannot shadow them.
  */
-export type RoleDomain = 'system' | 'content' | 'tasks';
+export type RoleDomain = z.infer<typeof RoleDomainSchema>;
 
 /**
  * Wire shape of a role returned by the IAM `/roles` endpoint.
@@ -35,24 +47,12 @@ export type RoleDomain = 'system' | 'content' | 'tasks';
  * (system, content, future tasks/etc.) and each partition has its own
  * vocabulary. For the tightly-typed system-only view (with `permissions:
  * Permission[]`) use `SystemRoleDefinition` and the `/roles/system` endpoint.
- *
- * NOTE: this interface is intentionally non-generic. The OpenAPI generator
- * doesn't handle TypeScript generics cleanly in array response types and
- * produces a degenerate `RoleDefinitionArray` schema. Keeping the wire shapes
- * concrete avoids that. `SystemRoleDefinition` extends and narrows
- * `permissions` to `Permission[]`.
  */
-export interface RoleDefinition {
-    name: string;
-    permissions: string[];
-    domain: RoleDomain;
-}
+export type RoleDefinition = z.infer<typeof RoleDefinitionSchema>;
 
 /**
  * Tightly-typed view of a system-domain role: permissions are central
  * `Permission` enum values. Returned by `client.iam.roles.listSystem()` and
  * by the server's `/roles/system` endpoint.
  */
-export interface SystemRoleDefinition extends RoleDefinition {
-    permissions: Permission[];
-}
+export type SystemRoleDefinition = z.infer<typeof SystemRoleDefinitionSchema>;

package/src/runs.ts

@@ -1,35 +1,28 @@
-import type { FacetResult } from './facets.js';
-import type { NamedInteractionExecutionPayload } from './interaction.js';
+import type { z } from 'zod';
+import type {
+    ExecutionRunDocRefSchema,
+    RunClonePayloadSchema,
+    RunCreatePayloadSchema,
+    RunSearchMetaResponseSchema,
+} from './api-schemas/interaction.js';
 
 /**
  * The run ref is used to identify a run document in the storage
  */
-export interface ExecutionRunDocRef {
-    id: string;
-    account: string;
-    project: string;
-}
+export type ExecutionRunDocRef = z.infer<typeof ExecutionRunDocRefSchema>;
 
 /**
  * Interaction execution payload for creating a new run
  * It uses interaction field (from NamedInteractionExecutionPayload) to pass the interaction ID to run
  */
-export interface RunCreatePayload extends NamedInteractionExecutionPayload {}
+export type RunCreatePayload = z.infer<typeof RunCreatePayloadSchema>;
 
 /**
  * Payload for cloning an existing ExecutionRun.
  * Creates a new run document with the same interaction/config but fresh status.
  * Used by fork flows to create a new ExecutionRun for the forked workflow.
  */
-export interface RunClonePayload {
-    /** The _id of the source ExecutionRun to clone */
-    source_run_id: string;
-    /** Temporal workflow reference for the new run */
-    workflow: {
-        run_id: string;
-        workflow_id: string;
-    };
-}
+export type RunClonePayload = z.infer<typeof RunClonePayloadSchema>;
 
 /**
  * To be used as a value for a numeric or date filters
@@ -41,10 +34,4 @@ export interface RangeValue {
     lte?: number | string;
 }
 
-export interface RunSearchMetaResponse {
-    count: {
-        lower_bound?: number;
-        total?: number;
-    };
-    facet: Record<string, FacetResult>;
-}
+export type RunSearchMetaResponse = z.infer<typeof RunSearchMetaResponseSchema>;