holarchy-eidolon-adapter 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "holarchy-eidolon-adapter",
+  "version": "0.1.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",
+    "./HolonExecutionBinding": "./src/HolonExecutionBinding.ts",
+    "./HolonExecutionBindingProjection": "./src/HolonExecutionBindingProjection.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ai-workflow-contract": "0.1.7",
+    "halfcode-compiler.xnl": "0.2.2",
+    "holarchy-core-contract": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/HolarchyEidolonAdapterError.ts

@@ -0,0 +1,9 @@
+export class HolarchyEidolonAdapterError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(`${code}: ${message}`)
+    this.name = "HolarchyEidolonAdapterError"
+  }
+}

package/src/HolonExecutionBinding.ts

@@ -0,0 +1,414 @@
+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_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
+
+export const HOLON_EXECUTION_BINDING_KIND_DEFINITION_BYTES: Readonly<Uint8Array> =
+  new TextEncoder().encode(HOLON_EXECUTION_BINDING_KIND_DEFINITION_SOURCE)
+
+export const HOLON_MEMBER_EXECUTION_ADAPTER_KINDS = Object.freeze([
+  "ai-agent",
+  "human-endpoint",
+  "service",
+  "hybrid",
+] as const)
+
+export type HolonExecutionResourceRef = `resource://${string}`
+
+export type HolonExecutionTarget =
+  | Readonly<{ readonly kind: "member"; readonly memberRef: string }>
+  | Readonly<{ readonly kind: "role"; readonly roleRef: string }>
+
+export type HolonMemberExecutionAdapter =
+  | Readonly<{
+      readonly kind: "ai-agent"
+      readonly agentDefinitionRef: HolonExecutionResourceRef
+      readonly runtimeProfileRef: HolonExecutionResourceRef
+    }>
+  | Readonly<{
+      readonly kind: "human-endpoint"
+      readonly humanEndpointRef: HolonExecutionResourceRef
+      readonly inboxProfileRef: HolonExecutionResourceRef
+    }>
+  | Readonly<{
+      readonly kind: "service"
+      readonly serviceAdapterRef: HolonExecutionResourceRef
+      readonly runtimeProfileRef: HolonExecutionResourceRef
+    }>
+  | Readonly<{
+      readonly kind: "hybrid"
+      readonly policyRef: HolonExecutionResourceRef
+      readonly candidateBindingRefs: readonly [HolonExecutionResourceRef, ...HolonExecutionResourceRef[]]
+    }>
+
+export type HolonExecutionRuntimeIntent =
+  | Readonly<{ readonly mode: "shared-member-runtime" }>
+  | Readonly<{ readonly mode: "isolated-task-runtime" }>
+
+export interface HolonExecutionPolicyV1 {
+  readonly version: "1"
+  readonly runtime: HolonExecutionRuntimeIntent
+  readonly taskProfileRef: HolonExecutionResourceRef
+  readonly capabilityRefs: readonly HolonExecutionResourceRef[]
+  readonly toolRefs: readonly HolonExecutionResourceRef[]
+  readonly materialRefs: readonly HolonExecutionResourceRef[]
+}
+
+export interface HolonExecutionBinding {
+  readonly apiVersion: typeof HOLON_EXECUTION_BINDING_API_VERSION
+  readonly kind: typeof HOLON_EXECUTION_BINDING_KIND
+  readonly bindingRef: HolonExecutionResourceRef
+  readonly snapshotRef: HolonExecutionResourceRef
+  readonly target: HolonExecutionTarget
+  readonly adapter: HolonMemberExecutionAdapter
+  readonly policy: HolonExecutionPolicyV1
+}
+
+export interface HolonExecutionInvocation {
+  readonly apiVersion: typeof HOLON_EXECUTION_BINDING_API_VERSION
+  readonly kind: "HolonExecutionInvocation"
+  readonly taskSpaceRef: string
+  readonly taskRef: string
+  readonly claimRef: string
+  readonly invocationRef: string
+  readonly targetBindingRef: HolonExecutionResourceRef
+  readonly input: ClosedValue
+  readonly materialRefs: readonly HolonExecutionResourceRef[]
+  readonly resultContractRef: HolonExecutionResourceRef
+}
+
+interface ClosedArray extends ReadonlyArray<ClosedValue> {}
+interface ClosedRecord { readonly [key: string]: ClosedValue }
+export type ClosedValue = null | string | number | boolean | ClosedArray | ClosedRecord
+
+export class HolonExecutionBindingContractError extends Error {
+  constructor(readonly path: string, message: string) {
+    super(`${path}: ${message}`)
+    this.name = "HolonExecutionBindingContractError"
+  }
+}
+
+const invalid = (path: string, message: string): never => {
+  throw new HolonExecutionBindingContractError(path, message)
+}
+
+const compareUtf16CodeUnits = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0
+
+function closedObject(value: unknown, path: string): Readonly<Record<string, unknown>> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return invalid(path, "Expected a plain object")
+  }
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype !== Object.prototype && prototype !== null) {
+    return invalid(path, "Expected a plain object")
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  const keys = Reflect.ownKeys(descriptors)
+  if (keys.some((key) => typeof key !== "string")) {
+    return invalid(path, "Symbol properties are not allowed")
+  }
+  const result: Record<string, unknown> = Object.create(null)
+  for (const key of (keys as string[]).sort(compareUtf16CodeUnits)) {
+    const descriptor = descriptors[key]
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      return invalid(`${path}.${key}`, "Expected one enumerable own-data property")
+    }
+    result[key] = descriptor.value
+  }
+  return result
+}
+
+function exactKeys(
+  value: Readonly<Record<string, unknown>>,
+  expected: readonly string[],
+  path: string,
+): void {
+  const expectedSet = new Set(expected)
+  const extra = Object.keys(value).find((key) => !expectedSet.has(key))
+  if (extra !== undefined) invalid(`${path}.${extra}`, "Unsupported field")
+  const missing = expected.find((key) => !Object.prototype.hasOwnProperty.call(value, key))
+  if (missing !== undefined) invalid(`${path}.${missing}`, "Required field is missing")
+}
+
+function exactString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()) {
+    return invalid(path, "Expected an exact non-empty string")
+  }
+  return value
+}
+
+function exactLiteral<T extends string>(value: unknown, expected: T, path: string): T {
+  if (value !== expected) invalid(path, `Expected '${expected}'`)
+  return expected
+}
+
+function resourceRef(value: unknown, path: string): HolonExecutionResourceRef {
+  const exact = exactString(value, path)
+  const prefix = "resource://"
+  if (!exact.startsWith(prefix)) invalid(path, "Expected an exact resource:// reference")
+  const identity = exact.slice(prefix.length)
+  if (!identity || identity.includes("://")) invalid(path, "Expected one exact Resource identity")
+  return exact as HolonExecutionResourceRef
+}
+
+function denseArray(value: unknown, path: string): readonly unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+    return invalid(path, "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(`${path}[${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(path, "Symbol and extra array properties are not allowed")
+    }
+  }
+  return value
+}
+
+function resourceRefs(
+  value: unknown,
+  path: string,
+  options: { readonly nonEmpty?: boolean; readonly sort?: boolean } = {},
+): readonly HolonExecutionResourceRef[] {
+  const refs = denseArray(value, path).map((entry, index) => resourceRef(entry, `${path}[${index}]`))
+  if (options.nonEmpty && refs.length === 0) invalid(path, "Expected at least one Resource reference")
+  if (new Set(refs).size !== refs.length) invalid(path, "Resource reference list contains a duplicate")
+  if (options.sort) refs.sort(compareUtf16CodeUnits)
+  return Object.freeze(refs)
+}
+
+function target(value: unknown): HolonExecutionTarget {
+  const record = closedObject(value, "$.target")
+  const kind = exactString(record.kind, "$.target.kind")
+  if (kind === "member") {
+    exactKeys(record, ["kind", "memberRef"], "$.target")
+    return Object.freeze({ kind, memberRef: exactString(record.memberRef, "$.target.memberRef") })
+  }
+  if (kind === "role") {
+    exactKeys(record, ["kind", "roleRef"], "$.target")
+    return Object.freeze({ kind, roleRef: exactString(record.roleRef, "$.target.roleRef") })
+  }
+  return invalid("$.target.kind", "Expected 'member' or 'role'")
+}
+
+function adapter(value: unknown): HolonMemberExecutionAdapter {
+  const record = closedObject(value, "$.adapter")
+  const kind = exactString(record.kind, "$.adapter.kind")
+  if (kind === "ai-agent") {
+    exactKeys(record, ["kind", "agentDefinitionRef", "runtimeProfileRef"], "$.adapter")
+    return Object.freeze({
+      kind,
+      agentDefinitionRef: resourceRef(record.agentDefinitionRef, "$.adapter.agentDefinitionRef"),
+      runtimeProfileRef: resourceRef(record.runtimeProfileRef, "$.adapter.runtimeProfileRef"),
+    })
+  }
+  if (kind === "human-endpoint") {
+    exactKeys(record, ["kind", "humanEndpointRef", "inboxProfileRef"], "$.adapter")
+    return Object.freeze({
+      kind,
+      humanEndpointRef: resourceRef(record.humanEndpointRef, "$.adapter.humanEndpointRef"),
+      inboxProfileRef: resourceRef(record.inboxProfileRef, "$.adapter.inboxProfileRef"),
+    })
+  }
+  if (kind === "service") {
+    exactKeys(record, ["kind", "serviceAdapterRef", "runtimeProfileRef"], "$.adapter")
+    return Object.freeze({
+      kind,
+      serviceAdapterRef: resourceRef(record.serviceAdapterRef, "$.adapter.serviceAdapterRef"),
+      runtimeProfileRef: resourceRef(record.runtimeProfileRef, "$.adapter.runtimeProfileRef"),
+    })
+  }
+  if (kind === "hybrid") {
+    exactKeys(record, ["kind", "policyRef", "candidateBindingRefs"], "$.adapter")
+    const refs = resourceRefs(record.candidateBindingRefs, "$.adapter.candidateBindingRefs", { nonEmpty: true })
+    return Object.freeze({
+      kind,
+      policyRef: resourceRef(record.policyRef, "$.adapter.policyRef"),
+      candidateBindingRefs: refs as readonly [HolonExecutionResourceRef, ...HolonExecutionResourceRef[]],
+    })
+  }
+  return invalid("$.adapter.kind", "Expected one closed execution adapter kind")
+}
+
+function policy(value: unknown): HolonExecutionPolicyV1 {
+  const record = closedObject(value, "$.policy")
+  exactKeys(record, [
+    "version",
+    "runtime",
+    "taskProfileRef",
+    "capabilityRefs",
+    "toolRefs",
+    "materialRefs",
+  ], "$.policy")
+  exactLiteral(record.version, "1", "$.policy.version")
+  const runtime = closedObject(record.runtime, "$.policy.runtime")
+  exactKeys(runtime, ["mode"], "$.policy.runtime")
+  const mode = exactString(runtime.mode, "$.policy.runtime.mode")
+  if (mode !== "shared-member-runtime" && mode !== "isolated-task-runtime") {
+    invalid("$.policy.runtime.mode", "Expected one closed runtime intent")
+  }
+  const normalizedMode = mode as HolonExecutionRuntimeIntent["mode"]
+  return Object.freeze({
+    version: "1",
+    runtime: Object.freeze({ mode: normalizedMode }),
+    taskProfileRef: resourceRef(record.taskProfileRef, "$.policy.taskProfileRef"),
+    capabilityRefs: resourceRefs(record.capabilityRefs, "$.policy.capabilityRefs", { sort: true }),
+    toolRefs: resourceRefs(record.toolRefs, "$.policy.toolRefs", { sort: true }),
+    materialRefs: resourceRefs(record.materialRefs, "$.policy.materialRefs", { sort: true }),
+  })
+}
+
+export function normalizeHolonExecutionBinding(value: unknown): HolonExecutionBinding {
+  const record = closedObject(value, "$")
+  exactKeys(record, [
+    "apiVersion",
+    "kind",
+    "bindingRef",
+    "snapshotRef",
+    "target",
+    "adapter",
+    "policy",
+  ], "$")
+  return Object.freeze({
+    apiVersion: exactLiteral(record.apiVersion, HOLON_EXECUTION_BINDING_API_VERSION, "$.apiVersion"),
+    kind: exactLiteral(record.kind, HOLON_EXECUTION_BINDING_KIND, "$.kind"),
+    bindingRef: resourceRef(record.bindingRef, "$.bindingRef"),
+    snapshotRef: resourceRef(record.snapshotRef, "$.snapshotRef"),
+    target: target(record.target),
+    adapter: adapter(record.adapter),
+    policy: policy(record.policy),
+  })
+}
+
+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 canonicalHolonExecutionBindingBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(normalizeHolonExecutionBinding(value)))
+}
+
+export function parseHolonExecutionBindingBytes(bytes: Uint8Array): HolonExecutionBinding {
+  let decoded: string
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  } catch {
+    return invalid("$bytes", "Binding bytes are not valid UTF-8")
+  }
+  let value: unknown
+  try {
+    value = JSON.parse(decoded)
+  } catch {
+    return invalid("$bytes", "Binding bytes are not valid JSON")
+  }
+  const binding = normalizeHolonExecutionBinding(value)
+  if (!sameBytes(bytes, canonicalHolonExecutionBindingBytes(binding))) {
+    return invalid("$bytes", "Binding bytes are not canonical")
+  }
+  return binding
+}
+
+export function validateHolonExecutionBindingGraph(
+  values: readonly HolonExecutionBinding[],
+): readonly HolonExecutionBinding[] {
+  const bindings = values.map(normalizeHolonExecutionBinding)
+  const byRef = new Map<HolonExecutionResourceRef, HolonExecutionBinding>()
+  for (const binding of bindings) {
+    if (byRef.has(binding.bindingRef)) {
+      invalid("$.bindings", `Duplicate binding identity '${binding.bindingRef}'`)
+    }
+    byRef.set(binding.bindingRef, binding)
+  }
+  const visiting = new Set<HolonExecutionResourceRef>()
+  const visited = new Set<HolonExecutionResourceRef>()
+  const visit = (bindingRef: HolonExecutionResourceRef): void => {
+    if (visited.has(bindingRef)) return
+    if (visiting.has(bindingRef)) invalid("$.bindings", `Hybrid binding cycle includes '${bindingRef}'`)
+    const binding = byRef.get(bindingRef)
+      ?? invalid("$.bindings", `Hybrid candidate '${bindingRef}' is unresolved`)
+    visiting.add(bindingRef)
+    if (binding.adapter.kind === "hybrid") {
+      for (const candidateRef of binding.adapter.candidateBindingRefs) visit(candidateRef)
+    }
+    visiting.delete(bindingRef)
+    visited.add(bindingRef)
+  }
+  for (const binding of bindings) visit(binding.bindingRef)
+  return Object.freeze(bindings)
+}
+
+function cloneClosedValue(value: unknown, path: string, active = new Set<object>()): ClosedValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) invalid(path, "Expected a finite number")
+    return value
+  }
+  if (typeof value !== "object") return invalid(path, "Expected JSON-compatible plain data")
+  if (active.has(value)) return invalid(path, "Cycles are not allowed")
+  active.add(value)
+  try {
+    if (Array.isArray(value)) {
+      return Object.freeze(denseArray(value, path).map((entry, index) =>
+        cloneClosedValue(entry, `${path}[${index}]`, active)))
+    }
+    const record = closedObject(value, path)
+    const output: Record<string, ClosedValue> = Object.create(null)
+    for (const key of Object.keys(record).sort(compareUtf16CodeUnits)) {
+      output[key] = cloneClosedValue(record[key], `${path}.${key}`, active)
+    }
+    return Object.freeze(output)
+  } finally {
+    active.delete(value)
+  }
+}
+
+export function normalizeHolonExecutionInvocation(value: unknown): HolonExecutionInvocation {
+  const record = closedObject(value, "$")
+  exactKeys(record, [
+    "apiVersion",
+    "kind",
+    "taskSpaceRef",
+    "taskRef",
+    "claimRef",
+    "invocationRef",
+    "targetBindingRef",
+    "input",
+    "materialRefs",
+    "resultContractRef",
+  ], "$")
+  return Object.freeze({
+    apiVersion: exactLiteral(record.apiVersion, HOLON_EXECUTION_BINDING_API_VERSION, "$.apiVersion"),
+    kind: exactLiteral(record.kind, "HolonExecutionInvocation", "$.kind"),
+    taskSpaceRef: exactString(record.taskSpaceRef, "$.taskSpaceRef"),
+    taskRef: exactString(record.taskRef, "$.taskRef"),
+    claimRef: exactString(record.claimRef, "$.claimRef"),
+    invocationRef: exactString(record.invocationRef, "$.invocationRef"),
+    targetBindingRef: resourceRef(record.targetBindingRef, "$.targetBindingRef"),
+    input: cloneClosedValue(record.input, "$.input"),
+    materialRefs: resourceRefs(record.materialRefs, "$.materialRefs", { sort: true }),
+    resultContractRef: resourceRef(record.resultContractRef, "$.resultContractRef"),
+  })
+}

package/src/HolonExecutionBindingProjection.ts

@@ -0,0 +1,450 @@
+import {
+  HOLON_EXECUTION_BINDING_KIND,
+  HOLON_EXECUTION_BINDING_KIND_DEFINITION_BYTES,
+  HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN,
+  parseHolonExecutionBindingBytes,
+  validateHolonExecutionBindingGraph,
+  type HolonExecutionBinding,
+  type HolonExecutionResourceRef,
+} from "./HolonExecutionBinding"
+import {
+  HOLON_EFFECTIVE_SNAPSHOT_KIND,
+  HOLON_EFFECTIVE_SNAPSHOT_KIND_DEFINITION_BYTES,
+  HOLON_EFFECTIVE_SNAPSHOT_KIND_DEFINITION_FQN,
+  parseHolonEffectiveSnapshotBytes,
+  parseHolonEffectiveSnapshotIssuanceReceiptBytes,
+  type HolonEffectiveSnapshot,
+  type HolonEffectiveSnapshotIssuanceReceipt,
+} from "holarchy-core-contract"
+import {
+  buildResourceDependencySnapshot,
+  sha256Digest,
+  type EffectiveResourceRegistry,
+  type ResourceContentIdentity,
+  type ResourceRecord,
+} from "halfcode-compiler.xnl/resource-core"
+import type { AIWorkflowAgentResourceProjection } from "ai-workflow-contract"
+
+import { HolarchyEidolonAdapterError as EidolonResourceRegistryError } from "./HolarchyEidolonAdapterError"
+
+export interface EidolonHolonExecutionBindingProjection {
+  readonly schemaVersion: "eidolon.holon-execution-binding-projection/v1"
+  readonly resource: ResourceRecord
+  readonly binding: HolonExecutionBinding
+  readonly snapshotResource: ResourceRecord
+  readonly snapshot: HolonEffectiveSnapshot
+  readonly receipt: HolonEffectiveSnapshotIssuanceReceipt
+  readonly bindingBytesDigest: `sha256:${string}`
+  readonly receiptBytesDigest: `sha256:${string}`
+  readonly closureResourceIds: readonly string[]
+  readonly registryRevision: string
+}
+
+export interface EidolonHolonExecutionAgentProof {
+  readonly agentDefinitionRef: HolonExecutionResourceRef
+  readonly agentContentDigest: `sha256:${string}`
+  readonly closureResourceIds: readonly string[]
+  readonly snapshotRevision: `sha256:${string}`
+}
+
+export interface EidolonHolonExecutionBindingFreezeReceipt {
+  readonly schemaVersion: "eidolon.holon-execution-binding-freeze/v1"
+  readonly bindingRef: HolonExecutionResourceRef
+  readonly snapshotRef: HolonExecutionResourceRef
+  readonly snapshotTreeDigest: `sha256:${string}`
+  readonly snapshotReceiptDigest: `sha256:${string}`
+  readonly bindingBytesDigest: `sha256:${string}`
+  readonly registryRevision: string
+  readonly closure: readonly Readonly<{
+    readonly resourceId: string
+    readonly kind: string
+    readonly authorityDigest: `sha256:${string}`
+    readonly contentDigest: `sha256:${string}`
+  }>[]
+  readonly agentProofs: readonly EidolonHolonExecutionAgentProof[]
+  readonly semanticFingerprint: `sha256:${string}`
+}
+
+export interface HolonExecutionBindingProjectionInput {
+  readonly registry: EffectiveResourceRegistry
+  readonly contentIdentities: ReadonlyMap<string, ResourceContentIdentity>
+  readonly kindDefinitionAuthorityDigests: ReadonlyMap<string, `sha256:${string}`>
+  readonly registryRevision: string
+}
+
+export interface HolonExecutionBindingFreezeInput {
+  readonly registry: EffectiveResourceRegistry
+  readonly contentIdentities: ReadonlyMap<string, ResourceContentIdentity>
+  readonly registryRevision: string
+  readonly projection: EidolonHolonExecutionBindingProjection
+  readonly agentResources: AIWorkflowAgentResourceProjection
+}
+
+const authenticProjections = new WeakSet<object>()
+const authenticFreezeReceipts = new WeakSet<object>()
+
+export async function projectHolonExecutionBindings(
+  input: HolonExecutionBindingProjectionInput,
+): Promise<readonly EidolonHolonExecutionBindingProjection[]> {
+  const resources = [...(input.registry.byKind.get(HOLON_EXECUTION_BINDING_KIND) ?? [])]
+    .sort((left, right) => compareUtf16(left.resourceId, right.resourceId))
+  if (resources.length === 0) return Object.freeze([])
+  assertCanonicalKindDefinition(input, {
+    resourceKind: HOLON_EXECUTION_BINDING_KIND,
+    fqn: HOLON_EXECUTION_BINDING_KIND_DEFINITION_FQN,
+    bytes: HOLON_EXECUTION_BINDING_KIND_DEFINITION_BYTES,
+    code: "EIDOLON_HOLON_BINDING_KIND_DEFINITION_MISMATCH",
+  })
+  assertCanonicalKindDefinition(input, {
+    resourceKind: HOLON_EFFECTIVE_SNAPSHOT_KIND,
+    fqn: HOLON_EFFECTIVE_SNAPSHOT_KIND_DEFINITION_FQN,
+    bytes: HOLON_EFFECTIVE_SNAPSHOT_KIND_DEFINITION_BYTES,
+    code: "EIDOLON_HOLON_SNAPSHOT_KIND_DEFINITION_MISMATCH",
+  })
+
+  const decoded = resources.map((resource) => {
+    const bindingBytes = canonicalBase64Property(resource, "bindingBytesBase64")
+    const binding = parseHolonExecutionBindingBytes(bindingBytes)
+    if (binding.bindingRef !== resourceRef(resource.resourceId)) {
+      throw new EidolonResourceRegistryError(
+        "EIDOLON_HOLON_BINDING_IDENTITY_MISMATCH",
+        `HolonExecutionBinding '${resource.resourceId}' bytes select '${binding.bindingRef}'.`,
+      )
+    }
+    return Object.freeze({ resource, binding, bindingBytes })
+  })
+  const bindingGraph = validateHolonExecutionBindingGraph(decoded.map(({ binding }) => binding))
+  const decodedByRef = new Map(decoded.map((entry) => [entry.binding.bindingRef, entry]))
+
+  const projections: EidolonHolonExecutionBindingProjection[] = []
+  for (const binding of bindingGraph) {
+    const decodedBinding = decodedByRef.get(binding.bindingRef)
+    if (!decodedBinding) throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_GRAPH_INTERNAL",
+      `HolonExecutionBinding '${binding.bindingRef}' disappeared during projection.`,
+    )
+    const snapshotId = resourceId(binding.snapshotRef)
+    const snapshotResource = exactResource(input.registry, snapshotId)
+    if (snapshotResource.kind !== HOLON_EFFECTIVE_SNAPSHOT_KIND) {
+      throw new EidolonResourceRegistryError(
+        "EIDOLON_HOLON_SNAPSHOT_KIND_MISMATCH",
+        `Resource '${snapshotId}' must be a canonical ${HOLON_EFFECTIVE_SNAPSHOT_KIND} Resource.`,
+      )
+    }
+    const snapshotBytes = canonicalBase64Property(snapshotResource, "snapshotBytesBase64")
+    const snapshot = await parseHolonEffectiveSnapshotBytes(snapshotBytes)
+    const receiptBytes = canonicalBase64Property(snapshotResource, "issuanceReceiptBytesBase64")
+    const receipt = parseHolonEffectiveSnapshotIssuanceReceiptBytes(receiptBytes, snapshot)
+    assertTargetExists(binding, snapshot)
+
+    const closureResourceIds = resolveBindingClosureResourceIds(binding, decodedByRef, input.registry)
+    for (const resourceId of closureResourceIds) requiredIdentity(input.contentIdentities, resourceId)
+    requiredIdentity(input.contentIdentities, snapshotResource.resourceId)
+
+    const projection = Object.freeze({
+      schemaVersion: "eidolon.holon-execution-binding-projection/v1",
+      resource: decodedBinding.resource,
+      binding,
+      snapshotResource,
+      snapshot,
+      receipt,
+      bindingBytesDigest: sha256Digest(decodedBinding.bindingBytes),
+      receiptBytesDigest: sha256Digest(receiptBytes),
+      closureResourceIds,
+      registryRevision: input.registryRevision,
+    })
+    authenticProjections.add(projection)
+    projections.push(projection)
+  }
+  return Object.freeze(projections)
+}
+
+export function freezeHolonExecutionBinding(
+  input: HolonExecutionBindingFreezeInput,
+): EidolonHolonExecutionBindingFreezeReceipt {
+  if (!authenticProjections.has(input.projection as object)) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_PROJECTION_UNTRUSTED",
+      "Binding freeze requires the exact projection produced by the shared registry.",
+    )
+  }
+  const closure = Object.freeze(input.projection.closureResourceIds.map((resourceId) => {
+    const resource = exactResource(input.registry, resourceId)
+    const identity = requiredIdentity(input.contentIdentities, resourceId)
+    return Object.freeze({
+      resourceId,
+      kind: resource.kind,
+      authorityDigest: exactSha256(identity.authorityDigest, `${resourceId}.authorityDigest`),
+      contentDigest: exactSha256(identity.contentDigest, `${resourceId}.contentDigest`),
+    })
+  }))
+  const agentProofs = Object.freeze(agentRefs(input.projection.binding, new Map(
+    (input.registry.byKind.get(HOLON_EXECUTION_BINDING_KIND) ?? []).map((resource) => {
+      const projected = resourceRef(resource.resourceId)
+      return [projected, projected === input.projection.binding.bindingRef
+        ? input.projection.binding
+        : parseHolonExecutionBindingBytes(canonicalBase64Property(resource, "bindingBytesBase64"))]
+    }),
+  )).map((agentDefinitionRef) => {
+    const agentId = resourceId(agentDefinitionRef)
+    const agent = input.agentResources.agentDefinitions.find(
+      (candidate) => candidate.resource.resourceId === agentId,
+    )
+    if (!agent) throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_AGENT_PROJECTION_MISSING",
+      `AIAgentDefinition '${agentDefinitionRef}' has no authentic shared-registry projection.`,
+    )
+    const roots = agentClosureResourceIds(agent)
+    const dependencySnapshot = buildResourceDependencySnapshot({
+      registry: input.registry,
+      roots,
+      edges: input.agentResources.dependencyEdges,
+      contentIdentities: input.contentIdentities,
+    })
+    return Object.freeze({
+      agentDefinitionRef,
+      agentContentDigest: requiredIdentity(input.contentIdentities, agentId).contentDigest,
+      closureResourceIds: Object.freeze(dependencySnapshot.closure.map(({ resourceId }) => resourceId)),
+      snapshotRevision: dependencySnapshot.snapshotRevision,
+    })
+  }))
+  const semanticFingerprint = sha256Digest(JSON.stringify({
+    schemaVersion: "eidolon.holon-execution-binding-freeze-semantic/v1",
+    bindingRef: input.projection.binding.bindingRef,
+    snapshotRef: input.projection.binding.snapshotRef,
+    snapshotTreeDigest: input.projection.snapshot.treeDigest,
+    snapshotReceiptDigest: input.projection.receiptBytesDigest,
+    bindingBytesDigest: input.projection.bindingBytesDigest,
+    registryRevision: input.registryRevision,
+    closure,
+    agentProofs,
+  }))
+  const receipt = Object.freeze({
+    schemaVersion: "eidolon.holon-execution-binding-freeze/v1" as const,
+    bindingRef: input.projection.binding.bindingRef,
+    snapshotRef: input.projection.binding.snapshotRef,
+    snapshotTreeDigest: input.projection.snapshot.treeDigest,
+    snapshotReceiptDigest: input.projection.receiptBytesDigest,
+    bindingBytesDigest: input.projection.bindingBytesDigest,
+    registryRevision: input.registryRevision,
+    closure,
+    agentProofs,
+    semanticFingerprint,
+  })
+  authenticFreezeReceipts.add(receipt)
+  return receipt
+}
+
+export function assertHolonExecutionBindingFreezeReceipt(
+  value: EidolonHolonExecutionBindingFreezeReceipt,
+): EidolonHolonExecutionBindingFreezeReceipt {
+  if (!authenticFreezeReceipts.has(value as object)) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_FREEZE_RECEIPT_UNTRUSTED",
+      "Holon binding dispatch requires the authentic receipt produced by the shared registry freeze boundary.",
+    )
+  }
+  return value
+}
+
+function agentRefs(
+  root: HolonExecutionBinding,
+  byRef: ReadonlyMap<HolonExecutionResourceRef, HolonExecutionBinding>,
+): readonly HolonExecutionResourceRef[] {
+  const refs = new Set<HolonExecutionResourceRef>()
+  const visited = new Set<HolonExecutionResourceRef>()
+  const visit = (binding: HolonExecutionBinding): void => {
+    if (visited.has(binding.bindingRef)) return
+    visited.add(binding.bindingRef)
+    if (binding.adapter.kind === "ai-agent") refs.add(binding.adapter.agentDefinitionRef)
+    if (binding.adapter.kind === "hybrid") {
+      for (const candidateRef of binding.adapter.candidateBindingRefs) {
+        const candidate = byRef.get(candidateRef)
+        if (!candidate) throw new EidolonResourceRegistryError(
+          "EIDOLON_HOLON_BINDING_CANDIDATE_MISSING",
+          `Hybrid candidate '${candidateRef}' disappeared before freeze.`,
+        )
+        visit(candidate)
+      }
+    }
+  }
+  visit(root)
+  return Object.freeze([...refs].sort(compareUtf16))
+}
+
+function agentClosureResourceIds(
+  agent: AIWorkflowAgentResourceProjection["agentDefinitions"][number],
+): readonly string[] {
+  const ids = new Set<string>([agent.resource.resourceId])
+  for (const message of agent.messages) {
+    ids.add(message.prompt.resource.resourceId)
+    if (message.schema) ids.add(message.schema.resource.resourceId)
+  }
+  if (agent.inputSchema) ids.add(agent.inputSchema.resource.resourceId)
+  if (agent.outputSchema) ids.add(agent.outputSchema.resource.resourceId)
+  if (agent.effectPolicy) ids.add(agent.effectPolicy.resource.resourceId)
+  for (const tool of agent.tools) ids.add(tool.resource.resourceId)
+  for (const port of agent.materialPorts) ids.add(port.resource.resourceId)
+  return Object.freeze([...ids].sort(compareUtf16))
+}
+
+function assertCanonicalKindDefinition(
+  input: HolonExecutionBindingProjectionInput,
+  expected: {
+    readonly resourceKind: string
+    readonly fqn: string
+    readonly bytes: Readonly<Uint8Array>
+    readonly code: string
+  },
+): void {
+  const kindDefinition = input.registry.kindDefinitions.get(expected.resourceKind)?.definition
+  if (!kindDefinition || kindDefinition.resourceId !== expected.fqn) {
+    throw new EidolonResourceRegistryError(
+      expected.code,
+      `Kind '${expected.resourceKind}' must be registered by canonical KindDefinition '${expected.fqn}'.`,
+    )
+  }
+  const expectedDigest = sha256Digest(Uint8Array.from(expected.bytes))
+  if (input.kindDefinitionAuthorityDigests.get(expected.resourceKind) !== expectedDigest) {
+    throw new EidolonResourceRegistryError(
+      expected.code,
+      `KindDefinition '${expected.fqn}' bytes do not match the canonical owner bytes.`,
+    )
+  }
+}
+
+function canonicalBase64Property(resource: ResourceRecord, property: string): Uint8Array {
+  const value = resource.node.properties[property]
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_RESOURCE_BYTES_MISSING",
+      `Resource '${resource.resourceId}' requires exact '${property}' base64 bytes.`,
+    )
+  }
+  let bytes: Uint8Array
+  try {
+    bytes = Uint8Array.from(Buffer.from(value, "base64"))
+  } catch {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_RESOURCE_BYTES_INVALID",
+      `Resource '${resource.resourceId}' '${property}' is not valid base64.`,
+    )
+  }
+  if (bytes.byteLength === 0 || Buffer.from(bytes).toString("base64") !== value) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_RESOURCE_BYTES_INVALID",
+      `Resource '${resource.resourceId}' '${property}' is not canonical base64.`,
+    )
+  }
+  return bytes
+}
+
+function assertTargetExists(binding: HolonExecutionBinding, snapshot: HolonEffectiveSnapshot): void {
+  const expectedKind = binding.target.kind === "member" ? "Member" : "Role"
+  const targetRef = binding.target.kind === "member" ? binding.target.memberRef : binding.target.roleRef
+  if (!snapshot.records.some((record) => record.kind === expectedKind && record.id === targetRef)) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_TARGET_MISSING",
+      `${expectedKind} '${targetRef}' is not present in frozen snapshot '${snapshot.snapshotId}'.`,
+    )
+  }
+}
+
+function resolveBindingClosureResourceIds(
+  root: HolonExecutionBinding,
+  bindings: ReadonlyMap<HolonExecutionResourceRef, Readonly<{
+    readonly resource: ResourceRecord
+    readonly binding: HolonExecutionBinding
+    readonly bindingBytes: Uint8Array
+  }>>,
+  registry: EffectiveResourceRegistry,
+): readonly string[] {
+  const selected = new Set<string>()
+  const visited = new Set<HolonExecutionResourceRef>()
+  const add = (ref: HolonExecutionResourceRef, expectedKind?: string): void => {
+    const id = resourceId(ref)
+    const resource = exactResource(registry, id)
+    if (expectedKind && resource.kind !== expectedKind) {
+      throw new EidolonResourceRegistryError(
+        "EIDOLON_HOLON_BINDING_RESOURCE_KIND_MISMATCH",
+        `Resource '${id}' must have kind '${expectedKind}', got '${resource.kind}'.`,
+      )
+    }
+    selected.add(id)
+  }
+  const visit = (binding: HolonExecutionBinding): void => {
+    if (visited.has(binding.bindingRef)) return
+    visited.add(binding.bindingRef)
+    add(binding.bindingRef, HOLON_EXECUTION_BINDING_KIND)
+    add(binding.snapshotRef, HOLON_EFFECTIVE_SNAPSHOT_KIND)
+    add(binding.policy.taskProfileRef)
+    for (const ref of binding.policy.capabilityRefs) add(ref)
+    for (const ref of binding.policy.toolRefs) add(ref)
+    for (const ref of binding.policy.materialRefs) add(ref)
+    if (binding.adapter.kind === "ai-agent") {
+      add(binding.adapter.agentDefinitionRef, "AIAgentDefinition")
+      add(binding.adapter.runtimeProfileRef)
+    } else if (binding.adapter.kind === "human-endpoint") {
+      add(binding.adapter.humanEndpointRef)
+      add(binding.adapter.inboxProfileRef)
+    } else if (binding.adapter.kind === "service") {
+      add(binding.adapter.serviceAdapterRef)
+      add(binding.adapter.runtimeProfileRef)
+    } else {
+      add(binding.adapter.policyRef)
+      for (const candidateRef of binding.adapter.candidateBindingRefs) {
+        const candidate = bindings.get(candidateRef)
+        if (!candidate) throw new EidolonResourceRegistryError(
+          "EIDOLON_HOLON_BINDING_CANDIDATE_MISSING",
+          `Hybrid candidate '${candidateRef}' is not present in the admitted registry.`,
+        )
+        visit(candidate.binding)
+      }
+    }
+  }
+  visit(root)
+  return Object.freeze([...selected].sort(compareUtf16))
+}
+
+function exactResource(registry: EffectiveResourceRegistry, resourceId: string): ResourceRecord {
+  const resource = registry.byId.get(resourceId)?.resource
+  if (!resource) {
+    throw new EidolonResourceRegistryError(
+      "EIDOLON_HOLON_BINDING_RESOURCE_MISSING",
+      `Resource '${resourceId}' is not present in the admitted registry.`,
+    )
+  }
+  return resource
+}
+
+function requiredIdentity(
+  identities: ReadonlyMap<string, ResourceContentIdentity>,
+  resourceId: string,
+): ResourceContentIdentity {
+  const identity = identities.get(resourceId)
+  if (!identity) throw new EidolonResourceRegistryError(
+    "EIDOLON_HOLON_BINDING_CONTENT_IDENTITY_MISSING",
+    `Resource '${resourceId}' has no exact content identity.`,
+  )
+  return identity
+}
+
+function resourceId(ref: HolonExecutionResourceRef): string {
+  return ref.slice("resource://".length)
+}
+
+function resourceRef(resourceId: string): HolonExecutionResourceRef {
+  return `resource://${resourceId}`
+}
+
+function compareUtf16(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+function exactSha256(value: string, path: string): `sha256:${string}` {
+  if (!/^sha256:[0-9a-f]{64}$/.test(value)) throw new EidolonResourceRegistryError(
+    "EIDOLON_HOLON_BINDING_DIGEST_INVALID",
+    `Expected one canonical SHA-256 digest at '${path}'.`,
+  )
+  return value as `sha256:${string}`
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./HolarchyEidolonAdapterError"
+export * from "./HolonExecutionBinding"
+export * from "./HolonExecutionBindingProjection"