@hypit/hypit 0.0.1 → 0.1.1

package/packages/runtime-host-node/src/packages.ts

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export type RegistryPackageSpec = {
+  readonly name: string;
+  readonly version: string;
+  readonly specifier: string;
+};
+
+export type HostPackageReport = RegistryPackageSpec & {
+  readonly root: string;
+  readonly action: "already-installed" | "installed";
+};
+
+export type HostPackageProgress = RegistryPackageSpec & {
+  readonly phase: "checking" | "installing" | "ready";
+};
+
+function exactVersion(value: string): boolean {
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(value);
+}
+
+/** Registry packages are pinned by version; npm owns their files and dependency graph. */
+export function parseRegistryPackageSpec(specifier: string): RegistryPackageSpec {
+  const value = specifier.trim();
+  const slash = value.startsWith("@") ? value.indexOf("/", 1) : -1;
+  const at = value.lastIndexOf("@");
+  const split = value.startsWith("@") ? (at > slash ? at : -1) : at;
+  const name = split > 0 ? value.slice(0, split) : "";
+  const version = split > 0 ? value.slice(split + 1) : "";
+  if (name.length === 0 || name.startsWith("@hypit/") || !exactVersion(version)) {
+    throw new Error(
+      `${specifier} must name one external npm registry package at an exact version, for example hyperframes@0.7.101`,
+    );
+  }
+  if (name.startsWith("@") && (slash < 2 || slash >= name.length - 1)) {
+    throw new Error(`${specifier} is not a valid scoped npm package specifier`);
+  }
+  if (!name.startsWith("@") && !/^[a-z0-9][a-z0-9._-]*$/u.test(name)) {
+    throw new Error(`${specifier} is not a valid npm package specifier`);
+  }
+  return { name, version, specifier: `${name}@${version}` };
+}
+
+async function installedVersion(root: string, name: string): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(await readFile(
+      join(root, "node_modules", ...name.split("/"), "package.json"),
+      "utf8",
+    )) as { readonly name?: unknown; readonly version?: unknown };
+    return manifest.name === name && typeof manifest.version === "string"
+      ? manifest.version
+      : undefined;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function inspectHostPackage(
+  specifier: string,
+  root: string,
+): Promise<HostPackageReport | undefined> {
+  const required = parseRegistryPackageSpec(specifier);
+  const version = await installedVersion(resolve(root), required.name);
+  return version === required.version
+    ? { ...required, root: resolve(root), action: "already-installed" }
+    : undefined;
+}
+
+function runNpm(root: string, specifiers: readonly string[]): Promise<void> {
+  const npmArgs = [
+    "install",
+    "--prefix", root,
+    "--save-exact",
+    "--package-lock=false",
+    "--no-audit",
+    "--no-fund",
+    "--omit=dev",
+    ...specifiers,
+  ];
+  const windows = process.platform === "win32";
+  const command = windows ? (process.env.ComSpec ?? "cmd.exe") : "npm";
+  const args = windows ? ["/d", "/s", "/c", "npm.cmd", ...npmArgs] : npmArgs;
+  return new Promise((done, reject) => {
+    const child = spawn(command, args, {
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    child.stdout.on("data", (chunk: Buffer) => { output = `${output}${chunk.toString()}`.slice(-32_000); });
+    child.stderr.on("data", (chunk: Buffer) => { output = `${output}${chunk.toString()}`.slice(-32_000); });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) done();
+      else reject(new Error(`npm install failed${output.trim().length === 0 ? "" : `: ${output.trim().split("\n").at(-1)}`}`));
+    });
+  });
+}
+
+/**
+ * Install missing upstream packages into one user/machine npm home.
+ * npm's ordinary package.json is the only persistent package-set record; Hypit
+ * creates no lock, receipt, hash inventory or project-local copy.
+ */
+export async function prepareHostPackages(
+  specifiers: readonly string[],
+  options: {
+    readonly root: string;
+    readonly onProgress?: (event: HostPackageProgress) => void;
+  },
+): Promise<readonly HostPackageReport[]> {
+  const root = resolve(options.root);
+  const byName = new Map<string, RegistryPackageSpec>();
+  for (const specifier of specifiers) {
+    const parsed = parseRegistryPackageSpec(specifier);
+    const previous = byName.get(parsed.name);
+    if (previous !== undefined && previous.version !== parsed.version) {
+      throw new Error(`${parsed.name} is required at both ${previous.version} and ${parsed.version}`);
+    }
+    byName.set(parsed.name, parsed);
+  }
+  const required = [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+  const missing: RegistryPackageSpec[] = [];
+  for (const item of required) {
+    options.onProgress?.({ ...item, phase: "checking" });
+    if (await installedVersion(root, item.name) !== item.version) missing.push(item);
+  }
+  if (missing.length > 0) {
+    await mkdir(root, { recursive: true });
+    try {
+      await readFile(join(root, "package.json"), "utf8");
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+      await writeFile(join(root, "package.json"), `${JSON.stringify({
+        name: "hypit-machine-packages",
+        private: true,
+        description: "Upstream npm packages used on demand by Hypit",
+        dependencies: {},
+      }, null, 2)}\n`, "utf8");
+    }
+    for (const item of missing) options.onProgress?.({ ...item, phase: "installing" });
+    await runNpm(root, missing.map((item) => item.specifier));
+  }
+  const installed = new Set(missing.map((item) => item.name));
+  const reports: HostPackageReport[] = [];
+  for (const item of required) {
+    const version = await installedVersion(root, item.name);
+    if (version !== item.version) {
+      throw new Error(`npm did not install ${item.specifier} into ${root}`);
+    }
+    options.onProgress?.({ ...item, phase: "ready" });
+    reports.push({ ...item, root, action: installed.has(item.name) ? "installed" : "already-installed" });
+  }
+  return reports;
+}

package/packages/runtime-kit/README.md

@@ -0,0 +1,42 @@
+# `@hypit/hypit/runtime-kit`
+
+Host facets for the two environmental choices a Local Runtime Profile may select:
+
+* an Endpoint implements external capabilities;
+* a Credential Store resolves explicit credential references.
+
+External packages use this public subpath from their `@hypit/hypit` development dependency. The built
+package's `hypit.activation` entry exports a default package contribution with
+`format: "hypit.node-package@1"` and the declared `hostFacets`.
+
+For a Provider, `createRuntimeEndpointAdapterFacet({ use, activate })` advertises its owner-scoped
+package name. `activate(context)` reads `instance`, `pool`, and the package's own `config`, then
+returns `{ endpoint }` from `defineEndpointPackage`; it can also return `program` and `diagnose`.
+The configuration helpers parse values and CredentialRefs. Activation describes the deployment;
+credential resolution, remote invocation, and Managed Program startup happen through their Runtime
+operations. Installing the same package in another project preserves its `use` name.
+
+```json
+{
+  "endpoints": {
+    "art.personal": {
+      "use": "@studio/provider-art",
+      "config": { "apiKey": { "store": "os", "key": "art.personal" } }
+    }
+  }
+}
+```
+
+This is a Profile fragment: the Provider defines its actual config fields, and the complete Profile
+selects the `os` Credential Store as well. Separate instances can use separate accounts. A binding
+names the chosen instance when several offer the same capability. The default pool identity is the
+instance; declare a shared pool only for a real shared account, deployment, or compute quota.
+
+Each adapter is addressed by its kind and `use` name. A package advertises that name through a Host
+facet; the Runtime Profile selects it explicitly. Installing a package does not activate it.
+
+Endpoint activation returns one Endpoint and may also describe a Managed Program such as a warm local
+WhisperX process. Credential adapters validate configuration before opening a store. Active Resource
+storage belongs to the Runtime implementation, while project Build Result repositories use the
+separate `@hypit/build-result-kit` boundary. Runtime Kit knows no Provider, filesystem, database or
+video package by name.

package/packages/runtime-kit/package.json

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

package/packages/runtime-kit/src/index.ts

@@ -0,0 +1,307 @@
+import { endpointActions } from "@hypit/endpoint-kit";
+import type { EndpointPackage } from "@hypit/endpoint-kit";
+import type { HostFacet } from "@hypit/host";
+import type { CanonicalValue } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, CredentialStore, CredentialValue } from "@hypit/runtime";
+
+export const runtimeEndpointAdapterHostAbi = "hypit.runtime-endpoint-adapter-host@1";
+export const runtimeCredentialStoreAdapterHostAbi = "hypit.runtime-credential-store-adapter-host@1";
+
+export type RuntimeAdapterKind = "endpoint" | "credential-store";
+
+type RuntimeAdapterAddress = {
+  readonly use: string;
+  readonly kind: RuntimeAdapterKind;
+};
+
+export type RuntimeAdapterFactoryContext = {
+  /** Persistent machine/user state supplied by the Host, outside every author project. */
+  readonly hostStateRoot: string;
+  /** Runtime/Profile state belonging to this project. */
+  readonly dataRoot: string;
+  readonly instance: string;
+  readonly pool?: string;
+  readonly config: CanonicalValue;
+};
+
+export type RuntimeDoctorDiagnostic = {
+  readonly severity: "error" | "warning" | "info";
+  readonly code: string;
+  readonly message: string;
+  readonly subject?: string;
+};
+
+export type ManagedProgramCommand = {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+};
+
+export type ManagedProgramInstallation = {
+  /** Truthful inspection of the installed program; no installer-owned receipt. */
+  probe(): Promise<ManagedProgramState>;
+  /** Commands run only when the installation probe is not ready. */
+  readonly commands: readonly ManagedProgramCommand[];
+};
+
+export type ManagedProgramState =
+  | { readonly state: "ready" }
+  | { readonly state: "down"; readonly detail: string }
+  | { readonly state: "mismatch"; readonly detail: string };
+
+export type ManagedProgram = {
+  readonly id: string;
+  /** Shared lifecycle files live here; absent means this Runtime owns them. */
+  readonly stateRoot?: string;
+  /** Installation and runtime readiness are deliberately separate states. */
+  readonly installation?: ManagedProgramInstallation;
+  probe(): Promise<ManagedProgramState>;
+  readonly start?: ManagedProgramCommand;
+};
+
+export type RuntimeEndpointActivation = {
+  readonly endpoint: EndpointPackage;
+  readonly program?: ManagedProgram;
+  readonly diagnose?: (context: {
+    readonly credentials: Readonly<Record<string, CredentialValue>>;
+    readonly capabilities?: readonly import("@hypit/protocol").CapabilityRef[];
+  }) => readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
+};
+
+export type RuntimeOpened<T> = {
+  readonly value: T;
+  readonly close?: () => void | Promise<void>;
+};
+
+export type RuntimeEndpointAdapterImplementation = {
+  activate(context: RuntimeAdapterFactoryContext): RuntimeEndpointActivation | Promise<RuntimeEndpointActivation>;
+};
+
+type RuntimeStoreAdapterImplementation<T> = {
+  validate(context: RuntimeAdapterFactoryContext): void;
+  open(context: RuntimeAdapterFactoryContext): RuntimeOpened<T> | Promise<RuntimeOpened<T>>;
+  doctor?(context: RuntimeAdapterFactoryContext): readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
+};
+
+type RuntimeAdapterImplementation =
+  | RuntimeEndpointAdapterImplementation
+  | RuntimeStoreAdapterImplementation<CredentialStore>;
+
+export type RuntimeAdapterHostFacet = HostFacet & {
+  readonly abi:
+    | typeof runtimeEndpointAdapterHostAbi
+    | typeof runtimeCredentialStoreAdapterHostAbi;
+  readonly implementation: RuntimeAdapterImplementation;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function abiFor(kind: RuntimeAdapterKind): RuntimeAdapterHostFacet["abi"] {
+  if (kind === "endpoint") return runtimeEndpointAdapterHostAbi;
+  return runtimeCredentialStoreAdapterHostAbi;
+}
+
+function address(facet: RuntimeAdapterHostFacet): RuntimeAdapterAddress {
+  const kind = facet.abi === runtimeEndpointAdapterHostAbi
+    ? "endpoint"
+    : facet.abi === runtimeCredentialStoreAdapterHostAbi ? "credential-store" : undefined;
+  assert(kind !== undefined, `Runtime Adapter ${facet.abi} ABI is unsupported`);
+  assert(facet.offers?.length === 1 && facet.offers[0]!.trim().length > 0,
+    "Runtime Adapter must offer exactly one non-empty use name");
+  return { use: facet.offers[0]!, kind };
+}
+
+function verifyImplementation(value: unknown, subject: string, kind: RuntimeAdapterKind): RuntimeAdapterImplementation {
+  assert(value !== null && typeof value === "object", `${subject} implementation is not an object`);
+  if (kind === "endpoint") {
+    assert(typeof (value as { activate?: unknown }).activate === "function", `${subject} does not implement activate()`);
+    return value as RuntimeEndpointAdapterImplementation;
+  }
+  assert(typeof (value as { validate?: unknown }).validate === "function", `${subject} does not implement validate()`);
+  assert(typeof (value as { open?: unknown }).open === "function", `${subject} does not implement open()`);
+  const doctor = (value as { doctor?: unknown }).doctor;
+  assert(doctor === undefined || typeof doctor === "function", `${subject}.doctor must be a function`);
+  return value as RuntimeAdapterImplementation;
+}
+
+function storeFacet<T>(kind: "credential-store", options: {
+  readonly use: string;
+  readonly validate: RuntimeStoreAdapterImplementation<T>["validate"];
+  readonly open: RuntimeStoreAdapterImplementation<T>["open"];
+  readonly doctor?: RuntimeStoreAdapterImplementation<T>["doctor"];
+}): RuntimeAdapterHostFacet {
+  assert(options.use.trim().length > 0, "Runtime Adapter use name is empty");
+  const implementation = {
+    validate: options.validate,
+    open: options.open,
+    ...(options.doctor === undefined ? {} : { doctor: options.doctor }),
+  };
+  return {
+    abi: abiFor(kind),
+    offers: [options.use],
+    implementation: verifyImplementation(implementation, `Runtime Adapter ${options.use}`, kind),
+  };
+}
+
+export function createRuntimeEndpointAdapterFacet(options: {
+  readonly use: string;
+  readonly activate: RuntimeEndpointAdapterImplementation["activate"];
+}): RuntimeAdapterHostFacet {
+  assert(options.use.trim().length > 0, "Runtime Adapter use name is empty");
+  return {
+    abi: runtimeEndpointAdapterHostAbi,
+    offers: [options.use],
+    implementation: verifyImplementation({ activate: options.activate }, `Runtime Adapter ${options.use}`, "endpoint"),
+  };
+}
+
+export function createRuntimeCredentialStoreAdapterFacet(options: {
+  readonly use: string;
+  readonly validate: RuntimeStoreAdapterImplementation<CredentialStore>["validate"];
+  readonly open: RuntimeStoreAdapterImplementation<CredentialStore>["open"];
+  readonly doctor?: RuntimeStoreAdapterImplementation<CredentialStore>["doctor"];
+}): RuntimeAdapterHostFacet {
+  return storeFacet("credential-store", options);
+}
+
+export function isRuntimeAdapterHostFacet(value: HostFacet): value is RuntimeAdapterHostFacet {
+  try {
+    const resolved = address(value as RuntimeAdapterHostFacet);
+    verifyImplementation(value.implementation, "Runtime Adapter", resolved.kind);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class RuntimeAdapterRegistry {
+  readonly #registrations = new Map<string, RuntimeAdapterImplementation>();
+
+  #key(use: string, kind: RuntimeAdapterKind): string {
+    return `${kind}\u0000${use}`;
+  }
+
+  registerFacet(facet: HostFacet): void {
+    assert(isRuntimeAdapterHostFacet(facet), `Host facet ${facet.abi} is not a valid Runtime Adapter`);
+    const resolved = address(facet);
+    const key = this.#key(resolved.use, resolved.kind);
+    assert(!this.#registrations.has(key), `Runtime ${resolved.kind} Adapter ${resolved.use} is already registered`);
+    this.#registrations.set(key, facet.implementation);
+  }
+
+  has(use: string, kind: RuntimeAdapterKind): boolean {
+    return this.#registrations.has(this.#key(use, kind));
+  }
+
+  async activateEndpoint(use: string, context: RuntimeAdapterFactoryContext): Promise<RuntimeEndpointActivation> {
+    const implementation = this.#registrations.get(this.#key(use, "endpoint")) as RuntimeEndpointAdapterImplementation | undefined;
+    assert(implementation !== undefined, `Runtime Endpoint adapter ${use} is not registered`);
+    const activation = await implementation.activate(context);
+    assert(activation.endpoint.instance.id === context.instance,
+      `Runtime Endpoint adapter ${use} created Endpoint ${activation.endpoint.instance.id} outside configured instance ${context.instance}`);
+    return activation;
+  }
+
+  async createEndpoint(use: string, context: RuntimeAdapterFactoryContext): Promise<EndpointPackage> {
+    return (await this.activateEndpoint(use, context)).endpoint;
+  }
+
+  async #openStore<T>(use: string, kind: "credential-store", context: RuntimeAdapterFactoryContext): Promise<RuntimeOpened<T>> {
+    const implementation = this.#registrations.get(this.#key(use, kind)) as RuntimeStoreAdapterImplementation<T> | undefined;
+    assert(implementation !== undefined, `Runtime ${kind} adapter ${use} is not registered`);
+    implementation.validate(context);
+    const opened = await implementation.open(context);
+    assert(opened.value !== null && typeof opened.value === "object", `Runtime ${kind} adapter ${use} returned no value`);
+    return opened;
+  }
+
+  async openCredentialStore(use: string, context: RuntimeAdapterFactoryContext): Promise<RuntimeOpened<CredentialStore>> {
+    return await this.#openStore(use, "credential-store", context);
+  }
+
+  validate(use: string, kind: Exclude<RuntimeAdapterKind, "endpoint">, context: RuntimeAdapterFactoryContext): readonly RuntimeDoctorDiagnostic[] {
+    const implementation = this.#registrations.get(this.#key(use, kind)) as RuntimeStoreAdapterImplementation<unknown> | undefined;
+    if (implementation === undefined) return [{
+      severity: "error", code: "RUNTIME_ADAPTER_MISSING", message: `Runtime Adapter ${use} is not registered`, subject: use,
+    }];
+    implementation.validate(context);
+    return [];
+  }
+
+  async doctor(use: string, kind: Exclude<RuntimeAdapterKind, "endpoint">, context: RuntimeAdapterFactoryContext): Promise<readonly RuntimeDoctorDiagnostic[]> {
+    const implementation = this.#registrations.get(this.#key(use, kind)) as RuntimeStoreAdapterImplementation<unknown> | undefined;
+    if (implementation === undefined) return [{
+      severity: "error", code: "RUNTIME_ADAPTER_MISSING", message: `Runtime Adapter ${use} is not registered`, subject: use,
+    }];
+    return implementation.doctor === undefined ? [] : await implementation.doctor(context);
+  }
+}
+
+export function runtimeConfigObject(value: CanonicalValue, subject: string): Record<string, CanonicalValue> {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} config must be an object`);
+  return value as Record<string, CanonicalValue>;
+}
+
+export function runtimeConfigExact(value: Record<string, CanonicalValue>, allowed: readonly string[], subject: string): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  assert(unknown.length === 0, `${subject} config does not accept ${unknown[0]}`);
+}
+
+export function runtimeConfigString(value: CanonicalValue | undefined, subject: string): string | undefined {
+  if (value === undefined) return undefined;
+  assert(typeof value === "string" && value.trim().length > 0, `${subject} must be a non-empty string`);
+  return value;
+}
+
+export function runtimeConfigPositiveInteger(value: CanonicalValue | undefined, subject: string): number | undefined {
+  if (value === undefined) return undefined;
+  assert(typeof value === "number" && Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+  return value;
+}
+
+export function runtimeConfigBoolean(value: CanonicalValue | undefined, subject: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  assert(typeof value === "boolean", `${subject} must be a boolean`);
+  return value;
+}
+
+export function runtimeConfigCredentialRef(
+  value: CanonicalValue | undefined,
+  subject: string,
+): CredentialRef | undefined {
+  if (value === undefined) return undefined;
+  const object = runtimeConfigObject(value, subject);
+  runtimeConfigExact(object, ["store", "key"], subject);
+  const store = runtimeConfigString(object.store, `${subject}.store`);
+  const key = runtimeConfigString(object.key, `${subject}.key`);
+  assert(store !== undefined && key !== undefined, `${subject} requires store and key`);
+  return credentialRef(store, key);
+}
+
+/** Common Profile representation for short action occupancy and rate budgets. */
+export function runtimeConfigActionLimits(value: CanonicalValue | undefined): import("@hypit/endpoint-kit").EndpointActionLimits | undefined {
+  if (value === undefined) return undefined;
+  const actions = runtimeConfigObject(value, "actionLimits");
+  runtimeConfigExact(actions, endpointActions, "actionLimits");
+  return Object.fromEntries(Object.entries(actions).map(([action, raw]) => {
+    const limit = runtimeConfigObject(raw, `actionLimits.${action}`);
+    runtimeConfigExact(limit, ["concurrency", "rate"], `actionLimits.${action}`);
+    const concurrency = runtimeConfigPositiveInteger(limit.concurrency, `${action} concurrency`);
+    let rate: { limit: number; periodMs: number } | undefined;
+    if (limit.rate !== undefined) {
+      const item = runtimeConfigObject(limit.rate, `${action} rate`);
+      runtimeConfigExact(item, ["limit", "periodMs"], `${action} rate`);
+      const units = runtimeConfigPositiveInteger(item.limit, `${action} rate.limit`);
+      const periodMs = runtimeConfigPositiveInteger(item.periodMs, `${action} rate.periodMs`);
+      if (units === undefined || periodMs === undefined) throw new Error(`${action} rate requires limit and periodMs`);
+      rate = { limit: units, periodMs };
+    }
+    return [action, { ...(concurrency === undefined ? {} : { concurrency }), ...(rate === undefined ? {} : { rate }) }];
+  }));
+}
+
+export { requestDeadline } from "./request-deadline.js";

package/packages/runtime-kit/src/request-deadline.ts

@@ -0,0 +1,17 @@
+/** A deadline covers headers and body consumption even when a transport ignores abort. */
+export function requestDeadline(timeoutMs: number, error: () => Error = () => new Error("Request timed out")) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error("Request timeout must be a positive integer");
+  const controller = new AbortController();
+  let reject!: (reason: Error) => void;
+  const expired = new Promise<never>((_resolve, fail) => { reject = fail; });
+  const timer = setTimeout(() => {
+    const reason = error();
+    reject(reason);
+    controller.abort(reason);
+  }, timeoutMs);
+  return {
+    signal: controller.signal,
+    wait: async <T>(work: Promise<T>): Promise<T> => await Promise.race([work, expired]),
+    finish: (): void => clearTimeout(timer),
+  };
+}

package/packages/runtime-local/README.md

@@ -0,0 +1,119 @@
+# `@hypit/runtime-local`
+
+The default local Runtime for Hypit. It owns the Worker, scheduler and active SQLite execution
+worklist. Project-owned Build Results hold finished public Outputs.
+
+A Runtime Profile selects only the environmental parts that genuinely vary:
+
+```json
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "env": { "use": "@hypit/credential-store-env" }
+  },
+  "endpoints": {},
+  "bindings": {}
+}
+```
+
+The official video Distribution selects this Runtime implementation before it opens the file. The
+Profile therefore describes only local execution and does not repeat a fake Runtime Host selector.
+
+Providers declare everything they can do and never hide a capability. When two selected Endpoints
+offer the same capability, `bindings` says which one serves it, keyed by the capability
+(`name@version#capability`) and naming an Endpoint instance of this Profile:
+
+```json
+"bindings": {
+  "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"
+}
+```
+
+A capability offered by exactly one Endpoint needs no binding. A contested capability without one is
+reported by `doctor` and `plan` and blocks the Need at Build time; a binding to an Endpoint that does
+not offer the capability is an error. `plan`, creation-time tools and the Build resolve Endpoints
+through the same registry with the same bindings.
+
+Disposable authoring clients may open one transient execution. It installs only immediate capabilities
+whose Provider explicitly declares `transient: true`, keeps the same Profile bindings and resolves each
+complete Need through its ordinary `supports` predicate. Pricing is informational and is never used as
+an execution permission. The Runtime retains Endpoint handlers, credentials and Program readiness; the
+client supplies its temporary Resources and receives no Endpoint registry. Declared concurrency is shared
+inside that one disposable session only. A Provider that needs durable or cross-Build quota admission must
+not opt that capability into transient execution.
+
+A project that wants a non-default Result repository owns a separate `hypit.results.json`:
+
+```json
+{
+  "format": "hypit.build-results@1",
+  "use": "@hypit/build-result-s3",
+  "config": { "bucket": "team-results", "prefix": "projects/episode-12" }
+}
+```
+
+Submitting a Build stores it and returns. The Worker may advance unrelated Builds together; only the
+resources declared by their Commands constrain execution. An Endpoint instance owns its capacity by
+default. A Profile `pool` is only for instances that really share one account, deployment or compute
+quota; exact-model limits may narrow it further. Build identity is not a capacity resource and creates
+no second queue.
+Claims may carry `units` (default 1): one render Need can occupy one request slot and four browser
+slots at once. The same admission rule applies to total Provider capacity, exact models, and local
+compute resources. SQLite retains the weighted reservation across Worker turns and restarts. This
+coordinates Builds sharing this Runtime's Execution Store; it does not enforce a service's quotas
+across other machines. Short-action limits are described below.
+
+A failed request ends that Build's execution attempt. Runtime saves completed public Outputs and
+non-secret Operation receipts with the failed Result, including any remote status still unknown.
+It accepts results from calls already in progress before finalizing, without starting further work
+or polling unfinished remote jobs.
+It then releases local reservations. Submission timeouts with no receipt remain recorded failures;
+a new Run and Build can request the remaining work. No original-Build reconciliation is required.
+An explicit cancellation stops new work and makes one best-effort remote cancellation call when
+supported; its acknowledgement is recorded separately from the local cancelled outcome.
+
+`defaultConcurrency` and exact-model limits govern managed Need occupancy. Asynchronous Providers can
+also expose `actionLimits` for `submit`, `poll` and `collect`; each action supports `concurrency` and
+`rate: { limit, periodMs }`. These action budgets share the same Runtime store and real `pool` identity.
+Rate permits replenish with time and are not returned when an action finishes. Rate counts admitted
+actions, not every HTTP request a Provider may make inside one action. Cloud services own their actual
+account-wide limits, including tasks submitted elsewhere or still running after a local failure.
+
+The Worker yields to sockets and timers between graph reads. Resource waiters are awakened as capacity
+becomes available; known Operations are polled from their own lightweight records. Graph hydration is
+serialized, while network actions and local work remain concurrent under their declared limits.
+
+HypiHub can be the explicitly selected gateway for users without their own service keys. A bound
+Provider's authentication, quota or transport error never changes that selection. Separate Kie and
+HypiHub accounts use separate pools even when they implement the same model.
+
+Without `hypit.results.json`, the official video Distribution selects the filesystem adapter at the
+project's `.hypit/results` directory, with no cloud account or service. Runtime Local opens that default
+through the same adapter registry as an explicit `@hypit/build-result-s3` selection; it contains no
+filesystem Repository shortcut.
+Runtime working Resources remain internal and Build-local; there is no ResourceStore selector. After
+a Result has an outcome, history is read from the selected repository, not Runtime SQLite.
+
+Saving a finished Result is a separate, idempotent storage action. If that write is interrupted, the
+Build keeps its already-decided outcome and reports exact operator attention. `hypit result finish
+<build-id>` performs only that pending write and active-state cleanup; it does not run the execution
+Worker, call a Producer or load Provider Endpoint packages. `hypit result discard <build-id>` is only
+for a submission that never became active and therefore has no Result to save.
+
+Source imports select author packages. Runtime Profile entries select only code allowed to access files,
+credentials, processes or networks. Installing a package changes neither selection.
+
+The lifecycle commands have deliberately narrow meanings:
+
+- `hypit runtime init` writes and selects the Distribution's starter Profile; it performs no setup or
+  network access and never overwrites an existing Profile.
+- `hypit runtime up` prepares selected local dependencies, starts declared local Programs and starts
+  the Worker. `hypit runtime down` stops the Worker; `hypit programs down` stops the Programs.
+  Remote services have no lifecycle for Hypit to start or stop.
+- `hypit runtime logs` reads the Worker's output, including separately redirected standard errors
+  on Windows. The files are `worker.log` and `worker.err.log` under the Runtime data directory's
+  `worker/`. Separate error output is labeled `[stderr]`; the files do not establish an interleaved
+  event order. A failure before readiness also includes the recorded error in its startup message.
+- `hypit doctor` is the active, read-only check. Endpoint-owned diagnostics may authenticate and read a
+  remote capability catalog; normal preflight never does.