@highstate/backend 0.9.21 → 0.9.23

package/dist/library/package-resolution-worker.js

@@ -21,7 +21,7 @@ for (const packageName of packageNames) {
     });
   } catch (error) {
     logger.error({ error }, `failed to resolve package "%s"`, packageName);
-    if (error instanceof Error && error.message.includes("not found")) {
+    if (error instanceof Error && error.message.includes(`Cannot find package '${packageName}'`)) {
       results.push({
         type: "not-found",
         packageName

package/dist/library/package-resolution-worker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/library/package-resolution-worker.ts"],"names":[],"mappings":";;;;;;;AA8BA,IAAM,EAAE,YAAA,EAAc,QAAA,EAAS,GAAI,UAAA;AAEnC,IAAM,MAAA,GAAS,KAAK,EAAE,IAAA,EAAM,4BAA4B,KAAA,EAAO,QAAA,IAAY,UAAU,CAAA;AAErF,IAAM,UAA2B,EAAC;AAElC,KAAA,MAAW,eAAe,YAAA,EAAc;AACtC,EAAA,IAAI;AACF,IAAA,MAAM,IAAA,GAAO,eAAA,CAAgB,WAAA,EAAa,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AACzD,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,SAAA,EAAY,WAAW,CAAA,WAAA,CAAa,CAAA;AAAA,IACtD;AAEA,IAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,MACX,IAAA,EAAM,SAAA;AAAA,MACN,WAAA;AAAA,MACA,eAAA,EAAiB,MAAM,QAAA,CAAS,OAAA,CAAQ,IAAI,CAAC;AAAA,KAC9C,CAAA;AAAA,EACH,SAAS,KAAA,EAAO;AACd,IAAA,MAAA,CAAO,KAAA,CAAM,EAAE,KAAA,EAAM,EAAG,kCAAkC,WAAW,CAAA;AAErE,IAAA,IAAI,iBAAiB,KAAA,IAAS,KAAA,CAAM,OAAA,CAAQ,QAAA,CAAS,WAAW,CAAA,EAAG;AACjE,MAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,QACX,IAAA,EAAM,WAAA;AAAA,QACN;AAAA,OACD,CAAA;AAAA,IACH,CAAA,MAAO;AACL,MAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,QACX,IAAA,EAAM,OAAA;AAAA,QACN,WAAA;AAAA,QACA,OAAO,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK;AAAA,OAC7D,CAAA;AAAA,IACH;AAAA,EACF;AACF;AAEA,UAAA,EAAY,WAAA,CAAY;AAAA,EACtB,IAAA,EAAM,QAAA;AAAA,EACN;AACF,CAAC,CAAA","file":"package-resolution-worker.js","sourcesContent":["import { realpath } from \"node:fs/promises\"\nimport { findPackageJSON } from \"node:module\"\nimport { dirname } from \"node:path\"\nimport { parentPort, workerData } from \"node:worker_threads\"\nimport pino, { type Level } from \"pino\"\n\nexport type PackageResolutionWorkerData = {\n  packageNames: string[]\n  logLevel?: Level\n}\n\nexport type PackageResult = { packageName: string } & (\n  | {\n      type: \"success\"\n      packageRootPath: string\n    }\n  | {\n      type: \"not-found\"\n    }\n  | {\n      type: \"error\"\n      error: string\n    }\n)\n\nexport type PackageResolutionResponse = {\n  type: \"result\"\n  results: PackageResult[]\n}\n\nconst { packageNames, logLevel } = workerData as PackageResolutionWorkerData\n\nconst logger = pino({ name: \"source-resolution-worker\", level: logLevel ?? \"silent\" })\n\nconst results: PackageResult[] = []\n\nfor (const packageName of packageNames) {\n  try {\n    const path = findPackageJSON(packageName, import.meta.url)\n    if (!path) {\n      throw new Error(`Package \"${packageName}\" not found`)\n    }\n\n    results.push({\n      type: \"success\",\n      packageName,\n      packageRootPath: await realpath(dirname(path)),\n    })\n  } catch (error) {\n    logger.error({ error }, `failed to resolve package \"%s\"`, packageName)\n\n    if (error instanceof Error && error.message.includes(\"not found\")) {\n      results.push({\n        type: \"not-found\",\n        packageName,\n      })\n    } else {\n      results.push({\n        type: \"error\",\n        packageName,\n        error: error instanceof Error ? error.message : String(error),\n      })\n    }\n  }\n}\n\nparentPort?.postMessage({\n  type: \"result\",\n  results,\n})\n"]}
+{"version":3,"sources":["../../src/library/package-resolution-worker.ts"],"names":[],"mappings":";;;;;;;AA8BA,IAAM,EAAE,YAAA,EAAc,QAAA,EAAS,GAAI,UAAA;AAEnC,IAAM,MAAA,GAAS,KAAK,EAAE,IAAA,EAAM,4BAA4B,KAAA,EAAO,QAAA,IAAY,UAAU,CAAA;AAErF,IAAM,UAA2B,EAAC;AAElC,KAAA,MAAW,eAAe,YAAA,EAAc;AACtC,EAAA,IAAI;AACF,IAAA,MAAM,IAAA,GAAO,eAAA,CAAgB,WAAA,EAAa,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AACzD,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,SAAA,EAAY,WAAW,CAAA,WAAA,CAAa,CAAA;AAAA,IACtD;AAEA,IAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,MACX,IAAA,EAAM,SAAA;AAAA,MACN,WAAA;AAAA,MACA,eAAA,EAAiB,MAAM,QAAA,CAAS,OAAA,CAAQ,IAAI,CAAC;AAAA,KAC9C,CAAA;AAAA,EACH,SAAS,KAAA,EAAO;AACd,IAAA,MAAA,CAAO,KAAA,CAAM,EAAE,KAAA,EAAM,EAAG,kCAAkC,WAAW,CAAA;AAErE,IAAA,IAAI,KAAA,YAAiB,SAAS,KAAA,CAAM,OAAA,CAAQ,SAAS,CAAA,qBAAA,EAAwB,WAAW,GAAG,CAAA,EAAG;AAC5F,MAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,QACX,IAAA,EAAM,WAAA;AAAA,QACN;AAAA,OACD,CAAA;AAAA,IACH,CAAA,MAAO;AACL,MAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,QACX,IAAA,EAAM,OAAA;AAAA,QACN,WAAA;AAAA,QACA,OAAO,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK;AAAA,OAC7D,CAAA;AAAA,IACH;AAAA,EACF;AACF;AAEA,UAAA,EAAY,WAAA,CAAY;AAAA,EACtB,IAAA,EAAM,QAAA;AAAA,EACN;AACF,CAAC,CAAA","file":"package-resolution-worker.js","sourcesContent":["import { realpath } from \"node:fs/promises\"\nimport { findPackageJSON } from \"node:module\"\nimport { dirname } from \"node:path\"\nimport { parentPort, workerData } from \"node:worker_threads\"\nimport pino, { type Level } from \"pino\"\n\nexport type PackageResolutionWorkerData = {\n  packageNames: string[]\n  logLevel?: Level\n}\n\nexport type PackageResult = { packageName: string } & (\n  | {\n      type: \"success\"\n      packageRootPath: string\n    }\n  | {\n      type: \"not-found\"\n    }\n  | {\n      type: \"error\"\n      error: string\n    }\n)\n\nexport type PackageResolutionResponse = {\n  type: \"result\"\n  results: PackageResult[]\n}\n\nconst { packageNames, logLevel } = workerData as PackageResolutionWorkerData\n\nconst logger = pino({ name: \"source-resolution-worker\", level: logLevel ?? \"silent\" })\n\nconst results: PackageResult[] = []\n\nfor (const packageName of packageNames) {\n  try {\n    const path = findPackageJSON(packageName, import.meta.url)\n    if (!path) {\n      throw new Error(`Package \"${packageName}\" not found`)\n    }\n\n    results.push({\n      type: \"success\",\n      packageName,\n      packageRootPath: await realpath(dirname(path)),\n    })\n  } catch (error) {\n    logger.error({ error }, `failed to resolve package \"%s\"`, packageName)\n\n    if (error instanceof Error && error.message.includes(`Cannot find package '${packageName}'`)) {\n      results.push({\n        type: \"not-found\",\n        packageName,\n      })\n    } else {\n      results.push({\n        type: \"error\",\n        packageName,\n        error: error instanceof Error ? error.message : String(error),\n      })\n    }\n  }\n}\n\nparentPort?.postMessage({\n  type: \"result\",\n  results,\n})\n"]}

package/dist/shared/index.js

@@ -1,4 +1,4 @@
-export { AccessError, BackendError, CannotDeleteLastUnlockMethodError, GraphResolver, InputHashResolver, InputResolver, InstanceLockLostError, InstanceLockedError, InstanceNotFoundError, InstanceStateNotFoundError, InvalidInstanceKindError, MAX_WORKER_START_ATTEMPTS, OperationNotFoundError, ProjectLockedError, ProjectNotFoundError, PromiseTracker, SystemSecretNames, ValidationResolver, WorkerVersionNotFoundError, apiKeyMetaSchema, apiKeyOutputSchema, apiKeyQuerySchema, applyLibraryUpdate, artifactOutputSchema, artifactQuerySchema, backendUnlockMethodSchema, codebaseLibrary, codebaseProjectModelStorage, collectionQueryResult, collectionQuerySchema, createAsyncBatcher, databaseProjectModelStorage, diffLibraries, extractDigestFromImage, finalInstanceOperationStatuses, finalOperationStatuses, forSchema, getAllDependents, getMatchedInjectionInstanceInputs, getResolvedHubInputs, getResolvedInjectionInstanceInputs, getResolvedInstanceInputs, getResolvedInstanceOutputs, getWorkerIdentity, globalProjectSpace, hasObjectMeta, hostPulumiBackend, instanceCustomStatusInputSchema, instanceLockEventSchema, instanceLockOutputSchema, instanceStateEventSchema, int32ToBytes, isFinalOperationStatus, isInstanceDeployed, isTransientInstanceOperationStatus, isTransientOperationStatus, isVirtualGhostInstance, librarySpecSchema, operationEventSchema, operationInputSchema, operationMetaSchema, operationOptionsSchema, operationOutputSchema, operationPhaseInstanceSchema, operationPhaseSchema, operationPhaseTypeSchema, operationStatusSchema, operationTypeSchema, pageDetailsOutputSchema, pageOutputSchema, pageQuerySchema, projectInputSchema, projectModelEventSchema, projectModelStorageSpecSchema, projectOutputSchema, projectUnlockStateSchema, projectUnlockSuiteSchema, pulumiBackendSpecSchema, resolverFactories, secretOutputSchema, secretQuerySchema, serviceAccountOutputSchema, serviceAccountQuerySchema, terminalDetailsOutputSchema, terminalOutputSchema, terminalQuerySchema, terminalSessionOutputSchema, terminalStatusSchema, toApiKeyOutput, toPageOutput, toSecretOutput, toTerminalDetailsOutput, toTerminalOutput, toTerminalSessionOutput, toWorkerOutput, toWorkerVersionOutput, triggerOutputSchema, triggerQuerySchema, unlockMethodInputSchema, unlockMethodMetaSchema, unlockMethodOutputSchema, unlockMethodType, waitAll, workerOutputSchema, workerQuerySchema, workerUnitRegistrationEventSchema, workerVersionOutputSchema, workerVersionStatusSchema } from '../chunk-JNUJ4LTX.js';
+export { AccessError, BackendError, CannotDeleteLastUnlockMethodError, GraphResolver, InputHashResolver, InputResolver, InstanceLockLostError, InstanceLockedError, InstanceNotFoundError, InstanceStateNotFoundError, InvalidInstanceKindError, MAX_WORKER_START_ATTEMPTS, OperationNotFoundError, ProjectLockedError, ProjectNotFoundError, PromiseTracker, SystemSecretNames, ValidationResolver, WorkerVersionNotFoundError, apiKeyMetaSchema, apiKeyOutputSchema, apiKeyQuerySchema, applyLibraryUpdate, artifactOutputSchema, artifactQuerySchema, backendUnlockMethodSchema, codebaseLibrary, codebaseProjectModelStorage, collectionQueryResult, collectionQuerySchema, createAsyncBatcher, databaseProjectModelStorage, diffLibraries, extractDigestFromImage, finalInstanceOperationStatuses, finalOperationStatuses, forSchema, getAllDependents, getMatchedInjectionInstanceInputs, getResolvedHubInputs, getResolvedInjectionInstanceInputs, getResolvedInstanceInputs, getResolvedInstanceOutputs, getWorkerIdentity, globalProjectSpace, hasObjectMeta, hostPulumiBackend, instanceCustomStatusInputSchema, instanceLockEventSchema, instanceLockOutputSchema, instanceStateEventSchema, int32ToBytes, isFinalOperationStatus, isInstanceDeployed, isTransientInstanceOperationStatus, isTransientOperationStatus, isVirtualGhostInstance, librarySpecSchema, operationEventSchema, operationInputSchema, operationMetaSchema, operationOptionsSchema, operationOutputSchema, operationPhaseInstanceSchema, operationPhaseSchema, operationPhaseTypeSchema, operationStatusSchema, operationTypeSchema, pageDetailsOutputSchema, pageOutputSchema, pageQuerySchema, projectInputSchema, projectModelEventSchema, projectModelStorageSpecSchema, projectOutputSchema, projectUnlockStateSchema, projectUnlockSuiteSchema, pulumiBackendSpecSchema, resolverFactories, secretOutputSchema, secretQuerySchema, serviceAccountOutputSchema, serviceAccountQuerySchema, terminalDetailsOutputSchema, terminalOutputSchema, terminalQuerySchema, terminalSessionOutputSchema, terminalStatusSchema, toApiKeyOutput, toPageOutput, toSecretOutput, toTerminalDetailsOutput, toTerminalOutput, toTerminalSessionOutput, toWorkerOutput, toWorkerVersionOutput, triggerOutputSchema, triggerQuerySchema, unlockMethodInputSchema, unlockMethodMetaSchema, unlockMethodOutputSchema, unlockMethodType, waitAll, workerOutputSchema, workerQuerySchema, workerUnitRegistrationEventSchema, workerVersionOutputSchema, workerVersionStatusSchema } from '../chunk-5LYHHLFW.js';
 import '../chunk-I7BWSAN6.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/backend",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "type": "module",
   "highstate": {
     "sourceHash": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@aws-crypto/crc32": "^5.2.0",
-    "@highstate/contract": "^0.9.21",
+    "@highstate/contract": "^0.9.23",
     "@msgpack/msgpack": "^3.1.2",
     "@napi-rs/keyring": "^1.1.8",
     "@noble/ciphers": "^1.3.0",
@@ -98,5 +98,5 @@
     "type-fest": "^4.41.0",
     "vitest": "^3.2.4"
   },
-  "gitHead": "390ff15c0e0076822a682f9d4e19260942a8d6c2"
+  "gitHead": "389be30a2144dfb1499b02e8a1e71074c26a3f9f"
 }

package/prisma/backend/postgresql/main.prisma

@@ -1,6 +1,6 @@
 datasource db {
     provider = "postgresql"
-    url      = env("BACKEND_DATABASE_URL")
+    url      = env("HIGHSTATE_MIGRATION_DATABASE_URL")
 }
 
 generator client {

package/prisma/backend/sqlite/main.prisma

@@ -1,6 +1,6 @@
 datasource db {
-    provider  = "sqlite"
-    directUrl = env("HIGHSTATE_MIGRATION_DATABASE_URL")
+    provider = "sqlite"
+    url      = env("HIGHSTATE_MIGRATION_DATABASE_URL")
 }
 
 generator client {

package/prisma/project/instance.prisma

@@ -1,28 +1,28 @@
 enum InstanceStatus {
     /// The instance is exists in the model (resident or virtual), but not yet deployed or was completely destroyed.
     ///
-    /// "partial", "deployed" and "failed" instances can be transitioned back to "undeployed" after
+    /// "attempted", "deployed" and "failed" instances can be transitioned back to "undeployed" after
     /// successful "destroy" operation.
     undeployed
 
-    /// The instance is partially deployed (attempted, but not yet successful).
+    /// The instance is attempted, but not yet fully deployed.
     ///
     /// Normally, this status is very short-lived, and here to indicate that the instance
     /// cannot be safely deleted from the the model until it will be completely destroyed.
-    partial
+    attempted
 
     /// The initial deployment of the instance was successful.
     ///
     /// The transition of "deployed -> failed" is not possible, so consequent failed operations
     /// will not affect this status.
     ///
-    /// Like "partial", that instance cannot be safely deleted from the model until it will be completely destroyed.
+    /// Like "attempted", that instance cannot be safely deleted from the model until it will be completely destroyed.
     deployed
 
     /// The initial deployment of the instance failed.
     /// It can still be transitioned to "deployed" by a successful operation
     ///
-    /// Like "partial", that instance cannot be safely deleted from the model until it will be completely destroyed.
+    /// Like "attempted", that instance cannot be safely deleted from the model until it will be completely destroyed.
     failed
 }
 

package/prisma/project/main.prisma

@@ -1,6 +1,6 @@
 datasource db {
-    provider  = "sqlite"
-    directUrl = env("HIGHSTATE_MIGRATION_DATABASE_URL")
+    provider = "sqlite"
+    url      = env("HIGHSTATE_MIGRATION_DATABASE_URL")
 }
 
 generator client {

package/prisma/project/migrations/20250921092621_b/migration.sql

@@ -0,0 +1,33 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `message` on the `InstanceState` table. All the data in the column will be lost.
+
+*/
+-- RedefineTables
+PRAGMA defer_foreign_keys=ON;
+PRAGMA foreign_keys=OFF;
+CREATE TABLE "new_InstanceState" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "instanceId" TEXT NOT NULL,
+    "status" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "kind" TEXT NOT NULL,
+    "parentId" TEXT,
+    "inputHashNonce" INTEGER,
+    "inputHash" INTEGER,
+    "outputHash" INTEGER,
+    "dependencyOutputHash" INTEGER,
+    "exportedArtifactIds" JSONB,
+    "model" JSONB,
+    "resolvedInputs" JSONB,
+    "currentResourceCount" INTEGER,
+    "statusFields" JSONB,
+    CONSTRAINT "InstanceState_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "InstanceState" ("id") ON DELETE SET NULL ON UPDATE CASCADE
+);
+INSERT INTO "new_InstanceState" ("currentResourceCount", "dependencyOutputHash", "exportedArtifactIds", "id", "inputHash", "inputHashNonce", "instanceId", "kind", "model", "outputHash", "parentId", "resolvedInputs", "source", "status", "statusFields") SELECT "currentResourceCount", "dependencyOutputHash", "exportedArtifactIds", "id", "inputHash", "inputHashNonce", "instanceId", "kind", "model", "outputHash", "parentId", "resolvedInputs", "source", "status", "statusFields" FROM "InstanceState";
+DROP TABLE "InstanceState";
+ALTER TABLE "new_InstanceState" RENAME TO "InstanceState";
+CREATE UNIQUE INDEX "InstanceState_instanceId_key" ON "InstanceState"("instanceId");
+PRAGMA foreign_keys=ON;
+PRAGMA defer_foreign_keys=OFF;

package/prisma/project/migrations/20250921093911_b/migration.sql

@@ -0,0 +1 @@
+-- This is an empty migration.

package/prisma/project/operation.prisma

@@ -136,6 +136,9 @@ model OperationLog {
     /// Can be `null` if the log is not associated with any instance.
     stateId String?
 
+    /// Whether this log is a system/runtime message (vs unit output).
+    isSystem Boolean @default(false)
+
     /// The content of the log.
     content String
 

package/src/business/instance-state.ts

@@ -92,7 +92,6 @@ export type ForgetInstanceStateOptions = {
 export type InstanceStatePatch = Pick<
   Partial<InstanceState>,
   | "status"
-  | "message"
   | "statusFields"
   | "parentId"
   | "lastOperationState"
@@ -308,7 +307,6 @@ export class InstanceStateService {
           inputHash: null,
           outputHash: null,
           dependencyOutputHash: null,
-          message: null,
           currentResourceCount: null,
           model: null,
           resolvedInputs: null,
@@ -370,7 +368,6 @@ export class InstanceStateService {
         inputHash: null,
         outputHash: null,
         dependencyOutputHash: null,
-        message: null,
         currentResourceCount: null,
         model: DbNull,
         resolvedInputs: DbNull,

package/src/database/_generated/project/client.ts

@@ -40,7 +40,11 @@ export { Prisma }
 
 /**
  * Model ApiKey
+ * The API key provides authentication tokens for accessing the platform API.
  * 
+ * Each API key impersonates a service account, inheriting its permissions and access scope.
+ * Keys are automatically created for worker versions and can be manually created for
+ * external integrations. The token is a 32-byte random hex string that can be regenerated.
  */
 export type ApiKey = Prisma.ApiKeyModel
 /**
@@ -63,7 +67,16 @@ export type Artifact = Prisma.ArtifactModel
 export type InstanceCustomStatus = Prisma.InstanceCustomStatusModel
 /**
  * Model InstanceEvaluationState
+ * The evaluation state tracks the result of evaluating composite instances to produce virtual instances.
  * 
+ * Composite instances are template components that generate other instances (virtual instances) when evaluated.
+ * The evaluation process executes the composite's create function with resolved inputs to produce a tree
+ * of child instances. These virtual instances exist in the source "virtual" state and can be units
+ * (mapping to Pulumi resources) or other composites (producing more virtual instances recursively).
+ * 
+ * Evaluation happens automatically after project unlock and library reloads to keep virtual instances
+ * synchronized with their composite definitions. Evaluation state persists the produced instance model
+ * and tracks success/error status with descriptive messages showing the instance tree or error details.
  */
 export type InstanceEvaluationState = Prisma.InstanceEvaluationStateModel
 /**
@@ -117,62 +130,138 @@ export type InstanceOperationState = Prisma.InstanceOperationStateModel
 export type OperationLog = Prisma.OperationLogModel
 /**
  * Model Page
+ * The page provides custom UI content for instances and service accounts.
  * 
+ * Pages can be created by units to display instance-specific information or by service accounts.
+ * The content consists of blocks that support markdown text, QR codes with optional content display,
+ * and file attachments (inline or artifact references). Instance pages are explicitly deleted
+ * when instances are destroyed.
  */
 export type Page = Prisma.PageModel
 /**
  * Model Secret
+ * The secret stores sensitive configuration values for instances, service accounts, and system components.
+ * 
+ * Secrets can be instance-owned (for unit configuration), service account-owned, or system-level
+ * (like Pulumi passwords). 
+ * 
+ * Secrets persist through normal destroy (recreate) operations
+ * and are only deleted when explicitly forgetting instance state with the deleteSecrets flag or when manually deleted.
  * 
+ * Secret updates invalidate instance input hashes via inputHashNonce, triggering re-execution
+ * during operations. But the content of the secrets itself do not contribute to the input hash.
+ * 
+ * System secrets like Pulumi passwords are created on-demand and persist for the whole project lifetime.
  */
 export type Secret = Prisma.SecretModel
 /**
  * Model ServiceAccount
+ * The service account represents an identity for non-human actors in the system.
  * 
+ * Service accounts are automatically created for workers and can be manually created
+ * for external integrations. They define the access scope for resources like artifacts,
+ * secrets, terminals, and pages. Multiple API keys can impersonate the same service account,
+ * allowing different authentication tokens to share the same permissions.
  */
 export type ServiceAccount = Prisma.ServiceAccountModel
 /**
  * Model Terminal
+ * The terminal provides interactive shell access to infrastructure resources.
+ * 
+ * Terminals can be created by units (owned by instances) or by service accounts.
+ * Each terminal maintains a specification for creating containers that power the terminal,
+ * including image, command, environment, and mounted files.
  * 
+ * Instance-owned terminals are marked unavailable when the instance is destroyed, preserving session history.
+ * Service account terminals persist independently.
  */
 export type Terminal = Prisma.TerminalModel
 /**
  * Model TerminalSession
+ * The terminal session represents a single interactive connection to a terminal.
  * 
+ * Each session tracks when it started and finished. All session output is preserved in logs.
  */
 export type TerminalSession = Prisma.TerminalSessionModel
 /**
  * Model TerminalSessionLog
+ * The terminal session log captures all input and output from a terminal session.
  * 
+ * Logs are stored with ULID identifiers for timestamp ordering.
  */
 export type TerminalSessionLog = Prisma.TerminalSessionLogModel
 /**
  * Model Trigger
+ * The trigger defines automated actions that execute in response to specific events.
  * 
+ * Triggers are created by units to perform actions at defined points in the instance lifecycle
+ * or on schedule. The spec field determines the trigger type and behavior - currently supporting
+ * before-destroy triggers, with planned support for additional types like cron scheduling.
+ * Triggers are deleted along with their instance.
  */
 export type Trigger = Prisma.TriggerModel
 /**
  * Model UnlockMethod
+ * The unlock method enables decryption of project databases through user authentication.
  * 
+ * Each project database is encrypted with a master key, which is then encrypted for each
+ * unlock method's recipient using AGE encryption. Users authenticate (password or passkey)
+ * to decrypt their specific AGE identity, which then decrypts the master key.
+ * 
+ * Multiple unlock methods can exist per project, allowing different authentication paths
+ * to the same encrypted database. When unlock methods are added/removed, the master key
+ * is re-encrypted for the new set of recipients.
+ * 
+ * The encryptedIdentity contains the AGE identity encrypted with the user's authentication
+ * method (password-derived key or WebAuthn), while the recipient is the public key
+ * corresponding to that identity.
  */
 export type UnlockMethod = Prisma.UnlockMethodModel
 /**
  * Model Worker
+ * The worker represents a containerized application that extends unit capabilities beyond Pulumi execution.
+ * 
+ * Workers enable units to perform runtime operations after Pulumi program completion,
+ * such as attaching custom statuses, monitoring resources, or triggering unit reconfigurations.
+ * Since Pulumi programs cannot affect instances after execution, workers bypass this limitation
+ * by providing persistent runtime behavior.
  * 
+ * The worker identity (fully qualified image name) indicates the same publisher/party and services as natural authentication mechanism.
+ * All versions of a worker share the same service account, meaning they operate over
+ * the same resources and have the same access scope within the platform.
  */
 export type Worker = Prisma.WorkerModel
 /**
  * Model WorkerVersion
+ * The worker version represents a specific container image digest of a worker.
  * 
+ * Each version corresponds to an immutable container image identified by its SHA256 digest.
+ * Versions are automatically created when units reference new image digests and deleted
+ * when no longer referenced by any unit registrations.
+ * 
+ * Each version has its own API key for isolation, but all versions of a worker
+ * share the same service account and thus the same access scope within the platform.
+ * The runtime starts containers when registrations exist and stops them when removed.
  */
 export type WorkerVersion = Prisma.WorkerVersionModel
 /**
  * Model WorkerUnitRegistration
+ * The worker unit registration tracks which unit instances require specific worker versions.
+ * 
+ * Units declare worker dependencies through their outputs, creating registrations that
+ * trigger the runtime to start corresponding worker containers. Each registration
+ * includes parameters passed to the worker for unit-specific configuration.
  * 
+ * Registrations are managed during operation execution - created when units declare workers
+ * and removed when units are destroyed. Worker versions without registrations are garbage collected.
  */
 export type WorkerUnitRegistration = Prisma.WorkerUnitRegistrationModel
 /**
  * Model WorkerVersionLog
+ * The worker version log captures output from running worker containers.
  * 
+ * Logs include both worker-generated output and system messages from the runtime.
+ * The ULID identifier provides timestamp ordering. Logs are deleted with the worker version.
  */
 export type WorkerVersionLog = Prisma.WorkerVersionLogModel