@hypit/hypit 0.1.14 → 0.2.1

package/packages/credential-store-platform/src/activation.ts

@@ -0,0 +1,39 @@
+import { join, resolve } from "node:path";
+import {
+  createRuntimeCredentialStoreAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import { PlatformCredentialStore } from "./store.js";
+
+const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
+  use: "@hypit/credential-store-platform",
+  validate(context) {
+    const config = runtimeConfigObject(context.config, "platform CredentialStore");
+    runtimeConfigExact(config, ["path", "service"], "platform CredentialStore");
+    runtimeConfigString(config.path, "platform credential path");
+    runtimeConfigString(config.service, "platform credential service");
+  },
+  open(context) {
+    const config = runtimeConfigObject(context.config, "platform CredentialStore");
+    const path = runtimeConfigString(config.path, "platform credential path");
+    const service = runtimeConfigString(config.service, "platform credential service");
+    return {
+      value: new PlatformCredentialStore({
+        // Linux uses the same directory the file Store uses by default, so a Profile
+        // that switches between them on Linux finds the credential it stored.
+        directory: path === undefined
+          ? join(context.hostStateRoot, "credentials")
+          : resolve(context.hostStateRoot, path),
+        ...(service === undefined ? {} : { service }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [platformCredentialStoreAdapter],
+};
+export default hypitPackage;

package/packages/credential-store-platform/src/index.ts

@@ -0,0 +1 @@
+export { PlatformCredentialStore } from "./store.js";

package/packages/credential-store-platform/src/store.ts

@@ -0,0 +1,89 @@
+import {
+  credentialRef,
+  verifyCredentialRef,
+} from "@hypit/runtime";
+import type {
+  CredentialRef,
+  CredentialValue,
+  WritableCredentialStore,
+} from "@hypit/runtime";
+import { FileCredentialStore } from "@hypit/credential-store-file";
+import { OsCredentialStore } from "@hypit/credential-store-os";
+import type {
+  OsCredentialDeleter,
+  OsCredentialReader,
+  OsCredentialWriter,
+} from "@hypit/credential-store-os";
+
+export type PlatformCredentialStoreOptions = {
+  /** Directory holding the documents this Store selects on Linux. */
+  readonly directory: string;
+  /** Service the locker's entries are filed under; the OS Store's own default applies where absent. */
+  readonly service?: string;
+  /**
+   * The platform to select for, defaulting to the running one. A Profile never states this: it is
+   * separate so the selection can be exercised on one machine for every platform.
+   */
+  readonly platform?: NodeJS.Platform;
+  /** Locker backend to read and write with, where the platform's own locker is not the one to use. */
+  readonly locker?: {
+    readonly read: OsCredentialReader;
+    readonly write: OsCredentialWriter;
+    readonly remove: OsCredentialDeleter;
+  };
+};
+
+/**
+ * An explicitly selected storage policy: OS credentials on macOS/Windows, files on Linux.
+ * The selected backend's errors propagate; other platforms are unsupported by this package.
+ */
+export class PlatformCredentialStore implements WritableCredentialStore {
+  readonly #delegate: WritableCredentialStore;
+  readonly #backing: "os" | "file";
+
+  constructor(options: PlatformCredentialStoreOptions) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin" || platform === "win32") {
+      this.#backing = "os";
+      this.#delegate = new OsCredentialStore({
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...options.locker,
+      });
+    } else if (platform === "linux") {
+      this.#backing = "file";
+      this.#delegate = new FileCredentialStore(options.directory);
+    } else {
+      throw new Error(`Platform CredentialStore does not support ${platform}; select an explicit CredentialStore supported by this host`);
+    }
+  }
+
+  owns(ref: CredentialRef): boolean {
+    return ref.store === "platform";
+  }
+
+  /**
+   * Each delegate owns its own name and refuses refs filed under another, so a ref this Store owns
+   * is retargeted before the delegate sees it. Only the name changes; the opaque key is untouched.
+   */
+  #translated(ref: CredentialRef): CredentialRef {
+    return credentialRef(this.#backing, ref.key);
+  }
+
+  async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) return undefined;
+    return await this.#delegate.resolve(this.#translated(ref));
+  }
+
+  async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`Platform CredentialStore does not own ${ref.store}`);
+    await this.#delegate.put(this.#translated(ref), value);
+  }
+
+  async delete(ref: CredentialRef): Promise<boolean> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`Platform CredentialStore does not own ${ref.store}`);
+    return await this.#delegate.delete(this.#translated(ref));
+  }
+}

package/packages/narrative/README.md

@@ -26,4 +26,6 @@ no Tokens. Authored order is independent of gaps, overlap or placement order in
 Caption uses this content query and the Narrative's display correspondence to select complete
 subtitle units. Timeline projection uses the same semantic references to locate events in physical
 time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
-source prose: whitespace, comments and source-preserving edits remain the author language's concern.
+source prose: comments and source-preserving edits remain the author language's concern. Caption
+Display Words separately carry `separatorBefore` (`""` or `" "`) so consumers can reconstruct the
+authored display spelling without guessing from Token boundaries or importing an author parser.

package/packages/narrative/src/schema.ts

@@ -29,6 +29,7 @@ export const narrativeExcerptSchema: ValueSchema = object({
   tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
 });
 const captionDisplayWord = object({
+  separatorBefore: { schema: { kind: "string", enum: ["", " "] } },
   id: { schema: string }, unitId: { schema: string }, segmentId: { schema: string },
   turnId: { schema: string }, role: { schema: string, optional: true }, text: { schema: string },
   attributes: { schema: { kind: "array", items: object({

package/packages/narrative/src/types.ts

@@ -50,6 +50,8 @@ export type NarrativeMomentRef = NarrativeMoment & {
 
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 export type CaptionDisplayWord = {
+  /** Authored display separator from the preceding word; ignored at a displayed line start. */
+  readonly separatorBefore: "" | " ";
   readonly id: string;
   readonly unitId: string;
   readonly segmentId: string;

package/packages/provider-whisperx-local/README.md

@@ -43,7 +43,8 @@ For multilingual transcription with quality as the priority and suitable hardwar
     "expectedModel": "large-v3",
     "expectedDevice": "cuda",
     "expectedCompute": "float16",
-    "expectedBatchSize": 4
+    "expectedBatchSize": 4,
+    "alignmentLanguages": ["zh", "en"]
   }
 }
 ```
@@ -57,7 +58,11 @@ or hosted service for the actual language, material and time available rather th
 successively larger models as a routine sequence.
 
 `expectedModel` selects speech recognition. WhisperX separately loads the language-specific
-alignment model when that language is first requested. A larger ASR model can improve the words
+alignment model from prepared local resources when that language is first requested. Set
+`alignmentLanguages` to the language codes needed by this production before preparation. This is a
+preparation demand, not a central language whitelist; already cached supported languages remain usable.
+Omission prepares only ASR and sentence data, and does not imply every alignment model is installed.
+A larger ASR model can improve the words
 fed into alignment, but does not select a larger aligner or guarantee better timing by itself.
 The health response identifies the loaded ASR configuration; it does not establish that every
 language's alignment weights are cached. See [WhisperX usage](https://github.com/m-bain/whisperX#usage-)
@@ -65,8 +70,9 @@ and [faster-whisper deployment](https://github.com/SYSTRAN/faster-whisper#usage)
 
 ## Preparation and downloads
 
-The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
-is selected. The environment is reused across projects and sessions. The current local package and
+An explicit `programs up` or `runtime up` prepares and starts the selected packaged service in the
+machine Program Home. Selecting an Endpoint alone does not install it. The environment is reused
+across projects and sessions. The current local package and
 service are trusted code; this is not a community-plugin sandbox.
 
 `hypit paths` reports the machine `hostState`. The managed installation lives below
@@ -75,21 +81,31 @@ service are trusted code; this is not a community-plugin sandbox.
 the service host includes its port. The default service is `http://127.0.0.1:8765` and exposes
 its configuration through `/health`. Inspect an existing Profile's address and expected settings
 when locating that service. A custom `serviceCommand` supplies its own installation and start command.
-`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
-and starts them. The managed installation does not require a global `whisperx` shell command.
+`hypit programs prepare --endpoint <instance>` prepares the configured ASR model, requested alignment
+models and sentence data without starting a process. It also works when the service is already online.
+`programs up` prepares and starts the selected Programs; `programs status` reports process readiness.
+Adding a language requires preparation, not a service restart, when its cache location is unchanged.
+`modelCacheDirectory` optionally selects a root with `huggingface/` and `torch/` subdirectories;
+relative paths resolve against the Runtime data root. Omission retains the upstream Hugging Face and
+torch caches and their environment settings. Changing a running service's cache selection requires
+an explicit restart when idle, just like changing its model or hardware. The managed installation
+does not require a global `whisperx` shell command.
 
 Preparation and service processes inherit the environment of the command starting them. Set
 network and cache variables there before `programs up` or `runtime up`. A service already running
 retains its earlier environment. Inspect its reported log before deciding whether a selected
 Program needs restarting, and account for active work using it.
 
+If NLTK refuses a proxied fetch during preparation, follow the service’s
+[explicit proxy preparation](../../services/whisperx/README.md#preparing-sentence-data-through-a-proxy).
+
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
 `program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
 `programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
-exist, even before installation finishes. Preparation notices name the Python environment and NLTK
-commands separately. The service logs the start and completion of ASR loading, transcription,
-language-alignment model loading and alignment, with elapsed times. Loading may include a download;
-transfer details come from the underlying client, not an estimated percentage from the Provider.
+exist, even before installation finishes. Preparation notices name the Python environment and selected model/language resources separately. The service logs the start and completion of ASR loading, transcription,
+language-alignment model loading and alignment, with elapsed times. Downloads happen only in
+preparation; startup and inference only load local resources. A missing resource fails with a
+preparation instruction. Transfer details come from the underlying client during preparation.
 The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
 can leave that process still loading. Its PID is recorded when spawned; repeated `up` observes it,
 and `programs down` can stop it during loading. PID liveness and service readiness are separate facts.

package/packages/provider-whisperx-local/src/activation.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import {
   createRuntimeEndpointAdapterFacet,
   runtimeConfigExact,
@@ -18,7 +19,7 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       "baseUrl", "expectedModel", "expectedDevice", "expectedCompute", "expectedBatchSize",
       "expectedServiceVersion", "expectedWhisperXVersion",
       "defaultConcurrency", "requestTimeoutMs", "maxResponseBytes",
-      "serviceCommand",
+      "serviceCommand", "alignmentLanguages", "modelCacheDirectory",
     ], "local WhisperX");
     const baseUrl = runtimeConfigString(config.baseUrl, "WhisperX baseUrl");
     if (baseUrl !== undefined) {
@@ -37,6 +38,12 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "WhisperX defaultConcurrency");
     const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "WhisperX requestTimeoutMs");
     const maxResponseBytes = runtimeConfigPositiveInteger(config.maxResponseBytes, "WhisperX maxResponseBytes");
+    const modelCacheDirectory = runtimeConfigString(config.modelCacheDirectory, "WhisperX modelCacheDirectory");
+    const alignmentLanguages = config.alignmentLanguages;
+    if (alignmentLanguages !== undefined && (!Array.isArray(alignmentLanguages)
+      || alignmentLanguages.some((item) => typeof item !== "string" || !/^[a-z]+$/u.test(item)))) {
+      throw new Error("WhisperX alignmentLanguages must be an array of lowercase language codes");
+    }
     const serviceCommandValue = config.serviceCommand;
     if (serviceCommandValue !== undefined
       && (!Array.isArray(serviceCommandValue) || serviceCommandValue.length === 0
@@ -80,6 +87,8 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         expectedServiceVersion: selectedServiceVersion,
         expectedWhisperXVersion: selectedWhisperXVersion,
         ...(serviceCommand === undefined ? {} : { serviceCommand }),
+        ...(alignmentLanguages === undefined ? {} : { alignmentLanguages: alignmentLanguages as string[] }),
+        ...(modelCacheDirectory === undefined ? {} : { modelCacheDirectory: resolve(context.dataRoot, modelCacheDirectory) }),
       }),
     };
   },

package/packages/provider-whisperx-local/src/program.ts

@@ -52,6 +52,8 @@ export type LocalWhisperXProgramOptions = {
   readonly expectedServiceVersion: string;
   readonly expectedWhisperXVersion: string;
   readonly serviceCommand?: ManagedProgramCommand;
+  readonly alignmentLanguages?: readonly string[];
+  readonly modelCacheDirectory?: string;
 };
 
 export function localWhisperXProgram(options: LocalWhisperXProgramOptions): ManagedProgram {
@@ -85,11 +87,13 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
     HYPIT_WHISPERX_COMPUTE: expected.compute,
     HYPIT_WHISPERX_BATCH_SIZE: String(expected.batchSize),
     HYPIT_WHISPERX_NLTK_DATA: nltkData,
+    ...(options.modelCacheDirectory === undefined ? {} : { HYPIT_WHISPERX_MODEL_CACHE: options.modelCacheDirectory }),
+    HYPIT_WHISPERX_ALIGNMENT_LANGUAGES: (options.alignmentLanguages ?? []).join(" "),
   };
   const check: ManagedProgramCommand = {
     command: pythonEnvironmentCommand(environment, "hypit-whisperx-check"),
-    args: [],
-    env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+    args: ["--models"],
+    env: serviceEnvironment,
   };
   const managedStart: ManagedProgramCommand = {
     command: pythonEnvironmentCommand(environment, "hypit-whisperx-service"),
@@ -131,10 +135,10 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
           args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],
           env: { UV_PROJECT_ENVIRONMENT: environment },
         }, {
-          label: "Prepare NLTK sentence data",
+          label: `Prepare WhisperX ${expected.model} and alignment resources for ${(options.alignmentLanguages ?? []).join(", ") || "no selected languages"}`,
           command: pythonEnvironmentCommand(environment, "hypit-whisperx-prepare"),
           args: ["--nltk-data", nltkData],
-          env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+          env: serviceEnvironment,
         }],
       },
     } : {}),

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

@@ -245,6 +245,7 @@ export type RuntimeController = {
     down(options?: { readonly maxWaitMs?: number }): Promise<RuntimeWorkerState>;
   };
   readonly programs: {
+    prepare(options?: { readonly endpoints?: readonly string[]; readonly onProgress?: (event: ManagedProgramProgress) => void }): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }>;
     up(options: {
       readonly maxWaitMs?: number;
       readonly onProgress?: (event: ManagedProgramProgress) => void;

package/packages/runtime-kit/README.md

@@ -43,8 +43,12 @@ video package by name.
 
 `ManagedProgram.installation.prepareBeforeStart` lets a Provider reconcile its installed environment
 before a cold start, even when the installation probe already passes. The declared commands use the
-Provider's ordinary package manager. A healthy running Program is reused before this preparation is
-considered; Runtime does not inspect source files or infer implementation versions.
+Provider's ordinary package manager. `programs prepare` runs the declared installation independently
+of process startup; `programs up` also checks its resources when the process is already healthy.
+The installation probe covers the owner's selected execution resources, while the process probe
+reports service readiness. Cold reconciliation still applies only before starting a new process.
+Runtime does not name models, inspect source files or infer implementation versions. Preparation
+may acquire resources; execution must consume already prepared resources and report what is missing.
 `ManagedProgramCommand.label` optionally names a command's purpose for progress and log headings.
 It is display text supplied by the Program owner, not a phase to persist or interpret. Runtime
 reports generic process/probe facts; the service itself owns domain-specific progress in its logs.

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

@@ -42,11 +42,11 @@ export type ManagedProgramCommand = {
 };
 
 export type ManagedProgramInstallation = {
-  /** Truthful inspection of the installed program; no installer-owned receipt. */
+  /** Read-only inspection of the selected environment and resources; no downloads or receipts. */
   probe(): Promise<ManagedProgramState>;
   /** Reconcile an installed environment before a cold start, using its package manager's cache. */
   readonly prepareBeforeStart?: boolean;
-  /** Commands run when installation is missing, or before a cold start when requested above. */
+  /** Explicit preparation commands, run for missing resources or cold reconciliation above. */
   readonly commands: readonly ManagedProgramCommand[];
 };
 

package/packages/runtime-local/README.md

@@ -242,7 +242,12 @@ controller returned by `await host.controller()`, and calls `build(...)` on the
 `await host.createRuntime()`. There is one production process-lifecycle path.
 
 Managed Programs have independent lifetimes. A healthy WhisperX service keeps its model loaded;
-`prepareBeforeStart` reconciles a cold installation through uv's source-aware synchronization.
+`programs prepare --endpoint <instance>` prepares selected resources without starting or stopping
+that service. Its installation probe is independent of process health, so an online service does not
+hide a newly requested language model. `programs up` prepares missing resources and starts the service
+if needed. `prepareBeforeStart` additionally reconciles a cold installation through the package
+manager's source-aware synchronization. The Provider owns the resource choices and commands;
+Runtime only invokes them under the existing lifecycle lock.
 `runtime down` stops the coordinator and asks its executors to stop; Programs are stopped separately.
 Distribution changes and shell environment changes still concern the coordinator's bootstrap process.
 Inspect active work before restarting it. Environment-backed credentials use that inherited process

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

@@ -23,6 +23,7 @@ import {
 } from "./config.js";
 import {
   bringManagedProgramsUp,
+  prepareManagedPrograms,
   reportManagedPrograms,
   takeManagedProgramsDown,
 } from "./programs.js";
@@ -82,6 +83,7 @@ export async function openLocalRuntimeHost(
         ),
       },
       programs: {
+        prepare: async (programOptions) => await prepareManagedPrograms(profile, { ...programOptions, packageRoot, ...distribution }),
         up: async (programOptions) => await bringManagedProgramsUp(profile, { ...programOptions, packageRoot, ...distribution }),
         down: async (scope) => await takeManagedProgramsDown(profile, { ...scope, packageRoot, ...distribution }),
         report: async (scope) => await reportManagedPrograms(profile, { ...scope, packageRoot, ...distribution }),

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

@@ -28,6 +28,7 @@ export {
 } from "./config.js";
 export {
   bringManagedProgramsUp,
+  prepareManagedPrograms,
   reportManagedPrograms,
   takeManagedProgramsDown,
 } from "./programs.js";

package/packages/runtime-local/src/programs.ts

@@ -293,6 +293,8 @@ async function bringUpOwned(
   onProgress?.({ id: program.id, phase: "checking" });
   const initial = await program.probe();
   if (initial.state === "ready") {
+    const prepared = await prepareOwned(root, program, endpoint, onProgress);
+    if (prepared.state.state !== "ready") return prepared;
     onProgress?.({ id: program.id, phase: "ready" });
     return { ...base, action: "already-running", state: initial };
   }
@@ -306,6 +308,10 @@ async function bringUpOwned(
   const installLogPath = join(directory(root, program), "install.log");
   const existingPid = await readPid(root, program);
   if (existingPid !== undefined && processAlive(existingPid)) {
+    if (program.installation !== undefined) {
+      const prepared = await prepareOwned(root, program, endpoint, onProgress);
+      if (prepared.state.state !== "ready") return prepared;
+    }
     release();
     onProgress?.({ id: program.id, phase: "waiting", logPath,
       detail: `observing existing process ${existingPid}` });
@@ -320,23 +326,9 @@ async function bringUpOwned(
   }
   if (existingPid !== undefined) await rm(join(directory(root, program), "process.pid"), { force: true });
   if (program.installation !== undefined) {
-    const installation = await program.installation.probe();
-    if (installation.state !== "ready" || program.installation.prepareBeforeStart === true) {
-      await mkdir(directory(root, program), { recursive: true });
-      await rotateLog(installLogPath);
-      for (const command of program.installation.commands) {
-        onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath, detail: commandLabel(command) });
-        const result = await run(root, command, installLogPath);
-        if (!result.ok) {
-          return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `${command.command} failed: ${result.detail}` };
-        }
-      }
-      const after = await program.installation.probe();
-      if (after.state !== "ready") {
-        return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `installation is ${after.state}: ${after.detail}` };
-      }
-      installed = true;
-    }
+    const prepared = await prepareOwned(root, program, endpoint, onProgress, program.installation.prepareBeforeStart === true);
+    if (prepared.state.state !== "ready") return prepared;
+    installed = prepared.action === "installed";
   }
   if (program.start === undefined) {
     // Nothing to keep running: installation was the whole job.
@@ -435,6 +427,50 @@ async function bringUp(
   } finally { release(); }
 }
 
+/** Resource preparation is independent of process readiness. Caller owns the lifecycle lock. */
+async function prepareOwned(
+  root: string, program: ManagedProgram, endpoint: string,
+  onProgress?: (event: ManagedProgramProgress) => void, reconcile = false,
+): Promise<ManagedProgramReport> {
+  const base = { id: program.id, endpoint };
+  const installation = program.installation;
+  if (installation === undefined) return { ...base, action: "unchanged", state: await program.probe() };
+  const logPath = join(directory(root, program), "install.log");
+  const before = await installation.probe();
+  if (before.state === "ready" && !reconcile) return { ...base, action: "unchanged", state: before };
+  await mkdir(root, { recursive: true });
+  await rotateLog(logPath);
+  for (const command of installation.commands) {
+    onProgress?.({ id: program.id, phase: "installing", logPath, detail: commandLabel(command) });
+    const result = await run(root, command, logPath);
+    if (!result.ok) return { ...base, action: "unchanged", state: { state: "down", detail: `${command.command} failed: ${result.detail}` }, installationLogPath: logPath };
+  }
+  const state = await installation.probe();
+  return { ...base, action: state.state === "ready" ? "installed" : "unchanged", state, installationLogPath: logPath };
+}
+
+/** Prepare selected resources without starting, stopping or trusting a running process. */
+export async function prepareManagedPrograms(
+  path: string, options: ManagedProgramOptions = {},
+): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
+  const { dataRoot, programs } = await declaredManagedPrograms(path, options);
+  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
+    const home = directory(dataRoot, program);
+    await mkdir(home, { recursive: true });
+    const { tryProgramLock } = await import("./program-lock.js");
+    const release = tryProgramLock(home);
+    if (release === undefined) return { id: program.id, endpoint: instance, action: "unchanged", state: { state: "down", detail: "another command owns this Program's preparation; inspect its logs" } };
+    try {
+      options.onProgress?.({ id: program.id, phase: "checking" });
+      const report = await prepareOwned(dataRoot, program, instance, options.onProgress);
+      if (report.state.state === "ready") options.onProgress?.({ id: program.id, phase: "ready" });
+      return report;
+    }
+    finally { release(); }
+  }));
+  return { dataRoot, programs: reports };
+}
+
 /** Install when needed and start every external program the Runtime Profile implies. */
 export async function bringManagedProgramsUp(
   path: string,