@hypit/hypit 0.0.1 → 0.1.0

package/packages/elaborator/src/fragment.ts

@@ -0,0 +1,505 @@
+import {
+  resolveProducer,
+} from "@hypit/core";
+import type {
+  Candidate,
+  Satisfaction,
+  CandidateRoot,
+  CompiledGraph,
+  GraphValueRef,
+  LinkedProgram,
+  LogicalOutput,
+  OperationNode,
+  ProducerRef,
+  TypeRef,
+} from "@hypit/protocol";
+
+export type FragmentInputRef = {
+  readonly kind: "fragment-input";
+  readonly name: string;
+};
+
+export type FragmentOperationRef = {
+  readonly kind: "fragment-operation";
+  readonly operation: string;
+};
+
+export type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+
+export type FragmentOperationResult =
+  | { readonly kind: "output"; readonly name: string }
+  | { readonly kind: "need"; readonly name: string };
+
+export type FragmentOperation = {
+  readonly id: string;
+  readonly producer: ProducerRef;
+  readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+  readonly result: FragmentOperationResult;
+};
+
+export type FragmentExport = {
+  readonly name: string;
+  readonly type: TypeRef;
+  readonly root: FragmentOperationRef;
+};
+
+export type GraphFragment = {
+  readonly format: "hypit.fragment@1";
+  readonly id: string;
+  readonly inputs: readonly { readonly name: string; readonly type: TypeRef }[];
+  readonly operations: readonly FragmentOperation[];
+  readonly exports: readonly FragmentExport[];
+};
+
+export type FragmentInstanceRequest = {
+  /** Stable author instance identity, not a content-deduplication key. */
+  readonly id: string;
+  readonly fragment: string;
+  readonly inputs: Readonly<Record<string, GraphValueRef>>;
+};
+
+export type ElaboratedFragmentExport = {
+  readonly name: string;
+  readonly type: TypeRef;
+  readonly root: CandidateRoot;
+};
+
+export type ElaboratedFragment = {
+  readonly format: "hypit.fragment-instance@1";
+  readonly id: string;
+  readonly fragment: string;
+  readonly instance: string;
+  readonly inputs: Readonly<Record<string, GraphValueRef>>;
+  readonly operations: readonly OperationNode[];
+  readonly exports: readonly ElaboratedFragmentExport[];
+};
+
+export type FragmentContribution = {
+  readonly outputs: readonly LogicalOutput[];
+  readonly candidates: readonly Candidate[];
+  readonly operations: readonly OperationNode[];
+  /** Explicit Run-Graph satisfactions; Author contributions leave this absent. */
+  readonly satisfactions?: readonly Satisfaction[];
+};
+
+export type RunFragmentExport = {
+  readonly name: string;
+  readonly candidate: string;
+  readonly type: TypeRef;
+};
+
+export type RunFragmentContribution = FragmentContribution & {
+  readonly exports: readonly RunFragmentExport[];
+};
+
+export class FragmentError extends Error {
+  readonly code: string;
+  readonly subject: string | undefined;
+
+  constructor(code: string, message: string, subject?: string) {
+    super(message);
+    this.name = "FragmentError";
+    this.code = code;
+    this.subject = subject;
+  }
+}
+
+function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {
+  if (!condition) throw new FragmentError(code, message, subject);
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.module.name === right.module.name
+    && left.module.version === right.module.version
+    && left.name === right.name;
+}
+
+function typeName(type: TypeRef): string {
+  return `${type.module.name}@${type.module.version}#${type.name}`;
+}
+
+function exactKeys(
+  actual: Readonly<Record<string, unknown>>,
+  expected: readonly string[],
+  subject: string,
+): void {
+  const left = Object.keys(actual).sort();
+  const right = [...expected].sort();
+  assert(
+    JSON.stringify(left) === JSON.stringify(right),
+    "FRAGMENT_PORT_BINDING_MISMATCH",
+    `${subject} binds [${left.join(", ")}] but declares [${right.join(", ")}]`,
+    subject,
+  );
+}
+
+function normalizeFragmentRef(ref: FragmentValueRef): FragmentValueRef {
+  if (ref.kind === "fragment-input") return { kind: "fragment-input", name: ref.name };
+  assert(
+    ref.kind === "fragment-operation",
+    "INVALID_FRAGMENT_REFERENCE",
+    "Fragment references must name a declared input or local Operation",
+  );
+  return { kind: "fragment-operation", operation: ref.operation };
+}
+
+function normalizeOperation(operation: FragmentOperation): FragmentOperation {
+  return {
+    id: operation.id,
+    producer: operation.producer,
+    inputs: Object.fromEntries(
+      Object.entries(operation.inputs)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, ref]) => [name, normalizeFragmentRef(ref)]),
+    ),
+    result: operation.result.kind === "output"
+      ? { kind: "output", name: operation.result.name }
+      : {
+          kind: "need",
+          name: operation.result.name,
+        },
+  };
+}
+
+function normalizeExport(item: FragmentExport): FragmentExport {
+  return {
+    name: item.name,
+    type: item.type,
+    root: normalizeFragmentRef(item.root) as FragmentOperationRef,
+  };
+}
+
+function fragmentContent(fragment: Omit<GraphFragment, "id">): Omit<GraphFragment, "id"> {
+  return {
+    format: "hypit.fragment@1",
+    inputs: [...fragment.inputs]
+      .map((input) => ({ name: input.name, type: input.type }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+    operations: [...fragment.operations].map(normalizeOperation).sort((left, right) => left.id.localeCompare(right.id)),
+    exports: [...fragment.exports].map(normalizeExport).sort((left, right) => left.name.localeCompare(right.name)),
+  };
+}
+
+export function sealGraphFragment(
+  fragment: Omit<GraphFragment, "format" | "id">,
+): GraphFragment {
+  const content = fragmentContent({ format: "hypit.fragment@1", ...fragment });
+  const producers = content.operations.map((operation) =>
+    `${operation.producer.module.name}@${operation.producer.module.version}#${operation.producer.name}:${operation.id}`);
+  const exports = content.exports.map((item) => item.name);
+  return { ...content, id: `fragment:${producers.join("+")}=>${exports.join("+")}` };
+}
+
+function resultType(program: LinkedProgram, operation: FragmentOperation): TypeRef {
+  const producer = resolveProducer(program.closure, operation.producer);
+  if (operation.result.kind === "output") {
+    const output = producer.outputs.find((port) => port.name === operation.result.name);
+    assert(
+      output !== undefined && producer.needs.length === 0,
+      "FRAGMENT_RESULT_MISMATCH",
+      `${operation.id} does not produce output ${operation.result.name}`,
+      operation.id,
+    );
+    return output.type;
+  }
+  const need = producer.needs.find((port) => port.name === operation.result.name);
+  assert(
+    need !== undefined && producer.outputs.length === 0,
+    "FRAGMENT_RESULT_MISMATCH",
+    `${operation.id} does not request Need ${operation.result.name}`,
+    operation.id,
+  );
+  return need.returns;
+}
+
+export function verifyGraphFragment(program: LinkedProgram, fragment: GraphFragment): void {
+  assert(fragment.format === "hypit.fragment@1", "UNSUPPORTED_FRAGMENT", "unsupported Graph Fragment format");
+  assert(fragment.id.trim().length > 0, "INVALID_FRAGMENT_ID", "Graph Fragment id is empty");
+  assert(fragment.exports.length > 0, "EMPTY_FRAGMENT_EXPORTS", `${fragment.id} has no exports`);
+
+  const inputs = new Map<string, TypeRef>();
+  for (const input of fragment.inputs) {
+    assert(input.name.length > 0, "EMPTY_FRAGMENT_INPUT", `${fragment.id} has an empty input name`);
+    assert(!inputs.has(input.name), "DUPLICATE_FRAGMENT_INPUT", `${fragment.id} repeats input ${input.name}`);
+    inputs.set(input.name, input.type);
+  }
+
+  const operations = new Map<string, FragmentOperation>();
+  for (const operation of fragment.operations) {
+    assert(operation.id.length > 0, "EMPTY_FRAGMENT_OPERATION", `${fragment.id} has an empty Operation id`);
+    assert(!operations.has(operation.id), "DUPLICATE_FRAGMENT_OPERATION", `${fragment.id} repeats ${operation.id}`);
+    operations.set(operation.id, operation);
+    const producer = resolveProducer(program.closure, operation.producer);
+    exactKeys(operation.inputs, producer.inputs.map((port) => port.name), `${fragment.id}.${operation.id}`);
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const operationType = (id: string): TypeRef => {
+    const operation = operations.get(id);
+    assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${id}`, id);
+    if (visited.has(id)) return resultType(program, operation);
+    assert(!visiting.has(id), "FRAGMENT_CYCLE", `${fragment.id} cycles through ${id}`, id);
+    visiting.add(id);
+    const producer = resolveProducer(program.closure, operation.producer);
+    for (const port of producer.inputs) {
+      const ref = operation.inputs[port.name];
+      assert(ref !== undefined, "FRAGMENT_PORT_BINDING_MISMATCH", `${operation.id}.${port.name} is unbound`);
+      const supplied = ref.kind === "fragment-input"
+        ? inputs.get(ref.name)
+        : operationType(ref.operation);
+      assert(supplied !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${fragment.id} references input ${ref.kind === "fragment-input" ? ref.name : ref.operation}`);
+      assert(
+        sameType(supplied, port.type),
+        "FRAGMENT_INPUT_TYPE_MISMATCH",
+        `${operation.id}.${port.name} wants ${typeName(port.type)} but receives ${typeName(supplied)}`,
+        operation.id,
+      );
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return resultType(program, operation);
+  };
+
+  const exports = new Set<string>();
+  const reachableOperations = new Set<string>();
+  const collectDependencies = (ref: FragmentValueRef): void => {
+    if (ref.kind === "fragment-input" || reachableOperations.has(ref.operation)) return;
+    reachableOperations.add(ref.operation);
+    const operation = operations.get(ref.operation);
+    assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${ref.operation}`);
+    Object.values(operation.inputs).forEach(collectDependencies);
+  };
+
+  for (const item of fragment.exports) {
+    assert(item.name.length > 0, "EMPTY_FRAGMENT_EXPORT", `${fragment.id} has an empty export name`);
+    assert(!exports.has(item.name), "DUPLICATE_FRAGMENT_EXPORT", `${fragment.id} repeats export ${item.name}`);
+    exports.add(item.name);
+    assert(
+      item.root.kind === "fragment-operation",
+      "INVALID_FRAGMENT_EXPORT_ROOT",
+      `${fragment.id}.${item.name} must export a local Operation result`,
+    );
+    const supplied = operationType(item.root.operation);
+    assert(
+      sameType(supplied, item.type),
+      "FRAGMENT_EXPORT_TYPE_MISMATCH",
+      `${fragment.id}.${item.name} declares ${typeName(item.type)} but returns ${typeName(supplied)}`,
+    );
+    collectDependencies(item.root);
+  }
+  for (const id of operations.keys()) {
+    assert(
+      reachableOperations.has(id),
+      "UNREACHABLE_FRAGMENT_OPERATION",
+      `${fragment.id}.${id} contributes to no export`,
+      id,
+    );
+  }
+}
+
+function normalizeGraphRef(ref: GraphValueRef): GraphValueRef {
+  if (ref.kind === "record") return { kind: "record", id: ref.id };
+  if (ref.kind === "logical-output") return { kind: "logical-output", id: ref.id };
+  assert(
+    ref.kind === "operation-result",
+    "INVALID_FRAGMENT_BINDING",
+    "Fragment inputs must bind to a Graph Value reference",
+  );
+  return { kind: "operation-result", operation: ref.operation };
+}
+
+function hygienicId(kind: string, instance: string, local: string): string {
+  return `${kind}:${encodeURIComponent(instance)}:${encodeURIComponent(local)}`;
+}
+
+export function elaborateGraphFragment(
+  program: LinkedProgram,
+  fragment: GraphFragment,
+  request: FragmentInstanceRequest,
+): ElaboratedFragment {
+  verifyGraphFragment(program, fragment);
+  assert(request.id.length > 0, "EMPTY_FRAGMENT_INSTANCE", "Fragment instance id is empty");
+  assert(request.fragment === fragment.id, "FRAGMENT_INSTANCE_MISMATCH", `${request.id} locks another Fragment`);
+  exactKeys(request.inputs, fragment.inputs.map((input) => input.name), request.id);
+  const inputs = Object.fromEntries(
+    Object.entries(request.inputs)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, ref]) => [name, normalizeGraphRef(ref)]),
+  );
+  const operationIds = new Map(fragment.operations.map((operation) => [
+    operation.id,
+    hygienicId("operation", request.id, operation.id),
+  ]));
+  const mapRef = (ref: FragmentValueRef): GraphValueRef => {
+    if (ref.kind === "fragment-input") {
+      const bound = inputs[ref.name];
+      assert(bound !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${request.id} does not bind ${ref.name}`);
+      return bound;
+    }
+    const operation = operationIds.get(ref.operation);
+    assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${ref.operation}`);
+    return { kind: "operation-result", operation };
+  };
+  const operations: OperationNode[] = fragment.operations.map((operation) => {
+    const id = operationIds.get(operation.id) as string;
+    const record = hygienicId("record", request.id, operation.id);
+    return {
+      id,
+      producer: operation.producer,
+      inputs: Object.fromEntries(Object.entries(operation.inputs).map(([name, ref]) => [name, mapRef(ref)])),
+      result: operation.result.kind === "output"
+        ? { kind: "output", name: operation.result.name, record }
+        : {
+            kind: "need",
+            name: operation.result.name,
+            id: hygienicId("need", request.id, operation.id),
+            record,
+          },
+    };
+  });
+  const exports: ElaboratedFragmentExport[] = fragment.exports.map((item) => {
+    const root = mapRef(item.root);
+    assert(root.kind === "operation-result", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
+    return {
+      name: item.name,
+      type: item.type,
+      root: { kind: "operation" as const, result: root },
+    };
+  });
+  const content = {
+    format: "hypit.fragment-instance@1" as const,
+    fragment: fragment.id,
+    instance: request.id,
+    inputs,
+    operations,
+    exports,
+  };
+  return { ...content, id: `fragment-instance:${request.id}` };
+}
+
+function exportMap(instance: ElaboratedFragment): Map<string, ElaboratedFragmentExport> {
+  return new Map(instance.exports.map((item) => [item.name, item]));
+}
+
+function reachableOperationIds(
+  instance: ElaboratedFragment,
+  selected: readonly ElaboratedFragmentExport[],
+): Set<string> {
+  const operations = new Map(instance.operations.map((operation) => [operation.id, operation]));
+  const reachable = new Set<string>();
+  const visit = (id: string): void => {
+    if (reachable.has(id)) return;
+    reachable.add(id);
+    const operation = operations.get(id);
+    assert(operation !== undefined, "UNKNOWN_ELABORATED_OPERATION", `${instance.instance} references ${id}`);
+    for (const ref of Object.values(operation.inputs)) {
+      if (ref.kind === "operation-result") visit(ref.operation);
+    }
+  };
+  for (const item of selected) {
+    assert(item.root.kind === "operation", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
+    visit(item.root.result.operation);
+  }
+  return reachable;
+}
+
+function bindExports(
+  instance: ElaboratedFragment,
+  bindings: Readonly<Record<string, string>>,
+  requireAll: boolean,
+): FragmentContribution {
+  const available = exportMap(instance);
+  if (requireAll) exactKeys(bindings, instance.exports.map((item) => item.name), instance.instance);
+  assert(Object.keys(bindings).length > 0, "EMPTY_FRAGMENT_BINDING", `${instance.instance} binds no exports`);
+  const selected = Object.keys(bindings).map((name) => {
+    const item = available.get(name);
+    assert(item !== undefined, "UNKNOWN_FRAGMENT_EXPORT", `${instance.instance} has no export ${name}`);
+    return item;
+  });
+  const candidates: Candidate[] = selected.map((item) => {
+    const output = bindings[item.name] as string;
+    assert(output.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", `${instance.instance}.${item.name} output is empty`);
+    return {
+      id: hygienicId("candidate", instance.instance, item.name),
+      type: item.type,
+      root: item.root,
+    };
+  });
+  const outputs: LogicalOutput[] = requireAll
+    ? selected.map((item, index) => ({
+        id: bindings[item.name] as string,
+        type: item.type,
+        primary: candidates[index]!.id,
+      }))
+    : [];
+  const reachable = reachableOperationIds(instance, selected);
+  return {
+    outputs,
+    candidates,
+    operations: instance.operations.filter((operation) => reachable.has(operation.id)),
+    ...(requireAll
+      ? {}
+      : {
+          satisfactions: selected.map((item, index) => ({
+            output: bindings[item.name] as string,
+            candidate: candidates[index]!.id,
+          })),
+        }),
+  };
+}
+
+/**
+ * Instantiate a Run-Graph Fragment without deciding which Author Logical Outputs it will satisfy.
+ * Multiple exports share the instance's internal Operations; separate calls always create separate
+ * instances because identity comes from the already elaborated `instance.instance` path.
+ */
+export function exportRunFragment(
+  instance: ElaboratedFragment,
+  names: readonly string[] = instance.exports.map((item) => item.name),
+): RunFragmentContribution {
+  assert(names.length > 0, "EMPTY_FRAGMENT_BINDING", `${instance.instance} exports no Run values`);
+  assert(new Set(names).size === names.length, "DUPLICATE_FRAGMENT_EXPORT", `${instance.instance} repeats a Run export`);
+  const available = exportMap(instance);
+  const selected = names.map((name) => {
+    const item = available.get(name);
+    assert(item !== undefined, "UNKNOWN_FRAGMENT_EXPORT", `${instance.instance} has no export ${name}`);
+    return item;
+  });
+  const candidates: Candidate[] = selected.map((item) => ({
+    id: hygienicId("candidate", instance.instance, item.name),
+    type: item.type,
+    root: item.root,
+  }));
+  const reachable = reachableOperationIds(instance, selected);
+  return {
+    outputs: [],
+    candidates,
+    operations: instance.operations.filter((operation) => reachable.has(operation.id)),
+    exports: selected.map((item, index) => ({
+      name: item.name,
+      candidate: candidates[index]!.id,
+      type: item.type,
+    })),
+  };
+}
+
+/** Bind all Fragment exports as new author-visible Logical Outputs. */
+export function bindAuthorFragment(
+  instance: ElaboratedFragment,
+  outputs: Readonly<Record<string, string>>,
+): FragmentContribution {
+  return bindExports(instance, outputs, true);
+}
+
+/** Merge already elaborated contributions; final Graph validation remains Core's authority. */
+export function mergeFragmentContributions(
+  graph: Pick<CompiledGraph, "outputs" | "candidates" | "operations">,
+  ...contributions: readonly FragmentContribution[]
+): Pick<CompiledGraph, "outputs" | "candidates" | "operations"> {
+  return {
+    outputs: [...graph.outputs, ...contributions.flatMap((item) => item.outputs)],
+    candidates: [...graph.candidates, ...contributions.flatMap((item) => item.candidates)],
+    operations: [...graph.operations, ...contributions.flatMap((item) => item.operations)],
+  };
+}

package/packages/elaborator/src/frontend-facet.ts

@@ -0,0 +1,30 @@
+import {
+  createFrontendHostFacet,
+  frontendsFromHostFacets,
+} from "@hypit/host";
+import type {
+  FrontendHostFacet,
+  HostFacet,
+} from "@hypit/host";
+import { sourceFrontendPackageAbi } from "@hypit/source";
+
+import type { AuthorFrontend } from "./source.js";
+
+export type AuthorFrontendHostFacet = FrontendHostFacet<"author", AuthorFrontend> & {
+  readonly abi: typeof sourceFrontendPackageAbi;
+};
+
+export function createAuthorFrontendHostFacet(frontend: AuthorFrontend): AuthorFrontendHostFacet {
+  return createFrontendHostFacet(sourceFrontendPackageAbi, "author", frontend) as AuthorFrontendHostFacet;
+}
+
+export function authorFrontendsFromHostFacets(facets: readonly HostFacet[]): readonly AuthorFrontend[] {
+  return frontendsFromHostFacets<"author", AuthorFrontend>(sourceFrontendPackageAbi, "author", facets);
+}
+
+export function installAuthorFrontendHostFacets(
+  facets: readonly HostFacet[],
+  registry: { register(frontend: AuthorFrontend): void },
+): void {
+  for (const frontend of authorFrontendsFromHostFacets(facets)) registry.register(frontend);
+}

package/packages/elaborator/src/index.ts

@@ -0,0 +1,78 @@
+export {
+  AuthorGraphError,
+  elaborateAuthorGraph,
+} from "./author.js";
+export type {
+  AuthorComponent,
+  AuthorComponentOutputRef,
+  AuthorOutputBinding,
+  AuthorRecordRef,
+  AuthorValueRef,
+  GraphFragmentResolver,
+} from "./author.js";
+export {
+  AuthorFrontendRegistry,
+  SourceClosureError,
+  compileSourceClosure,
+  prepareAuthorSource,
+  resolveCompiledSourceExport,
+} from "./source.js";
+export {
+  authorFrontendsFromHostFacets,
+  createAuthorFrontendHostFacet,
+  installAuthorFrontendHostFacets,
+} from "./frontend-facet.js";
+export type { AuthorFrontendHostFacet } from "./frontend-facet.js";
+export type {
+  AuthorFrontend,
+  AuthorElementProvenance,
+  AuthorElementProvenanceDraft,
+  AuthorInputProvenance,
+  AuthorInputProvenanceDraft,
+  AuthorProvenance,
+  AuthorFrontendSourceUnit,
+  AuthorFrontendRegistryLike,
+  AuthorSourceDecodeContext,
+  AuthorSourceDiscovery,
+  AuthorSourceAssetRequest,
+  AuthorSourceAssetResolver,
+  AuthorSourceExport,
+  AuthorSourceIdentity,
+  AuthorSourceImport,
+  AuthorSourceResolver,
+  AuthorSourceUnit,
+  AuthorRecordAdmitter,
+  Awaitable,
+  CompileSourceClosureRequest,
+  CompiledSourceClosure,
+  CompiledSourceExport,
+  DecodedAuthorSource,
+  ResolvedAuthorSourceAsset,
+  ResolvedAuthorSourceImport,
+  SourceClosure,
+  SourceClosureUnit,
+} from "./source.js";
+export {
+  bindAuthorFragment,
+  elaborateGraphFragment,
+  exportRunFragment,
+  FragmentError,
+  mergeFragmentContributions,
+  sealGraphFragment,
+  verifyGraphFragment,
+} from "./fragment.js";
+export type {
+  ElaboratedFragment,
+  ElaboratedFragmentExport,
+  FragmentContribution,
+  FragmentExport,
+  FragmentInputRef,
+  FragmentInstanceRequest,
+  FragmentOperation,
+  FragmentOperationRef,
+  FragmentOperationResult,
+  FragmentValueRef,
+  RunFragmentContribution,
+  RunFragmentExport,
+  GraphFragment,
+} from "./fragment.js";