@hypit/hypit 0.0.1 → 0.1.0

package/packages/driver-node/src/registry.ts

@@ -0,0 +1,234 @@
+import type {
+  EndpointRequest,
+  EndpointRegistrar,
+  EndpointRegistrationOptions,
+  EndpointScheduling,
+  ImmediateEndpointHandler,
+  AsyncEndpoint,
+} from "@hypit/endpoint-kit";
+import type {
+  ProducerRegistrar,
+} from "@hypit/component-kit";
+import type {
+  CapabilityRef,
+  ProducerRef,
+  TypeRef,
+} from "@hypit/protocol";
+import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
+
+import type {
+  ProducerHandler,
+  ProducerRegistration,
+  EndpointRegistration,
+  EndpointResolution,
+} from "./types.js";
+
+function moduleKey(ref: { readonly name: string; readonly version: string }): string {
+  return `${ref.name}@${ref.version}`;
+}
+
+function sameRef(
+  left: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+  right: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+): boolean {
+  return left.module.name === right.module.name
+    && left.module.version === right.module.version
+    && left.name === right.name;
+}
+
+function verifyScheduling(scheduling: EndpointScheduling | undefined): void {
+  if (scheduling === undefined) return;
+  if (scheduling.resources.length === 0) throw new Error("scheduling resources must not be empty");
+  for (const resources of [scheduling.resources, ...Object.values(scheduling.actions ?? {})]) {
+    const ids = resources.map((resource) => {
+      capacityUnits(resource);
+      return resource.id;
+    });
+    if (new Set(ids).size !== ids.length) throw new Error("scheduling resources contain duplicate ids");
+  }
+  if (scheduling.resources.some((resource) => resource.periodMs !== undefined)) {
+    throw new Error("Rate budgets apply to Endpoint actions; whole-operation resources declare occupancy");
+  }
+}
+
+export function producerRegistryKey(ref: ProducerRef): string {
+  return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
+export function endpointCapabilityKey(ref: CapabilityRef): string {
+  return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
+export function endpointReturnKey(ref: TypeRef): string {
+  return `${moduleKey(ref.module)}#${ref.name}`;
+}
+
+export class ProducerRegistry implements ProducerRegistrar {
+  readonly #producers = new Map<string, ProducerRegistration>();
+
+  registerProducer(
+    producer: ProducerRef,
+    handler: ProducerHandler,
+    options: { readonly scheduling?: EndpointScheduling } = {},
+  ): void {
+    const key = producerRegistryKey(producer);
+    if (this.#producers.has(key)) throw new Error(`producer ${key} is already registered`);
+    verifyScheduling(options.scheduling);
+    this.#producers.set(key, { handler, ...options });
+  }
+
+  producer(ref: ProducerRef): ProducerRegistration | undefined {
+    return this.#producers.get(producerRegistryKey(ref));
+  }
+}
+
+type EndpointOptions = EndpointRegistrationOptions;
+
+function verifyEndpointOptions(options: EndpointOptions): void {
+  verifyScheduling(options.scheduling);
+  for (const [slot, ref] of Object.entries(options.credentials ?? {})) {
+    if (slot.trim().length === 0) throw new Error("Endpoint credential slot must not be empty");
+    verifyCredentialRef(ref);
+  }
+}
+
+/**
+ * Endpoint selection always receives the complete support-relevant request. Upstream graph values
+ * may still be pending, but the package that declares the request exposes their semantic slots.
+ */
+
+export class EndpointRegistry implements EndpointRegistrar {
+  readonly #registrations: EndpointRegistration[] = [];
+  readonly #registrationKeys = new Set<string>();
+  readonly #registrationsByCapability = new Map<string, EndpointRegistration[]>();
+  readonly #bindings = new Map<string, string>();
+
+  /**
+   * Decide which Endpoint serves a capability that several Endpoints offer. Providers declare
+   * everything they can do; the deployment that selected them says who does it.
+   */
+  bind(capability: CapabilityRef, endpointId: string): void {
+    if (!endpointId.trim()) throw new Error("binding endpoint id must not be empty");
+    this.#bindings.set(endpointCapabilityKey(capability), endpointId);
+  }
+
+  /** Endpoint instance ids that registered at least one capability. */
+  endpointIds(): readonly string[] {
+    return [...new Set(this.#registrations.map((registration) => registration.id))].sort();
+  }
+
+  /**
+   * Shared capacity resources that different registrations size differently. Two Endpoints in one
+   * pool with different concurrency would otherwise only collide inside the scheduler, mid-Build.
+   */
+  capacityConflicts(): readonly { readonly resource: string; readonly limits: readonly number[]; readonly settings: readonly string[]; readonly endpointIds: readonly string[] }[] {
+    const resources = new Map<string, Map<string, { limit: number; endpoints: Set<string> }>>();
+    for (const registration of this.#registrations) {
+      const scheduling = registration.scheduling;
+      for (const resource of [...(scheduling?.resources ?? []), ...Object.values(scheduling?.actions ?? {}).flat()]) {
+        const settings = resource.periodMs === undefined ? `${resource.limit} concurrent` : `${resource.limit} per ${resource.periodMs} ms`;
+        const variants = resources.get(resource.id) ?? new Map();
+        const variant = variants.get(settings) ?? { limit: resource.limit, endpoints: new Set<string>() };
+        variant.endpoints.add(registration.id);
+        variants.set(settings, variant);
+        resources.set(resource.id, variants);
+      }
+    }
+    return [...resources.entries()].filter(([, variants]) => variants.size > 1).map(([resource, variants]) => ({
+      resource,
+      limits: [...new Set([...variants.values()].map((variant) => variant.limit))].sort((a, b) => a - b),
+      settings: [...variants.keys()].sort((a, b) => a.localeCompare(b, "en", { numeric: true })),
+      endpointIds: [...new Set([...variants.values()].flatMap((variant) => [...variant.endpoints]))].sort(),
+    })).sort((a, b) => a.resource.localeCompare(b.resource));
+  }
+
+  /** Capabilities offered by more than one Endpoint, with the ids, for a deployment to bind. */
+  contested(): readonly { readonly capability: CapabilityRef; readonly endpointIds: readonly string[]; readonly bound?: string }[] {
+    const found: { readonly capability: CapabilityRef; readonly endpointIds: readonly string[]; readonly bound?: string }[] = [];
+    for (const [key, registrations] of this.#registrationsByCapability) {
+      const ids = [...new Set(registrations.map((registration) => registration.id))].sort();
+      if (ids.length < 2) continue;
+      const bound = this.#bindings.get(key);
+      found.push({ capability: registrations[0]!.capability, endpointIds: ids, ...(bound === undefined ? {} : { bound }) });
+    }
+    return found.sort((left, right) => endpointCapabilityKey(left.capability).localeCompare(endpointCapabilityKey(right.capability)));
+  }
+
+  registerImmediateEndpoint(
+    id: string,
+    capability: CapabilityRef,
+    returns: TypeRef,
+    handler: ImmediateEndpointHandler,
+    options: EndpointOptions = {},
+  ): void {
+    if (!id.trim()) throw new Error("endpoint id must not be empty");
+    verifyEndpointOptions(options);
+    const key = `${id}\n${endpointCapabilityKey(capability)}`;
+    if (this.#registrationKeys.has(key)) throw new Error(`endpoint ${id} already registers ${endpointCapabilityKey(capability)}`);
+    const registration = { kind: "immediate" as const, id, capability, returns, handler, ...options };
+    this.#registrationKeys.add(key);
+    this.#registrations.push(registration);
+    const registrations = this.#registrationsByCapability.get(endpointCapabilityKey(capability)) ?? [];
+    registrations.push(registration);
+    this.#registrationsByCapability.set(endpointCapabilityKey(capability), registrations);
+  }
+
+  registerAsyncEndpoint(
+    id: string,
+    capability: CapabilityRef,
+    returns: TypeRef,
+    endpoint: AsyncEndpoint,
+    options: EndpointOptions = {},
+  ): void {
+    if (!id.trim()) throw new Error("endpoint id must not be empty");
+    verifyEndpointOptions(options);
+    const key = `${id}\n${endpointCapabilityKey(capability)}`;
+    if (this.#registrationKeys.has(key)) throw new Error(`endpoint ${id} already registers ${endpointCapabilityKey(capability)}`);
+    const registration = { kind: "asynchronous" as const, id, capability, returns, endpoint, ...options };
+    this.#registrationKeys.add(key);
+    this.#registrations.push(registration);
+    const registrations = this.#registrationsByCapability.get(endpointCapabilityKey(capability)) ?? [];
+    registrations.push(registration);
+    this.#registrationsByCapability.set(endpointCapabilityKey(capability), registrations);
+  }
+
+  resolve(need: EndpointRequest): EndpointResolution {
+    const key = endpointCapabilityKey(need.capability);
+    const registrations = (this.#registrationsByCapability.get(key) ?? [])
+      .filter((registration) => sameRef(registration.returns, need.returns));
+    const bound = this.#bindings.get(key);
+    if (bound !== undefined) {
+      const chosen = registrations.find((registration) => registration.id === bound);
+      if (chosen === undefined) return { status: "missing", endpointId: bound };
+      const support = chosen.supports?.(need) ?? { status: "supported" };
+      if (support.status === "unsupported") {
+        if (!support.reason.trim()) throw new Error(`Endpoint ${chosen.id} returned an empty unsupported reason`);
+        return { status: "unsupported", rejections: [{ endpointId: chosen.id, reason: support.reason }] };
+      }
+      return { status: "resolved", registration: chosen };
+    }
+    if (registrations.length === 0) return { status: "missing" };
+    const supported: EndpointRegistration[] = [];
+    const rejections: { endpointId: string; reason: string }[] = [];
+    for (const registration of registrations) {
+      const support = registration.supports?.(need) ?? { status: "supported" };
+      if (support.status === "supported") {
+        supported.push(registration);
+      } else {
+        if (!support.reason.trim()) throw new Error(`Endpoint ${registration.id} returned an empty unsupported reason`);
+        rejections.push({ endpointId: registration.id, reason: support.reason });
+      }
+    }
+    if (supported.length === 0) {
+      return { status: "unsupported", rejections: rejections.sort((left, right) => left.endpointId.localeCompare(right.endpointId)) };
+    }
+    if (supported.length > 1) {
+      return {
+        status: "ambiguous",
+        endpointIds: [...new Set(supported.map((registration) => registration.id))].sort(),
+      };
+    }
+    return { status: "resolved", registration: supported[0]! };
+  }
+
+}

package/packages/driver-node/src/resources.ts

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceIOOptions, ResourceStore } from "@hypit/runtime";
+
+export class MemoryResourceStore implements ResourceStore {
+  readonly #values = new Map<ResourceId, Uint8Array>();
+
+  async put(bytes: Uint8Array, mediaType: string, options: ResourceIOOptions = {}): Promise<BlobRef> {
+    options.signal?.throwIfAborted();
+    const copy = Uint8Array.from(bytes);
+    const resource = `res_${randomUUID()}` as ResourceId;
+    this.#values.set(resource, copy);
+    return { kind: "blob", resource, size: copy.byteLength, mediaType };
+  }
+
+  async write(resource: BlobRef, bytes: Uint8Array, options: ResourceIOOptions = {}): Promise<void> {
+    options.signal?.throwIfAborted();
+    const copy = Uint8Array.from(bytes);
+    if (copy.byteLength !== resource.size) {
+      throw new Error(`Resource ${resource.resource} has size ${copy.byteLength}, expected ${resource.size}`);
+    }
+    if (!this.#values.has(resource.resource)) this.#values.set(resource.resource, copy);
+  }
+
+  async get(resource: ResourceId, options: ResourceIOOptions = {}): Promise<Uint8Array | undefined> {
+    options.signal?.throwIfAborted();
+    const value = this.#values.get(resource);
+    return value === undefined ? undefined : Uint8Array.from(value);
+  }
+
+  async has(resource: ResourceId, options: ResourceIOOptions = {}): Promise<boolean> {
+    options.signal?.throwIfAborted();
+    return this.#values.has(resource);
+  }
+}

package/packages/driver-node/src/types.ts

@@ -0,0 +1,69 @@
+import type {
+  BuildState,
+  CoreCommand,
+  TypeRef,
+  CapabilityRef,
+} from "@hypit/protocol";
+import type {
+  ProducerHandler,
+} from "@hypit/component-kit";
+import type { EndpointRegistrationOptions, EndpointScheduling, ImmediateEndpointHandler, AsyncEndpoint } from "@hypit/endpoint-kit";
+
+export type {
+  ProducerHandler,
+  ProducerHandlerContext,
+  ProducerHandlerResult,
+  ProducerRegistrar,
+} from "@hypit/component-kit";
+
+export type DriverExecutionOutcome = {
+  readonly command: string;
+  readonly kind: CoreCommand["kind"];
+  readonly status: "completed" | "pending" | "error";
+  readonly operation?: string;
+  readonly wakeAt?: number;
+  readonly message?: string;
+};
+
+export type BlockedCommand = {
+  readonly command: string;
+  readonly reason:
+    | "missing-producer"
+    | "missing-endpoint"
+    | "unsupported-endpoint-request"
+    | "ambiguous-endpoint"
+    | "missing-operation-store";
+  readonly subject: string;
+};
+
+export type DriverRunResult = {
+  readonly status: "complete" | "paused" | "failed";
+  readonly state: BuildState;
+  readonly outcomes: readonly DriverExecutionOutcome[];
+  readonly blocked: readonly BlockedCommand[];
+};
+
+export type ProducerRegistration = {
+  readonly handler: ProducerHandler;
+  readonly scheduling?: EndpointScheduling;
+};
+
+type EndpointRegistrationBase = {
+  readonly id: string;
+  readonly capability: CapabilityRef;
+  readonly returns: TypeRef;
+} & EndpointRegistrationOptions;
+
+export type EndpointRegistration = EndpointRegistrationBase & (
+  | { readonly kind: "immediate"; readonly handler: ImmediateEndpointHandler }
+  | { readonly kind: "asynchronous"; readonly endpoint: AsyncEndpoint }
+);
+
+export type EndpointResolution =
+  | { readonly status: "resolved"; readonly registration: EndpointRegistration }
+  | { readonly status: "missing"; readonly endpointId?: string }
+  | {
+    readonly status: "unsupported";
+    readonly rejections: readonly { readonly endpointId: string; readonly reason: string }[];
+  }
+  | { readonly status: "ambiguous"; readonly endpointIds: readonly string[] };

package/packages/elaborator/README.md

@@ -0,0 +1,74 @@
+# `@hypit/elaborator`
+
+Parser-independent author linking and static Graph Fragment elaboration outside SVML Core.
+
+The package is the optional compilation layer between authored declarations and the domain-free
+Kernel. A frontend, API or visual editor first emits one sealed `hypit.author-module@1` containing
+component calls with symbolic Record/Component-output references. The Elaborator then works in two
+phases:
+
+1. lock every referenced Fragment and predeclare every component export;
+2. resolve references, reject missing values, type mismatches and cycles, hygienically instantiate
+   Fragments, then emit one ordinary `hypit.graph@1` for Core.
+
+Because all exports are collected before any input is resolved, declaration order has no meaning
+and a component may reference a later component. The linker itself does not parse `.svml`, execute
+package code or know any domain vocabulary. The non-video laboratory test demonstrates that the
+same layer works without `@hypit/markup` or audiovisual contracts.
+
+The official Markup adapter emits this exact Author Module format. Its separate non-video
+integration fixture proves the complete `source → Surface → AuthorModule → Graph → BuildPlan` path;
+Markup still does not become a prerequisite for direct API or visual-editor callers.
+
+The package also provides the domain-neutral recursive Source Closure reference implementation.
+The Host supplies an entry SourceUnit, exact Frontend registry, immutable module closure and a
+Source resolver. Source compilation discovers dependencies before decoding, rejects cycles and
+duplicate aliases, decodes dependencies first, hygienically qualifies private Record/component
+identities and binds only declared public exports into importer namespaces. Host filesystem paths
+are excluded from Source Closure identity; source contents, Frontend digests and written import
+edges remain covered. Every source asset actually requested during decode is also covered by its
+author-written locator and exact Resource `BlobRef`; raw bytes remain a Host transfer
+concern and never enter the parser-independent AuthorModule or Core BuildState.
+
+The same hygienic pass emits an ephemeral `hypit.author-provenance@1` sidecar. A Frontend may retain
+the structural ranges of author elements and inputs; Elaborator qualifies their Record, component,
+output and endpoint identities together with the graph. This is a compiler result, not a Source
+file, lock, digest inventory or editor database. It carries no domain or Studio presentation and
+lets any diagnostic/editor join a graph value back to the exact author endpoint without matching a
+local name after compilation.
+
+The orchestration ABI is asynchronous even when a local Text/SVS implementation is synchronous.
+This lets a browser, sandbox or remote repository provide SourceUnits without changing the
+compilation contract. The Host resolver is the authority for path canonicalization, workspace
+containment, symlink policy and I/O; Elaborator receives bytes and identities but never opens files
+or grants filesystem access itself.
+
+Asset resolution follows the same inversion of authority. The decode context exposes only an
+asynchronous `resolveAsset({ from, mediaType })` capability. Elaborator validates the returned
+identity, rejects conflicting media assignments for one written locator and folds the dependency
+into Source Closure identity. It does not know whether a Host obtained the bytes from a filesystem,
+browser upload, repository object or remote content store.
+
+Frontend output passes a Host-owned Record validation hook before linking. The hook is permitted to
+reject a Record but is forbidden to rewrite Record identity, Type or value.
+`@hypit/compiler-node` wires this to `@hypit/validation` by default, so authored
+values use the same Type-owner gate as Producer, Provider and provided Candidate values.
+
+A `hypit.fragment@1` value may reference only declared Fragment inputs and local Operations. It
+contains no JavaScript callback, ambient file lookup, credential access or Runtime endpoint. Before
+expansion the Elaborator verifies producer ports, types, cycles, reachable exports and Semantic
+Input Envelopes.
+
+Expansion assigns hygienic identities from `Fragment id + author instance id + local id`.
+Multiple exports of one instance therefore share internal Operations, while two explicit instances
+remain two nodes even when their content is identical. Author exports become Logical Outputs with
+Primary Candidates; Run exports become independent typed Candidates plus explicit Satisfaction
+edges. The result is ordinary graph data that Core validates again before freezing a BuildPlan.
+
+`exportRunFragment()` is the canonical Run-Graph boundary: it exports independent Candidates and
+does not name an Author Logical Output. Run frontends keep Candidate declaration and the explicit
+`output -> candidate` Satisfaction edge separate.
+
+`@hypit/elaborator` is not a public `@hypit/author` subsystem. It is a reusable graph-construction
+library. A domain normally adds its own contract and component packages; Text remains only one
+optional frontend capable of producing the same Author Module data.

package/packages/elaborator/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hypit/elaborator",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/host": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/source": "workspace:*"
+  }
+}