@highstate/contract 0.16.0 → 0.18.0

package/src/compaction.spec.ts

@@ -0,0 +1,215 @@
+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

@@ -0,0 +1,381 @@
+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
+}

package/src/component.spec.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, it } from "vitest"
+import { beforeEach, describe, expect, it } from "vitest"
 import { z } from "zod"
 import { defineComponent } from "./component"
 import { defineEntity } from "./entity"
@@ -25,7 +25,7 @@ describe("defineComponent", () => {
 
   it("should return a component with args", () => {
     const virtualMachine = defineComponent({
-      type: "proxmox.virtual_machine.v1",
+      type: "proxmox.virtual-machine.v1",
       args: {
         cores: z.number(),
       },
@@ -41,9 +41,21 @@ describe("defineComponent", () => {
   })
 
   it("should return a component with inputs", () => {
+    const resource = defineEntity({
+      type: "common.resource.v1",
+
+      schema: z.object({
+        id: z.string(),
+      }),
+    })
+
     const server = defineEntity({
       type: "common.server.v1",
 
+      includes: {
+        resource,
+      },
+
       schema: z.object({
         endpoint: z.string(),
       }),
@@ -55,6 +67,24 @@ describe("defineComponent", () => {
       },
     })
 
+    expect(server.model.directInclusions).toEqual([
+      {
+        field: "resource",
+        type: "common.resource.v1",
+        required: true,
+        multiple: false,
+      },
+    ])
+
+    const embeddedResult = server.schema.safeParse({
+      endpoint: "127.0.0.1",
+      resource: {
+        id: "test",
+      },
+    })
+
+    expect(embeddedResult.success).toBe(true)
+
     const cluster = defineComponent({
       type: "talos.cluster.v1",
       inputs: {
@@ -113,6 +143,52 @@ describe("defineComponent", () => {
     })
   })
 
+  it("should support entities with intersection schemas", () => {
+    const resource = defineEntity({
+      type: "common.resource.v1",
+
+      schema: z.object({
+        id: z.string(),
+      }),
+    })
+
+    const tagged = z.object({
+      tag: z.string(),
+    })
+
+    const server = defineEntity({
+      type: "common.server.v1",
+
+      includes: {
+        resource: { entity: resource, required: false, multiple: true },
+      },
+
+      schema: z.intersection(
+        tagged,
+        z.object({
+          endpoint: z.string(),
+        }),
+      ),
+    })
+
+    expect(server.model.directInclusions).toEqual([
+      {
+        field: "resource",
+        type: "common.resource.v1",
+        required: false,
+        multiple: true,
+      },
+    ])
+
+    expect(
+      server.schema.safeParse({
+        tag: "prod",
+        endpoint: "127.0.0.1",
+        "common.resource.v1": [{ id: "test" }],
+      }).success,
+    ).toBe(true)
+  })
+
   it("should return a component with args, inputs and outputs", () => {
     const server = defineEntity({
       type: "common.server.v1",