@hypit/hypit 0.0.1 → 0.1.0

package/packages/resource-store-s3/src/client.ts

@@ -0,0 +1,138 @@
+import { addAbortSignal, Readable } from "node:stream";
+import type { ResourceIOOptions } from "@hypit/runtime";
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  UploadPartCommand,
+} from "@aws-sdk/client-s3";
+import type {
+  AbortMultipartUploadCommandInput,
+  CompleteMultipartUploadCommandInput,
+  CreateMultipartUploadCommandInput,
+  GetObjectCommandInput,
+  PutObjectCommandInput,
+  S3ClientConfig,
+  UploadPartCommandInput,
+} from "@aws-sdk/client-s3";
+
+/**
+ * `put` and `get` are the whole port. The rest are optional: a client that
+ * omits them leaves the store implementing only the ResourceStore,
+ * which is exactly what the optional Streaming facet means.
+ */
+export type S3ObjectClient = {
+  put(input: PutObjectCommandInput, options?: ResourceIOOptions): Promise<void>;
+  get(input: GetObjectCommandInput, options?: ResourceIOOptions): Promise<Uint8Array | undefined>;
+  /**
+   * The object's bytes as they arrive. Separate from `get` because an Artifact
+   * may be a whole programme: a caller that asked to stream must not have the
+   * object assembled in memory on its behalf.
+   */
+  open?(input: GetObjectCommandInput, options?: ResourceIOOptions): Promise<AsyncIterable<Uint8Array> | undefined>;
+  /** Undefined when the key is absent. */
+  head?(input: GetObjectCommandInput, options?: ResourceIOOptions): Promise<{ readonly size: number } | undefined>;
+  createMultipart?(input: CreateMultipartUploadCommandInput, options?: ResourceIOOptions): Promise<string>;
+  uploadPart?(input: UploadPartCommandInput, options?: ResourceIOOptions): Promise<{ readonly etag: string }>;
+  completeMultipart?(input: CompleteMultipartUploadCommandInput, options?: ResourceIOOptions): Promise<void>;
+  abortMultipart?(input: AbortMultipartUploadCommandInput, options?: ResourceIOOptions): Promise<void>;
+};
+
+function statusCode(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null || !("$metadata" in error)) return undefined;
+  const metadata = error.$metadata;
+  if (typeof metadata !== "object" || metadata === null || !("httpStatusCode" in metadata)) return undefined;
+  return typeof metadata.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
+}
+
+function absent(error: unknown): boolean {
+  return statusCode(error) === 404
+    || (error instanceof Error && (error.name === "NoSuchKey" || error.name === "NotFound"));
+}
+
+export class AwsS3ObjectClient implements S3ObjectClient {
+  readonly #client: S3Client;
+
+  constructor(config: S3ClientConfig = {}) {
+    // Credentials come from the SDK default chain and are never rebuilt here
+    // from AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY. A managed runtime also
+    // injects AWS_SESSION_TOKEN, and a hand-assembled two-field credential
+    // object silently drops it — every request then fails InvalidAccessKeyId.
+    this.#client = new S3Client(config);
+  }
+
+  async put(input: PutObjectCommandInput, options: ResourceIOOptions = {}): Promise<void> {
+    await this.#client.send(new PutObjectCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+  }
+
+  async get(input: GetObjectCommandInput, options: ResourceIOOptions = {}): Promise<Uint8Array | undefined> {
+    const source = await this.open(input, options);
+    if (source === undefined) return undefined;
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of source) chunks.push(chunk);
+    return Uint8Array.from(Buffer.concat(chunks));
+  }
+
+  async open(input: GetObjectCommandInput, options: ResourceIOOptions = {}): Promise<AsyncIterable<Uint8Array> | undefined> {
+    options.signal?.throwIfAborted();
+    let body: Readable;
+    try {
+      const response = await this.#client.send(new GetObjectCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+      if (response.Body === undefined) throw new Error(`S3 object ${input.Key ?? "<unknown>"} has no body`);
+      body = response.Body as Readable;
+      // open() can be cancelled before its caller starts consuming the body.
+      body.on("error", () => {});
+      if (options.signal !== undefined) addAbortSignal(options.signal, body);
+    } catch (error) {
+      if (absent(error)) return undefined;
+      throw error;
+    }
+    return (async function* () {
+      try {
+        for await (const chunk of body) {
+          options.signal?.throwIfAborted();
+          yield Uint8Array.from(chunk as Buffer);
+        }
+      } finally { body.destroy(); }
+    })();
+  }
+
+  async head(input: GetObjectCommandInput, options: ResourceIOOptions = {}): Promise<{ readonly size: number } | undefined> {
+    try {
+      const response = await this.#client.send(new HeadObjectCommand({
+        Bucket: input.Bucket,
+        Key: input.Key,
+        ...(input.ExpectedBucketOwner === undefined ? {} : { ExpectedBucketOwner: input.ExpectedBucketOwner }),
+      }), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+      return { size: response.ContentLength ?? 0 };
+    } catch (error) {
+      if (absent(error)) return undefined;
+      throw error;
+    }
+  }
+
+  async createMultipart(input: CreateMultipartUploadCommandInput, options: ResourceIOOptions = {}): Promise<string> {
+    const response = await this.#client.send(new CreateMultipartUploadCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+    if (response.UploadId === undefined) throw new Error("S3 did not return a multipart upload id");
+    return response.UploadId;
+  }
+
+  async uploadPart(input: UploadPartCommandInput, options: ResourceIOOptions = {}): Promise<{ readonly etag: string }> {
+    const response = await this.#client.send(new UploadPartCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+    if (response.ETag === undefined) throw new Error("S3 did not return a part ETag");
+    return { etag: response.ETag };
+  }
+
+  async completeMultipart(input: CompleteMultipartUploadCommandInput, options: ResourceIOOptions = {}): Promise<void> {
+    await this.#client.send(new CompleteMultipartUploadCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+  }
+
+  async abortMultipart(input: AbortMultipartUploadCommandInput, options: ResourceIOOptions = {}): Promise<void> {
+    await this.#client.send(new AbortMultipartUploadCommand(input), (options.signal === undefined ? {} : { abortSignal: options.signal }));
+  }
+
+}

package/packages/resource-store-s3/src/index.ts

@@ -0,0 +1,10 @@
+export { AwsS3ObjectClient } from "./client.js";
+export type { S3ObjectClient } from "./client.js";
+export {
+  S3ResourceStore,
+  createS3ResourceStore,
+  normalizeS3ResourcePrefix,
+  s3ResourceKey,
+  s3ResourceStoreModuleRef,
+} from "./store.js";
+export type * from "./store.js";

package/packages/resource-store-s3/src/store.ts

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceIOOptions, ResourceStore } from "@hypit/runtime";
+
+import { AwsS3ObjectClient } from "./client.js";
+import type { S3ObjectClient } from "./client.js";
+
+export const s3ResourceStoreModuleRef = {
+  name: "@hypit/resource-store-s3",
+  version: "1",
+} as const;
+
+export function normalizeS3ResourcePrefix(prefix: string | undefined): string {
+  if (prefix === undefined || prefix.length === 0) return "";
+  const normalized = prefix.replace(/^\/+|\/+$/gu, "");
+  assert(normalized.length > 0, "S3 Resource prefix must contain a non-slash character");
+  assert(!normalized.split("/").some((part) => part === "." || part === ".."),
+    "S3 Resource prefix cannot contain dot path segments");
+  return normalized;
+}
+
+export function s3ResourceKey(prefix: string | undefined, resource: ResourceId): string {
+  if (!isResourceId(resource)) throw new Error("Resource id is invalid");
+  const normalized = normalizeS3ResourcePrefix(prefix);
+  const relative = `resources/${resource}`;
+  return normalized.length === 0 ? relative : `${normalized}/${relative}`;
+}
+
+type S3Location = {
+  readonly bucket: string;
+  readonly prefix?: string;
+  readonly expectedBucketOwner?: string;
+};
+
+export type S3ResourceStoreOptions = S3Location & {
+  readonly client: S3ObjectClient;
+  readonly partSizeBytes?: number;
+};
+
+export type CreateS3ResourceStorePackageOptions = S3Location & {
+  readonly instance?: string;
+  readonly partSizeBytes?: number;
+  readonly region?: string;
+  readonly endpoint?: string;
+  readonly forcePathStyle?: boolean;
+  readonly client?: S3ObjectClient;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
+  return value;
+}
+
+/** Optional S3 byte store for Runtime implementations that deliberately embed it. */
+export class S3ResourceStore implements ResourceStore {
+  readonly #client: S3ObjectClient;
+  readonly #bucket: string;
+  readonly #prefix: string;
+  readonly #expectedBucketOwner: string | undefined;
+  readonly #partSizeBytes: number;
+  readonly open?: (resource: ResourceId, options?: ResourceIOOptions) => Promise<AsyncIterable<Uint8Array> | undefined>;
+  readonly putStream?: (chunks: AsyncIterable<Uint8Array>, mediaType: string, options?: ResourceIOOptions) => Promise<BlobRef>;
+  readonly writeStream?: (resource: BlobRef, chunks: AsyncIterable<Uint8Array>, options?: ResourceIOOptions) => Promise<void>;
+
+  constructor(options: S3ResourceStoreOptions) {
+    assert(options.bucket.trim().length > 0, "S3 Resource bucket must not be empty");
+    if (options.expectedBucketOwner !== undefined) {
+      assert(options.expectedBucketOwner.trim().length > 0, "expected S3 bucket owner must not be empty");
+    }
+    this.#client = options.client;
+    this.#bucket = options.bucket;
+    this.#prefix = normalizeS3ResourcePrefix(options.prefix);
+    this.#expectedBucketOwner = options.expectedBucketOwner;
+    this.#partSizeBytes = positiveInteger(options.partSizeBytes ?? 16 * 1024 * 1024, "partSizeBytes");
+    assert(this.#partSizeBytes >= 5 * 1024 * 1024, "S3 requires multipart parts of at least 5 MiB");
+    const client = options.client;
+    if (client.open !== undefined && client.createMultipart !== undefined && client.uploadPart !== undefined
+      && client.completeMultipart !== undefined && client.abortMultipart !== undefined) {
+      this.open = (resource, options = {}) => this.#openStream(resource, options);
+      this.putStream = (chunks, mediaType, options = {}) => this.#putStream(chunks, mediaType, options);
+      this.writeStream = async (resource, chunks, options = {}) => {
+        await this.#storeStream(resource.resource, chunks, resource.mediaType, options, resource.size);
+      };
+    }
+  }
+
+  key(resource: ResourceId): string {
+    return s3ResourceKey(this.#prefix, resource);
+  }
+
+  #owner(): { readonly ExpectedBucketOwner?: string } {
+    return this.#expectedBucketOwner === undefined ? {} : { ExpectedBucketOwner: this.#expectedBucketOwner };
+  }
+
+  async put(bytes: Uint8Array, mediaType: string, options: ResourceIOOptions = {}): Promise<BlobRef> {
+    assert(mediaType.trim().length > 0, "Resource mediaType must not be empty");
+    options.signal?.throwIfAborted();
+    const copy = Uint8Array.from(bytes);
+    const resource = `res_${randomUUID()}` as ResourceId;
+    await this.#client.put({
+      Bucket: this.#bucket,
+      Key: this.key(resource),
+      Body: copy,
+      ContentLength: copy.byteLength,
+      ContentType: mediaType,
+      ...this.#owner(),
+    }, options);
+    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);
+    assert(copy.byteLength === resource.size,
+      `Resource ${resource.resource} has size ${copy.byteLength}, expected ${resource.size}`);
+    await this.#client.put({
+      Bucket: this.#bucket,
+      Key: this.key(resource.resource),
+      Body: copy,
+      ContentLength: copy.byteLength,
+      ContentType: resource.mediaType,
+      ...this.#owner(),
+    }, options);
+  }
+
+  async get(resource: ResourceId, options: ResourceIOOptions = {}): Promise<Uint8Array | undefined> {
+    options.signal?.throwIfAborted();
+    const bytes = await this.#client.get({
+      Bucket: this.#bucket,
+      Key: this.key(resource),
+      ...this.#owner(),
+    }, options);
+    return bytes === undefined ? undefined : Uint8Array.from(bytes);
+  }
+
+  async has(resource: ResourceId, options: ResourceIOOptions = {}): Promise<boolean> {
+    options.signal?.throwIfAborted();
+    if (this.#client.head === undefined) {
+      return await this.#client.get({ Bucket: this.#bucket, Key: this.key(resource), ...this.#owner() }, options) !== undefined;
+    }
+    return await this.#client.head({ Bucket: this.#bucket, Key: this.key(resource), ...this.#owner() }, options) !== undefined;
+  }
+
+  async #openStream(resource: ResourceId, options: ResourceIOOptions = {}): Promise<AsyncIterable<Uint8Array> | undefined> {
+    options.signal?.throwIfAborted();
+    return await this.#client.open!({
+      Bucket: this.#bucket,
+      Key: this.key(resource),
+      ...this.#owner(),
+    }, options);
+  }
+
+  async #putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string, options: ResourceIOOptions = {}): Promise<BlobRef> {
+    assert(mediaType.trim().length > 0, "Resource mediaType must not be empty");
+    const resource = `res_${randomUUID()}` as ResourceId;
+    const size = await this.#storeStream(resource, chunks, mediaType, options);
+    return { kind: "blob", resource, size, mediaType };
+  }
+
+  async #storeStream(
+    resource: ResourceId,
+    chunks: AsyncIterable<Uint8Array>,
+    mediaType: string,
+    options: ResourceIOOptions,
+    expectedSize?: number,
+  ): Promise<number> {
+    options.signal?.throwIfAborted();
+    const client = this.#client as Required<Pick<S3ObjectClient,
+      "createMultipart" | "uploadPart" | "completeMultipart">> & S3ObjectClient;
+    const key = this.key(resource);
+    const owner = this.#owner();
+    const uploadId = await client.createMultipart({
+      Bucket: this.#bucket, Key: key, ContentType: mediaType, ...owner,
+    }, options);
+    const parts: { PartNumber: number; ETag: string }[] = [];
+    let pending: Uint8Array[] = [];
+    let pendingBytes = 0;
+    let size = 0;
+    const flush = async (): Promise<void> => {
+      options.signal?.throwIfAborted();
+      if (pendingBytes === 0 && parts.length > 0) return;
+      const body = new Uint8Array(pendingBytes);
+      let offset = 0;
+      for (const piece of pending) {
+        body.set(piece, offset);
+        offset += piece.byteLength;
+      }
+      pending = [];
+      pendingBytes = 0;
+      const partNumber = parts.length + 1;
+      const { etag } = await client.uploadPart({
+        Bucket: this.#bucket, Key: key, UploadId: uploadId,
+        PartNumber: partNumber, Body: body, ContentLength: body.byteLength, ...owner,
+      }, options);
+      parts.push({ PartNumber: partNumber, ETag: etag });
+    };
+    try {
+      for await (const value of chunks) {
+        options.signal?.throwIfAborted();
+        if (!(value instanceof Uint8Array)) throw new Error("Resource stream yielded non-bytes");
+        const chunk = Uint8Array.from(value);
+        size += chunk.byteLength;
+        if (!Number.isSafeInteger(size)) throw new Error("Resource stream exceeds the supported size");
+        let offset = 0;
+        while (offset < chunk.byteLength) {
+          const take = Math.min(this.#partSizeBytes - pendingBytes, chunk.byteLength - offset);
+          pending.push(chunk.slice(offset, offset + take));
+          pendingBytes += take;
+          offset += take;
+          if (pendingBytes === this.#partSizeBytes) await flush();
+        }
+      }
+      if (pendingBytes > 0 || parts.length === 0) await flush();
+      if (expectedSize !== undefined && size !== expectedSize) {
+        throw new Error(`Resource ${resource} has size ${size}, expected ${expectedSize}`);
+      }
+      options.signal?.throwIfAborted();
+      await client.completeMultipart({
+        Bucket: this.#bucket, Key: key, UploadId: uploadId,
+        MultipartUpload: { Parts: parts }, ...owner,
+      }, options);
+      return size;
+    } catch (error) {
+      try {
+        await client.abortMultipart!({
+          Bucket: this.#bucket, Key: key, UploadId: uploadId, ...owner,
+        }, { signal: AbortSignal.timeout(5_000) });
+      } catch (cleanupError) {
+        throw new Error(`${String(error)}; S3 multipart cleanup failed for ${uploadId}: ${String(cleanupError)}`, { cause: error });
+      }
+      throw error;
+    }
+  }
+}
+
+export function createS3ResourceStore(
+  options: CreateS3ResourceStorePackageOptions,
+): S3ResourceStore {
+  const prefix = normalizeS3ResourcePrefix(options.prefix);
+  const client = options.client ?? new AwsS3ObjectClient({
+    ...(options.region === undefined ? {} : { region: options.region }),
+    ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+    ...(options.forcePathStyle === undefined ? {} : { forcePathStyle: options.forcePathStyle }),
+  });
+  return new S3ResourceStore({
+    client,
+    bucket: options.bucket,
+    ...(options.partSizeBytes === undefined ? {} : { partSizeBytes: options.partSizeBytes }),
+    ...(prefix.length === 0 ? {} : { prefix }),
+    ...(options.expectedBucketOwner === undefined ? {} : { expectedBucketOwner: options.expectedBucketOwner }),
+  });
+}

package/packages/run/README.md

@@ -0,0 +1,23 @@
+# `@hypit/run`
+
+Syntax-neutral Run Source and complete Run Graph compiler.
+
+This package is outside Core and knows no XML, filename suffix, video type, Provider or Runtime
+configuration. Given a self-described source unit, a registered `RunFrontend`, an already compiled
+Author Source and trusted Run Fragment registry, it produces:
+
+```text
+RunSourceClosure + RunDocument -> complete RunGraph
+```
+
+The Run Graph always exists and binds the exact Author Graph. It contains Run Candidates,
+Operations, explicit Satisfaction edges and Targets. A run
+that selects only primary Candidates therefore still has identity and cannot be replaced by hidden
+CLI flags.
+
+`RunSourceClosure` separately binds original source bytes, Frontend id/implementation and decoded
+semantic meaning. `RunFragmentRegistry` accepts trusted Fragment packages only through the
+`hypit.run-fragment-host@1` Host-facet installer. Package loading does not interpret Fragment code.
+
+The optional official XML-like syntax lives in `@hypit/run-markup`. Another trusted Frontend can emit
+the same `RunDocument` without changing this package or Core.

package/packages/run/package.json

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

package/packages/run/src/candidate.ts

@@ -0,0 +1,33 @@
+import {
+  canonicalize,
+} from "@hypit/protocol";
+import type {
+  Candidate,
+  StoredValue,
+  TypeRef,
+} from "@hypit/protocol";
+
+export type ProvidedCandidateInput = {
+  readonly id: string;
+  readonly type: TypeRef;
+  readonly value: StoredValue;
+  readonly record?: string;
+};
+
+export function createProvidedCandidate(input: ProvidedCandidateInput): Candidate {
+  if (input.id.trim().length === 0) throw new Error("Provided Candidate id is empty");
+  const value = input.value.kind === "inline"
+    ? { kind: "inline" as const, value: canonicalize(input.value.value) }
+    : { ...input.value };
+  return {
+    id: `candidate:run:${input.id}`,
+    type: input.type,
+    root: {
+      kind: "value",
+      value: {
+        id: input.record ?? `provided:run:${input.id}`,
+        value,
+      },
+    },
+  };
+}

package/packages/run/src/facet.ts

@@ -0,0 +1,59 @@
+import type { GraphFragment } from "@hypit/elaborator";
+import type { HostFacet } from "@hypit/host";
+
+import type {
+  RunFragmentPackage,
+} from "./types.js";
+
+export const runFragmentHostAbi = "hypit.run-fragment-host@1";
+
+export type RunFragmentHostFacet = HostFacet & {
+  readonly abi: typeof runFragmentHostAbi;
+  readonly offers: readonly string[];
+  readonly implementation: RunFragmentPackage;
+};
+
+function validateFragments(fragments: Readonly<Record<string, GraphFragment>>): void {
+  for (const [name, fragment] of Object.entries(fragments)) {
+    if (name.trim().length === 0 || fragment.id.trim().length === 0) {
+      throw new Error("Run Fragment Host facet has an invalid export");
+    }
+  }
+}
+
+/** Package helper: expose inert Run Fragments through the exact Run Host ABI. */
+export function createRunFragmentHostFacet(item: RunFragmentPackage): RunFragmentHostFacet {
+  if (item.name.trim().length === 0) throw new Error("Run Fragment Host facet package name is empty");
+  validateFragments(item.fragments);
+  return {
+    abi: runFragmentHostAbi,
+    offers: [item.name],
+    implementation: item,
+  };
+}
+
+/**
+ * Install only facets addressed to this Host ABI. Package loading itself never interprets or
+ * activates the executable Fragment objects.
+ */
+export function installRunFragmentHostFacets(
+  facets: readonly HostFacet[],
+  registry: { register(item: RunFragmentPackage): void },
+): void {
+  for (const opaque of facets) {
+    if (opaque.abi !== runFragmentHostAbi) continue;
+    if (opaque.implementation === null || typeof opaque.implementation !== "object"
+      || Array.isArray(opaque.implementation)) {
+      throw new Error("Run Fragment Host facet has an invalid implementation");
+    }
+    const facet = opaque as RunFragmentHostFacet;
+    if (typeof facet.implementation.name !== "string"
+      || facet.implementation.fragments === null
+      || typeof facet.implementation.fragments !== "object"
+      || Array.isArray(facet.implementation.fragments)) {
+      throw new Error("Run Fragment Host facet has an invalid package implementation");
+    }
+    validateFragments(facet.implementation.fragments);
+    registry.register(facet.implementation);
+  }
+}

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

@@ -0,0 +1,23 @@
+import {
+  createFrontendHostFacet,
+  frontendsFromHostFacets,
+} from "@hypit/host";
+import type {
+  FrontendHostFacet,
+  HostFacet,
+} from "@hypit/host";
+import { sourceFrontendPackageAbi } from "@hypit/source";
+
+import type { RunFrontend } from "./types.js";
+
+export type RunFrontendHostFacet = FrontendHostFacet<"run", RunFrontend> & {
+  readonly abi: typeof sourceFrontendPackageAbi;
+};
+
+export function createRunFrontendHostFacet(frontend: RunFrontend): RunFrontendHostFacet {
+  return createFrontendHostFacet(sourceFrontendPackageAbi, "run", frontend) as RunFrontendHostFacet;
+}
+
+export function runFrontendsFromHostFacets(facets: readonly HostFacet[]): readonly RunFrontend[] {
+  return frontendsFromHostFacets<"run", RunFrontend>(sourceFrontendPackageAbi, "run", facets);
+}

package/packages/run/src/frontend.ts

@@ -0,0 +1,62 @@
+import {
+  maskSourceHeader,
+  parseSourceHeader,
+} from "@hypit/source";
+
+import type {
+  RunDocument,
+  RunFrontend,
+  RunFrontendRegistryLike,
+  RunFrontendSourceUnit,
+  RunSourceUnit,
+} from "./types.js";
+
+export class RunSourceError extends Error {
+  readonly code: string;
+  readonly subject: string | undefined;
+
+  constructor(code: string, message: string, subject?: string) {
+    super(message);
+    this.name = "RunSourceError";
+    this.code = code;
+    this.subject = subject;
+  }
+}
+
+function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {
+  if (!condition) throw new RunSourceError(code, message, subject);
+}
+
+export class RunFrontendRegistry implements RunFrontendRegistryLike {
+  readonly #frontends = new Map<string, RunFrontend>();
+
+  register(frontend: RunFrontend): void {
+    assert(frontend.id.trim().length > 0, "EMPTY_RUN_FRONTEND", "Run Frontend id is empty");
+    assert(!this.#frontends.has(frontend.id), "DUPLICATE_RUN_FRONTEND", `${frontend.id} is already registered`, frontend.id);
+    this.#frontends.set(frontend.id, frontend);
+  }
+
+  resolve(id: string): RunFrontend | undefined {
+    return this.#frontends.get(id);
+  }
+}
+
+export function prepareRunSource(source: RunSourceUnit): RunFrontendSourceUnit {
+  const header = parseSourceHeader(source.name, source.text);
+  return {
+    ...source,
+    text: maskSourceHeader(source.text, header),
+    header,
+  };
+}
+
+export async function compileRunSource(
+  source: RunSourceUnit,
+  frontends: RunFrontendRegistryLike,
+): Promise<{ readonly document: RunDocument }> {
+  const prepared = prepareRunSource(source);
+  const frontend = frontends.resolve(prepared.header.using);
+  assert(frontend !== undefined, "UNKNOWN_RUN_FRONTEND", `Run Frontend ${prepared.header.using} is not registered`, prepared.header.using);
+  const decoded = await frontend.decode(prepared);
+  return { document: decoded.document };
+}