@hypit/hypit 0.0.1 → 0.1.0

package/packages/run/src/graph.ts

@@ -0,0 +1,65 @@
+import type { RunGraph } from "./types.js";
+
+export class RunGraphError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "RunGraphError";
+    this.code = code;
+  }
+}
+
+function assert(condition: unknown, code: string, message: string): asserts condition {
+  if (!condition) throw new RunGraphError(code, message);
+}
+
+function content(graph: RunGraph): RunGraph {
+  return {
+    format: "hypit.run-graph@1",
+    records: [...graph.records].sort((left, right) => left.id.localeCompare(right.id)),
+    candidates: [...graph.candidates].sort((left, right) => left.id.localeCompare(right.id)),
+    operations: [...graph.operations].sort((left, right) => left.id.localeCompare(right.id)),
+    satisfactions: [...graph.satisfactions].sort((left, right) => left.output.localeCompare(right.output)),
+    targets: [...graph.targets].sort((left, right) => left.output.localeCompare(right.output)),
+  };
+}
+
+export function sealRunGraph(input: Omit<RunGraph, "format">): RunGraph {
+  const graph = content({ format: "hypit.run-graph@1", ...input });
+  verifyRunGraph(graph);
+  return graph;
+}
+
+export function verifyRunGraph(graph: RunGraph): void {
+  assert(graph.format === "hypit.run-graph@1", "UNSUPPORTED_RUN_GRAPH", "unsupported Run Graph");
+  const recordIds = new Set<string>();
+  for (const record of graph.records) {
+    assert(record.id.length > 0, "EMPTY_RUN_RECORD", "Run Graph Record id is empty");
+    assert(!recordIds.has(record.id), "DUPLICATE_RUN_RECORD", `Run Graph repeats Record ${record.id}`);
+    assert(record.value.kind === "inline", "INVALID_RUN_RECORD", `Run Graph Record ${record.id} must be inline`);
+    recordIds.add(record.id);
+  }
+  const candidateIds = new Set<string>();
+  for (const candidate of graph.candidates) {
+    assert(!candidateIds.has(candidate.id), "DUPLICATE_RUN_CANDIDATE", `Run Graph repeats Candidate ${candidate.id}`);
+    candidateIds.add(candidate.id);
+  }
+  const operationIds = new Set<string>();
+  for (const operation of graph.operations) {
+    assert(!operationIds.has(operation.id), "DUPLICATE_RUN_OPERATION", `Run Graph repeats Operation ${operation.id}`);
+    operationIds.add(operation.id);
+  }
+  const satisfiedOutputs = new Set<string>();
+  for (const satisfaction of graph.satisfactions) {
+    assert(!satisfiedOutputs.has(satisfaction.output), "DUPLICATE_RUN_SATISFACTION", `Run Graph satisfies ${satisfaction.output} more than once`);
+    assert(candidateIds.has(satisfaction.candidate), "UNKNOWN_RUN_CANDIDATE", `Run Graph Satisfaction names absent Candidate ${satisfaction.candidate}`);
+    satisfiedOutputs.add(satisfaction.output);
+  }
+  assert(graph.targets.length > 0, "EMPTY_RUN_TARGETS", "Run Graph has no Targets");
+  const targets = new Set<string>();
+  for (const target of graph.targets) {
+    assert(!targets.has(target.output), "DUPLICATE_RUN_TARGET", `Run Graph repeats Target ${target.output}`);
+    targets.add(target.output);
+  }
+}

package/packages/run/src/index.ts

@@ -0,0 +1,33 @@
+export { RunFragmentRegistry } from "./registry.js";
+export {
+  createProvidedCandidate,
+} from "./candidate.js";
+export type {
+  ProvidedCandidateInput,
+} from "./candidate.js";
+export {
+  createRunFragmentHostFacet,
+  installRunFragmentHostFacets,
+  runFragmentHostAbi,
+} from "./facet.js";
+export type {
+  RunFragmentHostFacet,
+} from "./facet.js";
+export { collectRunModuleRequests, resolveRunDocument } from "./resolve.js";
+export {
+  compileRunSource,
+  prepareRunSource,
+  RunFrontendRegistry,
+  RunSourceError,
+} from "./frontend.js";
+export {
+  createRunFrontendHostFacet,
+  runFrontendsFromHostFacets,
+} from "./frontend-facet.js";
+export type { RunFrontendHostFacet } from "./frontend-facet.js";
+export {
+  RunGraphError,
+  sealRunGraph,
+  verifyRunGraph,
+} from "./graph.js";
+export type * from "./types.js";

package/packages/run/src/registry.ts

@@ -0,0 +1,24 @@
+import type { GraphFragment } from "@hypit/elaborator";
+
+import type { RunFragmentPackage, RunFragmentRegistryLike } from "./types.js";
+
+export class RunFragmentRegistry implements RunFragmentRegistryLike {
+  readonly #packages = new Map<string, ReadonlyMap<string, GraphFragment>>();
+
+  register(item: RunFragmentPackage): void {
+    if (item.name.trim().length === 0) throw new Error("Run Fragment package name must not be empty");
+    if (this.#packages.has(item.name)) throw new Error(`Run Fragment package ${item.name} is already registered`);
+    const fragments = new Map<string, GraphFragment>();
+    for (const [name, fragment] of Object.entries(item.fragments)) {
+      if (name.trim().length === 0) throw new Error(`${item.name} has an empty Run Fragment name`);
+      if (fragments.has(name)) throw new Error(`${item.name} repeats Run Fragment ${name}`);
+      fragments.set(name, fragment);
+    }
+    if (fragments.size === 0) throw new Error(`Run Fragment package ${item.name} exports no Fragments`);
+    this.#packages.set(item.name, fragments);
+  }
+
+  resolve(packageName: string, fragmentName: string): GraphFragment | undefined {
+    return this.#packages.get(packageName)?.get(fragmentName);
+  }
+}

package/packages/run/src/resolve.ts

@@ -0,0 +1,213 @@
+import {
+  elaborateGraphFragment,
+  exportRunFragment,
+  resolveCompiledSourceExport,
+} from "@hypit/elaborator";
+import { canonicalize, sameType } from "@hypit/protocol";
+import type {
+  Candidate,
+  GraphValueRef,
+  ModuleRef,
+  OperationNode,
+  TypedRecord,
+} from "@hypit/protocol";
+import {
+  createProvidedCandidate,
+} from "./candidate.js";
+
+import { sealRunGraph } from "./graph.js";
+
+import type {
+  ResolveRunDocumentContext,
+  RunCompilation,
+  RunDocument,
+} from "./types.js";
+
+function moduleRequest(ref: ModuleRef): string {
+  return `${ref.name}@${ref.version}`;
+}
+
+/** Module closure additions required only by the selected Run implementations. */
+export function collectRunModuleRequests(
+  document: RunDocument,
+  fragments: ResolveRunDocumentContext["fragments"],
+): readonly string[] {
+  const imports = new Map(document.imports.map((item) => [item.as, item.from]));
+  const requests = new Set<string>();
+  for (const declaration of document.candidates) {
+    if (declaration.kind === "provided") {
+      requests.add(moduleRequest(declaration.type.module));
+      continue;
+    }
+    if (declaration.kind === "file") {
+      requests.add(moduleRequest(declaration.type.module));
+      continue;
+    }
+    if (declaration.kind !== "fragment") continue;
+    const packageName = imports.get(declaration.using.alias);
+    if (packageName === undefined) throw new Error(`Run Fragment alias ${declaration.using.alias} is not imported`);
+    const fragment = fragments.resolve(packageName, declaration.using.name);
+    if (fragment === undefined) throw new Error(`${packageName} exports no Run Fragment ${declaration.using.name}`);
+    for (const input of fragment.inputs) requests.add(moduleRequest(input.type.module));
+    for (const operation of fragment.operations) requests.add(moduleRequest(operation.producer.module));
+    for (const item of fragment.exports) requests.add(moduleRequest(item.type.module));
+  }
+  return [...requests].sort();
+}
+
+function authorRef(context: ResolveRunDocumentContext, name: string): GraphValueRef {
+  const exported = resolveCompiledSourceExport(context.compilation, name);
+  return exported.ref;
+}
+
+function logicalOutput(context: ResolveRunDocumentContext, name: string): string {
+  const exported = resolveCompiledSourceExport(context.compilation, name);
+  if (exported.ref.kind !== "logical-output") {
+    throw new Error(`${name} is an authored Record, not a realizable Logical Output`);
+  }
+  return exported.ref.id;
+}
+
+/** Resolve both source graph structures before Core derives a finite BuildPlan. */
+export async function resolveRunDocument(
+  document: RunDocument,
+  context: ResolveRunDocumentContext,
+): Promise<RunCompilation> {
+  const imports = new Map(document.imports.map((item) => [item.as, item.from]));
+  const candidates = new Map<string, Candidate>();
+  const operations = new Map<string, OperationNode>();
+  const records = new Map<string, TypedRecord>();
+  const addCandidate = (candidate: Candidate): void => {
+    if (candidates.has(candidate.id)) throw new Error(`Run Candidate ${candidate.id} is declared twice`);
+    candidates.set(candidate.id, candidate);
+  };
+  const addOperation = (operation: OperationNode): void => {
+    if (operations.has(operation.id)) throw new Error(`Run Operation ${operation.id} is declared twice`);
+    operations.set(operation.id, operation);
+  };
+  const candidateNames = new Map<string, string>();
+  const candidateSources = new Map<string, RunCompilation["candidateSources"][string]>();
+  const declarationIds = new Set<string>();
+  const bindCandidateName = (name: string, candidate: string): void => {
+    if (candidateNames.has(name)) throw new Error(`Run Candidate reference ${name} is declared twice`);
+    candidateNames.set(name, candidate);
+  };
+
+  for (const declaration of document.candidates) {
+    if (declarationIds.has(declaration.id)) throw new Error(`Run Candidate ${declaration.id} is declared twice`);
+    declarationIds.add(declaration.id);
+    if (declaration.kind === "provided") {
+      const candidate = createProvidedCandidate({
+        id: declaration.id,
+        type: declaration.type,
+        value: { kind: "inline", value: null },
+      });
+      addCandidate(candidate);
+      bindCandidateName(declaration.id, candidate.id);
+      candidateSources.set(candidate.id, { kind: "stored-value", from: declaration.from });
+      continue;
+    }
+    if (declaration.kind === "file") {
+      const candidate = createProvidedCandidate({
+        id: declaration.id,
+        type: declaration.type,
+        value: { kind: "inline", value: null },
+      });
+      addCandidate(candidate);
+      bindCandidateName(declaration.id, candidate.id);
+      candidateSources.set(candidate.id, {
+        kind: "file",
+        from: declaration.from,
+        mediaType: declaration.mediaType,
+      });
+      continue;
+    }
+    if (declaration.kind === "build-record") {
+      const destinations = document.satisfactions
+        .filter((item) => item.candidate === declaration.id)
+        .map((item) => resolveCompiledSourceExport(context.compilation, item.output));
+      if (destinations.length === 0) continue;
+      const type = destinations[0]!.type;
+      for (const destination of destinations) {
+        if (destination.ref.kind !== "logical-output") {
+          throw new Error(`${declaration.id} satisfies an authored Record rather than a Logical Output`);
+        }
+        if (!sameType(destination.type, type)) {
+          throw new Error(`Historical Candidate ${declaration.id} is used for incompatible Logical Output types`);
+        }
+      }
+      const candidate = createProvidedCandidate({ id: declaration.id, type, value: { kind: "inline", value: null } });
+      addCandidate(candidate);
+      bindCandidateName(declaration.id, candidate.id);
+      candidateSources.set(candidate.id, {
+        kind: "build-output",
+        build: declaration.build,
+        output: declaration.output,
+      });
+      continue;
+    }
+    const packageName = imports.get(declaration.using.alias);
+    if (packageName === undefined) throw new Error(`Run Fragment alias ${declaration.using.alias} is not imported`);
+    const fragment = context.fragments.resolve(packageName, declaration.using.name);
+    if (fragment === undefined) {
+      throw new Error(`${packageName} exports no Run Fragment ${declaration.using.name}`);
+    }
+    const inputDeclarations = new Map(fragment.inputs.map((item) => [item.name, item]));
+    const fragmentInputs = Object.fromEntries(declaration.inputs.map((item): [string, GraphValueRef] => {
+      if ("from" in item) return [item.name, authorRef(context, item.from)];
+      const inputDeclaration = inputDeclarations.get(item.name);
+      if (inputDeclaration === undefined) {
+        throw new Error(`Run Fragment ${declaration.id} binds undeclared input ${item.name}`);
+      }
+      const id = `record:run:${declaration.id}:${item.name}`;
+      if (records.has(id)) throw new Error(`Run Fragment literal ${declaration.id}.${item.name} is declared twice`);
+      records.set(id, {
+        id,
+        type: inputDeclaration.type,
+        value: { kind: "inline", value: canonicalize(item.value) },
+      });
+      return [item.name, { kind: "record", id }];
+    }));
+    const instance = elaborateGraphFragment(context.compilation.program, fragment, {
+      id: `run:${declaration.id}`,
+      fragment: fragment.id,
+      inputs: fragmentInputs,
+    });
+    const contribution = exportRunFragment(instance, declaration.exports);
+    for (const candidate of contribution.candidates) addCandidate(candidate);
+    for (const operation of contribution.operations) addOperation(operation);
+    for (const item of contribution.exports) bindCandidateName(`${declaration.id}.${item.name}`, item.candidate);
+  }
+
+  const satisfactionNames = new Map<string, string>();
+  const satisfactions = document.satisfactions.map((item) => {
+    const candidate = candidateNames.get(item.candidate);
+    if (candidate === undefined) throw new Error(`Unknown Run Candidate ${item.candidate}`);
+    const output = logicalOutput(context, item.output);
+    if (satisfactionNames.has(output)) {
+      throw new Error(`Logical Output ${item.output} is satisfied more than once`);
+    }
+    satisfactionNames.set(output, item.candidate);
+    return {
+      output,
+      candidate,
+    } as const;
+  });
+  const targets = document.targets.map((item) => ({ output: logicalOutput(context, item.output) }));
+  const resolvedCandidates = [...candidates.values()];
+  const resolvedOperations = [...operations.values()];
+  const graph = sealRunGraph({
+    records: [...records.values()],
+    candidates: resolvedCandidates,
+    operations: resolvedOperations,
+    satisfactions,
+    targets,
+  });
+  return {
+    document,
+    graph,
+    candidates: Object.fromEntries([...candidateNames.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    candidateSources: Object.fromEntries([...candidateSources.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    satisfactionNames: Object.fromEntries([...satisfactionNames.entries()].sort(([left], [right]) => left.localeCompare(right))),
+  };
+}

package/packages/run/src/types.ts

@@ -0,0 +1,147 @@
+import type {
+  CompiledSourceClosure,
+  GraphFragment,
+} from "@hypit/elaborator";
+import type {
+  Candidate,
+  CanonicalValue,
+  OperationNode,
+  RunGraph,
+  Satisfaction,
+  TypeRef,
+} from "@hypit/protocol";
+export type { RunGraph } from "@hypit/protocol";
+import type { SourceHeader, SourceUnit } from "@hypit/source";
+
+export type RunSourceUnit = SourceUnit;
+
+export type RunFrontendSourceUnit = RunSourceUnit & {
+  readonly header: SourceHeader;
+};
+
+export type RunAuthorSourceRequest = {
+  readonly source: string;
+};
+
+export type RunImport = {
+  readonly from: string;
+  readonly as: string;
+};
+
+export type RunTarget = {
+  readonly output: string;
+};
+
+export type RunProvidedValue = {
+  readonly kind: "provided";
+  readonly id: string;
+  readonly type: TypeRef;
+  /** File containing one StoredValue JSON object. */
+  readonly from: string;
+};
+
+/** Ordinary source file admitted as one Resource Candidate of an explicitly named blob Type. */
+export type RunProvidedFile = {
+  readonly kind: "file";
+  readonly id: string;
+  readonly type: TypeRef;
+  readonly from: string;
+  readonly mediaType: string;
+};
+
+export type RunBuildRecord = {
+  readonly kind: "build-record";
+  readonly id: string;
+  readonly build: string;
+  /** Unique public Output name inside the prior Build Result. */
+  readonly output: string;
+};
+
+export type RunFragmentInput =
+  | {
+      readonly name: string;
+      /** Public author-source export. */
+      readonly from: string;
+    }
+  | {
+      readonly name: string;
+      /** An ordinary scalar owned by this Run, typed by the Fragment input declaration. */
+      readonly value: CanonicalValue;
+    };
+
+export type RunFragmentInstance = {
+  readonly kind: "fragment";
+  readonly id: string;
+  readonly using: {
+    readonly alias: string;
+    readonly name: string;
+  };
+  readonly inputs: readonly RunFragmentInput[];
+  /** Omitted means every Fragment export. */
+  readonly exports?: readonly string[];
+};
+
+export type RunCandidateDeclaration = RunProvidedValue | RunProvidedFile | RunBuildRecord | RunFragmentInstance;
+
+export type RunSatisfaction = {
+  readonly output: string;
+  /** Candidate id, or `fragment-instance.export`. */
+  readonly candidate: string;
+};
+
+export type RunDocument = {
+  readonly format: "hypit.run-document@1";
+  readonly author: RunAuthorSourceRequest;
+  readonly imports: readonly RunImport[];
+  readonly targets: readonly RunTarget[];
+  readonly candidates: readonly RunCandidateDeclaration[];
+  readonly satisfactions: readonly RunSatisfaction[];
+};
+
+export type RunSourceDiscovery = {
+  readonly author: RunAuthorSourceRequest;
+  readonly imports: readonly RunImport[];
+};
+
+export type DecodedRunSource = {
+  readonly document: RunDocument;
+};
+
+export type RunFrontend = {
+  readonly id: string;
+  discover(source: RunFrontendSourceUnit): RunSourceDiscovery | Promise<RunSourceDiscovery>;
+  decode(source: RunFrontendSourceUnit): DecodedRunSource | Promise<DecodedRunSource>;
+};
+
+export interface RunFrontendRegistryLike {
+  resolve(id: string): RunFrontend | undefined;
+}
+
+export type RunFragmentPackage = {
+  readonly name: string;
+  readonly fragments: Readonly<Record<string, GraphFragment>>;
+};
+
+export interface RunFragmentRegistryLike {
+  resolve(packageName: string, fragmentName: string): GraphFragment | undefined;
+}
+
+export type ResolveRunDocumentContext = {
+  readonly compilation: CompiledSourceClosure;
+  readonly fragments: RunFragmentRegistryLike;
+};
+
+export type RunCandidateSource =
+  | { readonly kind: "stored-value"; readonly from: string }
+  | { readonly kind: "file"; readonly from: string; readonly mediaType: string }
+  | { readonly kind: "build-output"; readonly build: string; readonly output: string };
+
+export type RunCompilation = {
+  readonly document: RunDocument;
+  readonly graph: RunGraph;
+  readonly candidates: Readonly<Record<string, string>>;
+  /** Sources for zero-input Candidates, materialized only after global planning selects them. */
+  readonly candidateSources: Readonly<Record<string, RunCandidateSource>>;
+  /** Author-written Candidate name selected for each resolved Logical Output. Presentation only. */
+  readonly satisfactionNames: Readonly<Record<string, string>>;
+};

package/packages/run-markup/README.md

@@ -0,0 +1,60 @@
+# `@hypit/run-markup`
+
+Official human-readable Frontend for `@hypit/run`.
+
+One Run Source is self-described and names one Author Source explicitly:
+
+```xml
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+  <author source="./main.svml"/>
+  <target output="final.video"/>
+
+  <build-record id="opening" build="prior-build-id" output="opening-take"/>
+  <file id="approved" type="@hypit/artifact@1#BlobArtifact" from="./approved.mp4" media-type="video/mp4"/>
+  <satisfy output="opening-take" candidate="opening"/>
+</svrun>
+```
+
+The Author Source's own Header—not this file and not its suffix—selects its Author Frontend.
+
+`<value>` declares a typed zero-input `StoredValue`; its JSON file includes the wrapper, such as
+`{"kind":"inline","value":{"enabled":true}}`, with the inner value matching the declared Type.
+`<file>` admits ordinary source
+bytes as the explicitly named blob Type; Run itself does not assume an Artifact module.
+`<build-record>` exposes one exact named Output from a prior Build Result as a zero-input Candidate. `<fragment>`
+instantiates a trusted package Fragment and may
+export several Candidates backed by shared Operations. Two declarations are two instances; one
+declaration with several exports is one instance.
+
+The `output` on `<build-record>` is the prior Result's unique public Output name. After Core plans the
+complete Author and Run graphs, the Host resolves only the selected zero-input Candidate sources;
+unreached local values, local files and historical Outputs are not opened. Core receives only the typed Candidate value,
+and the historical value receives no automatic semantic-relationship claim
+against the output it is selected to satisfy.
+
+Results are not selected automatically by repeating a Run, retaining an output name, or changing only
+its Targets. Cross-Build reuse requires an explicit Candidate selection. Removing a `satisfy` returns
+that Logical Output to its primary Candidate and can make the displaced generation route reachable
+again. Preserve unrelated selections when revising a Run.
+
+Imports form the opening prologue. They name Fragment libraries already admitted by the Host; they
+do not install packages. Provider credentials, queues, Stores, Endpoint bindings and inline
+callbacks are not Run language elements.
+
+## Fragment input references
+
+`<input name="media" from="opening-media.media"/>` names a public value of the Run's Author
+entry. A computed Author Output remains a graph dependency, with its selected Candidate applied.
+The reference is not another Run Candidate name and does not expose a nested Source namespace that
+the Author entry has not published.
+
+`<input name="duration" value="5"/>` supplies a scalar. The parser recognizes numbers, booleans
+and null; other text is a string. Typed object inputs are obtained through `from`, not by placing
+JSON in a scalar attribute. `<value>` reads a serialized typed value as a Candidate for a Logical
+Output; it does not introduce an Author binding for Fragment inputs.
+
+Fragment exports are available as `<instance-id>.<export-name>`. Optional `<export name="video"/>`
+children expose selected exports; omitting them exposes all Fragment exports. Their shared required
+operations remain one instance. Imports precede Targets and Candidate declarations, following the
+required `author` declaration.

package/packages/run-markup/package.json

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

package/packages/run-markup/src/activation.ts

@@ -0,0 +1,10 @@
+import { createRunFrontendHostFacet } from "@hypit/run";
+
+import { runMarkupFrontend } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createRunFrontendHostFacet(runMarkupFrontend)],
+};
+
+export default hypitPackage;

package/packages/run-markup/src/frontend.ts

@@ -0,0 +1,16 @@
+import type { RunFrontend } from "@hypit/run";
+
+import { parseRunDocument } from "./syntax.js";
+
+export const runMarkupFrontendId = "@hypit/run-markup@1";
+
+export const runMarkupFrontend: RunFrontend = {
+  id: runMarkupFrontendId,
+  discover(source) {
+    const document = parseRunDocument(source.name, source.text);
+    return { author: document.author, imports: document.imports };
+  },
+  decode(source) {
+    return { document: parseRunDocument(source.name, source.text) };
+  },
+};

package/packages/run-markup/src/index.ts

@@ -0,0 +1,5 @@
+export { runMarkupFrontend, runMarkupFrontendId } from "./frontend.js";
+export {
+  parseRunDocument,
+  RunSyntaxError,
+} from "./syntax.js";