@highstate/backend 0.9.31 → 0.9.33

package/src/orchestrator/operation-plan.preview.test.ts

@@ -0,0 +1,80 @@
+import { describe } from "vitest"
+import { createOperationPlan } from "./operation-plan"
+import { operationPlanTest } from "./operation-plan.fixtures"
+
+describe("OperationPlan - Preview Operations", () => {
+  operationPlanTest(
+    "1. returns single preview phase for requested unit",
+    async ({ testBuilder, expect }) => {
+      const { context, operation } = await testBuilder()
+        .unit("App")
+        .request("preview", "App")
+        .build()
+
+      const plan = createOperationPlan(
+        context,
+        operation.type,
+        operation.requestedInstanceIds,
+        operation.options,
+      )
+
+      expect(plan).toMatchInlineSnapshot(`
+        [
+          {
+            "instances": [
+              {
+                "id": "component.v1:App",
+                "message": "explicitly requested",
+                "parentId": undefined,
+              },
+            ],
+            "type": "preview",
+          },
+        ]
+      `)
+    },
+  )
+
+  operationPlanTest(
+    "2. throws when multiple instances are requested",
+    async ({ testBuilder, expect }) => {
+      const { context, operation } = await testBuilder()
+        .unit("A")
+        .unit("B")
+        .request("preview", "A", "B")
+        .build()
+
+      expect(() =>
+        createOperationPlan(
+          context,
+          operation.type,
+          operation.requestedInstanceIds,
+          operation.options,
+        ),
+      ).toThrowErrorMatchingInlineSnapshot(
+        "[Error: Preview operations can only target a single instance]",
+      )
+    },
+  )
+
+  operationPlanTest(
+    "3. throws when previewing composite instance",
+    async ({ testBuilder, expect }) => {
+      const { context, operation } = await testBuilder()
+        .composite("Group")
+        .request("preview", "Group")
+        .build()
+
+      expect(() =>
+        createOperationPlan(
+          context,
+          operation.type,
+          operation.requestedInstanceIds,
+          operation.options,
+        ),
+      ).toThrowErrorMatchingInlineSnapshot(
+        '[Error: Preview is not supported for composite instance "composite.v1:Group"]',
+      )
+    },
+  )
+})

package/src/orchestrator/operation-plan.ts

@@ -35,6 +35,38 @@ export function createOperationPlan(
   requestedInstanceIds: string[],
   options: OperationOptions,
 ): OperationPhase[] {
+  if (options.forceUpdateDependencies && options.ignoreDependencies) {
+    throw new Error(
+      "Operation options are invalid: forceUpdateDependencies and ignoreDependencies cannot both be enabled.",
+    )
+  }
+
+  if (type === "preview") {
+    if (requestedInstanceIds.length !== 1) {
+      throw new Error("Preview operations can only target a single instance")
+    }
+
+    const instanceId = requestedInstanceIds[0] as InstanceId
+    const instance = context.getInstance(instanceId)
+
+    if (instance.kind !== "unit") {
+      throw new Error(`Preview is not supported for composite instance "${instanceId}"`)
+    }
+
+    return [
+      {
+        type: "preview",
+        instances: [
+          {
+            id: instanceId,
+            parentId: instance.parentId,
+            message: "explicitly requested",
+          },
+        ],
+      },
+    ]
+  }
+
   // initialize work state
   const workState: WorkState = {
     included: new Map(),
@@ -195,6 +227,10 @@ function processUpdateInclusions(
   if (workState.included.has(instance.id)) {
     const dependencies = context.getDependencies(instance.id)
     for (const depInstance of dependencies) {
+      if (options.ignoreDependencies) {
+        continue
+      }
+
       const shouldInclude = options.forceUpdateDependencies || isOutdated(depInstance, context)
 
       if (shouldInclude && !workState.included.has(depInstance.id)) {
@@ -237,6 +273,10 @@ function processRefreshInclusions(
   if (workState.included.has(instance.id)) {
     const dependencies = context.getDependencies(instance.id)
     for (const depInstance of dependencies) {
+      if (options.ignoreDependencies) {
+        continue
+      }
+
       const shouldInclude = options.forceUpdateDependencies
 
       if (shouldInclude && !workState.included.has(depInstance.id)) {

package/src/orchestrator/operation-plan.update.test.ts

@@ -48,6 +48,47 @@ describe("OperationPlan - Update Operations", () => {
     },
   )
 
+  operationPlanTest(
+    "1a. should ignore dependencies when option enabled",
+    async ({ testBuilder, expect }) => {
+      // arrange
+      const { context, operation } = await testBuilder()
+        .unit("A")
+        .unit("B")
+        .unit("C")
+        .depends("C", "B")
+        .depends("B", "A")
+        .states({ A: "upToDate", B: "changed", C: "upToDate" })
+        .options({ ignoreDependencies: true })
+        .request("update", "C")
+        .build()
+
+      // act
+      const plan = createOperationPlan(
+        context,
+        operation.type,
+        operation.requestedInstanceIds,
+        operation.options,
+      )
+
+      // assert
+      expect(plan).toMatchInlineSnapshot(`
+        [
+          {
+            "instances": [
+              {
+                "id": "component.v1:C",
+                "message": "explicitly requested",
+                "parentId": undefined,
+              },
+            ],
+            "type": "update",
+          },
+        ]
+      `)
+    },
+  )
+
   operationPlanTest(
     "2. should not propagate beyond compositional inclusion",
     async ({ testBuilder, expect }) => {
@@ -158,6 +199,35 @@ describe("OperationPlan - Update Operations", () => {
     },
   )
 
+  operationPlanTest(
+    "3a. should reject conflicting dependency options",
+    async ({ testBuilder, expect }) => {
+      // arrange
+      const { context, operation } = await testBuilder()
+        .unit("A")
+        .unit("B")
+        .unit("C")
+        .depends("C", "B")
+        .depends("B", "A")
+        .states({ A: "upToDate", B: "upToDate", C: "upToDate" })
+        .options({ forceUpdateDependencies: true, ignoreDependencies: true })
+        .request("update", "C")
+        .build()
+
+      // act & assert
+      expect(() =>
+        createOperationPlan(
+          context,
+          operation.type,
+          operation.requestedInstanceIds,
+          operation.options,
+        ),
+      ).toThrowErrorMatchingInlineSnapshot(
+        "[Error: Operation options are invalid: forceUpdateDependencies and ignoreDependencies cannot both be enabled.]",
+      )
+    },
+  )
+
   operationPlanTest(
     "4. should include outdated children of substantive composite",
     async ({ testBuilder, expect }) => {

package/src/orchestrator/operation-workset.ts

@@ -120,18 +120,21 @@ export class OperationWorkset {
           inputs => inputs.map(input => input.input),
         )
 
+        const serializedResolvedInputs = this.context.serializeResolvedInputs(resolvedInputs)
+
         return [
           {
             stateId: state.id,
             operationId: this.operationId,
             status: "pending",
             model: instance,
-            resolvedInputs,
+            resolvedInputs: serializedResolvedInputs,
           },
           {
+            // preview runs still provision a pulumi stack; keep "attempted" so a later destroy removes it
             status: state.status === "undeployed" ? "attempted" : state.status,
             model: instance,
-            resolvedInputs,
+            resolvedInputs: serializedResolvedInputs,
           },
         ]
       }),
@@ -153,7 +156,7 @@ export class OperationWorkset {
       options,
     )
 
-    if (state.parentInstanceId) {
+    if (state.parentInstanceId && this.currentPhase !== "preview") {
       // TODO: update all updates in single transaction
       await this.recalculateCompositeInstanceState(state.parentInstanceId)
     }
@@ -231,6 +234,8 @@ export class OperationWorkset {
 
   getTransientStatusByOperationPhase(): InstanceOperationStatus {
     switch (this.currentPhase) {
+      case "preview":
+        return "previewing"
       case "update":
         return "updating"
       case "destroy":
@@ -242,6 +247,8 @@ export class OperationWorkset {
 
   getStableStatusByOperationPhase(): InstanceOperationStatus {
     switch (this.currentPhase) {
+      case "preview":
+        return "previewed"
       case "update":
         return "updated"
       case "destroy":
@@ -255,6 +262,8 @@ export class OperationWorkset {
     const state = this.context.getState(instanceId)
 
     switch (this.currentPhase) {
+      case "preview":
+        return state.status // do not change instance status when previewing
       case "update":
         return "deployed"
       case "destroy":

package/src/orchestrator/operation.ts

@@ -252,9 +252,60 @@ export class RuntimeOperation {
       case "refresh": {
         return this.refreshUnit(instance, state)
       }
+      case "preview": {
+        return this.previewUnit(instance, state)
+      }
     }
   }
 
+  private previewUnit(instance: InstanceModel, state: InstanceState): Promise<void> {
+    return this.getInstancePromise(instance.id, async (logger, signal, forceSignal) => {
+      signal.throwIfAborted()
+
+      if (this.operation.status === "failing") {
+        throw new AbortError("The operation is failing, aborting preview branch")
+      }
+
+      logger.info("previewing unit")
+
+      await this.workset.updateState(instance.id, {
+        operationState: {
+          status: "previewing",
+          startedAt: new Date(),
+        },
+      })
+
+      signal.throwIfAborted()
+
+      const secrets = await this.secretService.getInstanceSecretValues(this.project.id, state.id)
+      signal.throwIfAborted()
+
+      const config = this.prepareUnitConfig(instance, secrets)
+      const artifactIds = this.collectArtifactIdsForInstance(instance)
+      const artifacts = await this.artifactService.getArtifactsByIds(this.project.id, artifactIds)
+
+      logger.debug({ count: artifactIds.length }, "artifact ids collected for preview")
+
+      await this.runnerBackend.preview({
+        projectId: this.project.id,
+        libraryId: this.project.libraryId,
+        stateId: state.id,
+        instanceType: instance.type,
+        instanceName: instance.name,
+        config,
+        refresh: this.operation.options.refresh,
+        secrets,
+        artifacts,
+        signal,
+        forceSignal,
+        debug: this.operation.options.debug,
+      })
+
+      await this.watchStateStream(state, instance.type, instance.name, logger)
+      logger.info("unit preview completed")
+    })
+  }
+
   private getCompositePromise(instance: InstanceModel): Promise<void> {
     return this.getInstancePromise(instance.id, async logger => {
       let instanceState: InstanceStatePatch | undefined
@@ -353,7 +404,7 @@ export class RuntimeOperation {
 
       logger.debug({ count: artifactIds.length }, "artifact ids collected from dependencies")
 
-      await this.runnerBackend[this.operation.type === "preview" ? "preview" : "update"]({
+      await this.runnerBackend.update({
         projectId: this.project.id,
         libraryId: this.project.libraryId,
         stateId: state.id,
@@ -669,7 +720,6 @@ export class RuntimeOperation {
     state: InstanceState,
   ): Promise<void> {
     if (this.operation.type === "preview") {
-      // do not change instance status in preview mode
       await this.workset.updateState(update.unitId, {
         operationState: {
           status: this.workset.getStableStatusByOperationPhase(),

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

@@ -209,14 +209,6 @@ export class PlanTestBuilder {
     const instances = Array.from(this.instances.values())
     const states = Array.from(this.stateMap.values())
 
-    // Copy resolvedInputs from instances to states for dependency tracking
-    states.forEach(state => {
-      const instance = instances.find(i => i.id === state.instanceId)
-      if (instance?.resolvedInputs) {
-        state.resolvedInputs = instance.resolvedInputs
-      }
-    })
-
     // get requested instance IDs
     const requestedInstanceIds = this.requestedInstanceNames.map(name => {
       const instance = this.instances.get(name)
@@ -234,6 +226,14 @@ export class PlanTestBuilder {
     // create context with instances and initial states
     const context = await this.createContext(instances, states)
 
+    // copy resolvedInputs from instances to states for dependency tracking
+    states.forEach(state => {
+      const instance = instances.find(i => i.id === state.instanceId)
+      if (instance?.resolvedInputs) {
+        state.resolvedInputs = context.serializeResolvedInputs(instance.resolvedInputs)
+      }
+    })
+
     // update "upToDate" states with correct input hashes from context
     const updatedStates = states.map(state => {
       const stateEntry = Array.from(this.stateMap.entries()).find(

package/src/runner/local.ts

@@ -208,7 +208,7 @@ export class LocalRunnerBackend implements RunnerBackend {
               const outputs = await stack.outputs()
               const completionUpdate = this.createCompletionStateUpdate("update", unitId, outputs)
 
-              if (outputs["$artifacts"]) {
+              if (!preview && outputs["$artifacts"]) {
                 const artifacts = z
                   .record(z.string(), unitArtifactSchema.array())
                   .parse(outputs["$artifacts"].value)
@@ -221,6 +221,8 @@ export class LocalRunnerBackend implements RunnerBackend {
                   Object.values(artifacts).flat(),
                   childLogger,
                 )
+              } else if (preview && outputs["$artifacts"]) {
+                childLogger.debug({ msg: "skipping artifact persistence for preview" })
               }
 
               this.emitStateUpdate(completionUpdate)

package/src/runner/pulumi.ts

@@ -111,7 +111,12 @@ export class LocalPulumiHost {
         {
           projectSettings: {
             name: pulumiProjectName,
-            runtime: "nodejs",
+            runtime: {
+              name: "nodejs",
+              options: {
+                nodeargs: "--no-deprecation",
+              },
+            },
             main: "index.js",
           },
           stackSettings: stackConfig

package/src/shared/models/prisma.ts

@@ -24,7 +24,7 @@ declare global {
     type InstanceModel = contract.InstanceModel
 
     type InstanceArgs = Record<string, unknown>
-    type InstanceResolvedInputs = Record<string, contract.InstanceInput[]>
+    type InstanceResolvedInputs = Record<string, shared.StableInstanceInput[]>
     type UnlockMethodMeta = shared.UnlockMethodMeta
     type ProjectUnlockSuite = shared.ProjectUnlockSuite
 

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

@@ -4,7 +4,7 @@ import { instanceIdSchema, objectMetaSchema, z } from "@highstate/contract"
 /**
  * Phase type for operation execution.
  */
-export const operationPhaseTypeSchema = z.enum(["destroy", "update", "refresh"])
+export const operationPhaseTypeSchema = z.enum(["destroy", "preview", "update", "refresh"])
 
 /**
  * Instance information for operation phase.
@@ -61,6 +61,20 @@ export const operationOptionsSchema = z
      */
     forceUpdateDependencies: z.boolean().default(false),
 
+    /**
+     * Ignore dependencies and operate only on explicitly requested instances.
+     *
+     * **Operation Behavior Impact:**
+     * - skips dependency inclusion even when dependencies are failed or undeployed;
+     * - caller must explicitly include every prerequisite instance to avoid failures;
+     * - complements on-demand or targeted updates where dependency safety is managed externally.
+     *
+     * **Usage with other options:**
+     * - mutually exclusive with `forceUpdateDependencies`;
+     * - independent of child/composite inclusion options.
+     */
+    ignoreDependencies: z.boolean().default(false),
+
     /**
      * Force update all children of composite instances regardless of their state.
      *

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

@@ -8,6 +8,18 @@ import type {
 } from "../../../database"
 import { z } from "zod"
 
+export const stableInstanceInputSchema = z.object({
+  stateId: z.string(),
+  output: z.string(),
+})
+
+/**
+ * The instance input that references state IDs instead of instance IDs.
+ *
+ * This provides a stable reference to an instance output that is not affected by instance ID changes.
+ */
+export type StableInstanceInput = z.infer<typeof stableInstanceInputSchema>
+
 /**
  * The instance state aggregate including all related states.
  */
@@ -109,6 +121,7 @@ export type {
 } from "../../../database"
 
 export const finalInstanceOperationStatuses: InstanceOperationStatus[] = [
+  "previewed",
   "destroyed",
   "updated",
   "cancelled",

package/src/shared/resolvers/input-hash.ts

@@ -45,6 +45,9 @@ export class InputHashResolver extends GraphResolver<InputHashNode, InputHashOut
   }: InputHashNode): InputHashOutput {
     const inputHashSink: Uint8Array[] = []
 
+    // 0. include the instance id to reflect renames
+    inputHashSink.push(Buffer.from(instance.id))
+
     // 1. include the component definition hash
     inputHashSink.push(int32ToBytes(component.definitionHash))
 

package/src/shared/resolvers/registry.ts

@@ -1,9 +1,7 @@
 import type { Logger } from "pino"
-import type { InstanceState } from "../models/project"
 import type { DependentSetHandler, GraphResolver, ResolverOutputHandler } from "./graph-resolver"
 import { InputResolver, type InputResolverNode, type InputResolverOutput } from "./input"
 import { type InputHashNode, type InputHashOutput, InputHashResolver } from "./input-hash"
-import { StateResolver } from "./state"
 import { type ValidationNode, type ValidationOutput, ValidationResolver } from "./validation"
 
 export type GraphResolverType = keyof GraphResolverMap
@@ -12,15 +10,12 @@ export type GraphResolverMap = {
   InputResolver: [InputResolverNode, InputResolverOutput]
   InputHashResolver: [InputHashNode, InputHashOutput]
   ValidationResolver: [ValidationNode, ValidationOutput]
-  // biome-ignore lint/suspicious/noConfusingVoidType: it is return type
-  StateResolver: [InstanceState, void]
 }
 
 export const resolverFactories = {
   InputResolver,
   InputHashResolver,
   ValidationResolver,
-  StateResolver,
 } as Record<
   GraphResolverType,
   new (