holarchy-eidolon-adapter 0.1.0 → 0.2.0

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "holarchy-eidolon-adapter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Eidolon ResourcePackage adapter for frozen Holarchy organization snapshots and execution bindings.",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./HolonDeploymentDefinition": "./src/HolonDeploymentDefinition.ts",
+    "./HolonDeploymentRuntime": "./src/HolonDeploymentRuntime.ts",
     "./HolonExecutionBinding": "./src/HolonExecutionBinding.ts",
     "./HolonExecutionBindingProjection": "./src/HolonExecutionBindingProjection.ts"
   },
@@ -18,9 +20,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.1.7",
-    "halfcode-compiler.xnl": "0.2.2",
-    "holarchy-core-contract": "0.1.1"
+    "ai-workflow-contract": "0.2.0",
+    "depa-actor": "0.2.2",
+    "halfcode-compiler.xnl": "0.3.0",
+    "holarchy-core-contract": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0"

package/src/HolonDeploymentDefinition.ts

@@ -0,0 +1,241 @@
+import { HolarchyEidolonAdapterError } from "./HolarchyEidolonAdapterError"
+
+export const HOLON_DEPLOYMENT_DEFINITION_SCHEMA_VERSION =
+  "eidolon.holon-deployment-definition/v1" as const
+
+export interface HolonDeploymentDefinitionFile {
+  readonly path: string
+  readonly digest: `sha256:${string}`
+  readonly sizeBytes: number
+}
+
+export interface HolonDeploymentDefinition {
+  readonly schemaVersion: typeof HOLON_DEPLOYMENT_DEFINITION_SCHEMA_VERSION
+  readonly deploymentId: string
+  readonly rootHolonRef: string
+  readonly bindingRef: `resource://${string}`
+  readonly snapshotRef: `resource://${string}`
+  readonly registryRevision: string
+  readonly snapshotTreeDigest: `sha256:${string}`
+  readonly snapshotReceiptDigest: `sha256:${string}`
+  readonly bindingBytesDigest: `sha256:${string}`
+  readonly bindingSemanticFingerprint: `sha256:${string}`
+  readonly files: readonly HolonDeploymentDefinitionFile[]
+}
+
+const REQUIRED_AUTHORITY_FILES = Object.freeze([
+  "authority/execution-binding-freeze-receipt.json",
+  "authority/execution-binding.json",
+  "authority/organization-snapshot-receipt.json",
+  "authority/organization-snapshot.json",
+] as const)
+
+const compareUtf16 = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0
+
+const invalid = (path: string, message: string): never => {
+  throw new HolarchyEidolonAdapterError(
+    "EIDOLON_HOLON_DEPLOYMENT_DEFINITION_INVALID",
+    `${path}: ${message}`,
+  )
+}
+
+function closedObject(value: unknown, location: string): Readonly<Record<string, unknown>> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return invalid(location, "Expected a plain object")
+  }
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) {
+    return invalid(location, "Expected a plain object")
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  const keys = Reflect.ownKeys(descriptors)
+  if (keys.some((key) => typeof key !== "string")) {
+    return invalid(location, "Symbol properties are not allowed")
+  }
+  const result: Record<string, unknown> = Object.create(null)
+  for (const key of keys as string[]) {
+    const descriptor = descriptors[key]
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      return invalid(`${location}.${key}`, "Expected one enumerable own-data property")
+    }
+    result[key] = descriptor.value
+  }
+  return result
+}
+
+function exactKeys(
+  value: Readonly<Record<string, unknown>>,
+  expected: readonly string[],
+  location: string,
+): void {
+  const expectedSet = new Set(expected)
+  const extra = Object.keys(value).find((key) => !expectedSet.has(key))
+  if (extra !== undefined) invalid(`${location}.${extra}`, "Unsupported field")
+  const missing = expected.find((key) => !Object.prototype.hasOwnProperty.call(value, key))
+  if (missing !== undefined) invalid(`${location}.${missing}`, "Required field is missing")
+}
+
+function denseArray(value: unknown, location: string): readonly unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+    return invalid(location, "Expected a plain dense array")
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = descriptors[String(index)]
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      return invalid(`${location}[${index}]`, "Expected a dense enumerable own-data entry")
+    }
+  }
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (key === "length") continue
+    if (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length) {
+      return invalid(location, "Symbol and extra array properties are not allowed")
+    }
+  }
+  return value
+}
+
+function exactString(value: unknown, location: string): string {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()) {
+    return invalid(location, "Expected an exact non-empty string")
+  }
+  return value
+}
+
+function exactLiteral<T extends string>(value: unknown, expected: T, location: string): T {
+  if (value !== expected) invalid(location, `Expected '${expected}'`)
+  return expected
+}
+
+function exactIdentity(value: unknown, location: string): string {
+  const identity = exactString(value, location)
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(identity)) {
+    return invalid(location, "Expected one portable identity")
+  }
+  return identity
+}
+
+function resourceRef(value: unknown, location: string): `resource://${string}` {
+  const ref = exactString(value, location)
+  if (!ref.startsWith("resource://") || ref.slice("resource://".length).includes("://")) {
+    return invalid(location, "Expected one exact resource:// identity")
+  }
+  const identity = ref.slice("resource://".length)
+  if (!identity) invalid(location, "Expected one exact resource:// identity")
+  return ref as `resource://${string}`
+}
+
+function sha256(value: unknown, location: string): `sha256:${string}` {
+  if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value)) {
+    return invalid(location, "Expected one canonical sha256 digest")
+  }
+  return value as `sha256:${string}`
+}
+
+function relativeFilePath(value: unknown, location: string): string {
+  const filePath = exactString(value, location)
+  const segments = filePath.split("/")
+  if (filePath.startsWith("/") || filePath.includes("\\")
+    || segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    return invalid(location, "Expected one portable containment-safe relative file path")
+  }
+  return filePath
+}
+
+function file(value: unknown, index: number): HolonDeploymentDefinitionFile {
+  const location = `$.files[${index}]`
+  const record = closedObject(value, location)
+  exactKeys(record, ["path", "digest", "sizeBytes"], location)
+  if (!Number.isSafeInteger(record.sizeBytes) || (record.sizeBytes as number) < 0) {
+    invalid(`${location}.sizeBytes`, "Expected a non-negative safe integer")
+  }
+  return Object.freeze({
+    path: relativeFilePath(record.path, `${location}.path`),
+    digest: sha256(record.digest, `${location}.digest`),
+    sizeBytes: record.sizeBytes as number,
+  })
+}
+
+export function normalizeHolonDeploymentDefinition(value: unknown): HolonDeploymentDefinition {
+  const record = closedObject(value, "$")
+  exactKeys(record, [
+    "schemaVersion",
+    "deploymentId",
+    "rootHolonRef",
+    "bindingRef",
+    "snapshotRef",
+    "registryRevision",
+    "snapshotTreeDigest",
+    "snapshotReceiptDigest",
+    "bindingBytesDigest",
+    "bindingSemanticFingerprint",
+    "files",
+  ], "$")
+  const files = denseArray(record.files, "$.files")
+    .map((entry, index) => file(entry, index))
+    .sort((left, right) => compareUtf16(left.path, right.path))
+  if (files.length === 0 || new Set(files.map((entry) => entry.path)).size !== files.length) {
+    invalid("$.files", "Expected a non-empty list with unique file paths")
+  }
+  for (const required of REQUIRED_AUTHORITY_FILES) {
+    if (!files.some((entry) => entry.path === required)) {
+      invalid("$.files", `Required authority file '${required}' is missing`)
+    }
+  }
+  if (!files.some((entry) => /^\.agent-resources\/(global|workspace)\/manifest\.xnl$/.test(entry.path))) {
+    invalid("$.files", "At least one frozen ResourcePackage layer manifest is required")
+  }
+  return Object.freeze({
+    schemaVersion: exactLiteral(
+      record.schemaVersion,
+      HOLON_DEPLOYMENT_DEFINITION_SCHEMA_VERSION,
+      "$.schemaVersion",
+    ),
+    deploymentId: exactIdentity(record.deploymentId, "$.deploymentId"),
+    rootHolonRef: exactIdentity(record.rootHolonRef, "$.rootHolonRef"),
+    bindingRef: resourceRef(record.bindingRef, "$.bindingRef"),
+    snapshotRef: resourceRef(record.snapshotRef, "$.snapshotRef"),
+    registryRevision: sha256(record.registryRevision, "$.registryRevision"),
+    snapshotTreeDigest: sha256(record.snapshotTreeDigest, "$.snapshotTreeDigest"),
+    snapshotReceiptDigest: sha256(record.snapshotReceiptDigest, "$.snapshotReceiptDigest"),
+    bindingBytesDigest: sha256(record.bindingBytesDigest, "$.bindingBytesDigest"),
+    bindingSemanticFingerprint: sha256(
+      record.bindingSemanticFingerprint,
+      "$.bindingSemanticFingerprint",
+    ),
+    files: Object.freeze(files),
+  })
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false
+  for (let index = 0; index < left.byteLength; index += 1) {
+    if (left[index] !== right[index]) return false
+  }
+  return true
+}
+
+export function canonicalHolonDeploymentDefinitionBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(normalizeHolonDeploymentDefinition(value)))
+}
+
+export function parseHolonDeploymentDefinitionBytes(bytes: Uint8Array): HolonDeploymentDefinition {
+  let decoded: string
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  } catch {
+    return invalid("$bytes", "Definition bytes are not valid UTF-8")
+  }
+  let value: unknown
+  try {
+    value = JSON.parse(decoded)
+  } catch {
+    return invalid("$bytes", "Definition bytes are not valid JSON")
+  }
+  const definition = normalizeHolonDeploymentDefinition(value)
+  if (!sameBytes(bytes, canonicalHolonDeploymentDefinitionBytes(definition))) {
+    return invalid("$bytes", "Definition bytes are not canonical")
+  }
+  return definition
+}

package/src/HolonDeploymentRuntime.ts

@@ -0,0 +1,388 @@
+import {
+  parseActorRegistrationReceipt,
+  type ActorRegistrationReceipt,
+} from "depa-actor"
+import type { AIAgentSelector } from "ai-workflow-contract"
+
+import { HolarchyEidolonAdapterError } from "./HolarchyEidolonAdapterError"
+
+export const HOLON_DEPLOYMENT_RUNTIME_SCHEMA_VERSION =
+  "eidolon.holon-deployment-runtime/v1" as const
+
+export type HolonCoordinatorLifecycleStatus = "registered" | "ready" | "stopped"
+export type HolonMemberRuntimeLifecycleStatus = "registered" | "ready" | "stopped"
+export type HolonTaskSpaceSubscriptionStatus = "observing" | "paused" | "closed"
+
+export type HolonMemberRuntimeIsolation =
+  | Readonly<{ readonly mode: "shared" }>
+  | Readonly<{
+      readonly mode: "isolated"
+      readonly scope: "task-space" | "workflow-run"
+      readonly isolationKey: string
+    }>
+
+export type HolonGenericSessionRef =
+  | Readonly<{
+      readonly mode: "task-attempt"
+      readonly taskSpaceId: string
+      readonly taskId: string
+      readonly claimId: string
+      readonly attempt: number
+      readonly workflowInstanceId?: string
+      readonly runId?: string
+      readonly sessionRef: string
+    }>
+  | Readonly<{
+      readonly mode: "targeted-agent-instance"
+      readonly selector: AIAgentSelector
+      readonly sessionRef: string
+    }>
+
+export interface HolonCoordinatorLifecycleFact {
+  readonly holonRef: string
+  readonly status: HolonCoordinatorLifecycleStatus
+  readonly actorRef: string
+  readonly registrationReceipt: ActorRegistrationReceipt
+}
+
+export interface HolonMemberRuntimeLifecycleFact {
+  readonly runtimeRef: string
+  readonly holonRef: string
+  readonly memberRef: string
+  readonly isolation: HolonMemberRuntimeIsolation
+  readonly status: HolonMemberRuntimeLifecycleStatus
+  readonly actorRef: string
+  readonly registrationReceipt: ActorRegistrationReceipt
+  readonly sessions: readonly HolonGenericSessionRef[]
+}
+
+export interface HolonTaskSpaceSubscriptionFact {
+  readonly taskSpaceId: string
+  readonly holonRef: string
+  readonly cursor: string
+  readonly status: HolonTaskSpaceSubscriptionStatus
+}
+
+export interface HolonDeploymentRuntimeSnapshot {
+  readonly schemaVersion: typeof HOLON_DEPLOYMENT_RUNTIME_SCHEMA_VERSION
+  readonly deploymentId: string
+  readonly definitionSemanticFingerprint: `sha256:${string}`
+  readonly revision: number
+  readonly coordinators: readonly HolonCoordinatorLifecycleFact[]
+  readonly members: readonly HolonMemberRuntimeLifecycleFact[]
+  readonly subscriptions: readonly HolonTaskSpaceSubscriptionFact[]
+}
+
+const compareUtf16 = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0
+
+const invalid = (location: string, message: string): never => {
+  throw new HolarchyEidolonAdapterError(
+    "EIDOLON_HOLON_DEPLOYMENT_RUNTIME_INVALID",
+    `${location}: ${message}`,
+  )
+}
+
+function closedObject(value: unknown, location: string): Readonly<Record<string, unknown>> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return invalid(location, "Expected a plain object")
+  }
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) {
+    return invalid(location, "Expected a plain object")
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  const keys = Reflect.ownKeys(descriptors)
+  if (keys.some((key) => typeof key !== "string")) {
+    return invalid(location, "Symbol properties are not allowed")
+  }
+  const result: Record<string, unknown> = Object.create(null)
+  for (const key of keys as string[]) {
+    const descriptor = descriptors[key]
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      return invalid(`${location}.${key}`, "Expected one enumerable own-data property")
+    }
+    result[key] = descriptor.value
+  }
+  return result
+}
+
+function exactKeys(value: Readonly<Record<string, unknown>>, expected: readonly string[], location: string): void {
+  const allowed = new Set(expected)
+  const extra = Object.keys(value).find((key) => !allowed.has(key))
+  if (extra !== undefined) invalid(`${location}.${extra}`, "Unsupported field")
+  const missing = expected.find((key) => !Object.prototype.hasOwnProperty.call(value, key))
+  if (missing !== undefined) invalid(`${location}.${missing}`, "Required field is missing")
+}
+
+function denseArray(value: unknown, location: string): readonly unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+    return invalid(location, "Expected a plain dense array")
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = descriptors[String(index)]
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      return invalid(`${location}[${index}]`, "Expected a dense enumerable own-data entry")
+    }
+  }
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (key === "length") continue
+    if (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length) {
+      return invalid(location, "Symbol and extra array properties are not allowed")
+    }
+  }
+  return value
+}
+
+function exactString(value: unknown, location: string): string {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()
+    || value !== value.normalize("NFC") || /[\u0000-\u001f\u007f]/.test(value)) {
+    return invalid(location, "Expected one exact canonical non-empty string")
+  }
+  return value
+}
+
+function exactLiteral<T extends string>(value: unknown, expected: T, location: string): T {
+  if (value !== expected) invalid(location, `Expected '${expected}'`)
+  return expected
+}
+
+function exactUnion<T extends string>(value: unknown, expected: readonly T[], location: string): T {
+  const exact = exactString(value, location)
+  if (!expected.includes(exact as T)) invalid(location, `Expected ${expected.join(" | ")}`)
+  return exact as T
+}
+
+function digest(value: unknown, location: string): `sha256:${string}` {
+  if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value)) {
+    return invalid(location, "Expected one canonical sha256 digest")
+  }
+  return value as `sha256:${string}`
+}
+
+function receipt(value: unknown, location: string): ActorRegistrationReceipt {
+  try {
+    return parseActorRegistrationReceipt(value)
+  } catch (error) {
+    return invalid(location, error instanceof Error ? error.message : "Invalid depa-actor registration receipt")
+  }
+}
+
+function isolation(value: unknown, location: string): HolonMemberRuntimeIsolation {
+  const record = closedObject(value, location)
+  const mode = exactString(record.mode, `${location}.mode`)
+  if (mode === "shared") {
+    exactKeys(record, ["mode"], location)
+    return Object.freeze({ mode })
+  }
+  if (mode === "isolated") {
+    exactKeys(record, ["mode", "scope", "isolationKey"], location)
+    return Object.freeze({
+      mode,
+      scope: exactUnion(record.scope, ["task-space", "workflow-run"] as const, `${location}.scope`),
+      isolationKey: exactString(record.isolationKey, `${location}.isolationKey`),
+    })
+  }
+  return invalid(`${location}.mode`, "Expected shared | isolated")
+}
+
+function coordinator(value: unknown, index: number): HolonCoordinatorLifecycleFact {
+  const location = `$.coordinators[${index}]`
+  const record = closedObject(value, location)
+  exactKeys(record, ["holonRef", "status", "actorRef", "registrationReceipt"], location)
+  const registrationReceipt = receipt(record.registrationReceipt, `${location}.registrationReceipt`)
+  if (registrationReceipt.address.actorKind !== "coordinator") {
+    invalid(`${location}.registrationReceipt.address.actorKind`, "Expected coordinator")
+  }
+  return Object.freeze({
+    holonRef: exactString(record.holonRef, `${location}.holonRef`),
+    status: exactUnion(record.status, ["registered", "ready", "stopped"] as const, `${location}.status`),
+    actorRef: exactString(record.actorRef, `${location}.actorRef`),
+    registrationReceipt,
+  })
+}
+
+function session(value: unknown, location: string): HolonGenericSessionRef {
+  const record = closedObject(value, location)
+  const mode = exactString(record.mode, `${location}.mode`)
+  if (mode === "task-attempt") {
+    const optional = ["workflowInstanceId", "runId"].filter((key) => (
+      Object.prototype.hasOwnProperty.call(record, key)
+    ))
+    exactKeys(record, [
+      "mode", "taskSpaceId", "taskId", "claimId", "attempt", "sessionRef", ...optional,
+    ], location)
+    if (!Number.isSafeInteger(record.attempt) || (record.attempt as number) <= 0) {
+      invalid(`${location}.attempt`, "Expected one positive safe integer")
+    }
+    return Object.freeze({
+      mode,
+      taskSpaceId: exactString(record.taskSpaceId, `${location}.taskSpaceId`),
+      taskId: exactString(record.taskId, `${location}.taskId`),
+      claimId: exactString(record.claimId, `${location}.claimId`),
+      attempt: record.attempt as number,
+      ...(record.workflowInstanceId === undefined
+        ? {}
+        : { workflowInstanceId: exactString(record.workflowInstanceId, `${location}.workflowInstanceId`) }),
+      ...(record.runId === undefined ? {} : { runId: exactString(record.runId, `${location}.runId`) }),
+      sessionRef: exactString(record.sessionRef, `${location}.sessionRef`),
+    })
+  }
+  if (mode === "targeted-agent-instance") {
+    exactKeys(record, ["mode", "selector", "sessionRef"], location)
+    const selectorRecord = closedObject(record.selector, `${location}.selector`)
+    const hasId = Object.prototype.hasOwnProperty.call(selectorRecord, "byId")
+    const hasName = Object.prototype.hasOwnProperty.call(selectorRecord, "byName")
+    if (hasId === hasName) invalid(`${location}.selector`, "Expected exactly one targeted Agent selector")
+    exactKeys(selectorRecord, [hasId ? "byId" : "byName"], `${location}.selector`)
+    const selector = (hasId
+      ? Object.freeze({ byId: exactString(selectorRecord.byId, `${location}.selector.byId`) })
+      : Object.freeze({ byName: exactString(selectorRecord.byName, `${location}.selector.byName`) })) as unknown as AIAgentSelector
+    return Object.freeze({
+      mode,
+      selector,
+      sessionRef: exactString(record.sessionRef, `${location}.sessionRef`),
+    })
+  }
+  return invalid(`${location}.mode`, "Expected task-attempt | targeted-agent-instance")
+}
+
+function sessionIdentity(value: HolonGenericSessionRef): string {
+  return value.mode === "task-attempt"
+    ? JSON.stringify([value.mode, value.taskSpaceId, value.taskId, value.claimId, value.attempt])
+    : JSON.stringify([value.mode, value.selector])
+}
+
+function member(value: unknown, index: number): HolonMemberRuntimeLifecycleFact {
+  const location = `$.members[${index}]`
+  const record = closedObject(value, location)
+  exactKeys(record, [
+    "runtimeRef",
+    "holonRef",
+    "memberRef",
+    "isolation",
+    "status",
+    "actorRef",
+    "registrationReceipt",
+    "sessions",
+  ], location)
+  const registrationReceipt = receipt(record.registrationReceipt, `${location}.registrationReceipt`)
+  if (registrationReceipt.address.actorKind !== "member") {
+    invalid(`${location}.registrationReceipt.address.actorKind`, "Expected member")
+  }
+  const sessions = denseArray(record.sessions, `${location}.sessions`)
+    .map((entry, sessionIndex) => session(entry, `${location}.sessions[${sessionIndex}]`))
+    .sort((left, right) => compareUtf16(sessionIdentity(left), sessionIdentity(right)))
+  if (new Set(sessions.map(sessionIdentity)).size !== sessions.length) {
+    invalid(`${location}.sessions`, "Session scope identities must be unique")
+  }
+  return Object.freeze({
+    runtimeRef: exactString(record.runtimeRef, `${location}.runtimeRef`),
+    holonRef: exactString(record.holonRef, `${location}.holonRef`),
+    memberRef: exactString(record.memberRef, `${location}.memberRef`),
+    isolation: isolation(record.isolation, `${location}.isolation`),
+    status: exactUnion(record.status, ["registered", "ready", "stopped"] as const, `${location}.status`),
+    actorRef: exactString(record.actorRef, `${location}.actorRef`),
+    registrationReceipt,
+    sessions: Object.freeze(sessions),
+  })
+}
+
+function subscription(value: unknown, index: number): HolonTaskSpaceSubscriptionFact {
+  const location = `$.subscriptions[${index}]`
+  const record = closedObject(value, location)
+  exactKeys(record, ["taskSpaceId", "holonRef", "cursor", "status"], location)
+  return Object.freeze({
+    taskSpaceId: exactString(record.taskSpaceId, `${location}.taskSpaceId`),
+    holonRef: exactString(record.holonRef, `${location}.holonRef`),
+    cursor: exactString(record.cursor, `${location}.cursor`),
+    status: exactUnion(record.status, ["observing", "paused", "closed"] as const, `${location}.status`),
+  })
+}
+
+function unique<T>(values: readonly T[], identity: (value: T) => string, location: string): void {
+  if (new Set(values.map(identity)).size !== values.length) invalid(location, "Contains a duplicate identity")
+}
+
+export function normalizeHolonDeploymentRuntimeSnapshot(value: unknown): HolonDeploymentRuntimeSnapshot {
+  const record = closedObject(value, "$")
+  exactKeys(record, [
+    "schemaVersion",
+    "deploymentId",
+    "definitionSemanticFingerprint",
+    "revision",
+    "coordinators",
+    "members",
+    "subscriptions",
+  ], "$")
+  if (!Number.isSafeInteger(record.revision) || (record.revision as number) < 0) {
+    invalid("$.revision", "Expected one non-negative safe integer")
+  }
+  const coordinators = denseArray(record.coordinators, "$.coordinators")
+    .map(coordinator)
+    .sort((left, right) => compareUtf16(left.holonRef, right.holonRef))
+  const members = denseArray(record.members, "$.members")
+    .map(member)
+    .sort((left, right) => compareUtf16(left.runtimeRef, right.runtimeRef))
+  const subscriptions = denseArray(record.subscriptions, "$.subscriptions")
+    .map(subscription)
+    .sort((left, right) => compareUtf16(left.taskSpaceId, right.taskSpaceId))
+  unique(coordinators, (entry) => entry.holonRef, "$.coordinators")
+  unique(members, (entry) => entry.runtimeRef, "$.members")
+  unique(subscriptions, (entry) => entry.taskSpaceId, "$.subscriptions")
+  const deploymentId = exactString(record.deploymentId, "$.deploymentId")
+  for (const entry of [...coordinators, ...members]) {
+    if (entry.registrationReceipt.address.deploymentId !== deploymentId) {
+      invalid("$.deploymentId", "All actor registration receipts must belong to this deployment")
+    }
+  }
+  return Object.freeze({
+    schemaVersion: exactLiteral(
+      record.schemaVersion,
+      HOLON_DEPLOYMENT_RUNTIME_SCHEMA_VERSION,
+      "$.schemaVersion",
+    ),
+    deploymentId,
+    definitionSemanticFingerprint: digest(
+      record.definitionSemanticFingerprint,
+      "$.definitionSemanticFingerprint",
+    ),
+    revision: record.revision as number,
+    coordinators: Object.freeze(coordinators),
+    members: Object.freeze(members),
+    subscriptions: Object.freeze(subscriptions),
+  })
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false
+  for (let index = 0; index < left.byteLength; index += 1) {
+    if (left[index] !== right[index]) return false
+  }
+  return true
+}
+
+export function canonicalHolonDeploymentRuntimeSnapshotBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(normalizeHolonDeploymentRuntimeSnapshot(value)))
+}
+
+export function parseHolonDeploymentRuntimeSnapshotBytes(bytes: Uint8Array): HolonDeploymentRuntimeSnapshot {
+  let decoded: string
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  } catch {
+    return invalid("$bytes", "Runtime bytes are not valid UTF-8")
+  }
+  let value: unknown
+  try {
+    value = JSON.parse(decoded)
+  } catch {
+    return invalid("$bytes", "Runtime bytes are not valid JSON")
+  }
+  const snapshot = normalizeHolonDeploymentRuntimeSnapshot(value)
+  if (!sameBytes(bytes, canonicalHolonDeploymentRuntimeSnapshotBytes(snapshot))) {
+    return invalid("$bytes", "Runtime bytes are not canonical")
+  }
+  return snapshot
+}

package/src/HolonExecutionBinding.ts

@@ -1,19 +1,128 @@
+import {
+  digestCanonical,
+  type JsonSchema,
+  type KindReaderRegistration,
+  type KindSemanticContract,
+  type PortableSpec,
+} from "halfcode-compiler.xnl/resource-core"
+import {
+  createKindSpecRevision,
+  createKindSubjectOwner,
+} from "halfcode-compiler.xnl/kind-definition"
+
 export const HOLON_EXECUTION_BINDING_KIND = "HolonExecutionBinding" as const
 export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN =
   "Eidolon.AI.KindDefinition.HolonExecutionBinding" as const
 export const HOLON_EXECUTION_BINDING_API_VERSION = "eidolon.ai/v1" as const
-export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_VERSION = "1.0.0" as const
+export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_SPEC_VERSION = 1 as const
+export const HOLON_EXECUTION_BINDING_KIND_OWNER_PACKAGE_ID =
+  "holarchy-eidolon-adapter" as const
+
+export const HOLON_EXECUTION_BINDING_KIND_OWNER_PACKAGE_FINGERPRINT = digestCanonical(Object.freeze({
+  authority: "holarchy-eidolon-adapter/holon-execution-binding-kind/v1",
+  ownerPackageId: HOLON_EXECUTION_BINDING_KIND_OWNER_PACKAGE_ID,
+  subjects: Object.freeze([HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN]),
+  semanticContractVersion: HOLON_EXECUTION_BINDING_API_VERSION,
+}))
+
+export const HOLON_EXECUTION_BINDING_KIND_OWNER = createKindSubjectOwner({
+  kind: HOLON_EXECUTION_BINDING_KIND,
+  subjectFqn: HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN,
+  ownerPackageId: HOLON_EXECUTION_BINDING_KIND_OWNER_PACKAGE_ID,
+  ownerPackageFingerprint: HOLON_EXECUTION_BINDING_KIND_OWNER_PACKAGE_FINGERPRINT,
+  sourceShapes: Object.freeze(["single-file"]),
+  documentCardinality: "one",
+})
+
+export const HOLON_EXECUTION_BINDING_SPEC_SCHEMA_V1: JsonSchema = Object.freeze({
+  type: "object",
+  required: Object.freeze(["properties", "body", "subdomains"]),
+  properties: Object.freeze({
+    properties: Object.freeze({
+      type: "object",
+      required: Object.freeze(["bindingBytesBase64"]),
+      properties: Object.freeze({
+        bindingBytesBase64: Object.freeze({ type: "string", minLength: 1 }),
+      }),
+      additionalProperties: false,
+    }),
+    body: Object.freeze({ type: "array", maxItems: 0 }),
+    subdomains: Object.freeze({ type: "object", maxProperties: 0 }),
+  }),
+  additionalProperties: false,
+})
+
+export const HOLON_EXECUTION_BINDING_SEMANTIC_CONTRACT_V1: KindSemanticContract = Object.freeze({
+  semanticValidatorFingerprint: digestCanonical(Object.freeze({
+    authority: "holarchy-eidolon-adapter/holon-execution-binding-kind/v1",
+    role: "canonical-binding-and-graph-validation",
+    apiVersion: HOLON_EXECUTION_BINDING_API_VERSION,
+    validators: Object.freeze([
+      "parseHolonExecutionBindingBytes",
+      "validateHolonExecutionBindingGraph",
+    ]),
+  })),
+  referenceProjectionFingerprint: digestCanonical(Object.freeze({
+    authority: "holarchy-eidolon-adapter/holon-execution-binding-kind/v1",
+    role: "closed-execution-binding-reference-projection",
+    fields: Object.freeze([
+      "snapshotRef",
+      "adapter",
+      "policy.taskProfileRef",
+      "policy.capabilityRefs",
+      "policy.toolRefs",
+      "policy.materialRefs",
+    ]),
+  })),
+  compilerInputFingerprint: digestCanonical(Object.freeze({
+    authority: "holarchy-eidolon-adapter/holon-execution-binding-kind/v1",
+    role: "authored-resource-to-canonical-binding-input",
+    fields: Object.freeze(["properties.bindingBytesBase64"]),
+    encoding: "canonical-base64",
+  })),
+})
+
+export const HOLON_EXECUTION_BINDING_KIND_SPEC_REVISION_V1 = createKindSpecRevision({
+  kind: HOLON_EXECUTION_BINDING_KIND_OWNER.kind,
+  subjectFqn: HOLON_EXECUTION_BINDING_KIND_OWNER.subjectFqn,
+  specVersion: HOLON_EXECUTION_BINDING_KIND_DEFINITION_SPEC_VERSION,
+  specSchema: HOLON_EXECUTION_BINDING_SPEC_SCHEMA_V1,
+  semanticContract: HOLON_EXECUTION_BINDING_SEMANTIC_CONTRACT_V1,
+  sourceContractFingerprint: HOLON_EXECUTION_BINDING_KIND_OWNER.sourceContract.sourceContractFingerprint,
+  stability: "stable",
+})
+
+function renderHolonExecutionBindingKindDefinition(): string {
+  const owner = HOLON_EXECUTION_BINDING_KIND_OWNER
+  const revision = HOLON_EXECUTION_BINDING_KIND_SPEC_REVISION_V1
+  return [
+    `<KindDefinition #${HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN} envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {`,
+    '  lifecycle = "Stable"',
+    `  resourceKind = "${owner.kind}"`,
+    `  subjectFqn = "${owner.subjectFqn}"`,
+    '  sourceShapes = ["single-file"]',
+    `  documentCardinality = "${owner.sourceContract.documentCardinality}"`,
+    '  description = "Maps one frozen Holon Member or Role identity to an exact Eidolon execution adapter closure."',
+    '} (',
+    '  <SpecRevisions [',
+    `    <SpecRevision #v${revision.specVersion} {`,
+    `      specVersion = ${revision.specVersion}`,
+    '      schemaRef = "vfs://./spec-v1.schema.json"',
+    `      schemaFingerprint = "${revision.schemaFingerprint}"`,
+    `      contractFingerprint = "${revision.contractFingerprint}"`,
+    `      semanticValidatorFingerprint = "${revision.semanticContract.semanticValidatorFingerprint}"`,
+    `      referenceProjectionFingerprint = "${revision.semanticContract.referenceProjectionFingerprint}"`,
+    `      compilerInputFingerprint = "${revision.semanticContract.compilerInputFingerprint}"`,
+    `      stability = "${revision.stability}"`,
+    '    }>',
+    '  ]>',
+    ')>',
+    '',
+  ].join("\n")
+}
 
 export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_SOURCE =
-  `<KindDefinition #Eidolon.AI.KindDefinition.HolonExecutionBinding apiVersion="halfcode.resources/v1" version="1.0.0" {
-  lifecycle = "Stable"
-  resourceKind = "HolonExecutionBinding"
-  sourceShapes = ["single-file"]
-  currentApiVersion = "eidolon.ai/v1"
-  supportedApiVersions = ["eidolon.ai/v1"]
-  description = "Maps one frozen Holon Member or Role identity to an exact Eidolon execution adapter closure."
-}>
-` as const
+  renderHolonExecutionBindingKindDefinition()
 
 export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_BYTES: Readonly<Uint8Array> =
   new TextEncoder().encode(HOLON_EXECUTION_BINDING_KIND_DEFINITION_SOURCE)
@@ -331,6 +440,41 @@ export function parseHolonExecutionBindingBytes(bytes: Uint8Array): HolonExecuti
   return binding
 }
 
+function canonicalBase64SpecBytes(spec: PortableSpec, property: string): Uint8Array {
+  const properties = closedObject(spec.properties, "$.properties")
+  exactKeys(properties, [property], "$.properties")
+  const value = exactString(properties[property], `$.properties.${property}`)
+  let bytes: Uint8Array
+  try {
+    bytes = Uint8Array.from(Buffer.from(value, "base64"))
+  } catch {
+    return invalid(`$.properties.${property}`, "Expected canonical base64")
+  }
+  if (bytes.byteLength === 0 || Buffer.from(bytes).toString("base64") !== value) {
+    return invalid(`$.properties.${property}`, "Expected canonical non-empty base64")
+  }
+  return bytes
+}
+
+export const HOLON_EXECUTION_BINDING_KIND_READER_REGISTRATION_V1:
+KindReaderRegistration<HolonExecutionBinding> = Object.freeze({
+  readerId: "holarchy-eidolon-adapter.holon-execution-binding.v1",
+  subjectFqn: HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN,
+  readerSpecVersion: HOLON_EXECUTION_BINDING_KIND_DEFINITION_SPEC_VERSION,
+  contractFingerprint: HOLON_EXECUTION_BINDING_KIND_SPEC_REVISION_V1.contractFingerprint,
+  readerImplementationFingerprint: digestCanonical(Object.freeze({
+    authority: "holarchy-eidolon-adapter/holon-execution-binding-reader/v1",
+    implementation: Object.freeze([
+      "canonicalBase64SpecBytes",
+      "parseHolonExecutionBindingBytes",
+    ]),
+  })),
+  compatibilityPolicy: "exact",
+  read: (spec: PortableSpec) => parseHolonExecutionBindingBytes(
+    canonicalBase64SpecBytes(spec, "bindingBytesBase64"),
+  ),
+})
+
 export function validateHolonExecutionBindingGraph(
   values: readonly HolonExecutionBinding[],
 ): readonly HolonExecutionBinding[] {

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from "./HolarchyEidolonAdapterError"
+export * from "./HolonDeploymentDefinition"
+export * from "./HolonDeploymentRuntime"
 export * from "./HolonExecutionBinding"
 export * from "./HolonExecutionBindingProjection"