@highstate/contract 0.18.0 → 0.20.0

package/src/unit.ts

@@ -13,6 +13,8 @@ import {
   type ComponentInputSpec,
   type ComponentModel,
   type ComponentOptions,
+  type ComponentOutputOptions,
+  type ComponentOutputOptionsToSpec,
   componentArgumentSchema,
   componentModelSchema,
   defineComponent,
@@ -22,6 +24,7 @@ import {
   type ToFullComponentArgumentOptions,
   toFullComponentArgumentOptions,
 } from "./component"
+import { boundaryInput } from "./evaluation"
 
 export const componentSecretSchema = componentArgumentSchema.extend({
   /**
@@ -48,7 +51,7 @@ type UnitOptions<
   TType extends VersionedName,
   TArgs extends Record<string, ComponentArgumentOptions>,
   TInputs extends Record<string, ComponentInputOptions>,
-  TOutputs extends Record<string, ComponentInputOptions>,
+  TOutputs extends Record<string, ComponentOutputOptions<TInputs>>,
   TSecrets extends Record<string, ComponentSecretOptions>,
 > = Omit<ComponentOptions<TType, TArgs, TInputs, TOutputs>, "create"> & {
   source: UnitSource
@@ -97,7 +100,12 @@ export type Unit<
   TInputs extends Record<string, ComponentInputSpec> = Record<string, never>,
   TOutputs extends Record<string, ComponentInputSpec> = Record<string, never>,
   TSecrets extends Record<string, unknown> = Record<string, never>,
-> = Component<TType, TArgs, TInputs, TOutputs> & {
+  TInputOptions extends Record<string, ComponentInputOptions> = Record<string, never>,
+  TOutputOptions extends Record<string, ComponentOutputOptions<TInputOptions>> = Record<
+    string,
+    never
+  >,
+> = Component<TType, TArgs, TInputs, TOutputs, "unit", TInputOptions, TOutputOptions> & {
   /**
    * Holds the type of the unit secrets.
    *
@@ -115,7 +123,7 @@ export function defineUnit<
   TType extends VersionedName = VersionedName,
   TArgs extends Record<string, ComponentArgumentOptions> = Record<string, never>,
   TInputs extends Record<string, ComponentInputOptions> = Record<string, never>,
-  TOutputs extends Record<string, ComponentInputOptions> = Record<string, never>,
+  TOutputs extends Record<string, ComponentOutputOptions<TInputs>> = Record<string, never>,
   TSecrets extends Record<string, ComponentSecretOptions> = Record<string, never>,
 >(
   options: UnitOptions<TType, TArgs, TInputs, TOutputs, TSecrets>,
@@ -123,26 +131,34 @@ export function defineUnit<
   TType,
   { [K in keyof TArgs]: ComponentArgumentOptionsToSchema<TArgs[K]> },
   { [K in keyof TInputs]: ComponentInputOptionsToSpec<TInputs[K]> },
-  { [K in keyof TOutputs]: ComponentInputOptionsToSpec<TOutputs[K]> },
-  { [K in keyof TSecrets]: ComponentArgumentOptionsToSchema<TSecrets[K]> }
+  { [K in keyof TOutputs]: ComponentOutputOptionsToSpec<TOutputs[K], TInputs> },
+  { [K in keyof TSecrets]: ComponentArgumentOptionsToSchema<TSecrets[K]> },
+  TInputs,
+  TOutputs
 > {
   if (!options.source) {
     throw new Error("Unit source is required")
   }
 
-  const component = defineComponent<TType, TArgs, TInputs, TOutputs>({
+  const component = defineComponent<TType, TArgs, TInputs, TOutputs, "unit">({
     ...options,
     [kind]: "unit",
 
     create({ id }) {
-      const outputs: Record<string, InstanceInput[]> = {}
+      const outputs: Record<
+        string,
+        InstanceInput & { provided: true; [boundaryInput]: InstanceInput }
+      > = {}
       for (const key in options.outputs ?? {}) {
-        outputs[key] = [
-          {
+        outputs[key] = {
+          provided: true,
+          instanceId: id,
+          output: key,
+          [boundaryInput]: {
             instanceId: id,
             output: key,
           },
-        ]
+        }
       }
 
       return outputs as any

package/src/compaction.spec.ts

@@ -1,215 +0,0 @@
-import { describe, expect, it } from "vitest"
-import { compact, decompact } from "./compaction"
-import { HighstateSignature, objectRefSchema, objectWithIdSchema } from "./instance"
-
-describe("compaction", () => {
-  it("roundtrips primitives", () => {
-    expect(decompact(compact(null))).toBe(null)
-    expect(decompact(compact(undefined))).toBe(undefined)
-    expect(decompact(compact(true))).toBe(true)
-    expect(decompact(compact(123))).toBe(123)
-    expect(decompact(compact("abc"))).toBe("abc")
-  })
-
-  it("compacts repeated object identities", () => {
-    const shared = { x: 1 }
-    const value = { a: shared, b: shared }
-
-    const compacted = compact(value)
-
-    const compactedRecord = compacted as Record<string, unknown>
-    const aResult = objectWithIdSchema.safeParse(compactedRecord.a)
-    const bResult = objectRefSchema.safeParse(compactedRecord.b)
-
-    expect(aResult.success).toBe(true)
-    expect(bResult.success).toBe(true)
-
-    const roundtripped = decompact(compacted)
-    expect(roundtripped).toEqual(value)
-  })
-
-  it("preserves object identity on decompact", () => {
-    const shared = { x: 1 }
-    const value = { a: shared, b: shared }
-
-    const roundtripped = decompact(compact(value)) as { a: unknown; b: unknown }
-    expect(roundtripped).toEqual(value)
-    expect(roundtripped.a).toBe(roundtripped.b)
-  })
-
-  it("roundtrips self-referential objects", () => {
-    const value: { self?: unknown } = {}
-    value.self = value
-
-    const compacted = compact(value)
-    const roundtripped = decompact(compacted) as { self: unknown }
-
-    expect(roundtripped.self).toBe(roundtripped)
-  })
-
-  it("roundtrips mutual references", () => {
-    const a: { name: string; other?: unknown } = { name: "a" }
-    const b: { name: string; other?: unknown } = { name: "b" }
-
-    a.other = b
-    b.other = a
-
-    const compacted = compact({ a, b })
-    const roundtripped = decompact(compacted) as { a: { other: unknown }; b: { other: unknown } }
-
-    expect(roundtripped.a.other).toBe(roundtripped.b)
-    expect(roundtripped.b.other).toBe(roundtripped.a)
-  })
-
-  it("does not transform children of defined objects", () => {
-    const shared = { x: 1 }
-    const value = { a: shared, b: shared }
-
-    const compacted = compact(value) as Record<string, unknown>
-    const aResult = objectWithIdSchema.safeParse(compacted.a)
-    expect(aResult.success).toBe(true)
-
-    const sharedInside = (aResult.data as { value: unknown }).value
-    expect(objectWithIdSchema.safeParse(sharedInside).success).toBe(false)
-    // Refs to already-defined outer objects are allowed inside the Id value.
-    // Nested Id definitions are not.
-    expect(sharedInside).toEqual(shared)
-  })
-
-  it("assigns references so outer occurrences win in bfs", () => {
-    const shared = { x: 1 }
-    const outer = { shared }
-    const inner = { shared }
-
-    // bfs from root sees outer first, so it must be the definition site.
-    const compacted = compact({ outer, inner }) as Record<string, unknown>
-
-    const outerResult = objectWithIdSchema.safeParse(
-      (compacted.outer as Record<string, unknown>).shared,
-    )
-    const innerResult = objectRefSchema.safeParse(
-      (compacted.inner as Record<string, unknown>).shared,
-    )
-
-    if (!outerResult.success || !innerResult.success) {
-      throw new Error("Test invariant violation")
-    }
-
-    expect(innerResult.data.id).toBe(outerResult.data.id)
-  })
-
-  it("throws on unresolved refs", () => {
-    const bad = {
-      [HighstateSignature.Ref]: true,
-      id: 123,
-    }
-
-    expect(() => decompact(bad)).toThrow(/Unresolved compacted ref id/i)
-  })
-
-  it("real world case: nested entity embedding with deduped base", () => {
-    const metadata = {
-      namespace: "default",
-      name: "gw",
-      uid: "uid-1",
-      labels: { app: "demo" },
-      annotations: { a: "b" },
-    }
-
-    const resourceBase = {
-      clusterId: "c1",
-      clusterName: "cluster",
-      type: "gateway",
-      metadata,
-    }
-
-    const scopedResource = {
-      metadata,
-      clusterId: resourceBase.clusterId,
-      clusterName: resourceBase.clusterName,
-      type: resourceBase.type,
-      "k8s.resource.v1": resourceBase,
-    }
-
-    const gateway = {
-      type: "gateway",
-      metadata,
-      clusterId: resourceBase.clusterId,
-      clusterName: resourceBase.clusterName,
-      "k8s.scoped-resource.v1": scopedResource,
-      "k8s.resource.v1": resourceBase,
-    }
-
-    const compacted = compact(gateway) as Record<string, unknown>
-
-    const metadataResult = objectWithIdSchema.safeParse(compacted.metadata)
-    expect(metadataResult.success).toBe(true)
-
-    const scopedResult = compacted["k8s.scoped-resource.v1"] as Record<string, unknown>
-    const scopedMetadataRef = objectRefSchema.safeParse(scopedResult.metadata)
-    expect(scopedMetadataRef.success).toBe(true)
-    if (!metadataResult.success || !scopedMetadataRef.success) {
-      throw new Error("Test invariant violation")
-    }
-
-    expect(scopedMetadataRef.data.id).toBe(metadataResult.data.id)
-
-    // Once an object is defined (wrapped with Id), its subtree must remain untransformed.
-    const definedMetadataValue = (metadataResult.data as { value: unknown }).value
-    expect(objectWithIdSchema.safeParse(definedMetadataValue).success).toBe(false)
-    // Refs to already-defined outer objects are allowed inside the Id value.
-    // Nested Id definitions are not.
-
-    expect(compacted).toMatchInlineSnapshot(`
-      {
-        "clusterId": "c1",
-        "clusterName": "cluster",
-        "k8s.resource.v1": {
-          "348d020e-0d9e-4ae7-9415-b91af99f5339": true,
-          "id": 2,
-          "value": {
-            "clusterId": "c1",
-            "clusterName": "cluster",
-            "metadata": {
-              "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8": true,
-              "id": 1,
-            },
-            "type": "gateway",
-          },
-        },
-        "k8s.scoped-resource.v1": {
-          "clusterId": "c1",
-          "clusterName": "cluster",
-          "k8s.resource.v1": {
-            "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8": true,
-            "id": 2,
-          },
-          "metadata": {
-            "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8": true,
-            "id": 1,
-          },
-          "type": "gateway",
-        },
-        "metadata": {
-          "348d020e-0d9e-4ae7-9415-b91af99f5339": true,
-          "id": 1,
-          "value": {
-            "annotations": {
-              "a": "b",
-            },
-            "labels": {
-              "app": "demo",
-            },
-            "name": "gw",
-            "namespace": "default",
-            "uid": "uid-1",
-          },
-        },
-        "type": "gateway",
-      }
-    `)
-
-    const roundtripped = decompact(compacted)
-    expect(roundtripped).toEqual(gateway)
-  })
-})

package/src/compaction.ts

@@ -1,381 +0,0 @@
-import { mapValues } from "remeda"
-import { HighstateSignature, objectRefSchema, objectWithIdSchema } from "./instance"
-
-export function compact<T>(value: T): unknown {
-  const counts = new WeakMap<object, number>()
-  const cyclic = new WeakSet<object>()
-  const expanded = new WeakSet<object>()
-  const inStack = new WeakSet<object>()
-  const stack: object[] = []
-
-  function countIdentities(current: unknown): void {
-    if (current === null || typeof current !== "object") {
-      return
-    }
-
-    counts.set(current, (counts.get(current) ?? 0) + 1)
-
-    if (inStack.has(current)) {
-      cyclic.add(current)
-
-      for (const entry of stack) {
-        cyclic.add(entry)
-      }
-      return
-    }
-
-    if (expanded.has(current)) {
-      return
-    }
-
-    expanded.add(current)
-    inStack.add(current)
-    stack.push(current)
-
-    if (Array.isArray(current)) {
-      try {
-        for (const item of current) {
-          countIdentities(item)
-        }
-        return
-      } finally {
-        stack.pop()
-        inStack.delete(current)
-      }
-    }
-
-    try {
-      for (const entryValue of Object.values(current)) {
-        countIdentities(entryValue)
-      }
-    } finally {
-      stack.pop()
-      inStack.delete(current)
-    }
-  }
-
-  countIdentities(value)
-
-  type DefinitionSite = { parent: object; key: string | number }
-
-  const ids = new WeakMap<object, number>()
-  const definitionSites = new WeakMap<object, DefinitionSite>()
-  let nextId = 1
-
-  function ensureId(current: object): number {
-    const existing = ids.get(current)
-    if (existing !== undefined) {
-      return existing
-    }
-
-    const allocated = nextId
-    nextId += 1
-    ids.set(current, allocated)
-    return allocated
-  }
-
-  function assignDefinitionSitesBfs(root: unknown): void {
-    if (root === null || typeof root !== "object") {
-      return
-    }
-
-    const queue: Array<{ parent: object; key: string | number; value: unknown }> = []
-    const expandedQueue = new WeakSet<object>()
-
-    if (Array.isArray(root)) {
-      for (let index = 0; index < root.length; index += 1) {
-        queue.push({ parent: root, key: index, value: root[index] })
-      }
-    } else {
-      for (const [key, entryValue] of Object.entries(root)) {
-        queue.push({ parent: root, key, value: entryValue })
-      }
-    }
-
-    while (queue.length > 0) {
-      const current = queue.shift()
-      if (current === undefined) {
-        continue
-      }
-
-      if (current.value === null || typeof current.value !== "object") {
-        continue
-      }
-
-      const occurrences = counts.get(current.value) ?? 0
-      if (occurrences > 1 && definitionSites.get(current.value) === undefined) {
-        definitionSites.set(current.value, { parent: current.parent, key: current.key })
-        ensureId(current.value)
-      }
-
-      if (expandedQueue.has(current.value)) {
-        continue
-      }
-
-      expandedQueue.add(current.value)
-
-      if (Array.isArray(current.value)) {
-        for (let index = 0; index < current.value.length; index += 1) {
-          queue.push({ parent: current.value, key: index, value: current.value[index] })
-        }
-        continue
-      }
-
-      for (const [key, entryValue] of Object.entries(current.value)) {
-        queue.push({ parent: current.value, key, value: entryValue })
-      }
-    }
-  }
-
-  assignDefinitionSitesBfs(value)
-
-  const emitted = new WeakSet<object>()
-
-  function buildTreeChildren(current: object, rootOfIdValue?: object): unknown {
-    if (Array.isArray(current)) {
-      return current.map(item => buildTree(item, rootOfIdValue))
-    }
-
-    return mapValues(current, entryValue => buildTree(entryValue, rootOfIdValue))
-  }
-
-  function buildTree(current: unknown, rootOfIdValue?: object): unknown {
-    if (current === null || typeof current !== "object") {
-      return current
-    }
-
-    // Inside an Id value, never emit nested Id wrappers.
-    // Match existing real-world snapshot: do not introduce refs for nested objects
-    // unless the nested object has already been defined earlier.
-    if (rootOfIdValue !== undefined && emitted.has(current)) {
-      const id = ids.get(current)
-      if (id === undefined) {
-        throw new Error("Compaction invariant violation: missing id for repeated object")
-      }
-
-      return {
-        [HighstateSignature.Ref]: true,
-        id,
-      }
-    }
-
-    // Cycles inside an Id value require defining the cyclic objects inline,
-    // otherwise we would infinitely recurse.
-    if (rootOfIdValue !== undefined && cyclic.has(current) && !emitted.has(current)) {
-      const id = ensureId(current)
-      emitted.add(current)
-
-      return {
-        [HighstateSignature.Id]: true,
-        id,
-        value: buildTreeChildren(current, current),
-      }
-    }
-
-    return buildTreeChildren(current, rootOfIdValue)
-  }
-
-  function buildAt(parent: object, key: string | number, current: unknown): unknown {
-    if (current === null || typeof current !== "object") {
-      return current
-    }
-
-    const occurrences = counts.get(current) ?? 0
-    if (occurrences <= 1) {
-      if (Array.isArray(current)) {
-        return current.map((item, index) => buildAt(current, index, item))
-      }
-
-      return mapValues(current, (entryValue, entryKey) => buildAt(current, entryKey, entryValue))
-    }
-
-    const site = definitionSites.get(current)
-    const shouldDefineHere = site?.parent === parent && site.key === key
-
-    const id = ids.get(current)
-    if (id === undefined) {
-      throw new Error("Compaction invariant violation: missing id for repeated object")
-    }
-
-    if (!shouldDefineHere || emitted.has(current)) {
-      return {
-        [HighstateSignature.Ref]: true,
-        id,
-      }
-    }
-
-    emitted.add(current)
-
-    return {
-      [HighstateSignature.Id]: true,
-      id,
-      value: buildTreeChildren(current, current),
-    }
-  }
-
-  // Prefer keeping the top-level value unwrapped for stability.
-  if (value === null || typeof value !== "object") {
-    return value
-  }
-
-  const topLevelOccurrences = counts.get(value) ?? 0
-  if (topLevelOccurrences > 1) {
-    const id = ensureId(value)
-    emitted.add(value)
-
-    return {
-      [HighstateSignature.Id]: true,
-      id,
-      value: buildTreeChildren(value, value),
-    }
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((item, index) => buildAt(value, index, item))
-  }
-
-  return mapValues(value as Record<string, unknown>, (entryValue, entryKey) =>
-    buildAt(value as Record<string, unknown>, entryKey, entryValue),
-  )
-}
-
-export function decompact<T>(value: unknown): T {
-  const rawValuesById = new Map<number, unknown>()
-  const placeholdersById = new Map<number, unknown>()
-
-  function collect(current: unknown, visited: WeakSet<object>): void {
-    const result = objectWithIdSchema.safeParse(current)
-    if (result.success) {
-      const { id } = result.data
-      if (rawValuesById.has(id)) {
-        throw new Error(`Duplicate compacted id ${id}`)
-      }
-
-      rawValuesById.set(id, result.data.value)
-      collect(result.data.value, visited)
-      return
-    }
-
-    if (current === null || current === undefined || typeof current !== "object") {
-      return
-    }
-
-    if (visited.has(current)) {
-      return
-    }
-
-    visited.add(current)
-
-    if (Array.isArray(current)) {
-      for (const item of current) {
-        collect(item, visited)
-      }
-      return
-    }
-
-    for (const entryValue of Object.values(current)) {
-      collect(entryValue, visited)
-    }
-  }
-
-  function ensurePlaceholder(id: number): unknown {
-    const existing = placeholdersById.get(id)
-    if (existing !== undefined) {
-      return existing
-    }
-
-    const raw = rawValuesById.get(id)
-    if (raw === undefined) {
-      throw new Error(`Unresolved compacted ref id ${id}`)
-    }
-
-    let placeholder: unknown
-    if (raw !== null && typeof raw === "object") {
-      placeholder = Array.isArray(raw) ? [] : {}
-    } else {
-      placeholder = raw
-    }
-
-    placeholdersById.set(id, placeholder)
-    return placeholder
-  }
-
-  function resolve(current: unknown): unknown {
-    const refResult = objectRefSchema.safeParse(current)
-    if (refResult.success) {
-      return ensurePlaceholder(refResult.data.id)
-    }
-
-    const withIdResult = objectWithIdSchema.safeParse(current)
-    if (withIdResult.success) {
-      return ensurePlaceholder(withIdResult.data.id)
-    }
-
-    if (current === null || current === undefined || typeof current !== "object") {
-      return current
-    }
-
-    if (Array.isArray(current)) {
-      return current.map(item => resolve(item))
-    }
-
-    return mapValues(current, entryValue => resolve(entryValue))
-  }
-
-  function fillPlaceholder(id: number, visitedIds: Set<number>): void {
-    if (visitedIds.has(id)) {
-      return
-    }
-
-    visitedIds.add(id)
-
-    const raw = rawValuesById.get(id)
-    if (raw === undefined) {
-      throw new Error(`Unresolved compacted ref id ${id}`)
-    }
-
-    const placeholder = ensurePlaceholder(id)
-    if (placeholder === null || typeof placeholder !== "object") {
-      return
-    }
-
-    if (raw === null || typeof raw !== "object") {
-      throw new Error(`Compaction invariant violation: id ${id} points to non-object value`)
-    }
-
-    const resolved = resolve(raw)
-
-    if (Array.isArray(placeholder)) {
-      if (!Array.isArray(resolved)) {
-        throw new Error(`Compaction invariant violation: id ${id} array placeholder mismatch`)
-      }
-
-      placeholder.length = 0
-      for (const item of resolved) {
-        placeholder.push(item)
-      }
-      return
-    }
-
-    if (Array.isArray(resolved) || resolved === null || typeof resolved !== "object") {
-      throw new Error(`Compaction invariant violation: id ${id} object placeholder mismatch`)
-    }
-
-    for (const [key, entryValue] of Object.entries(resolved)) {
-      ;(placeholder as Record<string, unknown>)[key] = entryValue
-    }
-  }
-
-  collect(value, new WeakSet<object>())
-
-  for (const id of rawValuesById.keys()) {
-    ensurePlaceholder(id)
-  }
-
-  const visitedIds = new Set<number>()
-  for (const id of rawValuesById.keys()) {
-    fillPlaceholder(id, visitedIds)
-  }
-
-  return resolve(value) as T
-}