@highstate/backend 0.9.21 → 0.9.23

package/src/database/_generated/project/models/Page.ts

@@ -15,7 +15,12 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 PageModel = runtime.Types.Result.DefaultSelection<Prisma.$PagePayload>
 
@@ -917,7 +922,9 @@ export type $PagePayload<ExtArgs extends runtime.Types.Extensions.InternalArgs =
      */
     serviceAccountId: string | null
     /**
-     * The content of the page managed by the backend.
+     * The content of the page as an array of blocks.
+     * 
+     * Supports markdown, QR codes, and file blocks.
      * 
      * [PageContent]
      */

package/src/database/_generated/project/models/Secret.ts

@@ -15,7 +15,18 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 SecretModel = runtime.Types.Result.DefaultSelection<Prisma.$SecretPayload>
 

package/src/database/_generated/project/models/ServiceAccount.ts

@@ -15,7 +15,12 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 ServiceAccountModel = runtime.Types.Result.DefaultSelection<Prisma.$ServiceAccountPayload>
 

package/src/database/_generated/project/models/Terminal.ts

@@ -15,7 +15,14 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 TerminalModel = runtime.Types.Result.DefaultSelection<Prisma.$TerminalPayload>
 
@@ -1077,7 +1084,9 @@ export type $TerminalPayload<ExtArgs extends runtime.Types.Extensions.InternalAr
      */
     status: $Enums.TerminalStatus
     /**
-     * The specification of the terminal managed by the backend.
+     * The specification for creating the container that powers this terminal.
+     * 
+     * Includes image, command, working directory, environment variables, and files.
      * 
      * [TerminalSpec]
      */

package/src/database/_generated/project/models/TerminalSession.ts

@@ -15,7 +15,9 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 TerminalSessionModel = runtime.Types.Result.DefaultSelection<Prisma.$TerminalSessionPayload>
 

package/src/database/_generated/project/models/TerminalSessionLog.ts

@@ -15,7 +15,9 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 TerminalSessionLogModel = runtime.Types.Result.DefaultSelection<Prisma.$TerminalSessionLogPayload>
 

package/src/database/_generated/project/models/Trigger.ts

@@ -15,7 +15,12 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 TriggerModel = runtime.Types.Result.DefaultSelection<Prisma.$TriggerPayload>
 
@@ -574,7 +579,7 @@ export type $TriggerPayload<ExtArgs extends runtime.Types.Extensions.InternalArg
      */
     name: string
     /**
-     * The specification of the trigger describing its behavior and configuration.
+     * The specification of the trigger describing its type and behavior.
      * 
      * [TriggerSpec]
      */

package/src/database/_generated/project/models/UnlockMethod.ts

@@ -15,7 +15,19 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 UnlockMethodModel = runtime.Types.Result.DefaultSelection<Prisma.$UnlockMethodPayload>
 

package/src/database/_generated/project/models/Worker.ts

@@ -15,7 +15,16 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 WorkerModel = runtime.Types.Result.DefaultSelection<Prisma.$WorkerPayload>
 
@@ -578,7 +587,7 @@ export type $WorkerPayload<ExtArgs extends runtime.Types.Extensions.InternalArgs
      */
     id: string
     /**
-     * The ID of the worker.
+     * The identity of the worker derived from the container image.
      * 
      * This is the fully qualified image name without the tag or digest.
      * The format is `{<registry>/}[<namespace>/]<name>`.

package/src/database/_generated/project/models/WorkerUnitRegistration.ts

@@ -15,7 +15,14 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 WorkerUnitRegistrationModel = runtime.Types.Result.DefaultSelection<Prisma.$WorkerUnitRegistrationPayload>
 
@@ -660,7 +667,7 @@ export type $WorkerUnitRegistrationPayload<ExtArgs extends runtime.Types.Extensi
      */
     stateId: string
     /**
-     * The name of the workor within the instance.
+     * The name of the worker within the instance.
      */
     name: string
     /**

package/src/database/_generated/project/models/WorkerVersion.ts

@@ -15,7 +15,15 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 WorkerVersionModel = runtime.Types.Result.DefaultSelection<Prisma.$WorkerVersionPayload>
 

package/src/database/_generated/project/models/WorkerVersionLog.ts

@@ -15,7 +15,10 @@ import type * as Prisma from "../internal/prismaNamespace.ts"
 
 /**
  * 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 WorkerVersionLogModel = runtime.Types.Result.DefaultSelection<Prisma.$WorkerVersionLogPayload>
 

package/src/library/local.ts

@@ -88,13 +88,10 @@ export class LocalLibraryBackend implements LibraryBackend {
   }
 
   async loadLibrary(): Promise<LibraryModel> {
-    return await this.lock.acquire(async () => {
-      return await this.getLibrary()
-    })
+    return await this.lock.acquire(async () => await this.getLibrary())
   }
 
   async *watchLibrary(_libraryId: string, signal?: AbortSignal): AsyncIterable<LibraryUpdate[]> {
-    // For local backend, we ignore libraryId since there's only one library
     for await (const [library] of on(this.eventEmitter, "library", { signal })) {
       yield library
     }
@@ -142,7 +139,6 @@ export class LocalLibraryBackend implements LibraryBackend {
     _libraryId: string,
     signal?: AbortSignal,
   ): AsyncIterable<ResolvedUnitSource> {
-    // For local backend, we ignore libraryId since there's only one library
     for await (const [resolvedUnitSource] of on(this.eventEmitter, "resolvedUnitSource", {
       signal,
     })) {

package/src/library/package-resolution-worker.ts

@@ -49,7 +49,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/src/orchestrator/manager.ts

@@ -88,7 +88,7 @@ export class OperationManager {
 
     const operation = await this.operationService.createOperation(
       request.projectId,
-      {},
+      request.meta,
       request.type,
       request.instanceIds,
       options,
@@ -268,7 +268,6 @@ export class OperationManager {
         },
         data: {
           status: "failed",
-          message: "Operation was interrupted",
         },
       })
 

package/src/orchestrator/operation-context.ts

@@ -44,8 +44,6 @@ export class OperationContext {
     Record<InstanceId, ResolvedInstanceInput[]>
   >()
 
-  private instanceIdToStateIdMap: Record<InstanceId, string> | null = null
-
   private constructor(
     public readonly project: ProjectOutput,
     public readonly library: LibraryModel,
@@ -213,18 +211,21 @@ export class OperationContext {
     }
   }
 
-  public getInstanceIdToStateIdMap(): Record<InstanceId, string> {
-    if (this.instanceIdToStateIdMap) {
-      return this.instanceIdToStateIdMap
-    }
-
-    // build map on first request and cache it
+  /**
+   * Gets a map of instance IDs to state IDs for dependencies of the given instance.
+   *
+   * @param instanceId The instance ID to get the state ID map for.
+   * @returns A map of instance IDs to state IDs.
+   */
+  public getInstanceIdToStateIdMap(instanceId: InstanceId): Record<InstanceId, string> {
     const map: Record<InstanceId, string> = {}
-    for (const [instanceId, state] of this.stateMap.entries()) {
+    const dependencies = this.getDependencies(instanceId).map(i => i.id)
+
+    for (const dep of dependencies) {
+      const state = this.getState(dep)
       map[instanceId] = state.id
     }
 
-    this.instanceIdToStateIdMap = map
     return map
   }
 

package/src/orchestrator/operation.ts

@@ -309,7 +309,6 @@ export class RuntimeOperation {
           },
           instanceState: {
             status: this.workset.getNextStableInstanceStatus(instance.id),
-            message: null,
           },
         })
       }
@@ -327,6 +326,10 @@ export class RuntimeOperation {
 
       signal.throwIfAborted()
 
+      if (this.operation.status === "failing") {
+        throw new AbortError("The operation is failing, aborting current branch (still not failed)")
+      }
+
       logger.info("updating unit")
 
       await this.workset.updateState(instance.id, {
@@ -467,9 +470,19 @@ export class RuntimeOperation {
         dependentPromises.push(this.getInstancePromiseForOperation(instance, dependent))
       }
 
-      await waitAll(dependentPromises)
+      await Promise.race([
+        waitAll(dependentPromises),
+
+        // to immediately abort the operation if requested
+        waitForAbort(signal),
+      ])
+
       signal.throwIfAborted()
 
+      if (this.operation.status === "failing") {
+        throw new AbortError("The operation is failing, aborting current branch (still not failed)")
+      }
+
       await this.processBeforeDestroyTriggers(instance, state, logger, signal, forceSignal)
       signal.throwIfAborted()
 
@@ -594,7 +607,7 @@ export class RuntimeOperation {
       inputs: mapValues(resolvedInputs ?? {}, input => input.map(value => value.input)),
       invokedTriggers,
       secretNames: Object.keys(secrets),
-      stateIdMap: this.context.getInstanceIdToStateIdMap(),
+      stateIdMap: this.context.getInstanceIdToStateIdMap(instance.id),
     }
   }
 
@@ -655,7 +668,6 @@ export class RuntimeOperation {
       instanceState: {
         // keep "deployed" status for initially deployed instances even if the operation was failed or cancelled
         status: state.status === "deployed" ? "deployed" : "failed",
-        message: update.message,
       },
       operationState: {
         status: isAbortErrorLike(update.message) ? "cancelled" : "failed",
@@ -672,7 +684,6 @@ export class RuntimeOperation {
 
     const data: InstanceStatePatch = {
       status: this.workset.getNextStableInstanceStatus(instance.id),
-      message: update.message,
       statusFields: update.statusFields ?? null,
     }
 
@@ -697,7 +708,6 @@ export class RuntimeOperation {
         data.parentId = null
       }
     } else {
-      data.message = null
       data.inputHash = null
       data.dependencyOutputHash = null
       data.outputHash = null

package/src/orchestrator/plan-test-builder.ts

@@ -109,7 +109,6 @@ export class PlanTestBuilder {
       statusFields: null,
       exportedArtifactIds: null,
       inputHashNonce: null,
-      message: null,
       currentResourceCount: null,
       model: null,
       resolvedInputs: null,

package/src/project-model/backends/codebase.ts

@@ -272,7 +272,7 @@ export class CodebaseProjectModelBackend implements ProjectModelBackend {
         return {}
       })
 
-      this.logger.info(
+      this.logger.debug(
         { projectId: project.id, instanceCount: instances.length, hubCount: hubs.length },
         "created nodes in project model",
       )

package/src/project-model/backends/database.ts

@@ -415,7 +415,7 @@ export class DatabaseProjectModelBackend implements ProjectModelBackend {
         ])
       })
 
-      this.logger.info(
+      this.logger.debug(
         { projectId: project.id, instanceCount: instances.length, hubCount: hubs.length },
         "created nodes in project model",
       )

package/src/runner/abstractions.ts

@@ -56,11 +56,6 @@ export type UnitStateUpdate = {
        */
       operationType: OperationType
 
-      /**
-       * The summary message produced by the unit.
-       */
-      message?: string | null
-
       /**
        * The CRC32 hash of the output produced by the unit.
        */

package/src/runner/local.ts

@@ -41,12 +41,7 @@ import {
   collectAndStoreArtifacts,
   setupArtifactEnvironment,
 } from "./artifact-env"
-import {
-  getOperationSummary,
-  type LocalPulumiHost,
-  pulumiErrorToString,
-  updateResourceCount,
-} from "./pulumi"
+import { type LocalPulumiHost, pulumiErrorToString, updateResourceCount } from "./pulumi"
 
 type Events = {
   [K in `update:${string}`]: [UnitStateUpdate]
@@ -172,7 +167,7 @@ export class LocalRunnerBackend implements RunnerBackend {
 
           await runWithRetryOnError(
             async () => {
-              const { stdout } = await stack[preview ? "preview" : "up"]({
+              await stack[preview ? "preview" : "up"]({
                 color: "always",
                 refresh: options.refresh,
                 signal,
@@ -211,12 +206,7 @@ export class LocalRunnerBackend implements RunnerBackend {
               })
 
               const outputs = await stack.outputs()
-              const completionUpdate = this.createCompletionStateUpdate(
-                "update",
-                unitId,
-                outputs,
-                stdout,
-              )
+              const completionUpdate = this.createCompletionStateUpdate("update", unitId, outputs)
 
               if (outputs["$artifacts"]) {
                 const artifacts = z
@@ -333,7 +323,7 @@ export class LocalRunnerBackend implements RunnerBackend {
           try {
             await runWithRetryOnError(
               async () => {
-                const { stdout } = await stack.destroy({
+                await stack.destroy({
                   color: "always",
                   refresh: options.refresh,
                   remove: true,
@@ -361,7 +351,7 @@ export class LocalRunnerBackend implements RunnerBackend {
                   },
                 })
 
-                await this.emitCompletionStateUpdate("destroy", unitId, stack, stdout)
+                await this.emitCompletionStateUpdate("destroy", unitId, stack)
               },
               error => this.pulumiProjectHost.tryUnlockStack(stack, error),
             )
@@ -431,7 +421,7 @@ export class LocalRunnerBackend implements RunnerBackend {
 
           await runWithRetryOnError(
             async () => {
-              const { stdout } = await stack.refresh({
+              await stack.refresh({
                 color: "always",
                 debug: options.debug,
 
@@ -472,7 +462,6 @@ export class LocalRunnerBackend implements RunnerBackend {
                 type: "completion",
                 operationType: "refresh",
                 unitId,
-                message: getOperationSummary(stdout),
 
                 // do not emit output-related fields on refresh since they will not change
                 // some of them (like artifact files) are not even available on refresh
@@ -495,7 +484,6 @@ export class LocalRunnerBackend implements RunnerBackend {
     opType: "update" | "destroy" | "refresh",
     unitId: InstanceId,
     outputs: OutputMap,
-    stdout: string,
   ): TypedUnitStateUpdate<"completion"> {
     const unitOutputs = omitBy(outputs, (_, key) => key.startsWith("$"))
 
@@ -503,7 +491,6 @@ export class LocalRunnerBackend implements RunnerBackend {
       unitId,
       type: "completion",
       operationType: opType,
-      message: getOperationSummary(stdout),
 
       outputHash: crc32(sha256(encode(unitOutputs))),
 
@@ -535,10 +522,9 @@ export class LocalRunnerBackend implements RunnerBackend {
     opType: OperationType,
     unitId: InstanceId,
     stack: Stack,
-    stdout: string,
   ): Promise<TypedUnitStateUpdate<"completion">> {
     const output = await stack.outputs()
-    const update = this.createCompletionStateUpdate(opType, unitId, output, stdout)
+    const update = this.createCompletionStateUpdate(opType, unitId, output)
 
     return this.emitStateUpdate(update)
   }

package/src/runner/pulumi.ts

@@ -204,7 +204,6 @@ export function calculateTotalResources(opMap: OpMap | undefined): number {
   for (const [op, count] of Object.entries(opMap)) {
     const opType = op as OpType
     const value = count ?? 0
-
     total = updateResourceCount(opType, value)
   }
 
@@ -230,13 +229,3 @@ export async function pulumiErrorToString(error: unknown): Promise<string> {
 
   return errorToString(error)
 }
-
-export function getOperationSummary(stdout: string): string | null {
-  const summaryStart = stdout.indexOf("\u001b[38;5;13m\u001b[1mOutputs:")
-
-  if (summaryStart !== -1) {
-    return stdout.slice(summaryStart)
-  }
-
-  return null
-}

package/src/shared/models/project/operation.ts

@@ -206,17 +206,19 @@ export const operationStatusSchema = z.enum([
   "cancelled",
 ]) satisfies z.ZodType<OperationStatus>
 
-export const operationMetaSchema = objectMetaSchema.pick({
-  title: true,
-  description: true,
-})
+export const operationMetaSchema = objectMetaSchema
+  .pick({
+    title: true,
+    description: true,
+  })
+  .required({ title: true })
 
 export const operationInputSchema = z.object({
   projectId: z.string(),
   type: operationTypeSchema,
   instanceIds: z.array(instanceIdSchema).min(1),
   options: operationOptionsSchema.partial().optional(),
-  meta: operationMetaSchema.optional(),
+  meta: operationMetaSchema,
   plan: operationPhaseSchema.array().optional(),
 })
 

package/src/shared/models/project/terminal.ts

@@ -1,6 +1,7 @@
 import type { ServiceAccount, Terminal, TerminalSession, TerminalStatus } from "../../../database"
 import {
   commonObjectMetaSchema,
+  globalCommonObjectMetaSchema,
   serviceAccountMetaSchema,
   terminalSpecSchema,
 } from "@highstate/contract"
@@ -15,7 +16,7 @@ export const terminalStatusSchema = z.enum([
 export const terminalSessionOutputSchema = z.object({
   id: z.cuid2(),
   terminalId: z.cuid2(),
-  meta: commonObjectMetaSchema,
+  meta: globalCommonObjectMetaSchema,
   startedAt: z.date(),
   finishedAt: z.date().nullable(),
 })

package/src/shared/resolvers/state.ts

@@ -3,12 +3,8 @@ import { GraphResolver } from "./graph-resolver"
 
 export class StateResolver extends GraphResolver<InstanceState, void> {
   protected getNodeDependencies(node: InstanceState): string[] {
-    if (!node.lastOperationState) {
-      return []
-    }
-
     const dependencies = new Set<string>()
-    for (const inputs of Object.values(node.lastOperationState.resolvedInputs)) {
+    for (const inputs of Object.values(node.resolvedInputs ?? {})) {
       for (const input of inputs) {
         dependencies.add(input.instanceId)
       }