Isis — Technical Specifications

Technical reference for the Isis generative-AI factory domain: data models, database schema, enumerations, the job-envelope contract, API surface, event contracts, the library inventory, configuration, and operational contracts.

Every statement below is traceable to source in libs/isis/* or apps/isis/*. The canonical Prisma schema is libs/isis/database/prisma/schema.prisma.

This document is the engineering reference for the Isis domain. Where the architecture and features documents explain what Isis does and why, this document records the precise contracts that all services in the domain must agree on: the exact shape of every database table, every enumeration value, every API endpoint, every event payload schema, and every configuration variable. When you are building a new Isis service, adding an endpoint, or integrating with Isis from another domain, start here.

Domain Layout#

Isis is split across two top-level trees in the monorepo. There is no services/isis/ tree — all services live under apps/.

Applications (apps/isis/)#

Each REST service reads its listen port from process.env.PORT, defaulting to 3000 / 3001 / 3002 respectively (apps/isis/*/src/index.ts).

Database Configuration#

All Isis services share a single PostgreSQL database. The Prisma schema is the canonical source of truth for the data model; every table, column, and index described in this document is defined there.

The generator and datasource blocks declare provider = "postgresql" with the URL sourced from env("ISIS_DATABASE_URL").

Data Models#

The schema defines 24 models. They group into five clusters: the core generation pipeline (jobs, workflows, outputs, provenance, models), the canonical model-and-governance contracts, retention/worker/audit infrastructure, the canonical platform audit event, and the pipeline-state persistence layer. Each cluster is described below.

Core Pipeline Models#

These models form the heart of the domain — they track every job, workflow, output, and model that flows through Isis.

GenerationJob (generation_jobs)#

The core work unit. Each record represents one AI generation request with full lifecycle tracking. id is a cuid() stored as VarChar(25).

Relations: model (ModelRegistry?), workflow (Workflow?), outputs (GeneratedOutput[]), provenance (Provenance?). Indexes: status, type, priority, userId, organizationId, projectId, workerId, createdAt, deletedAt, plus composites [status, type] and [userId, status].

Workflow (workflows)#

Reusable workflow definitions for ComfyUI, Blender, Unreal, Godot, or custom pipelines. Supports semver versioning, community statistics, and visibility controls.

Unique: [ownerId, name]. Relations: versions, jobs, generatedOutputs, stars.

WorkflowVersion (workflow_versions)#

Immutable snapshot of a workflow definition at a specific version point. Each version locks the complete definition, parameters, and requirements so prior workflow versions are always exactly reproducible.

Unique: [workflowId, version].

WorkflowStar (workflow_stars)#

User star/favorite on a workflow. Fields: id, workflowId, userId, createdAt. Unique: [workflowId, userId].

WorkflowTemplate (workflow_templates)#

Curated starter templates for quick-start workflow creation. Fields: id, name, description, engine (WorkflowEngine), category (WorkflowCategory), definition (Json), parameters (Json default []), previewImage, tags (String[]), featured (Boolean default false), usageCount (Int default 0), createdAt, updatedAt.

GeneratedOutput (generated_outputs)#

Every file produced by a generation job; the node type of the lineage graph. The storageBucket + storageKey pair is unique (enforced by the @@unique([storageBucket, storageKey]) constraint) to prevent duplicate storage entries for the same physical file.

Relations: job, workflow, provenance, parentEdges (LineageEdge[] via LineageTarget), childEdges (LineageEdge[] via LineageSource).

LineageEdge (lineage_edges)#

Directed edge in the output lineage graph. An edge connects a source output (the origin) to a target output (the derivative). Both endpoint relations cascade- delete so edges are removed automatically when either output is deleted.

Unique: [sourceId, targetId].

Provenance (provenance)#

Full generation metadata for an output, enabling reproducibility. The outputId relation is 1:1 with GeneratedOutput, and jobId is unique (one provenance record per job execution).

ModelRegistry (model_registry)#

Registry of available AI model checkpoints, LoRAs, and other artifacts. The [name, version] pair is unique, ensuring no two registry entries refer to the same model version.

Unique: [name, version]. Relations: jobs.

Canonical Model and Governance Models#

A second model-management cluster carries richer, governance-grade contracts for model cards, version lineage, provenance bundles, and review packages. All five use uuid() primary keys and a unique slug / graphId. These models are separate from ModelRegistry because they capture compliance and review metadata that goes beyond simple operational tracking.

Retention, Worker, and Audit Models#

RetentionPolicy (retention_policies)#

Storage-lifecycle configuration controlling how outputs transition between tiers. A policy with organizationId = null is the global default; org-scoped policies override it for that organization's outputs.

GpuWorker (gpu_workers)#

Registration record for each GPU worker instance. Workers self-register at startup and update lastHeartbeat periodically; the generation API uses supportedTypes and supportedEngines to route jobs to capable workers.

AuditLog (audit_log)#

Per-entity change tracking for operational audit purposes. Fields: id, action, entityType, entityId, previousState (Json?), newState (Json?), changes (Json?), userId, ipAddress, userAgent, requestId, metadata, createdAt.

CanonicalAuditEvent (canonical_audit_events)#

The canonical platform audit event (per ADR-0023). This model is append-only — no update or delete. eventId is the UUID primary key. It carries the full canonical envelope defined in @oshun/contracts (CanonicalPlatformAuditEventSchema):

• Actor fields: actorType, actorId, actorRole, actorLabel, actorSystem
• Target fields: resourceType, resourceId, resourceName, domain, parent resource, tenantId
• Required canonical fields: reason, traceId, spanId, requestId, sessionId
• Evidence fields: ipAddress, userAgent, geo
• Payload fields: previousState, newState, metadata
• Compliance fields: policyId, retentionTag, schemaVersion

Pipeline-State Persistence Models#

Six models persist PipelineOrchestrator runs so they survive BFF restarts. They back the PostgresPipelineRepository in libs/isis/operation-orchestrator/src/persistence.

IDs are uuid-typed so the orchestrator's branded PipelineId / ChainId round-trip without conversion. Status fields are stored as String (not Prisma enums) because the orchestrator's ChainStatus and CheckpointDecisionStatus are TypeScript const-objects that may gain values in patch releases without requiring a database migration.

Cascade deletes mirror runtime semantics: deleting a pipeline drops its chains; deleting a chain drops its phases; deleting a phase drops its artifacts and checkpoints.

Enumerations#

The schema defines 14 enums. All enum values listed here are exact — they must match in code, API payloads, and any external integrations.

JobStatus#

The six states a GenerationJob passes through:

PENDING, QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED

(The generation-api request/response layer in job.schema.ts uses the same six values in lowercase: pending, queued, running, completed, failed, cancelled.)

JobPriority#

LOW, NORMAL, HIGH, URGENT

GenerationType (15 values)#

The complete set of generation modes supported by the domain:

TEXT_TO_IMAGE, IMAGE_TO_IMAGE, TEXT_TO_VIDEO, IMAGE_TO_VIDEO, TEXT_TO_3D, IMAGE_TO_3D, TEXT_TO_AUDIO, VOICE_SYNTHESIS, MUSIC_GENERATION, UPSCALING, INPAINTING, BLENDER_RENDER, GAUSSIAN_SPLATTING, MESH_PROCESSING, TEXTURE_UPSCALE

WorkflowEngine#

COMFYUI, BLENDER, UNREAL, GODOT, CUSTOM

WorkflowStatus#

DRAFT, PUBLISHED, DEPRECATED, ARCHIVED

WorkflowVisibility#

PRIVATE, TEAM, ORGANIZATION, PUBLIC

WorkflowCategory (12 values)#

IMAGE_GENERATION, VIDEO_GENERATION, AUDIO_GENERATION, GENERATION_3D, UPSCALING, STYLE_TRANSFER, INPAINTING, COMPOSITING, RENDERING, SIMULATION, UTILITY, OTHER

OutputFileType (11 values)#

IMAGE, VIDEO, AUDIO, MODEL_3D, POINT_CLOUD, ANIMATION, TEXTURE, MATERIAL, DOCUMENT, DATA, OTHER

OutputStatus#

PENDING, AVAILABLE, ARCHIVED, EXPIRED, DELETED

StorageTier#

The four storage tiers from hottest (most accessible, most expensive) to coldest (least accessible, cheapest):

HOT, WARM, COLD, GLACIER

HashAlgorithm#

SHA256, SHA512, MD5, BLAKE3

LineageEdgeType#

DERIVED_FROM, COMPOSED_OF, REFINED_FROM, UPSCALED_FROM, CONVERTED_FROM

ModelType#

CHECKPOINT, LORA, CONTROLNET, VAE, EMBEDDING, UPSCALER, CUSTOM

ModelFormat#

SAFETENSORS, PYTORCH, ONNX, GGUF, BLEND, GLTF, FBX, OTHER

Job Envelope Contract#

The job envelope is the canonical queue message defined by @isis/job-envelope (libs/isis/job-envelope/src/job-envelope.ts). It is not a flat copy of the GenerationJob row — it is a compact, strict Zod-validated message designed for reliable serialization over a Redis queue. Every producer (API, SDK, CLI) and every consumer (GPU workers, executors) uses this exact shape.

export const ISIS_JOB_ENVELOPE_VERSION = '1.0.0';

interface IsisJobEnvelope {
  jobId: string; // UUID
  type: IsisGenerationType;
  input: Record<string, unknown>;
  priority: IsisJobPriority; // 'low' | 'normal' | 'high' | 'urgent'
  metadata: IsisJobEnvelopeMetadata; // { userId?, projectId?, correlationId?, ...catchall }
  idempotencyKey: string; // non-empty, max 128 chars
}

IsisJobEnvelopeSchema is .strict() — unknown top-level keys are rejected. IsisJobEnvelopeMetadataSchema is a .catchall(z.unknown()) object: userId, projectId, and correlationId are typed optionals; any other key is allowed.

Helper functions exported alongside the schema: createIsisJobEnvelope(), parseIsisJobEnvelope(), safeParseIsisJobEnvelope(), isIsisJobEnvelope(). createIsisJobEnvelope() defaults priority to 'normal', metadata to {}, and idempotencyKey to the jobId when not supplied.

Generation-type identifiers (ISIS_GENERATION_TYPES)#

The envelope's type field uses kebab-case identifiers, which differ from the database GenerationType enum's SCREAMING_SNAKE_CASE. There are 18 total: the 15 standard modes plus three scene-from-image composer dispatch types.

text-to-image, image-to-image, text-to-video, image-to-video, text-to-3d, image-to-3d, text-to-audio, voice-synthesis, music-generation, upscaling, inpainting, blender-render, gaussian-splatting, mesh-processing, texture-upscale, scene-from-image-environment, scene-from-image-mesh, scene-from-image-bake.

ISIS_GENERATION_TYPE_ALIASES maps legacy SCREAMING_SNAKE/snake_case spellings (e.g. BLENDER_RENDER, blender_render) onto the kebab-case canonical values; normalizeIsisGenerationType() resolves any input form. This means callers do not need to know which spelling the system expects — they can submit in any historically-used form and it will be normalized.

Composer dispatch payloads (@isis/job-envelope/payloads)#

payloads.ts defines typed input/output payloads for the three scene-from-image dispatch types. These are the shapes that the @isis/scene-from-image-composer uses when dispatching work to the GPU worker pool:

• EnvironmentDispatchInput / EnvironmentDispatchOutput
• MeshDispatchInput / MeshDispatchOutput
• BakeDispatchInput / BakeDispatchOutput
• ScenecomposerDispatchPayload (union of the three above)
• SCENECOMPOSER_DISPATCH_TYPES constant

Binary buffers are wrapped via encodeDispatchBuffer() / decodeDispatchBuffer() (DispatchBuffer).

Generation-Type Manifest#

ISIS_GENERATION_TYPE_MANIFEST in job-envelope.ts is the single source of truth for what each generation type requires and produces. It is a Record<IsisGenerationType, IsisGenerationTypeManifestEntry> covering all 18 generation types. Every entry declares:

IsisOutputPackageType is image | video | audio | 3d | text. The helper isIsisOutputPackageCompatibleWithGenerationType() validates a produced package against a type's rules. For example, text-to-3d and image-to-3d accept either a 3d package or a multi-image reconstruction package — the manifest entry encodes both valid shapes.

Control-Input Vocabulary#

@isis/job-envelope defines the canonical vocabulary for image-conditioning controls (ControlNet, IP-Adapter, InstantID). This vocabulary is shared by all producers and consumers so that parameter names never drift between the API, the GPU worker, and ComfyUI workflow nodes.

ISIS_DEFAULT_CONTROL_BLEND_PRECEDENCE is instantid → ipadapter → controlnet. When multiple control domains are active simultaneously, this precedence order determines which one wins at each pixel.

Each vocabulary has an alias map and a normalize* function, plus legacy- workflow-mode maps (ISIS_CONTROLNET_LEGACY_WORKFLOW_MODE_MAP, etc.) that translate major modes into the string identifiers older ComfyUI workflows expect.

API Surface#

All three REST services are Hono apps. /api/* routes are rate-limited (generation-api: 100 requests per 60 seconds), require authentication, and pass through a structured security-log middleware. /health and /ready bypass authentication.

Generation API (apps/isis/generation-api, port 3000)#

Mounts: /api/v1/jobs, /api/v1/queue/stats, /api/v1/models, /api/v1/workflows, /api/v1/webhook-subscriptions, and /webhooks (provider callbacks). Route modules are jobs.ts, models.ts, workflows.ts, webhook-subscriptions.ts, and provider-callbacks.ts.

Jobs (/api/v1/jobs)#

The jobs endpoints cover the full lifecycle from submission through output retrieval. Admin endpoints (prefixed /admin/) provide operational tools for backfilling missing data and managing the queue.

Models (/api/v1/models)#

The models endpoints manage the model registry, including pre-signed upload URLs for large model files that bypass the API server.

Workflow execution (/api/v1/workflows)#

The workflow-run path validates a typed contract per workflow recipe (see Asset-Pack Workflow Recipes).

Webhook subscriptions (/api/v1/webhook-subscriptions)#

Manages callback subscriptions for job lifecycle events. Provides full CRUD plus lifecycle operations:

GET /event-types, GET /event-schemas, GET /event-schemas/:eventType, POST /callback-security/sign, POST /callback-security/verify, POST /, GET /, GET /:subscriptionId, PATCH /:subscriptionId, DELETE /:subscriptionId, POST /:subscriptionId/activate, POST /:subscriptionId/pause, POST /:subscriptionId/rotate-secret.

Provider callbacks (/webhooks)#

POST /webhooks/runpod — signature-validated callback endpoint for RunPod provider results. Runs outside the authenticated /api/* namespace so RunPod can call it directly.

Health endpoints#

GET /health — liveness probe; always returns 200 if the process is running. GET /ready — readiness probe; runs job-service, model-service, and ComfyUI-service health checks in parallel and returns 200/503 with a per-dependency breakdown (jobs DB, models DB, queue, storage, provider).

Workflow Registry (apps/isis/workflow-registry, port 3001)#

Mounts /api/v1/workflows, /api/v1/templates, /api/v1/staging-recipes, plus /health and /ready. The workflow service supports two storage backends — postgres (production) and in-memory (explicit test/dev override).

Output Registry (apps/isis/output-registry, port 3002)#

Mounts /api/v1/outputs, /api/v1/policies, /api/v1/provenance, plus /health and /ready.

Asset-Pack Workflow Recipes#

apps/isis/generation-api/src/schemas/ defines 32 typed asset-pack workflow recipes. Each recipe has its own request schema and a validate<Recipe>WorkflowRunContract function consumed by the /api/v1/workflows/:workflowId/run route. Each recipe additionally carries a budget-utility module, a quality-gate-utility module, and a regression golden-dataset module under generation-api/src/routes/.

The 32 recipes are:

animatic-shot-set, architecture-kitbash-pack, audio-sfx-pack, character-concept-art, character-costume-variant-pack, character-expression-sheet, character-prop-interaction-sheet, character-turnaround-sheet, cinematic-shot-sequence, creature-concept-art, decal-pack, environment-concept-art, environment-matte-painting, environment-tileset-pack, foliage-pack, hud-element-pack, interior-scene-pack, marketing-key-art-pack, material-pbr-pack, music-cue-pack, npc-crowd-variation-pack, prop-pack-general, sky-atmosphere-pack, social-cutdown-pack, storyboard-frame-set, terrain-heightmap-pack, ui-icon-pack, vehicle-exterior-pack, vehicle-interior-pack, vfx-element-pack, voice-line-pack, weapon-pack.

Job Lifecycle#

Database Job Status (JobStatus)#

The following state machine governs GenerationJob.status. A job begins at PENDING, advances through QUEUED and RUNNING, and ends at one of three terminal states. FAILED jobs may be retried while retryCount < maxRetries; cancellation is possible from any non-terminal state.

PENDING ──► QUEUED ──► RUNNING ──► COMPLETED
   │           │          │
   │           │          └──────► FAILED ──► (retry → QUEUED while retryCount < maxRetries)
   │           │
   └───────────┴─────────────────► CANCELLED

The progress field advances from 0 to 100 during the RUNNING phase. Long- running jobs (3D generation, Blender renders) use this to display meaningful progress indicators in the UI and CLI.

GPU-Worker Internal Job Status#

The gpu-worker app tracks a finer-grained per-job status that is not stored in the database — it is internal to the worker process (gpu-worker/src/types.ts): pending, downloading, processing, uploading, completed, cancelled, failed. The worker process itself has a separate WorkerStatus: idle, initializing, processing, shutting-down, error. Worker job priority adds a background tier beyond the database JobPriority enum.

GPU-Worker Executors#

apps/isis/gpu-worker/src/executors/ registers four concrete executors over a BaseExecutor / registerExecutor / createExecutor registry. All other generation types route through the generic executor that calls external provider APIs.

The WorkerTypeSchema enum recognises seven worker types: texture-upscale, mesh-processing, blender-render, gaussian-splatting, video-generation, neural-bake, general.

Event Contracts#

Isis publishes events through @isis/event-publisher (libs/isis/event-publisher), which wraps @oshun/event-bus (Redis Streams). Event types and payload schemas are defined canonically in @oshun/contracts (libs/contracts/src/events/isis.ts) as IsisEventTypes. This separation means that changes to the Isis internal implementation never affect the event contract that other domains depend on — only changes to @oshun/contracts do.

Events Published#

The following table lists every event type, the @isis/event-publisher method that emits it, and the payload schema in @oshun/contracts:

The @oshun/contracts event layer uses its own coarse GenerationTypeSchema (image, video, audio, model_3d, texture, animation, avatar, world) and GenerationStatusSchema (queued, processing, completed, failed, cancelled) for cross-domain payloads — these are distinct from the Isis database GenerationType enum and are intentionally simpler.

Representative Payload Shapes#

The following examples show the most commonly consumed event payloads. Full schemas are in @oshun/contracts.

• isis.job.queued — jobId, projectId, userId, type, workflow, priority (0–10 int), estimatedDurationMs?, queuePosition?, parameters.
• isis.job.completed — jobId, projectId, userId, type, workflow, durationMs, outputs[] (assetId, type, url, filename, sizeBytes, metadata?), optional metrics (gpuTimeMs, memoryPeakMb, modelLoadTimeMs).
• isis.job.failed — jobId, projectId, userId, type, workflow, error (code, message, details?, retryable), attemptCount, totalDurationMs.
• isis.asset.generated — assetId, projectId, userId, jobId, type, name, filename, url, sizeBytes, mimeType, provenance (model, modelVersion?, workflow, prompt?, seed?, parameters?), optional thumbnails.

Event Publisher Configuration#

Event publishing is non-fatal: a publish failure is logged and swallowed so it never breaks the main generation flow. The publisher is configurable via IsisEventPublisherConfig (redisUrl, enabled, keyPrefix) and can be disabled entirely with ISIS_EVENTS_ENABLED=false. The default keyPrefix is oshun:events.

The gpu-worker additionally emits internal (in-process, non-bus) lifecycle events on its own event emitter: worker:started, worker:stopped, worker:health, job:started, job:progress, job:completed, job:failed. These are not published to Redis Streams and are not visible outside the worker process.

Library Inventory#

libs/isis/ contains 55 library directories: 54 @isis/* TypeScript packages plus one Python package (comfyui-nodes, packaged with pyproject.toml, no package.json). Every directory has real src/ source.

Core platform#

AI providers and LLM#

ComfyUI#

Image, video, and audio#

3D generation#

Models, quality, and operations#

(@oshun/web host: apps/isis/web, package @isis/web — front-end app.)

Validation Rules#

All write paths use Zod (@hono/zod-validator on the REST routes). The following table records the constraints that are most likely to affect callers integrating with the API:

JobParametersSchema is .passthrough() and accepts both camelCase and snake_case aliases (controlnet/controlNet, control_blend/controlBlend, etc.) so callers and ComfyUI graphs interoperate. JobConsistencyStrengthSchema is low\|medium\|high\|strict.

Configuration and Environment Variables#

All Isis services are configured purely through environment variables. No configuration files are read at runtime. The variables below are organized by the service or subsystem that reads them.

Database and infrastructure#

ISIS_DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/isis
REDIS_URL=redis://localhost:6379

Generation API#

PORT=3000                         # Listen port (default 3000)
BASE_URL=http://localhost:3000    # Public base URL
JWT_SECRET=<secret>               # Required in production — service refuses to boot without it
JWT_ISSUER=oshun                  # JWT issuer (default 'oshun')
JWT_AUDIENCE=oshun-generation-api # JWT audience
CORS_ORIGINS=                     # Comma-separated allowed origins
NODE_ENV=development|production

Queue producer#

ISIS_QUEUE_NAME=...                       # Queue name
ISIS_QUEUE_PREFIX=...                     # BullMQ key prefix
ISIS_QUEUE_JOB_NAME=...                   # Job name on the queue
ISIS_QUEUE_REDIS_URL=...                  # Queue Redis URL (defaults to REDIS_URL)
ISIS_QUEUE_DEFAULT_ATTEMPTS=...           # Default retry attempts
ISIS_QUEUE_DEFAULT_BACKOFF_MS=...         # Default backoff
ISIS_QUEUE_PRODUCER_ENABLED=true          # Master dispatch switch
ISIS_QUEUE_PRODUCER_CANARY_ENABLED=false  # Canary-mode switch
ISIS_QUEUE_PRODUCER_CANARY_PERCENTAGE=0   # Percent of traffic to the new queue
ISIS_QUEUE_PRODUCER_CANARY_PROJECT_IDS=   # Comma-separated project allowlist

When ISIS_QUEUE_PRODUCER_ENABLED is true the app calls validateQueueProducerEnvRequirements() at boot and fails fast if queue connection config is missing.

Event publisher#

ISIS_EVENTS_ENABLED=true   # Set 'false' to disable cross-domain event publishing

GPU worker#

GPU_DEVICES=0,1                       # Comma-separated CUDA device indices
QUEUE_NAME=...                        # Redis queue to poll
WORKER_ID=...                         # Unique worker identifier (registered in GpuWorker)
WORKER_TYPE=general                   # Worker-type enum value
WORK_DIR=/tmp/isis-work               # Temporary working directory
MODEL_CACHE_DIR=/models/cache         # Model-checkpoint cache
LOG_LEVEL=info
ISIS_ALLOW_SIMULATED_EXECUTION=...    # Test/dev gate; real execution required in production
BLENDER_BIN=...                       # Blender executable path
GAUSSIAN_SPLATTING_PATH=...           # Operator-supplied 3DGS train.py (@isis/gaussian-splatting);
                                      # Isis bundles no trainer, see tracker T.01.10
MESH_PIPELINE_PYTHON_BIN / MESH_PIPELINE_SCRIPT_PATH
TEXTURE_UPSCALE_PYTHON_BIN / TEXTURE_UPSCALE_SCRIPT_PATH
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION / AWS_DEFAULT_REGION

The GPU worker reads S3-style credentials from the standard AWS_* environment variables for output upload.

AI provider credentials#

Provider API keys are read by @isis/ai-providers adapters; configure the keys for whichever providers are enabled (Anthropic, OpenAI, Google AI, xAI, ElevenLabs, Stability AI, Black Forest Labs, Civitai, RunPod, etc.).

Operational Tooling#

scripts/isis/ contains the operational toolchain. Canary and release scripts referenced by the architecture doc all exist here:

RunPod-specific tooling also lives in scripts/isis/:

• apply_runpod_warm_cold_policy.mjs — apply warm/cold tier policies to RunPod endpoints
• detect_runpod_endpoint_drift.py — detect configuration drift between registered and live RunPod endpoints
• evaluate-runpod-release-gate.mjs — evaluate whether a RunPod endpoint change meets release criteria
• execute_runpod_endpoint_canary_strategy.sh — execute the canary rollout strategy for RunPod endpoint changes

check-generation-type-enum-drift.mjs detects mismatches between the ISIS_GENERATION_TYPES constant in @isis/job-envelope and the Prisma GenerationType enum — this must be run whenever a new generation type is added.

SLO definitions are in docs/domains/isis/remediation/ISIS_SLO_DEFINITIONS.json and .../remediation-v2/.

Architecture Decision Records#

Five ADRs under docs/domains/isis/adr/ document the key architectural choices made during Isis's design:

ADR-0023, referenced by the CanonicalAuditEvent model comment, is a platform-wide ADR defining the canonical audit-event envelope. It is not an Isis-local ADR.

Acceptance Criteria#

A change to Isis is acceptance-complete when all of the following conditions are satisfied:

1. Schema integrity — npx prisma validate passes against libs/isis/database/prisma/schema.prisma; any new model/enum is reflected in the generated client and in this document.
2. Envelope compatibility — Any new generation type is added to ISIS_GENERATION_TYPES, ISIS_GENERATION_TYPE_MANIFEST, and the database GenerationType enum together; check-generation-type-enum-drift.mjs reports no drift.
3. Event-contract parity — New events are defined in @oshun/contracts (IsisEventTypes + payload schema) before any publisher method is added; the event-publisher cross-service contract specs pass.
4. API validation — Every new route has a Zod request schema wired through @hono/zod-validator; the OpenAPI contract spec (generation-api/src/openapi.contract.spec.ts) passes.
5. Health endpoints — /health and /ready remain unauthenticated and /ready continues to reflect real dependency state (DB, queue, storage, provider).
6. Tests — Unit and integration tests pass under Vitest, including the route-parity and schema-compatibility contract specs.
7. No simulated execution in production — gpu-worker execution paths must not be gated to simulated runtimes when NODE_ENV=production.