@highstate/backend 0.19.1 → 0.20.0

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

@@ -62,15 +62,31 @@ export const operationOptionsSchema = z
     forceUpdateDependencies: z.boolean().default(false),
 
     /**
-     * Ignore dependencies and operate only on explicitly requested instances.
+     * Ignore only changed dependencies and keep failed/undeployed prerequisites.
      *
      * **Operation Behavior Impact:**
-     * - skips dependency inclusion even when dependencies are failed or undeployed;
+     * - skips dependency inclusion when dependency is only changed;
+     * - still includes failed or undeployed dependencies to preserve safety for missing/broken prerequisites;
+     * - useful for targeted updates where stale-but-healthy dependencies are intentionally not traversed.
+     *
+     * **Usage with other options:**
+     * - mutually exclusive with `forceUpdateDependencies`;
+     * - mutually exclusive with `ignoreDependencies`;
+     * - independent of child/composite inclusion options.
+     */
+    ignoreChangedDependencies: z.boolean().default(false),
+
+    /**
+     * Ignore all dependencies and operate only on explicitly requested instances.
+     *
+     * **Operation Behavior Impact:**
+     * - skips dependency inclusion entirely, including failed and undeployed prerequisites;
      * - caller must explicitly include every prerequisite instance to avoid failures;
-     * - complements on-demand or targeted updates where dependency safety is managed externally.
+     * - intended for fully manual execution flows.
      *
      * **Usage with other options:**
      * - mutually exclusive with `forceUpdateDependencies`;
+     * - mutually exclusive with `ignoreChangedDependencies`;
      * - independent of child/composite inclusion options.
      */
     ignoreDependencies: z.boolean().default(false),
@@ -89,6 +105,48 @@ export const operationOptionsSchema = z
      */
     forceUpdateChildren: z.boolean().default(false),
 
+    /**
+     * Run only ghost cleanup destroy phase and skip update phase entirely.
+     *
+     * **Operation Behavior Impact:**
+     * - applies to update operations only;
+     * - skips update phase even if normal update candidates exist;
+     * - keeps only ghost cleanup destroy phase for affected substantive composites.
+     *
+     * **Usage with other options:**
+     * - mutually exclusive with `firstDestroyGhosts`;
+     * - mutually exclusive with `ignoreGhosts`.
+     */
+    onlyDestroyGhosts: z.boolean().default(false),
+
+    /**
+     * Run ghost cleanup destroy phase before update phase.
+     *
+     * **Operation Behavior Impact:**
+     * - applies to update operations only;
+     * - keeps both phases but changes order to destroy ghosts first;
+     * - useful when stale ghost resources should be removed prior to update execution.
+     *
+     * **Usage with other options:**
+     * - mutually exclusive with `onlyDestroyGhosts`;
+     * - mutually exclusive with `ignoreGhosts`.
+     */
+    firstDestroyGhosts: z.boolean().default(false),
+
+    /**
+     * Ignore ghost cleanup and skip destroy phase for ghosts.
+     *
+     * **Operation Behavior Impact:**
+     * - applies to update operations only;
+     * - disables ghost cleanup destroy phase generation;
+     * - update phase remains unchanged.
+     *
+     * **Usage with other options:**
+     * - mutually exclusive with `onlyDestroyGhosts`;
+     * - mutually exclusive with `firstDestroyGhosts`.
+     */
+    ignoreGhosts: z.boolean().default(false),
+
     /**
      * Include dependent instances when destroying instances.
      *

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

@@ -11,6 +11,7 @@ import { z } from "zod"
 export const stableInstanceInputSchema = z.object({
   stateId: z.string(),
   output: z.string(),
+  path: z.string().optional(),
 })
 
 /**
@@ -77,6 +78,15 @@ export const instanceStateEventSchema = z.discriminatedUnion("type", [
     stateId: z.string(),
     patch: z.custom<Partial<InstanceState>>(),
   }),
+  z.object({
+    type: z.literal("patched-batch"),
+    patches: z.array(
+      z.object({
+        stateId: z.string(),
+        patch: z.custom<Partial<InstanceState>>(),
+      }),
+    ),
+  }),
   z.object({
     type: z.literal("deleted"),
     stateId: z.string(),

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

@@ -52,6 +52,13 @@ export const workerVersionStatusSchema = z.enum([
 
 export type WorkerVersionStatus = z.infer<typeof workerVersionStatusSchema>
 
+export const workerVersionStatusEventSchema = z.object({
+  workerVersionId: z.cuid2(),
+  status: workerVersionStatusSchema,
+})
+
+export type WorkerVersionStatusEvent = z.infer<typeof workerVersionStatusEventSchema>
+
 export const workerVersionOutputSchema = z.object({
   id: z.cuid2(),
   digest: z.string(),

package/src/shared/resolvers/effective-output-type.test.ts

@@ -0,0 +1,494 @@
+import type {
+  ComponentModel,
+  EntityModel,
+  HubInput,
+  InstanceInput,
+  InstanceModel,
+} from "@highstate/contract"
+import { describe, expect, test } from "vitest"
+import { type InstanceTypeContext, resolveEffectiveOutputType } from "./effective-output-type"
+
+function createEntity(
+  type: EntityModel["type"],
+  inclusions?: EntityModel["inclusions"],
+): EntityModel {
+  return {
+    type,
+    inclusions,
+    schema: {},
+    meta: {
+      title: type,
+    },
+    definitionHash: 1,
+  }
+}
+
+function createInputSpec(
+  type: EntityModel["type"],
+  options?: { fromInput?: string; multiple?: boolean },
+) {
+  return {
+    type,
+    fromInput: options?.fromInput,
+    required: true,
+    multiple: options?.multiple ?? false,
+    meta: {
+      title: type,
+    },
+  }
+}
+
+function createComponent(options: {
+  type: ComponentModel["type"]
+  inputs?: Record<string, ReturnType<typeof createInputSpec>>
+  outputs?: Record<string, ReturnType<typeof createInputSpec>>
+}): ComponentModel {
+  return {
+    type: options.type,
+    kind: "unit",
+    args: {},
+    inputs: options.inputs ?? {},
+    outputs: options.outputs ?? {},
+    meta: {
+      title: options.type,
+      defaultNamePrefix: "test",
+    },
+    definitionHash: 1,
+  }
+}
+
+function createInstance(options: {
+  id: InstanceModel["id"]
+  type: InstanceModel["type"]
+  inputs?: Record<string, InstanceInput[]>
+  hubInputs?: Record<string, HubInput[]>
+  injectionInputs?: HubInput[]
+}): InstanceModel {
+  return {
+    id: options.id,
+    name: "instance",
+    type: options.type,
+    kind: "unit",
+    inputs: options.inputs,
+    hubInputs: options.hubInputs,
+    injectionInputs: options.injectionInputs,
+  }
+}
+
+function createResolver(contexts: Record<string, InstanceTypeContext>) {
+  return (instanceId: string) => contexts[instanceId]
+}
+
+describe("resolveEffectiveOutputType", () => {
+  test.concurrent("returns declared output type when no fromInput is used", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1"),
+    }
+
+    const instance = createInstance({
+      id: "example.writer.v1:writer-1",
+      type: "example.writer.v1",
+    })
+
+    const component = createComponent({
+      type: "example.writer.v1",
+      outputs: {
+        value: createInputSpec("example.base.v1"),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: { instanceId: instance.id, output: "value" },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [instance.id]: {
+          instance,
+          component,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.base.v1")
+  })
+
+  test.concurrent("forwards output type from a single direct input", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1"),
+      "example.child.v1": createEntity("example.child.v1"),
+    }
+
+    const source = createInstance({
+      id: "example.source.v1:source-1",
+      type: "example.source.v1",
+    })
+
+    const sourceComponent = createComponent({
+      type: "example.source.v1",
+      outputs: {
+        value: createInputSpec("example.child.v1"),
+      },
+    })
+
+    const forwarder = createInstance({
+      id: "example.forwarder.v1:forwarder-1",
+      type: "example.forwarder.v1",
+      inputs: {
+        source: [{ instanceId: source.id, output: "value" }],
+      },
+    })
+
+    const forwarderComponent = createComponent({
+      type: "example.forwarder.v1",
+      inputs: {
+        source: createInputSpec("example.base.v1"),
+      },
+      outputs: {
+        value: createInputSpec("example.base.v1", { fromInput: "source" }),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: { instanceId: forwarder.id, output: "value" },
+      fallbackType: "example.base.v1",
+      getInstanceContext: createResolver({
+        [source.id]: {
+          instance: source,
+          component: sourceComponent,
+          entities,
+        },
+        [forwarder.id]: {
+          instance: forwarder,
+          component: forwarderComponent,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.child.v1")
+  })
+
+  test.concurrent("falls back when forwarded source input has hub inputs", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1"),
+      "example.child.v1": createEntity("example.child.v1"),
+    }
+
+    const source = createInstance({
+      id: "example.source.v1:source-1",
+      type: "example.source.v1",
+    })
+
+    const sourceComponent = createComponent({
+      type: "example.source.v1",
+      outputs: {
+        value: createInputSpec("example.child.v1"),
+      },
+    })
+
+    const forwarder = createInstance({
+      id: "example.forwarder.v1:forwarder-1",
+      type: "example.forwarder.v1",
+      inputs: {
+        source: [{ instanceId: source.id, output: "value" }],
+      },
+      hubInputs: {
+        source: [{ hubId: "hub1" }],
+      },
+    })
+
+    const forwarderComponent = createComponent({
+      type: "example.forwarder.v1",
+      inputs: {
+        source: createInputSpec("example.base.v1"),
+      },
+      outputs: {
+        value: createInputSpec("example.base.v1", { fromInput: "source" }),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: { instanceId: forwarder.id, output: "value" },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [source.id]: {
+          instance: source,
+          component: sourceComponent,
+          entities,
+        },
+        [forwarder.id]: {
+          instance: forwarder,
+          component: forwarderComponent,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.base.v1")
+  })
+
+  test.concurrent("falls back when forwarded source input has multiple direct inputs", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1"),
+      "example.child.v1": createEntity("example.child.v1"),
+    }
+
+    const source = createInstance({
+      id: "example.source.v1:source-1",
+      type: "example.source.v1",
+    })
+
+    const sourceComponent = createComponent({
+      type: "example.source.v1",
+      outputs: {
+        value: createInputSpec("example.child.v1"),
+      },
+    })
+
+    const forwarder = createInstance({
+      id: "example.forwarder.v1:forwarder-1",
+      type: "example.forwarder.v1",
+      inputs: {
+        source: [
+          { instanceId: source.id, output: "value" },
+          { instanceId: source.id, output: "value" },
+        ],
+      },
+    })
+
+    const forwarderComponent = createComponent({
+      type: "example.forwarder.v1",
+      inputs: {
+        source: createInputSpec("example.base.v1"),
+      },
+      outputs: {
+        value: createInputSpec("example.base.v1", { fromInput: "source" }),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: { instanceId: forwarder.id, output: "value" },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [source.id]: {
+          instance: source,
+          component: sourceComponent,
+          entities,
+        },
+        [forwarder.id]: {
+          instance: forwarder,
+          component: forwarderComponent,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.base.v1")
+  })
+
+  test.concurrent("applies path traversal to the resolved type", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1", [
+        {
+          type: "example.child.v1",
+          field: "child",
+          required: true,
+          multiple: false,
+        },
+      ]),
+      "example.child.v1": createEntity("example.child.v1", [
+        {
+          type: "example.leaf.v1",
+          field: "leaf",
+          required: true,
+          multiple: false,
+        },
+      ]),
+      "example.leaf.v1": createEntity("example.leaf.v1"),
+    }
+
+    const instance = createInstance({
+      id: "example.writer.v1:writer-1",
+      type: "example.writer.v1",
+    })
+
+    const component = createComponent({
+      type: "example.writer.v1",
+      outputs: {
+        value: createInputSpec("example.base.v1"),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: {
+        instanceId: instance.id,
+        output: "value",
+        path: "child.leaf",
+      },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [instance.id]: {
+          instance,
+          component,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.leaf.v1")
+  })
+
+  test.concurrent("returns root type when path is invalid", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1", [
+        {
+          type: "example.child.v1",
+          field: "child",
+          required: true,
+          multiple: false,
+        },
+      ]),
+      "example.child.v1": createEntity("example.child.v1"),
+    }
+
+    const instance = createInstance({
+      id: "example.writer.v1:writer-1",
+      type: "example.writer.v1",
+    })
+
+    const component = createComponent({
+      type: "example.writer.v1",
+      outputs: {
+        value: createInputSpec("example.base.v1"),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: {
+        instanceId: instance.id,
+        output: "value",
+        path: "missing.segment",
+      },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [instance.id]: {
+          instance,
+          component,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.base.v1")
+  })
+
+  test.concurrent(
+    "uses direct inclusion when no path is provided and fallback matches inclusion type",
+    () => {
+      const entities = {
+        "example.identity.v1": createEntity("example.identity.v1", [
+          {
+            type: "example.peer.v1",
+            field: "peer",
+            required: true,
+            multiple: false,
+          },
+        ]),
+        "example.peer.v1": createEntity("example.peer.v1"),
+      }
+
+      const identity = createInstance({
+        id: "example.identity.v1:identity-1",
+        type: "example.identity.v1",
+      })
+
+      const component = createComponent({
+        type: "example.identity.v1",
+        outputs: {
+          identity: createInputSpec("example.identity.v1"),
+        },
+      })
+
+      const resolved = resolveEffectiveOutputType({
+        input: {
+          instanceId: identity.id,
+          output: "identity",
+        },
+        fallbackType: "example.peer.v1",
+        getInstanceContext: createResolver({
+          [identity.id]: {
+            instance: identity,
+            component,
+            entities,
+          },
+        }),
+      })
+
+      expect(resolved).toBe("example.peer.v1")
+    },
+  )
+
+  test.concurrent("handles forwarding cycles without recursion errors", () => {
+    const entities = {
+      "example.base.v1": createEntity("example.base.v1"),
+    }
+
+    const instanceA = createInstance({
+      id: "example.a.v1:a-1",
+      type: "example.a.v1",
+      inputs: {
+        source: [{ instanceId: "example.b.v1:b-1", output: "value" }],
+      },
+    })
+
+    const instanceB = createInstance({
+      id: "example.b.v1:b-1",
+      type: "example.b.v1",
+      inputs: {
+        source: [{ instanceId: "example.a.v1:a-1", output: "value" }],
+      },
+    })
+
+    const componentA = createComponent({
+      type: "example.a.v1",
+      inputs: {
+        source: createInputSpec("example.base.v1"),
+      },
+      outputs: {
+        value: createInputSpec("example.base.v1", { fromInput: "source" }),
+      },
+    })
+
+    const componentB = createComponent({
+      type: "example.b.v1",
+      inputs: {
+        source: createInputSpec("example.base.v1"),
+      },
+      outputs: {
+        value: createInputSpec("example.base.v1", { fromInput: "source" }),
+      },
+    })
+
+    const resolved = resolveEffectiveOutputType({
+      input: {
+        instanceId: instanceA.id,
+        output: "value",
+      },
+      fallbackType: "example.fallback.v1",
+      getInstanceContext: createResolver({
+        [instanceA.id]: {
+          instance: instanceA,
+          component: componentA,
+          entities,
+        },
+        [instanceB.id]: {
+          instance: instanceB,
+          component: componentB,
+          entities,
+        },
+      }),
+    })
+
+    expect(resolved).toBe("example.base.v1")
+  })
+})