@highstate/contract 0.20.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/contract",
-  "version": "0.20.0",
+  "version": "0.26.0",
   "type": "module",
   "files": [
     "dist",
@@ -28,29 +28,28 @@
       "platform"
     ]
   },
+  "scripts": {
+    "build": "bun run --bun highstate build",
+    "test": "bun run --bun vitest run",
+    "typecheck": "tsgo --noEmit --skipLibCheck",
+    "biome": "biome check --write --unsafe --error-on-warnings",
+    "biome:check": "biome check --error-on-warnings"
+  },
   "dependencies": {
-    "@paralleldrive/cuid2": "^2.2.2",
     "@noble/hashes": "^2.0.0",
+    "@paralleldrive/cuid2": "^2.2.2",
     "remeda": "^2.21.0",
     "type-fest": "^4.41.0",
     "yaml": "^2.8.0",
-    "zod": "^4.0.5"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",
     "@typescript/native-preview": "^7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "2.1.8",
-    "highstate-cli-bootstrap": "npm:@highstate/cli",
     "vitest": "^3.2.4"
   },
   "repository": {
     "url": "https://github.com/highstate-io/highstate"
-  },
-  "scripts": {
-    "build": "highstate build",
-    "test": "vitest run",
-    "typecheck": "tsgo --noEmit --skipLibCheck",
-    "biome": "biome check --write --unsafe --error-on-warnings",
-    "biome:check": "biome check --error-on-warnings"
   }
-}
+}

package/src/component.spec.ts

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it } from "vitest"
 import { z } from "zod"
-import { defineComponent, kind } from "./component"
+import { defineComponent } from "./component"
 import { defineEntity } from "./entity"
-import { boundaryInput, getRuntimeInstances, resetEvaluation } from "./evaluation"
+import { getRuntimeInstances, resetEvaluation } from "./evaluation"
 import { type EntityInput, type InstanceInput, selectInput } from "./instance"
+import { boundaryInput, kind } from "./shared"
 
 describe("defineComponent", () => {
   beforeEach(resetEvaluation)

package/src/component.ts

@@ -2,21 +2,20 @@
 
 import type { Simplify } from "type-fest"
 import type { Entity, implementedTypes } from "./entity"
+import type {
+  EntityInput,
+  InstanceId,
+  InstanceInput,
+  MultipleInput,
+  RequiredInput,
+  RequiredMultipleInput,
+  RuntimeInput,
+} from "./instance"
 import type { OptionalEmptyRecords, PartialKeys } from "./utils"
 import { isNonNullish, mapValues, pickBy, uniqueBy } from "remeda"
 import { z } from "zod"
-import { boundaryInput, registerInstance } from "./evaluation"
+import { registerInstance } from "./evaluation"
 import { camelCaseToHumanReadable } from "./i18n"
-import {
-  type EntityInput,
-  type InstanceId,
-  type InstanceInput,
-  inputKey,
-  type MultipleInput,
-  type RequiredInput,
-  type RequiredMultipleInput,
-  type RuntimeInput,
-} from "./instance"
 import {
   createDeepOutputAccessor,
   createInput,
@@ -31,8 +30,14 @@ import {
   type VersionedName,
   versionedNameSchema,
 } from "./meta"
-
-export const runtimeSchema = Symbol("runtimeSchema")
+import {
+  boundaryInput,
+  type ComponentKind,
+  componentKindSchema,
+  inputKey,
+  kind,
+  runtimeSchema,
+} from "./shared"
 
 let validationEnabled = true
 
@@ -40,9 +45,6 @@ export function setValidationEnabled(enabled: boolean): void {
   validationEnabled = enabled
 }
 
-export const componentKindSchema = z.enum(["composite", "unit"])
-export type ComponentKind = z.infer<typeof componentKindSchema>
-
 export const componentArgumentSchema = z.object({
   /**
    * The JSON schema of the argument value.
@@ -478,7 +480,6 @@ type ValidateCallInputs<
 }
 
 export const originalCreate = Symbol("originalCreate")
-export const kind = Symbol("kind")
 
 export type Component<
   TType extends VersionedName = VersionedName,

package/src/entity.ts

@@ -383,6 +383,37 @@ type AddSchemaInclusions<
   ? TSchema
   : z.ZodIntersection<TSchema, z.ZodObject<InclusionShape<TImplements>>>
 
+/**
+ * The common ancestor of all entities. Any entity can be assigned to this entity.
+ */
+export const objectEntity = {
+  type: "system.object.v1",
+  schema: z.object().loose(),
+  model: {
+    type: "system.object.v1",
+    definitionHash: 0,
+    schema: z.object().loose().toJSONSchema(),
+    meta: {
+      title: "Object",
+      description:
+        "The common ancestor of all entities. Any entity can be assigned to this entity.",
+      color: "#9e9e9e",
+      icon: "mdi:cube",
+      iconColor: "#9e9e9e",
+    },
+  },
+} as unknown as Entity<"system.object.v1", { "system.object.v1": true }, z.ZodUnknown>
+
+type DefineEntityTypeExtensions<
+  TImplementedTypes extends EntityTypes,
+  TExtends extends Record<string, Entity>,
+> = AddTypeExtensions<TImplementedTypes, TExtends> & (typeof objectEntity)[typeof implementedTypes]
+
+type DefineEntitySchemaExtensions<
+  TSchema extends z.ZodTypeAny,
+  TExtends extends Record<string, Entity>,
+> = AddSchemaExtensions<TSchema, TExtends>
+
 export function defineEntity<
   TType extends VersionedName,
   TSchema extends z.ZodType,
@@ -392,8 +423,8 @@ export function defineEntity<
   options: EntityOptions<TType, TSchema, TExtends, TIncludes>,
 ): Entity<
   TType,
-  Simplify<AddTypeExtensions<{ [K in TType]: true }, TExtends>>,
-  MakeEntitySchema<AddSchemaExtensions<AddSchemaInclusions<TSchema, TIncludes>, TExtends>>,
+  DefineEntityTypeExtensions<{ [K in TType]: true }, TExtends>,
+  MakeEntitySchema<DefineEntitySchemaExtensions<AddSchemaInclusions<TSchema, TIncludes>, TExtends>>,
   DefineEntityValue<TSchema, TExtends, AddIncludeExtensions<TIncludes, TExtends>>,
   DefineEntityInput<TSchema, TExtends, AddIncludeExtensions<TIncludes, TExtends>>,
   AddIncludeExtensions<TIncludes, TExtends>
@@ -455,16 +486,34 @@ export function defineEntity<
     {} as Record<string, z.ZodTypeAny>,
   )
 
-  let finalSchema = Object.values(options.extends ?? {}).reduce(
-    (schema, entity) => z.intersection(schema, entity.schema),
-    options.schema as z.ZodType,
+  const inheritedExtensions = [...Object.values(options.extends ?? {}), objectEntity].filter(
+    entity => entity.type !== options.type,
+  )
+
+  const uniqueExtensions = Array.from(
+    new Map(inheritedExtensions.map(entity => [entity.type, entity])).values(),
+  )
+
+  const schemaExtensions = uniqueExtensions.filter(entity => entity.type !== objectEntity.type)
+
+  const strictIntersectionBase = (schema: z.ZodTypeAny): z.ZodTypeAny => {
+    if (schema instanceof z.ZodObject) {
+      return schema.strict()
+    }
+
+    return schema
+  }
+
+  let finalSchema = schemaExtensions.reduce(
+    (schema, entity) => z.intersection(schema, strictIntersectionBase(entity.schema)),
+    strictIntersectionBase(options.schema as z.ZodTypeAny),
   )
 
   if (includeRefs.length > 0) {
-    finalSchema = z.intersection(finalSchema, z.object(inclusionShape))
+    finalSchema = z.intersection(finalSchema, strictIntersectionBase(z.object(inclusionShape)))
   }
 
-  finalSchema = z.intersection(finalSchema, entityWithMetaSchema)
+  finalSchema = z.intersection(finalSchema, strictIntersectionBase(entityWithMetaSchema))
 
   const directInclusions = () =>
     includeRefs.map(includeRef => ({
@@ -473,12 +522,12 @@ export function defineEntity<
       multiple: includeRef.multiple,
       field: includeRef.field,
     }))
-  const directExtensions = Object.values(options.extends ?? {}).map(entity => entity.type)
+  const directExtensions = uniqueExtensions.map(entity => entity.type)
 
   const getInclusions = () => {
     const incs = [...directInclusions()]
 
-    for (const entity of Object.values(options.extends ?? {})) {
+    for (const entity of uniqueExtensions) {
       if (entity.model.inclusions) {
         incs.push(...entity.model.inclusions)
       }
@@ -487,7 +536,7 @@ export function defineEntity<
     return incs
   }
 
-  const extensions = Object.values(options.extends ?? {}).reduce((exts, entity) => {
+  const extensions = uniqueExtensions.reduce((exts, entity) => {
     exts.push(...(entity.model.extensions ?? []), entity.type)
 
     return exts

package/src/evaluation.ts

@@ -1,14 +1,13 @@
 import type { Component } from "./component"
 import type { InstanceInput, InstanceModel, RuntimeInput } from "./instance"
 import { mapValues } from "remeda"
+import { boundaryInput } from "./shared"
 
 export type RuntimeInstance = {
   instance: InstanceModel
   component: Component
 }
 
-export const boundaryInput = Symbol("boundaryInput")
-
 function isStableInstanceInput(value: unknown): value is InstanceInput {
   return (
     typeof value === "object" &&

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   defineEntity,
   entityModelSchema,
   getEntityId,
+  objectEntity,
 } from "./entity"
 
 export * from "./instance"
@@ -23,6 +24,7 @@ export * from "./terminal"
 export * from "./page"
 export * from "./trigger"
 export * from "./worker"
+export * from "./runtime"
 export * from "./cuidv2d"
 
 export {
@@ -53,13 +55,11 @@ export {
   getInstanceId,
   // for unit API
   type ComponentInputSpec,
-  runtimeSchema,
   // types
   type Component,
   type ComponentModel,
   type ComponentInput,
   type ComponentArgument,
-  type ComponentKind,
   // extra types
   type ComponentArgumentOptions,
   type FullComponentArgumentOptions,
@@ -76,6 +76,15 @@ export {
   originalCreate,
 } from "./component"
 
+export {
+  boundaryInput,
+  inputKey,
+  kind,
+  runtimeSchema,
+  componentKindSchema,
+  type ComponentKind,
+} from "./shared"
+
 // for runner <-> stack communication
 export * from "./pulumi"
 

package/src/instance-input.ts

@@ -1,5 +1,5 @@
 import type { InstanceInput, MultipleInput, RequiredInput, RuntimeInput } from "./instance"
-import { boundaryInput } from "./evaluation"
+import { boundaryInput } from "./shared"
 
 type CreateInputOptions = {
   boundary?: InstanceInput

package/src/instance.ts

@@ -2,8 +2,6 @@
 
 import type { Entity, EntityIncludeRef, EntityTypes } from "./entity"
 import { z } from "zod"
-import { componentKindSchema } from "./component"
-import { boundaryInput } from "./evaluation"
 import { createInput, createNonProvidedInput } from "./instance-input"
 import {
   type GenericName,
@@ -12,6 +10,7 @@ import {
   type VersionedName,
   versionedNameSchema,
 } from "./meta"
+import { boundaryInput, componentKindSchema } from "./shared"
 
 declare const type: unique symbol
 
@@ -240,12 +239,6 @@ type SelectInputResult<TInput extends RuntimeInput> = TInput extends RequiredInp
   ? TRuntime
   : TInput
 
-export function inputKey(input: InstanceInput): string {
-  return input.path
-    ? `${input.instanceId}:${input.output}:${input.path}`
-    : `${input.instanceId}:${input.output}`
-}
-
 export const positionSchema = z.object({
   x: z.number(),
   y: z.number(),

package/src/runtime.ts

@@ -0,0 +1,74 @@
+import { z } from "zod"
+import { unitConfigSchema } from "./pulumi"
+
+export const runtimeConfigGetInputSchema = z.void()
+
+export const runtimeConfigGetOutputSchema = unitConfigSchema
+
+export const runtimeResultSubmitInputSchema = z.record(z.string(), z.unknown())
+
+export const runtimeResultSubmitOutputSchema = z.object({})
+
+export const runtimeSidecarFileSchema = z.object({
+  path: z.string(),
+  content: z.string(),
+  secret: z.boolean().default(false),
+  mode: z.number().int().optional(),
+})
+
+export const runtimeSidecarPortSchema = z.object({
+  name: z.string(),
+  containerPort: z.number().int().positive().max(65535),
+  protocol: z.literal("tcp").default("tcp"),
+})
+
+export const runtimeSidecarReadinessSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("tcp"),
+    port: z.string(),
+    timeoutSeconds: z.number().int().positive().default(30),
+  }),
+  z.object({
+    type: z.literal("http"),
+    port: z.string(),
+    path: z.string(),
+    statuses: z.number().int().positive().array().default([200]),
+    timeoutSeconds: z.number().int().positive().default(30),
+  }),
+  z.object({
+    type: z.literal("log"),
+    pattern: z.string(),
+    timeoutSeconds: z.number().int().positive().default(30),
+  }),
+])
+
+export const runtimeSidecarStartInputSchema = z.object({
+  identity: z.string().regex(/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/),
+  image: z.string(),
+  command: z.string().array().optional(),
+  args: z.string().array().default([]),
+  env: z.record(z.string(), z.string()).default({}),
+  files: runtimeSidecarFileSchema.array().default([]),
+  ports: runtimeSidecarPortSchema.array().default([]),
+  readiness: runtimeSidecarReadinessSchema.optional(),
+})
+
+export const runtimeSidecarStartOutputSchema = z.object({
+  id: z.string(),
+  host: z.string(),
+  ports: z.record(
+    z.string(),
+    z.object({
+      host: z.string(),
+      port: z.number().int().positive().max(65535),
+    }),
+  ),
+})
+
+export type RuntimeConfigGetInput = z.infer<typeof runtimeConfigGetInputSchema>
+export type RuntimeConfigGetOutput = z.infer<typeof runtimeConfigGetOutputSchema>
+export type RuntimeResultSubmitInput = z.infer<typeof runtimeResultSubmitInputSchema>
+export type RuntimeResultSubmitOutput = z.infer<typeof runtimeResultSubmitOutputSchema>
+export type RuntimeSidecarReadiness = z.infer<typeof runtimeSidecarReadinessSchema>
+export type RuntimeSidecarStartInput = z.infer<typeof runtimeSidecarStartInputSchema>
+export type RuntimeSidecarStartOutput = z.infer<typeof runtimeSidecarStartOutputSchema>

package/src/shared.ts

@@ -0,0 +1,15 @@
+import type { InstanceInput } from "./instance"
+import { z } from "zod"
+
+export const componentKindSchema = z.enum(["composite", "unit"])
+export type ComponentKind = z.infer<typeof componentKindSchema>
+
+export const runtimeSchema = Symbol("runtimeSchema")
+export const kind = Symbol("kind")
+export const boundaryInput = Symbol("boundaryInput")
+
+export function inputKey(input: InstanceInput): string {
+  return input.path
+    ? `${input.instanceId}:${input.output}:${input.path}`
+    : `${input.instanceId}:${input.output}`
+}

package/src/unit.ts

@@ -19,12 +19,11 @@ import {
   componentModelSchema,
   defineComponent,
   type FullComponentArgumentOptions,
-  kind,
   mapArgument,
   type ToFullComponentArgumentOptions,
   toFullComponentArgumentOptions,
 } from "./component"
-import { boundaryInput } from "./evaluation"
+import { boundaryInput, kind } from "./shared"
 
 export const componentSecretSchema = componentArgumentSchema.extend({
   /**

package/src/worker.ts

@@ -19,11 +19,21 @@ export const workerRunOptionsSchema = z.object({
    */
   workerVersionId: z.cuid2(),
 
+  /**
+   * The ID of the concrete worker instance.
+   */
+  workerInstanceId: z.cuid2(),
+
   /**
    * The URL of the backend API to connect to.
    */
   apiUrl: z.url(),
 
+  /**
+   * The host and port of the worker data endpoint reachable by the frontend gateway.
+   */
+  dataEndpoint: z.string().min(1),
+
   /**
    * The API key used to authenticate the worker with the backend.
    */

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Exeteres
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.