@hypit/hypit 0.0.1 → 0.1.0

package/packages/runtime/src/execution.ts

@@ -0,0 +1,125 @@
+import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
+import type { CommandResult } from "@hypit/protocol";
+import type {
+  CapacityAcquire,
+  CapacityAcquireRequest,
+  CapacityReservation,
+} from "./capacity.js";
+
+export type BuildOutcome = "complete" | "failed" | "cancelled";
+
+export type BuildExecutionRequest = {
+  readonly build: string;
+  /** Installed component packages loaded when a Worker takes an execution turn. */
+  readonly componentPackages: readonly string[];
+  /** Exact project Result Repository selected at submission. */
+  readonly result: BuildResultRepositoryLocation;
+};
+
+export type BuildExecutionDecision = {
+  readonly outcome: BuildOutcome;
+  readonly reason?: string;
+};
+
+/** A durable instruction to stop launching work, independent of remote Operation termination. */
+export type BuildExecutionStop = {
+  readonly cause: "user-cancelled" | "execution-failed";
+  readonly reason?: string;
+};
+
+export type BuildExecutionAttention = {
+  readonly step: "result" | "cleanup";
+  readonly error: string;
+};
+
+export type BuildExecutionTurn = {
+  readonly owner: string;
+  readonly acquiredAt: number;
+};
+
+export type BuildResultWriteLease = BuildExecutionTurn;
+
+/**
+ * The complete active Runtime root for one Build.
+ *
+ * It has no persisted lifecycle phase. Scheduling is derived from `wakeAt` and `turn`; the one
+ * immutable execution conclusion is `decision`; `stop` records why new work must stop while
+ * the Result is written. Operator attention is an independent fact.
+ */
+export type BuildExecutionSnapshot = BuildExecutionRequest & {
+  readonly createdAt: number;
+  /** Absent when waiting for a resource release. */
+  readonly wakeAt?: number;
+  /** Only these Operations can advance the Build until their next outcome. */
+  readonly operationWait?: readonly string[];
+  readonly turn?: BuildExecutionTurn;
+  readonly resultWrite?: BuildResultWriteLease;
+  readonly stop?: BuildExecutionStop;
+  readonly decision?: BuildExecutionDecision;
+  readonly attention?: BuildExecutionAttention;
+};
+
+export type BuildExecutionActivity = "ready" | "running" | "waiting" | "saving-result";
+
+export function buildExecutionActivity(
+  execution: BuildExecutionSnapshot,
+  now = Date.now(),
+): BuildExecutionActivity {
+  if (execution.decision !== undefined) return "saving-result";
+  if (execution.turn !== undefined) return "running";
+  return execution.wakeAt === undefined || execution.wakeAt > now ? "waiting" : "ready";
+}
+
+/** Ephemeral acknowledgement returned after active Runtime state has been removed. */
+export type BuildCompletion = BuildExecutionDecision & {
+  readonly build: string;
+};
+
+export type BuildExecutionStore = {
+  create(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<BuildExecutionSnapshot>;
+  read(build: string): Promise<BuildExecutionSnapshot | undefined>;
+  list(): Promise<readonly BuildExecutionSnapshot[]>;
+  /** Atomically take one ready, undecided execution turn for this Worker owner. */
+  claim(owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
+  /** A new owning Worker clears turns left by the previous process; no external action is repeated here. */
+  reclaimTurns(now?: number): Promise<readonly string[]>;
+  /** An unobserved stop wakes the next turn immediately to finish the attempt. */
+  releaseTurn(build: string, owner: string, wakeAt: number | undefined, operationWait?: readonly string[]): Promise<BuildExecutionSnapshot>;
+  /** Freeze the one conclusion. An execution with a decision can never be claimed again. */
+  decide(build: string, owner: string, outcome: BuildOutcome, reason?: string): Promise<BuildExecutionSnapshot>;
+  /** Record the first stop request. Repeated requests cannot replace its cause or reason. */
+  requestStop(build: string, stop: BuildExecutionStop): Promise<BuildExecutionSnapshot>;
+  setAttention(build: string, attention: BuildExecutionAttention | undefined): Promise<BuildExecutionSnapshot>;
+  claimResultWrite(build: string, owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
+  releaseResultWrite(build: string, owner: string): Promise<BuildExecutionSnapshot>;
+  /** Clear only Result-writer ownership left by the previous Runtime process and record attention. */
+  reclaimResultWrites(): Promise<readonly string[]>;
+  acquireCapacity(request: CapacityAcquireRequest): Promise<CapacityAcquire>;
+  releaseCapacity(build: string, command: string): Promise<void>;
+  releaseBuildCapacity(build: string): Promise<void>;
+  reclaimActionCapacity(): Promise<void>;
+  listCapacity(): Promise<readonly CapacityReservation[]>;
+};
+
+export type CommandExecutionReceipt = {
+  readonly build: string;
+  readonly command: string;
+  readonly status: "started" | "completed";
+  readonly event?: CommandResult;
+};
+
+export type CommandExecutionBegin = {
+  readonly created: boolean;
+  readonly receipt: CommandExecutionReceipt;
+};
+
+/**
+ * Live handoff for commands that complete in one call. It prevents the same Build from invoking
+ * an immediate Producer or Endpoint again after the process stops between execution and Core fact.
+ */
+export type CommandExecutionStore = {
+  begin(build: string, command: string): Promise<CommandExecutionBegin>;
+  complete(build: string, command: string, event: CommandResult): Promise<CommandExecutionReceipt>;
+  list(build: string): Promise<readonly CommandExecutionReceipt[]>;
+  removeBuild(build: string): Promise<void>;
+};

package/packages/runtime/src/index.ts

@@ -0,0 +1,24 @@
+export { plannedNeeds } from "@hypit/core";
+export type * from "./catalog.js";
+export {
+  CompositeCredentialStore,
+  credentialRef,
+  decodeOAuth2Credential,
+  encodeOAuth2Credential,
+  isWritableCredentialStore,
+  writableCredentialStore,
+  verifyCredentialRef,
+} from "./credentials.js";
+export type * from "./credentials.js";
+export type * from "./capacity.js";
+export { capacityUnits } from "./capacity.js";
+export { buildExecutionActivity } from "./execution.js";
+export type * from "./execution.js";
+export type * from "./environment.js";
+export type * from "./operations.js";
+export { LocalBuildScheduler } from "./scheduler.js";
+export type * from "./submission.js";
+export {
+  isStreamingResourceStore,
+} from "./types.js";
+export type * from "./types.js";

package/packages/runtime/src/operations.ts

@@ -0,0 +1,99 @@
+import type {
+  CanonicalValue,
+  StoredValue,
+  FulfillNeedCommand,
+} from "@hypit/protocol";
+import type { CredentialRef } from "./credentials.js";
+
+/** Provider-authored, non-secret acknowledgement suitable for Results and user inspection. */
+export type OperationReceipt = {
+  readonly id: string;
+  readonly url?: string;
+};
+
+export type OperationFacts = {
+  readonly createdAt?: number;
+  readonly acknowledgedAt?: number;
+  readonly endedAt?: number;
+  /** The exact request needed to advance this Operation without materializing its Build. */
+  readonly request?: FulfillNeedCommand;
+  readonly credentials?: Readonly<Record<string, CredentialRef>>;
+  readonly pool?: string;
+  readonly receipt?: OperationReceipt;
+  readonly remoteEnded?: true;
+  readonly submission?: "queued" | "started" | "accepted";
+};
+
+export type OperationIdentity = {
+  readonly id: string;
+  readonly build: string;
+  readonly command: string;
+  readonly endpoint: string;
+};
+
+export type OperationCompletion = {
+  readonly value: StoredValue;
+};
+
+export type OperationFailure = {
+  readonly code: string;
+  readonly message: string;
+};
+
+/**
+ * Provider-neutral, human-observable progress for one asynchronous Operation.
+ *
+ * The opaque handle remains the Provider's private task state. This
+ * deliberately small projection is the only part Runtime tools may display;
+ * it must not carry credentials, request bodies or vendor-specific payloads.
+ */
+export type OperationProgress = {
+  readonly phase: string;
+  readonly completed?: number;
+  readonly total?: number;
+  readonly unit?: string;
+};
+
+export type OperationSnapshot = OperationIdentity & OperationFacts & {
+  readonly status: OperationUpdate["status"];
+  readonly handle?: CanonicalValue;
+  readonly wakeAt?: number;
+  readonly progress?: OperationProgress;
+  readonly completion?: OperationCompletion;
+  readonly failure?: OperationFailure;
+  /** Last acknowledgement of an explicit, best-effort cancellation request. */
+  readonly cancellation?: { readonly outcome: "confirmed" | "accepted" | "unsupported" | "too-late" | "failed"; readonly message?: string };
+};
+
+export type OperationUpdate = OperationFacts & (
+  | {
+      readonly status: "pending";
+      /** Candidate awaits Build-boundary validation. */
+      readonly completion?: OperationCompletion;
+      /** Provider-owned task state once submission is acknowledged. */
+      readonly handle?: CanonicalValue;
+      readonly wakeAt?: number;
+      readonly progress?: OperationProgress;
+    }
+  | {
+      readonly status: "completed";
+      readonly completion: OperationCompletion;
+    }
+  | { readonly status: "failed"; readonly failure: OperationFailure }
+  | { readonly status: "cancelled"; readonly cancellation?: OperationSnapshot["cancellation"] });
+
+export type OperationQuery = {
+  readonly build?: string;
+  readonly command?: string;
+  readonly endpoint?: string;
+};
+
+export type OperationStore = {
+  create(operation: OperationSnapshot): Promise<OperationSnapshot>;
+  read(id: string): Promise<OperationSnapshot | undefined>;
+  list(query: OperationQuery): Promise<readonly OperationSnapshot[]>;
+  /** One local Worker owns execution. A terminal Operation is returned unchanged. */
+  update(id: string, update: OperationUpdate): Promise<OperationSnapshot>;
+  /** Drop Provider execution payloads after the owning Build Result has an outcome. */
+  removeBuild?(build: string): Promise<void>;
+};

package/packages/runtime/src/scheduler.ts

@@ -0,0 +1,281 @@
+import { BuildMachine, reduce } from "@hypit/core";
+import type { BuildState, CommandResult } from "@hypit/protocol";
+import { capacityUnits } from "./capacity.js";
+
+import type {
+  BuildSchedulerOptions,
+  RuntimeCommandExecutor,
+  RuntimeExecutionResult,
+  RuntimeRunnableCommand,
+  ScheduledBuild,
+  ScheduledBuildResult,
+  SchedulerExecutionOutcome,
+} from "./types.js";
+
+type MutableBuild = {
+  readonly id: string;
+  state: BuildState;
+  machine: BuildMachine | undefined;
+  readonly outcomes: SchedulerExecutionOutcome[];
+  blocked: ScheduledBuildResult["blocked"];
+  stopped: boolean;
+  failure?: Extract<CommandResult, { readonly kind: "command-failed" }>;
+  readonly attempted: Set<string>;
+};
+
+type ActiveResult = {
+  readonly key: string;
+  readonly build: MutableBuild;
+  readonly command: RuntimeRunnableCommand;
+  readonly execution?: RuntimeExecutionResult;
+  readonly error?: unknown;
+};
+
+type ActiveCommand = {
+  readonly build: MutableBuild;
+  readonly command: RuntimeRunnableCommand;
+  readonly promise: Promise<ActiveResult>;
+};
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`${name} must be a positive safe integer`);
+  return value;
+}
+
+function buildCommandKey(build: string, command: string): string {
+  return `${build}\u0000${command}`;
+}
+
+/**
+ * Queue-free, one-process reference Scheduler. It atomically admits every declared resource
+ * across all submitted Builds,
+ * but never searches a Graph: every runnable command is regenerated by Core through the Executor.
+ */
+export class LocalBuildScheduler {
+  readonly #executor: RuntimeCommandExecutor;
+  readonly #buildStore: BuildSchedulerOptions["buildStore"];
+  readonly #onStateChange: BuildSchedulerOptions["onStateChange"];
+
+  constructor(executor: RuntimeCommandExecutor, options: BuildSchedulerOptions = {}) {
+    this.#executor = executor;
+    this.#buildStore = options.buildStore;
+    this.#onStateChange = options.onStateChange;
+  }
+
+  async run(requests: readonly ScheduledBuild[]): Promise<readonly ScheduledBuildResult[]> {
+    const ids = new Set<string>();
+    const builds: MutableBuild[] = [];
+    for (const request of requests) {
+      if (request.id.trim().length === 0) throw new Error("scheduled build id must not be empty");
+      if (ids.has(request.id)) throw new Error(`scheduled build ${request.id} is duplicated`);
+      ids.add(request.id);
+      let state: BuildState;
+      let machine: BuildMachine | undefined;
+      if (this.#buildStore === undefined) {
+        if (request.state === undefined) throw new Error(`scheduled Build ${request.id} has no in-memory state`);
+        state = structuredClone(request.state);
+      } else {
+        const snapshot = request.snapshot;
+        if (snapshot === undefined) {
+          throw new Error(`scheduled Build ${request.id} has no durable snapshot`);
+        }
+        if (snapshot.build !== request.id) {
+          throw new Error(`scheduled Build snapshot ${snapshot.build} does not belong to ${request.id}`);
+        }
+        state = snapshot.state;
+        machine = new BuildMachine(snapshot.definition, snapshot.facts);
+      }
+      builds.push({
+        id: request.id,
+        state,
+        machine,
+        outcomes: [],
+        blocked: [],
+        stopped: false,
+        attempted: new Set(),
+      });
+    }
+    const active = new Map<string, ActiveCommand>();
+    const resourceDefaults = new Map<string, number>();
+    let cursor = 0;
+
+    const resourceLimit = (resource: RuntimeRunnableCommand["resources"][number]): number => {
+      capacityUnits(resource);
+      const proposed = positiveInteger(resource.limit, `resource ${resource.id} limit`);
+      const previous = resourceDefaults.get(resource.id);
+      if (previous !== undefined && previous !== proposed) {
+        throw new Error(`resource ${resource.id} has conflicting default concurrency ${previous} and ${proposed}`);
+      }
+      resourceDefaults.set(resource.id, proposed);
+      return proposed;
+    };
+
+    const accept = async (build: MutableBuild, event: CommandResult): Promise<void> => {
+      if (this.#buildStore === undefined || build.machine === undefined) {
+        build.state = reduce(build.state, event);
+        await this.#onStateChange?.(build.id, build.state);
+        return;
+      }
+      const fact = build.machine.evaluate(event);
+      if (fact === undefined) {
+        build.state = build.machine.view();
+        return;
+      }
+      await this.#buildStore.append(build.id, fact);
+      build.machine.commit();
+      build.state = build.machine.view();
+      await this.#onStateChange?.(build.id, build.state);
+    };
+
+    const preparations = async (): Promise<Map<string, readonly RuntimeRunnableCommand[]>> => {
+      const ready = new Map<string, readonly RuntimeRunnableCommand[]>();
+      for (const build of builds) {
+        if (build.stopped || build.state.status === "complete" || build.state.status === "failed") {
+          ready.set(build.id, []);
+          continue;
+        }
+        const prepared = this.#executor.prepare(build.state);
+        build.state = prepared.state;
+        build.blocked = prepared.blocked;
+        ready.set(build.id, prepared.runnable.filter((item) =>
+          !active.has(buildCommandKey(build.id, item.command.id)) && !build.attempted.has(item.command.id)));
+      }
+      return ready;
+    };
+
+    const resourceCounts = (): Map<string, number> => {
+      const counts = new Map<string, number>();
+      for (const item of active.values()) {
+        for (const resource of item.command.resources) {
+          counts.set(resource.id, (counts.get(resource.id) ?? 0) + capacityUnits(resource));
+        }
+      }
+      return counts;
+    };
+
+    const launch = (build: MutableBuild, command: RuntimeRunnableCommand): void => {
+      const key = buildCommandKey(build.id, command.command.id);
+      const startedFrom = build.state;
+      const promise = this.#executor.executeCommand(startedFrom, command, { build: build.id }).then(
+        (execution) => ({ key, build, command, execution }),
+        (error: unknown) => ({ key, build, command, error }),
+      );
+      active.set(key, { build, command, promise });
+    };
+
+    try {
+      while (true) {
+        const ready = await preparations();
+        const counts = resourceCounts();
+
+        while (builds.length > 0) {
+          let selected = false;
+          for (let offset = 0; offset < builds.length; offset += 1) {
+            const index = (cursor + offset) % builds.length;
+            const build = builds[index]!;
+            const command = (ready.get(build.id) ?? []).find((candidate) =>
+              candidate.resources.every((resource) =>
+                (counts.get(resource.id) ?? 0) + capacityUnits(resource) <= resourceLimit(resource)));
+            if (command === undefined) continue;
+            ready.set(build.id, (ready.get(build.id) ?? []).filter((item) =>
+              item.command.id !== command.command.id));
+            launch(build, command);
+            for (const resource of command.resources) {
+              counts.set(resource.id, (counts.get(resource.id) ?? 0) + capacityUnits(resource));
+            }
+            cursor = (index + 1) % builds.length;
+            selected = true;
+            break;
+          }
+          if (!selected) break;
+        }
+
+        if (active.size === 0) break;
+        const settled = await Promise.race([...active.values()].map((item) => item.promise));
+        active.delete(settled.key);
+        const build = settled.build;
+        if (build.state.status === "failed" || build.state.status === "complete") continue;
+        if (settled.execution === undefined) {
+          build.stopped = true;
+          build.outcomes.push({
+            command: settled.command.command.id,
+            kind: settled.command.command.kind,
+            resources: settled.command.resources.map((resource) => resource.id),
+            status: "error",
+            message: settled.error instanceof Error ? settled.error.message : String(settled.error),
+          });
+          continue;
+        }
+        if (settled.execution.status === "pending") {
+          build.attempted.add(settled.command.command.id);
+          build.outcomes.push({
+            command: settled.command.command.id,
+            kind: settled.command.command.kind,
+            resources: settled.command.resources.map((resource) => resource.id),
+            status: "pending",
+            operation: settled.execution.operation,
+            ...(settled.execution.wakeAt === undefined ? {} : { wakeAt: settled.execution.wakeAt }),
+          });
+          continue;
+        }
+        if (settled.execution.status === "deferred") {
+          build.attempted.add(settled.command.command.id);
+          build.outcomes.push({
+            command: settled.command.command.id,
+            kind: settled.command.command.kind,
+            resources: settled.command.resources.map((resource) => resource.id),
+            status: "deferred",
+            ...(settled.execution.wakeAt === undefined ? {} : { wakeAt: settled.execution.wakeAt }),
+            message: settled.execution.reason,
+          });
+          continue;
+        }
+        const event = settled.execution.event;
+        try {
+          if (event.kind === "command-failed") {
+            // Stop launching work immediately, but accept results of calls already running
+            // before the failure clears Core's outstanding commands. No pending job is polled.
+            build.stopped = true;
+            build.failure ??= event;
+          } else {
+            await accept(build, event);
+          }
+          build.outcomes.push({
+            command: settled.command.command.id,
+            kind: settled.command.command.kind,
+            resources: settled.command.resources.map((resource) => resource.id),
+            status: "completed",
+          });
+        } catch (error) {
+          build.stopped = true;
+          build.outcomes.push({
+            command: settled.command.command.id,
+            kind: settled.command.command.kind,
+            resources: settled.command.resources.map((resource) => resource.id),
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      for (const build of builds) {
+        if (build.failure !== undefined) await accept(build, build.failure);
+      }
+
+    } catch (error) {
+      // Do not let a classification/configuration error release capacity beneath other active calls.
+      await Promise.allSettled([...active.values()].map((item) => item.promise));
+      throw error;
+    }
+
+    return builds.map((build) => ({
+      id: build.id,
+      status: build.state.status === "complete"
+        ? "complete"
+        : build.state.status === "failed" ? "failed" : "paused",
+      state: build.state,
+      outcomes: [...build.outcomes],
+      blocked: [...build.blocked],
+    }));
+  }
+}

package/packages/runtime/src/submission.ts

@@ -0,0 +1,24 @@
+import type { BuildDefinition } from "@hypit/protocol";
+import type { BuildCatalogDescriptor } from "./catalog.js";
+import type { BuildExecutionRequest, BuildExecutionSnapshot } from "./execution.js";
+
+export type PendingBuildSubmission = BuildExecutionRequest & {
+  readonly createdAt: number;
+};
+
+export type PendingBuildCommit = BuildExecutionRequest & {
+  readonly definition: BuildDefinition;
+  readonly catalog: BuildCatalogDescriptor;
+};
+
+/**
+ * One exact cross-store submission transaction. A pending submission is not schedulable and can
+ * only become active execution or be explicitly discarded with its Result draft and temporary resources.
+ */
+export type PendingBuildStore = {
+  prepare(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<PendingBuildSubmission>;
+  read(build: string): Promise<PendingBuildSubmission | undefined>;
+  list(): Promise<readonly PendingBuildSubmission[]>;
+  commit(request: PendingBuildCommit): Promise<BuildExecutionSnapshot>;
+  discard(build: string): Promise<void>;
+};