@hypit/hypit 0.0.1 → 0.1.0

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

@@ -0,0 +1,304 @@
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import type {
+  RunBuildRecord,
+  RunCandidateDeclaration,
+  RunDocument,
+  RunFragmentInstance,
+  RunImport,
+  RunProvidedFile,
+  RunProvidedValue,
+  RunSatisfaction,
+  RunTarget,
+} from "@hypit/run";
+import {
+  parseStructuredElement,
+  skipTextTrivia,
+} from "@hypit/markup";
+import type {
+  MarkupSource,
+  StructuredElement,
+} from "@hypit/markup";
+
+export class RunSyntaxError extends Error {
+  readonly code: string;
+  readonly offset: number;
+  readonly sourceName: string | undefined;
+  readonly line: number | undefined;
+  readonly column: number | undefined;
+
+  constructor(code: string, message: string, offset: number, sourceName?: string, source?: string) {
+    const before = source === undefined ? undefined : source.slice(0, offset);
+    const line = before === undefined ? undefined : before.split("\n").length;
+    const column = before === undefined ? undefined : [...(before.split("\n").at(-1) ?? "")].length + 1;
+    super(sourceName === undefined || line === undefined ? message : `${sourceName}:${line}:${column}: ${message}`);
+    this.name = "RunSyntaxError";
+    this.code = code;
+    this.offset = offset;
+    this.sourceName = sourceName;
+    this.line = line;
+    this.column = column;
+  }
+}
+
+function fail(element: StructuredElement, code: string, message: string): never {
+  throw new RunSyntaxError(code, message, element.range.start);
+}
+
+function elements(element: StructuredElement): readonly StructuredElement[] {
+  const result: StructuredElement[] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim().length > 0) fail(element, "RUN_TEXT", `<${element.name}> only accepts elements`);
+      continue;
+    }
+    result.push(child);
+  }
+  return result;
+}
+
+function exactAttributes(element: StructuredElement, allowed: readonly string[]): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) fail(element, "RUN_ATTRIBUTE", `<${element.name}> does not accept ${unknown[0]}`);
+}
+
+function stringAttribute(element: StructuredElement, name: string, required = true): string | undefined {
+  const value = element.attributes[name];
+  if (value === undefined) {
+    if (required) fail(element, "RUN_ATTRIBUTE", `<${element.name}> requires ${name}`);
+    return undefined;
+  }
+  if (typeof value !== "string") fail(element, "RUN_ATTRIBUTE", `<${element.name}> ${name} must be a string`);
+  const normalized = value.trim();
+  if (normalized.length === 0) fail(element, "RUN_ATTRIBUTE", `<${element.name}> ${name} must not be empty`);
+  return normalized;
+}
+
+function empty(element: StructuredElement): void {
+  if (elements(element).length > 0) fail(element, "RUN_CHILD", `<${element.name}> must be empty`);
+}
+
+function parseTypeRef(value: string): TypeRef {
+  const hash = value.lastIndexOf("#");
+  const version = hash <= 0 ? -1 : value.lastIndexOf("@", hash);
+  if (hash <= 0 || version <= 0 || version === hash - 1 || hash === value.length - 1) {
+    throw new Error(`Type ${value} must use package@version#Type`);
+  }
+  return {
+    module: { name: value.slice(0, version), version: value.slice(version + 1, hash) },
+    name: value.slice(hash + 1),
+  };
+}
+
+function authorDeclaration(element: StructuredElement): { readonly source: string } {
+  exactAttributes(element, ["source"]);
+  empty(element);
+  return { source: stringAttribute(element, "source")! };
+}
+
+function importDeclaration(element: StructuredElement): RunImport {
+  exactAttributes(element, ["from", "as"]);
+  empty(element);
+  return { from: stringAttribute(element, "from")!, as: stringAttribute(element, "as")! };
+}
+
+function target(element: StructuredElement): RunTarget {
+  exactAttributes(element, ["output"]);
+  empty(element);
+  return { output: stringAttribute(element, "output")! };
+}
+
+function provided(element: StructuredElement): RunProvidedValue {
+  exactAttributes(element, ["id", "type", "from"]);
+  empty(element);
+  let type: TypeRef;
+  try {
+    type = parseTypeRef(stringAttribute(element, "type")!);
+  } catch (error) {
+    fail(element, "RUN_TYPE", error instanceof Error ? error.message : String(error));
+  }
+  return {
+    kind: "provided",
+    id: stringAttribute(element, "id")!,
+    type,
+    from: stringAttribute(element, "from")!,
+  };
+}
+
+function file(element: StructuredElement): RunProvidedFile {
+  exactAttributes(element, ["id", "type", "from", "media-type"]);
+  empty(element);
+  let type: TypeRef;
+  try {
+    type = parseTypeRef(stringAttribute(element, "type")!);
+  } catch (error) {
+    fail(element, "RUN_TYPE", error instanceof Error ? error.message : String(error));
+  }
+  const mediaType = stringAttribute(element, "media-type")!;
+  if (!/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/iu.test(mediaType)) {
+    fail(element, "RUN_MEDIA_TYPE", "<file> media-type must be a concrete MIME media type");
+  }
+  return {
+    kind: "file",
+    id: stringAttribute(element, "id")!,
+    type,
+    from: stringAttribute(element, "from")!,
+    mediaType,
+  };
+}
+
+function buildRecord(element: StructuredElement): RunBuildRecord {
+  exactAttributes(element, ["id", "build", "output"]);
+  empty(element);
+  return {
+    kind: "build-record",
+    id: stringAttribute(element, "id")!,
+    build: stringAttribute(element, "build")!,
+    output: stringAttribute(element, "output")!,
+  };
+}
+
+function scalar(value: string): CanonicalValue {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u.test(value)) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return value;
+}
+
+function fragment(element: StructuredElement): RunFragmentInstance {
+  exactAttributes(element, ["id", "using"]);
+  const using = stringAttribute(element, "using")!;
+  const separator = using.indexOf(":");
+  if (separator <= 0 || separator === using.length - 1) {
+    fail(element, "RUN_FRAGMENT_REF", `<fragment> using must be alias:fragment`);
+  }
+  const inputs: RunFragmentInstance["inputs"][number][] = [];
+  const exports: string[] = [];
+  for (const child of elements(element)) {
+    if (child.name === "input") {
+      exactAttributes(child, ["name", "from", "value"]);
+      empty(child);
+      const name = stringAttribute(child, "name")!;
+      const from = stringAttribute(child, "from", false);
+      const value = stringAttribute(child, "value", false);
+      if ((from === undefined) === (value === undefined)) {
+        fail(child, "RUN_FRAGMENT_INPUT", `<input> ${name} requires exactly one of from or value`);
+      }
+      inputs.push(from === undefined ? { name, value: scalar(value!) } : { name, from });
+      continue;
+    }
+    if (child.name === "export") {
+      exactAttributes(child, ["name"]);
+      empty(child);
+      exports.push(stringAttribute(child, "name")!);
+      continue;
+    }
+    fail(child, "RUN_CHILD", `<fragment> does not accept <${child.name}>`);
+  }
+  unique(inputs.map((item) => item.name), `${stringAttribute(element, "id")} Fragment input`, element);
+  unique(exports, `${stringAttribute(element, "id")} Fragment export`, element);
+  return {
+    kind: "fragment",
+    id: stringAttribute(element, "id")!,
+    using: { alias: using.slice(0, separator), name: using.slice(separator + 1) },
+    inputs,
+    ...(exports.length === 0 ? {} : { exports }),
+  };
+}
+
+function satisfaction(element: StructuredElement): RunSatisfaction {
+  exactAttributes(element, ["output", "candidate"]);
+  empty(element);
+  return {
+    output: stringAttribute(element, "output")!,
+    candidate: stringAttribute(element, "candidate")!,
+  };
+}
+
+function unique(values: readonly string[], subject: string, element: StructuredElement): void {
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (seen.has(value)) fail(element, "RUN_DUPLICATE", `${subject} repeats ${value}`);
+    seen.add(value);
+  }
+}
+
+/** Parse only the public Run language. No package code, Runtime or Provider executes here. */
+function parseRunDocumentBody(name: string, text: string): RunDocument {
+  const source: MarkupSource = { name, text };
+  const start = skipTextTrivia(source, 0);
+  const parsed = parseStructuredElement(source, start);
+  const end = skipTextTrivia(source, parsed.nextOffset);
+  if (end !== text.length) throw new RunSyntaxError("RUN_TRAILING", "Only trivia may follow </svrun>", end);
+  const root = parsed.element;
+  if (root.name !== "svrun") fail(root, "RUN_ROOT", "Run document root must be <svrun>");
+  exactAttributes(root, ["version"]);
+  if (stringAttribute(root, "version") !== "1") fail(root, "RUN_VERSION", "Only .svrun version 1 is supported");
+
+  let author: { readonly source: string } | undefined;
+  const imports: RunImport[] = [];
+  const targets: RunTarget[] = [];
+  const candidates: RunCandidateDeclaration[] = [];
+  const satisfactions: RunSatisfaction[] = [];
+  const satisfiedOutputs = new Set<string>();
+  let bodyStarted = false;
+  for (const child of elements(root)) {
+    if (child.name === "author") {
+      if (bodyStarted || author !== undefined || imports.length > 0) {
+        fail(child, "RUN_AUTHOR_ORDER", "<author> must be the first and only Author declaration");
+      }
+      author = authorDeclaration(child);
+      continue;
+    }
+    if (child.name === "import") {
+      if (bodyStarted) fail(child, "RUN_IMPORT_ORDER", "Run imports must form the opening prologue");
+      if (author === undefined) fail(child, "RUN_AUTHOR_ORDER", "<author> must precede Run imports");
+      imports.push(importDeclaration(child));
+      continue;
+    }
+    bodyStarted = true;
+    if (author === undefined) fail(child, "RUN_AUTHOR_MISSING", "<svrun> requires an opening <author> declaration");
+    if (child.name === "target") targets.push(target(child));
+    else if (child.name === "value") candidates.push(provided(child));
+    else if (child.name === "file") candidates.push(file(child));
+    else if (child.name === "build-record") candidates.push(buildRecord(child));
+    else if (child.name === "fragment") candidates.push(fragment(child));
+    else if (child.name === "satisfy") {
+      const item = satisfaction(child);
+      if (satisfiedOutputs.has(item.output)) {
+        fail(child, "RUN_SATISFACTION_DUPLICATE", `<satisfy> repeats output ${item.output}`);
+      }
+      satisfiedOutputs.add(item.output);
+      satisfactions.push(item);
+    }
+    else fail(child, "RUN_CHILD", `<svrun> does not accept <${child.name}>`);
+  }
+  if (author === undefined) fail(root, "RUN_AUTHOR_MISSING", "<svrun> requires exactly one <author> declaration");
+
+  unique(imports.map((item) => item.as), "Run import alias", root);
+  unique(candidates.map((item) => item.id), "Candidate declaration", root);
+  unique(targets.map((item) => item.output), "Run target", root);
+  if (targets.length === 0) fail(root, "RUN_TARGETS", "<svrun> requires at least one <target>");
+  return {
+    format: "hypit.run-document@1",
+    author,
+    imports,
+    targets,
+    candidates,
+    satisfactions,
+  };
+}
+
+export function parseRunDocument(name: string, text: string): RunDocument {
+  try {
+    return parseRunDocumentBody(name, text);
+  } catch (error) {
+    if (error instanceof RunSyntaxError && error.sourceName === undefined) {
+      throw new RunSyntaxError(error.code, error.message, error.offset, name, text);
+    }
+    throw error;
+  }
+}

package/packages/runtime/README.md

@@ -0,0 +1,39 @@
+# `@hypit/runtime`
+
+Environment neutral execution contracts around Core.
+
+The package defines the small ports used by a runtime:
+
+* `BuildStore` keeps one active Build definition and its accepted facts until the Result is saved and active state is removed.
+* `OperationStore` keeps asynchronous external work only while the owning Build is active.
+* `PendingBuildStore` owns the short submission transaction before the Build becomes active.
+* `BuildExecutionStore` owns active scheduling facts, a stop request, the immutable decision, attention and shared capacity reservations.
+* `ResourceStore` is the transient byte gateway used during Provider execution.
+* `CredentialStore` resolves secrets outside source and build state.
+* `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.
+* `LocalBuildScheduler` runs ready commands concurrently while respecting declared resource limits.
+
+These contracts do not define historical Build Results or choose a provider or source language. The default local
+implementation lives in `@hypit/runtime-local`; Node component and endpoint execution lives in
+`@hypit/driver-node`.
+
+The scheduler never changes graph meaning. Targets and candidates are fixed before execution, and
+resource limits only control when an already selected command may run.
+
+Resource I/O accepts an optional `ResourceIOOptions` with an `AbortSignal`. The selected store owns
+stopping its transport and closing its streams before the call rejects. A caller passing a stream
+to `putStream` or `writeStream` uses the same signal for its producer, so a pending chunk can also
+be interrupted. Cancellation affects the current transfer; completed resources remain available.
+An execution deadline belongs to its caller and is passed through this ordinary I/O interface.
+
+
+A Build's `stop` records `user-cancelled` or `execution-failed` and an optional reason. The first
+cause is retained. Runtime stops launching work, saves the attempt's outcome, completed Outputs and
+available Operation receipts, then releases its local reservations. Pending remote work can remain
+pending in the Result: ending local execution does not assert that a cloud task was cancelled.
+A later attempt is a new Build with explicit Run Candidates for reusable Outputs or retrieved files.
+
+Capacity claims describe occupancy; action rate budgets describe admissions over time. An asynchronous
+Operation holds its declared occupancy while Runtime manages the remote task. Its submit, poll and
+collect actions can have separate concurrency and rate limits. Waiting claims park until a resource
+release or their next eligible time; polling does not require rematerializing the whole Build.

package/packages/runtime/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/runtime",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/build-result-kit": "workspace:*",
+    "@hypit/core": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/runtime/src/capacity.ts

@@ -0,0 +1,51 @@
+/** A shared resource: occupancy when periodMs is absent, a replenishing rate budget otherwise. */
+export type CapacityResourceClaim = {
+  readonly id: string;
+  readonly limit: number;
+  /** Number of units held by this Command; ordinary requests occupy one. */
+  readonly units?: number;
+  /** Replenish `limit` units per period, with a burst of at most `limit`. Rate units are not returned. */
+  readonly periodMs?: number;
+};
+
+export function capacityUnits(resource: CapacityResourceClaim): number {
+  const units = resource.units ?? 1;
+  if (resource.id.trim().length === 0 || !Number.isSafeInteger(resource.limit) || resource.limit < 1
+    || !Number.isSafeInteger(units) || units < 1) {
+    throw new Error(`Capacity ${resource.id} requires a positive integer limit and units`);
+  }
+  if (units > resource.limit) {
+    throw new Error(`Capacity ${resource.id} request needs ${units} units but its limit is ${resource.limit}`);
+  }
+  if (resource.periodMs !== undefined && (!Number.isSafeInteger(resource.periodMs) || resource.periodMs < 1)) {
+    throw new Error(`Resource ${resource.id} periodMs must be a positive integer`);
+  }
+  return units;
+}
+
+/** Capacity held by one executing Command, including a pending external Operation. */
+export type CapacityReservation = {
+  readonly build: string;
+  readonly command: string;
+  readonly resources: readonly CapacityResourceClaim[];
+  readonly createdAt: number;
+  readonly lifetime?: "action" | "operation";
+};
+
+export type CapacityAcquireRequest = {
+  readonly lifetime?: "action" | "operation";
+  readonly build: string;
+  readonly command: string;
+  readonly resources: readonly CapacityResourceClaim[];
+  readonly now: number;
+};
+
+export type CapacityAcquire =
+  | { readonly status: "acquired"; readonly reservation: CapacityReservation }
+  | {
+      readonly status: "blocked";
+      /** Absent when only a resource release can make this work ready. */
+      readonly availableAt?: number;
+      readonly reason: "resource-in-flight" | "rate-limit";
+      readonly resource: string;
+    };

package/packages/runtime/src/catalog.ts

@@ -0,0 +1,30 @@
+import type {
+  LogicalOutputRef,
+} from "@hypit/protocol";
+
+export type BuildPublishedOutput = {
+  readonly name: string;
+  readonly ref: LogicalOutputRef;
+};
+
+export type BuildCatalogDescriptor = {
+  readonly source: {
+    readonly path: string;
+  };
+  readonly run?: {
+    readonly path: string;
+  };
+  readonly publishedOutputs: readonly BuildPublishedOutput[];
+};
+
+export type BuildCatalogEntry = BuildCatalogDescriptor & {
+  readonly build: string;
+};
+
+/** Host presentation index only. It is never Build truth. */
+export type BuildCatalog = {
+  record(build: string, descriptor: BuildCatalogDescriptor): Promise<BuildCatalogEntry>;
+  read(build: string): Promise<BuildCatalogEntry | undefined>;
+  /** Result manifests own finished presentation; Runtime Catalog covers active execution only. */
+  remove?(build: string): Promise<void>;
+};

package/packages/runtime/src/credentials.ts

@@ -0,0 +1,124 @@
+export type CredentialRef = {
+  /** CredentialStore implementation name, for example env, os or aws-default. */
+  readonly store: string;
+  /** Store-local opaque lookup key. It is configuration, never the secret value. */
+  readonly key: string;
+};
+
+export type CredentialValue = {
+  /** Opaque secret revealed only to the selected Endpoint invocation. */
+  readonly secret: string;
+  readonly expiresAt?: number;
+};
+
+export type OAuth2Credential = {
+  readonly format: "hypit.oauth2-credential@1";
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  readonly expiresAt?: number;
+};
+
+export function encodeOAuth2Credential(value: Omit<OAuth2Credential, "format">): string {
+  assert(value.accessToken.length > 0, "OAuth access token is empty");
+  if (value.refreshToken !== undefined) assert(value.refreshToken.length > 0, "OAuth refresh token is empty");
+  if (value.expiresAt !== undefined) assert(Number.isFinite(value.expiresAt), "OAuth expiry is invalid");
+  return JSON.stringify({ format: "hypit.oauth2-credential@1", ...value } satisfies OAuth2Credential);
+}
+
+export function decodeOAuth2Credential(secret: string): OAuth2Credential | undefined {
+  let value: unknown;
+  try { value = JSON.parse(secret); } catch { return undefined; }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const candidate = value as Partial<OAuth2Credential>;
+  if (candidate.format !== "hypit.oauth2-credential@1"
+    || typeof candidate.accessToken !== "string" || candidate.accessToken.length === 0
+    || (candidate.refreshToken !== undefined
+      && (typeof candidate.refreshToken !== "string" || candidate.refreshToken.length === 0))
+    || (candidate.expiresAt !== undefined
+      && (typeof candidate.expiresAt !== "number" || !Number.isFinite(candidate.expiresAt)))) return undefined;
+  return candidate as OAuth2Credential;
+}
+
+/** Host-facing way to acquire one credential; Provider-specific values stay in its Endpoint package. */
+export type CredentialAcquisition = {
+  readonly kind: "oauth2-pkce";
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly clientId: string;
+  readonly scopes: readonly string[];
+  /** Maximum duration of the service-owned token exchange after browser authorization returns. */
+  readonly requestTimeoutMs: number;
+};
+
+export type CredentialStore = {
+  resolve(ref: CredentialRef): Promise<CredentialValue | undefined>;
+};
+
+export type WritableCredentialStore = CredentialStore & {
+  owns(ref: CredentialRef): boolean;
+  put(ref: CredentialRef, value: CredentialValue): Promise<void>;
+  delete(ref: CredentialRef): Promise<boolean>;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function credentialRef(store: string, key: string): CredentialRef {
+  const value = { store, key };
+  verifyCredentialRef(value);
+  return value;
+}
+
+export function verifyCredentialRef(ref: CredentialRef): void {
+  assert(ref.store.trim().length > 0, "CredentialRef store is empty");
+  assert(ref.key.trim().length > 0, "CredentialRef key is empty");
+}
+
+export function isWritableCredentialStore(value: CredentialStore): value is WritableCredentialStore {
+  return "owns" in value && typeof value.owns === "function"
+    && "put" in value && typeof value.put === "function"
+    && "delete" in value && typeof value.delete === "function";
+}
+
+export async function writableCredentialStore(
+  store: CredentialStore,
+  ref: CredentialRef,
+): Promise<WritableCredentialStore | undefined> {
+  verifyCredentialRef(ref);
+  if (store instanceof CompositeCredentialStore) return await store.writable(ref);
+  return isWritableCredentialStore(store) && store.owns(ref) ? store : undefined;
+}
+
+/**
+ * Compose independently selected stores without a central store-name registry. Every implementation
+ * sees the exact CredentialRef and must decline names it does not own. Ambiguous ownership fails.
+ */
+export class CompositeCredentialStore implements CredentialStore {
+  readonly #stores: readonly CredentialStore[];
+
+  constructor(stores: readonly CredentialStore[]) {
+    this.#stores = [...stores];
+  }
+
+  async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
+    verifyCredentialRef(ref);
+    const resolved = (await Promise.all(this.#stores.map(async (store) => await store.resolve(ref))))
+      .filter((value): value is CredentialValue => value !== undefined);
+    assert(resolved.length <= 1, `CredentialRef store ${ref.store} is implemented more than once`);
+    return resolved[0];
+  }
+
+  async writable(ref: CredentialRef): Promise<WritableCredentialStore | undefined> {
+    verifyCredentialRef(ref);
+    const candidates: WritableCredentialStore[] = [];
+    for (const store of this.#stores) {
+      if (!isWritableCredentialStore(store)) continue;
+      // A read cannot prove ownership for a missing key. Writable implementations therefore expose
+      // an optional structural ownership predicate rather than a framework registry.
+      if (store.owns(ref)) candidates.push(store);
+    }
+    assert(candidates.length <= 1, `CredentialRef store ${ref.store} has several writable owners`);
+    return candidates[0];
+  }
+}

package/packages/runtime/src/environment.ts

@@ -0,0 +1,6 @@
+export type RuntimeEnvironmentStore = {
+  /** Select this literal normalized configuration, changing it only when no Runtime work is active. */
+  use(config: string): Promise<void>;
+  /** Refuse work when this Runtime instance was assembled from a different active configuration. */
+  assert(config: string): Promise<void>;
+};