@hypit/hypit 0.2.1 → 0.2.3

package/packages/credential-store-file/README.md

@@ -47,7 +47,8 @@ report the read error rather than treating corruption as a missing credential.
 ## Storage
 
 The default directory is `credentials` under the Host state root printed by `hypit paths`.
-`config.path` explicitly selects a directory, resolving relative paths against that Host root.
+`config.path` explicitly selects a directory, including an absolute directory outside that root;
+relative paths resolve against the Host root.
 Opening the adapter and reading an absent key do not create files. Keep this directory outside Git.
 
 Each key has its own JSON file containing only `secret` and optional `expiresAt`, as defined by
@@ -56,7 +57,11 @@ CredentialValue. Filenames use reversible lower-case hex encoding of the key's U
 case-insensitive filesystems and keeps slashes and reserved names out of filesystem path syntax.
 Filesystem path-length limits still apply; an overlong key fails rather than selecting another name.
 
-Writes create an owner-only temporary file and replace the single destination with rename. Different
-keys do not overwrite each other's updates; concurrent writes to the same key keep the last completed
-replacement. The Store does not enumerate credentials, maintain an index, or record write history.
+Writes create an owner-only temporary file and replace the single destination through `@hypit/file-io-node`.
+On Windows this uses native POSIX replacement semantics, so an open reader keeps the old file
+while a new open sees the replacement; it does not use Node’s `MoveFileExW` path. Different
+keys do not overwrite each other's updates. Reads see a complete document, and the last completed
+replacement of the same key supplies its value. There is no process-local queue or cross-process
+coordination; filesystem errors propagate to the caller rather than being retried or hidden.
+The Store does not enumerate credentials, maintain an index, or record write history.
 Permission and I/O errors propagate. Existing directory permissions are not silently changed.

package/packages/credential-store-file/package.json

@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@hypit/runtime": "workspace:*",
-    "@hypit/runtime-kit": "workspace:*"
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/file-io-node": "workspace:*"
   }
 }

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

@@ -17,8 +17,9 @@ const fileCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
   open(context) {
     const config = runtimeConfigObject(context.config, "file CredentialStore");
     const path = runtimeConfigString(config.path, "file credential path");
-    return { value: new FileCredentialStore(path === undefined
-      ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path)) };
+    return { value: new FileCredentialStore(
+      path === undefined ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path),
+    ) };
   },
 });
 

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

@@ -1,5 +1,6 @@
+import { replaceFile } from "@hypit/file-io-node";
 import { randomUUID } from "node:crypto";
-import { mkdir, open, rename, rm, stat, unlink } from "node:fs/promises";
+import { mkdir, open, rm, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { verifyCredentialRef } from "@hypit/runtime";
 import type { CredentialRef, CredentialValue, WritableCredentialStore } from "@hypit/runtime";
@@ -74,7 +75,7 @@ export class FileCredentialStore implements WritableCredentialStore {
     const file = await open(temporary, "wx", 0o600);
     try {
       try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
-      await rename(temporary, path);
+      await replaceFile(temporary, path);
     } finally { await rm(temporary, { force: true }); }
   }
 

package/packages/credential-store-os/runtime/windows-credential.ps1

@@ -35,8 +35,7 @@ switch ($Operation) {
     @{ found = $true; secret = [Convert]::ToBase64String($bytes) } | ConvertTo-Json -Compress
   }
   "write" {
-    $existing = Find-Credential
-    if ($null -ne $existing) { $vault.Remove($existing) }
+    # Add replaces the same resource/account; do not destroy the old value before it succeeds.
     $bytes = [Convert]::FromBase64String([string]$request.secret)
     $secret = [System.Text.Encoding]::UTF8.GetString($bytes)
     $credential = New-Object Windows.Security.Credentials.PasswordCredential(

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

@@ -1,5 +1,5 @@
-import { execFile, spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { windowsCredential } from "./windows.js";
 
 import { verifyCredentialRef } from "@hypit/runtime";
 import type {
@@ -59,64 +59,6 @@ function macosDeleter(service: string): OsCredentialDeleter {
   });
 }
 
-type WindowsCredentialResult = {
-  readonly found?: boolean;
-  readonly deleted?: boolean;
-  readonly secret?: string;
-};
-
-const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
-
-function windowsCredential(
-  operation: "read" | "write" | "delete",
-  service: string,
-  account: string,
-  secret?: string,
-): Promise<WindowsCredentialResult> {
-  return new Promise((resolve, reject) => {
-    const child = spawn("powershell.exe", [
-      "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
-      "-File", windowsScript, "-Operation", operation,
-    ], { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    const fail = (error: Error): void => {
-      if (settled) return;
-      settled = true;
-      reject(error);
-    };
-    child.on("error", fail);
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout += chunk.toString("utf8");
-      if (stdout.length > 4 * 1024 * 1024) fail(new Error("Windows credential response is too large"));
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf8");
-      if (stderr.length > 64 * 1024) fail(new Error("Windows credential error is too large"));
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      if (code !== 0) {
-        fail(new Error(`Windows credential ${operation} for ${account} failed${stderr.trim().length === 0 ? "" : `: ${stderr.trim()}`}`));
-        return;
-      }
-      try {
-        const result = JSON.parse(stdout.replace(/^\uFEFF/u, "").trim()) as WindowsCredentialResult;
-        settled = true;
-        resolve(result);
-      } catch {
-        fail(new Error(`Windows credential ${operation} returned an invalid response`));
-      }
-    });
-    child.stdin.end(JSON.stringify({
-      service,
-      account,
-      ...(secret === undefined ? {} : { secret: Buffer.from(secret, "utf8").toString("base64") }),
-    }));
-  });
-}
-
 function windowsBackend(): {
   readonly read: OsCredentialReader;
   readonly write: OsCredentialWriter;
@@ -142,8 +84,9 @@ function platformBackend(service: string) {
   }
   if (process.platform === "win32") return windowsBackend();
   // A Profile that selects this Store cannot be repaired by anything the user does here, and the
-  // other two Stores are the answer, so name them where the failure is read.
+  // other Stores are the answer, so name them where the failure is read.
   throw new Error("OS CredentialStore supports macOS and Windows only; select "
+    + "@hypit/credential-store-platform (platform locker, owner-private file on Linux), "
     + "@hypit/credential-store-file (owner-private local file) or @hypit/credential-store-env "
     + "(externally supplied value) in this Profile's credentials instead");
 }

package/packages/credential-store-os/src/windows.ts

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+type WindowsCredentialResult = {
+  readonly found?: boolean;
+  readonly deleted?: boolean;
+  readonly secret?: string;
+};
+
+const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
+
+/** The OS adapter owns this one child; Node owns its timeout, bounded output and termination. */
+export function windowsCredential(
+  operation: "read" | "write" | "delete",
+  service: string,
+  account: string,
+  secret?: string,
+): Promise<WindowsCredentialResult> {
+  return new Promise((resolve, reject) => {
+    const child = execFile("powershell.exe", [
+      "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+      "-File", windowsScript, "-Operation", operation,
+    ], {
+      shell: false, windowsHide: true, encoding: "utf8", timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      if (error !== null) {
+        reject(new Error(`Windows credential ${operation} for ${account} failed`
+          + (error.code === undefined ? "" : ` (${error.code})`)
+          + (error.killed ? " (child terminated)" : "")
+          + (stderr.trim().length === 0 ? "" : `: ${stderr.trim()}`)));
+        return;
+      }
+      try { resolve(JSON.parse(stdout.replace(/^\uFEFF/u, "").trim()) as WindowsCredentialResult); }
+      catch { reject(new Error(`Windows credential ${operation} returned an invalid response`)); }
+    });
+    // A closed input pipe is an operation failure too. Do not leave the child waiting for a request.
+    child.stdin!.on("error", () => {
+      child.kill();
+      reject(new Error(`Windows credential ${operation} request could not be written`));
+    });
+    child.stdin!.end(JSON.stringify({
+      service, account,
+      ...(secret === undefined ? {} : { secret: Buffer.from(secret, "utf8").toString("base64") }),
+    }));
+  });
+}

package/packages/credential-store-platform/README.md

@@ -53,7 +53,8 @@ credential stored in a locker stays in that locker; a credential stored in a fil
 
 On macOS and Windows the credential is held by the platform locker, with exactly the rules of
 `@hypit/credential-store-os`: it is encrypted and access-controlled by the operating system, and it
-is not readable from another machine.
+follows that locker’s access and synchronization policy. Windows Credential Locker may roam
+credentials through the user’s Microsoft account.
 
 On Linux the credential is held by an owner-private document with exactly the rules of
 `@hypit/credential-store-file`: unencrypted JSON, one document per key, directory mode `0700`, file

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

@@ -23,9 +23,7 @@ const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet(
       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),
+        directory: path === undefined ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path),
         ...(service === undefined ? {} : { service }),
       }),
     };

package/packages/file-io-node/README.md

@@ -0,0 +1,20 @@
+# `@hypit/file-io-node`
+
+Node filesystem operations shared by file-backed adapters. This package has no knowledge of
+credentials, Build Results, Runtime or repository formats.
+
+`replaceFile(from, to)` publishes a complete file at a destination on the same filesystem. The
+caller owns creating and closing the source file, its contents and permissions, and temporary-file
+cleanup. Existing readers retain the old file; subsequent opens see the new file. The destination
+may be absent. Concurrent replacements are ordered by the filesystem, with the last replacement
+supplying the current value.
+
+POSIX uses Node's `rename`. Windows uses `SetFileInformationByHandle(FileRenameInfoEx)` with
+`REPLACE_IF_EXISTS | POSIX_SEMANTICS`, the same primitive previously owned by `build-result`.
+This avoids `MoveFileExW` rejecting replacement while another process has the destination open.
+The native structure layout comes from Koffi; constants are Windows API values.
+
+There is no pre-read, queue, lock file, retry or fallback. Windows filesystems must support this
+operation; unsupported operations, access denials and other I/O errors are reported to the caller.
+Read-only destinations are not overridden. The package does not promise power-loss durability or
+coordinate transactions across multiple files.

package/packages/file-io-node/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@hypit/file-io-node",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "koffi": "3.2.1"
+  }
+}

package/packages/file-io-node/src/index.ts

@@ -0,0 +1 @@
+export { replaceFile } from "./replace-file.js";

package/packages/{build-result → file-io-node}/src/replace-file-windows.ts

@@ -1,4 +1,4 @@
-import { toNamespacedPath } from "node:path";
+import { resolve, toNamespacedPath } from "node:path";
 import koffi from "koffi";
 
 const kernel = koffi.load("kernel32.dll");
@@ -35,7 +35,7 @@ function failure(syscall: string, from: string, to: string): Error {
  * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c
  */
 export function replaceWindowsFile(from: string, to: string): void {
-  const filename = Buffer.from(toNamespacedPath(to), "utf16le");
+  const filename = Buffer.from(toNamespacedPath(resolve(to)), "utf16le");
   const nameOffset = koffi.offsetof(renameInfo, "FileName");
   // Win32 requires a NUL-terminated FileName even though FileNameLength excludes
   // that terminator. Buffer.alloc leaves the final WCHAR zero-initialized.
@@ -45,7 +45,7 @@ export function replaceWindowsFile(from: string, to: string): void {
   info.writeUInt32LE(filename.length, koffi.offsetof(renameInfo, "FileNameLength"));
   filename.copy(info, nameOffset);
 
-  const handle = createFile(toNamespacedPath(from), DELETE, SHARE_READ_WRITE_DELETE,
+  const handle = createFile(toNamespacedPath(resolve(from)), DELETE, SHARE_READ_WRITE_DELETE,
     null, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0) as number | bigint;
   if (handle === -1 || handle === -1n) throw failure("CreateFileW", from, to);
   try {

package/packages/generation/README.md

@@ -37,3 +37,9 @@ Media wire mappings (`url`, `urlArray`, `itemObject`) may declare `resourceField
 paths against the declared media fields. False, zero and empty strings remain values; omitted fields
 remain absent. The resolver implements the service protocol; this package knows no particular
 service or classification. Providers using custom transports carry those fields through that boundary.
+
+A Model item field being optional means authors may omit it. If a request supplies that field,
+`mappingSupportsRequest` and final wire compilation require the mapping to carry it through
+`fieldKeys` or `resourceFields`, including an explicit `false`. A service may support requests
+without a particular optional field and refuse requests that supply it; no field is silently dropped.
+Final compilation checks the whole request before resolving or uploading any reference.

package/packages/generation/src/mapping.ts

@@ -89,8 +89,9 @@ export function selectWireModelForRequest(
   request: GenerationRequest,
   pendingPorts: readonly string[] = [],
 ): string {
-  assert(mappingSupportsRequest(mapping, request),
-    `${mapping.capability.name} request contains a port this Provider cannot map`);
+  const unsupported = unsupportedRequestField(mapping, request);
+  assert(unsupported === undefined,
+    `${mapping.capability.name} request contains ${unsupported} this Provider cannot map`);
   const present = new Set(presentPorts(request));
   for (const port of pendingPorts) {
     assert(mapping.fields[port] !== undefined,
@@ -149,19 +150,38 @@ export async function compileWireRequest(
   return { model, input: canonicalize(input) };
 }
 
-/** Does this request only use ports this mapping can write? Needs no model package. */
-export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+/** Describe only a supplied value the mapping cannot carry; no model table or saved verdict. */
+function unsupportedRequestField(mapping: GenerationWireMapping, value: unknown): string | undefined {
   const request = value as GenerationRequest | undefined;
-  if (request === undefined || request.ports === null || typeof request.ports !== "object") return false;
-  return Object.keys(request.ports).every((port) => mapping.fields[port] !== undefined);
+  if (request === undefined || request === null || request.ports === null || typeof request.ports !== "object") {
+    return "invalid ports";
+  }
+  for (const [port, supplied] of Object.entries(request.ports)) {
+    const field = mapping.fields[port];
+    if (field === undefined) return `port ${port}`;
+    if (field.as !== "url" && field.as !== "urlArray" && field.as !== "itemObject") continue;
+    for (const item of supplied as readonly GenerationMediaValue[]) {
+      for (const name of Object.keys(item.fields ?? {})) {
+        if (!field.resourceFields?.includes(name)
+          && !(field.as === "itemObject" && Object.hasOwn(field.fieldKeys, name))) {
+          return `field ${port}.${name}`;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
+export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+  return unsupportedRequestField(mapping, value) === undefined;
 }
 
 /**
- * Prove one service mapping covers every port the model declares.
+ * Check structural port coverage and required item fields against the model declaration.
  *
- * This is the check the old hand-written per-model translators could not have:
- * a forgotten reference role or item field used to surface only after a paid
- * generation returned the wrong result.
+ * A service may omit optional item capabilities. mappingSupportsRequest and final compilation
+ * additionally refuse requests that actually supply such an unmapped field.
  */
 export function assertMappingCoversPorts(
   table: GenerationPortTable,

package/packages/media-execution/src/process-env.ts

@@ -1,4 +1,4 @@
-const windowsProcessCreation = ["PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec"] as const;
+const windowsProcessCreation = ["PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec", "TEMP", "TMP"] as const;
 
 /**
  * ffmpeg and ffprobe are started as PATH executables. The Host environment is
@@ -7,9 +7,10 @@ const windowsProcessCreation = ["PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec"] as
  */
 export function mediaProcessEnv(
   extra?: Readonly<Record<string, string>>,
+  platform: NodeJS.Platform = process.platform,
 ): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { PATH: process.env.PATH ?? "" };
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     for (const name of windowsProcessCreation) {
       const value = process.env[name];
       if (value !== undefined && value.length > 0) env[name] = value;

package/packages/media-execution/src/toolchain.ts

@@ -1,18 +1,14 @@
 import { execFile } from "node:child_process";
+import { mediaProcessEnv } from "./process-env.js";
 
 export type MediaToolchainState =
   | { readonly state: "ready"; readonly ffprobeVersion: string; readonly ffmpegVersion?: string }
   | { readonly state: "down" | "mismatch"; readonly detail: string };
 
-const REQUIRED_ENCODERS = ["aac", "libx264", "pcm_s16le"] as const;
-const REQUIRED_FILTERS = [
-  "aformat", "amix", "aresample", "asetpts", "atempo", "atrim",
-  "loop", "pad", "scale", "select", "setpts", "setsar", "trim",
-] as const;
-
-function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
+function run(executable: string, args: readonly string[], env: NodeJS.ProcessEnv): Promise<{ ok: boolean; output: string }> {
   return new Promise((resolve) => {
     execFile(executable, [...args], {
+      env,
       timeout: 15_000,
       shell: false,
       windowsHide: true,
@@ -29,22 +25,18 @@ function firstLine(value: string): string {
   return value.split(/\r?\n/u, 1)[0]?.trim() ?? "";
 }
 
-function missingNames(output: string, required: readonly string[]): readonly string[] {
-  return required.filter((name) => !new RegExp(`(?:^|\\s)${name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}(?:\\s|$)`, "mu")
-    .test(output));
-}
-
 /**
- * Compatibility probe for a deployment-owned FFmpeg toolchain. It deliberately
- * checks the commands the shared execution body uses instead of requiring one
- * blessed version number. A managed distribution may pin binaries separately;
- * a custom installation remains valid when it supplies the same capability.
+ * Check availability of the selected executables in their execution environment.
+ * This does not predict compatibility with every future media command: the execution
+ * implementation owns those commands and reports the tool's actual failure.
  */
 export async function probeMediaToolchain(options: {
   readonly ffprobePath: string;
   readonly ffmpegPath?: string;
+  readonly environment?: NodeJS.ProcessEnv;
 }): Promise<MediaToolchainState> {
-  const probeVersion = await run(options.ffprobePath, ["-version"]);
+  const env = options.environment ?? mediaProcessEnv();
+  const probeVersion = await run(options.ffprobePath, ["-version"], env);
   if (!probeVersion.ok) {
     return { state: "down", detail: `${options.ffprobePath} is unavailable: ${probeVersion.output}` };
   }
@@ -52,28 +44,10 @@ export async function probeMediaToolchain(options: {
   if (ffprobeVersion.length === 0) return { state: "mismatch", detail: "ffprobe returned no version" };
   if (options.ffmpegPath === undefined) return { state: "ready", ffprobeVersion };
 
-  const [ffmpegVersionResult, encoders, filters] = await Promise.all([
-    run(options.ffmpegPath, ["-version"]),
-    run(options.ffmpegPath, ["-hide_banner", "-encoders"]),
-    run(options.ffmpegPath, ["-hide_banner", "-filters"]),
-  ]);
+  const ffmpegVersionResult = await run(options.ffmpegPath, ["-version"], env);
   if (!ffmpegVersionResult.ok) {
     return { state: "down", detail: `${options.ffmpegPath} is unavailable: ${ffmpegVersionResult.output}` };
   }
-  if (!encoders.ok || !filters.ok) {
-    return { state: "mismatch", detail: "ffmpeg could not enumerate its encoders and filters" };
-  }
-  const missingEncoders = missingNames(encoders.output, REQUIRED_ENCODERS);
-  const missingFilters = missingNames(filters.output, REQUIRED_FILTERS);
-  if (missingEncoders.length > 0 || missingFilters.length > 0) {
-    return {
-      state: "mismatch",
-      detail: [
-        missingEncoders.length === 0 ? "" : `missing encoders ${missingEncoders.join(", ")}`,
-        missingFilters.length === 0 ? "" : `missing filters ${missingFilters.join(", ")}`,
-      ].filter(Boolean).join("; "),
-    };
-  }
   const ffmpegVersion = firstLine(ffmpegVersionResult.output);
   return ffmpegVersion.length === 0
     ? { state: "mismatch", detail: "ffmpeg returned no version" }

package/packages/performance/package.json

@@ -25,6 +25,7 @@
     "@hypit/markup": "workspace:*",
     "@hypit/temporal": "workspace:*",
     "@hypit/temporal-markup": "workspace:*",
-    "@hypit/media-track": "workspace:*"
+    "@hypit/media-track": "workspace:*",
+    "@hypit/visual-ir": "workspace:*"
   }
 }

package/packages/provider-hyperframes-local/src/process.ts

@@ -35,8 +35,12 @@ export async function mediaExecutablePath(value: string): Promise<string> {
   throw new Error(`HyperFrames media executable ${value} is unavailable; correct the Provider's ffmpegPath or ffprobePath.`);
 }
 
-function processEnvironment(): NodeJS.ProcessEnv {
-  const names = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
+export function processEnvironment(platform: NodeJS.Platform = process.platform): NodeJS.ProcessEnv {
+  // POSIX temp is TMPDIR; Windows is TEMP/TMP. HyperFrames writes extracted
+  // frames under %TEMP%\hf-render-… and ffmpeg creates temporary files the same way.
+  const names = platform === "win32"
+    ? ["PATH", "PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec", "TEMP", "TMP", "USERPROFILE", "LANG", "LC_ALL"] as const
+    : ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
   return Object.fromEntries(names.flatMap((name) => process.env[name] === undefined
     ? []
     : [[name, process.env[name]]])) as NodeJS.ProcessEnv;

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

@@ -5,6 +5,7 @@ import { probeMediaToolchain } from "@hypit/media-execution";
 import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
 import { browserCacheDirectory, browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
 import type { BrowserOptions } from "./browser.js";
+import { processEnvironment } from "./process.js";
 
 /**
  * This Provider owns browser selection and preparation. Probes never install;
@@ -44,7 +45,7 @@ export function localHyperframesBrowserProgram(
     async probe(): Promise<ManagedProgramState> {
       const browser = await probeBrowser();
       if (browser.state !== "ready") return browser;
-      const media = await probeMediaToolchain({ ffprobePath: input.ffprobePath, ...(input.ffmpegPath === undefined ? {} : { ffmpegPath: input.ffmpegPath }) });
+      const media = await probeMediaToolchain({ environment: processEnvironment(), ffprobePath: input.ffprobePath, ...(input.ffmpegPath === undefined ? {} : { ffmpegPath: input.ffmpegPath }) });
       return media.state === "ready"
         ? { state: "ready" }
         : { state: media.state, detail: media.detail };

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

@@ -43,7 +43,8 @@ Source. Local HyperFrames extracts alpha-preserving PNGs and composites them aga
 Canvas and lower visual layers before encoding the final MP4.
 
 The Runtime Adapter declares the selected `ffmpeg`/`ffprobe` pair as an external, non-daemon Program.
-Its shared probe checks the encoders and filters used by the execution body. Compatible custom paths
+Its probe checks that the selected executables start in the media execution environment. It does not
+guarantee every codec or filter for every task; an unsupported operation reports FFmpeg’s actual error. Custom paths
 remain valid; the package neither pins a semantic Capability to one FFmpeg version nor mutates a
 system package manager.
 

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

@@ -296,6 +296,8 @@ async function bringUpOwned(
     const prepared = await prepareOwned(root, program, endpoint, onProgress);
     if (prepared.state.state !== "ready") return prepared;
     onProgress?.({ id: program.id, phase: "ready" });
+    // A usable tool may have no process. Preserve the preparation action in that case.
+    if (program.start === undefined) return prepared;
     return { ...base, action: "already-running", state: initial };
   }
   if (initial.state === "mismatch") {
@@ -504,11 +506,14 @@ export async function takeManagedProgramsDown(
       if (pid === undefined || !processAlive(pid)) {
         if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
         const state = await program.probe();
-        return state.state === "down"
-          ? { ...base, action: "nothing-to-stop", state }
-          // Someone else's process, or one started by hand. Killing it is not this
-          // command's business; saying so is.
-          : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
+        if (state.state === "down" || program.start === undefined) {
+          // Probe-only Programs describe installed tools or resources. Readiness means they are
+          // usable, not that a process exists for Hypit to stop.
+          return { ...base, action: "nothing-to-stop", state };
+        }
+        // Someone else's process, or one started by hand. Killing it is not this
+        // command's business; saying so is.
+        return { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
       }
       const term = await stopProcessTree(pid);
       if (term === "denied") {

package/packages/video-cli/README.md

@@ -35,10 +35,12 @@ Keep an existing chosen service, or configure the chosen local or hosted Provide
 bindings. HypiHub is the recommended integrated hosted route in the official Distribution; other
 services use project Provider packages. If the user chooses HypiHub,
 `hypit auth login hypihub.default` connects that account after choosing its CredentialStore.
-The starter selects the OS store for macOS Keychain / Windows Credential Locker. On Linux, or when
-explicitly choosing file storage, edit the Profile's `credentials` and Endpoint reference as shown
-in [file CredentialStore](../credential-store-file/README.md#select-it-before-login) before `auth` or
-`runtime up`. This selection is configuration; execution never switches stores automatically.
+The starter selects the [platform CredentialStore](../credential-store-platform/README.md#select-it):
+macOS Keychain or Windows Credential Locker on those two platforms, and an owner-private file on
+Linux, so the Profile it writes needs no edit on any of them. Name another Store in `credentials` and
+in the Endpoint's credential reference — as the
+[file CredentialStore](../credential-store-file/README.md#select-it-before-login) shows — to choose it
+explicitly. This selection is configuration; execution never switches stores automatically.
 `hypit doctor --endpoint <name>` checks a selected Endpoint;
 `hypit runtime up --endpoint <name>` prepares that Endpoint and starts the Worker. Repeat the flag
 for several chosen Endpoints; omitting it prepares the whole Profile. `hypit programs up --endpoint

package/packages/video-cli/package.json

@@ -25,6 +25,7 @@
     "@hypit/protocol": "workspace:*",
     "@hypit/provider-hypihub": "workspace:*",
     "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",
     "@hypit/runtime-local": "workspace:*",
     "@hypit/speech": "workspace:*",

package/packages/video-cli/src/distribution.ts

@@ -25,15 +25,18 @@ export const videoCliDistribution: CliDistribution = {
   initialRuntimeProfile: {
     format: "hypit.runtime-local@1",
     dataRoot: ".hypit/runtimes/local",
+    // The starter selects the portable Store, so the Profile it writes is openable and writable on
+    // Linux as well: macOS and Windows keep the platform locker, and a Linux host uses an
+    // owner-private file. `os` and `file` stay selectable by name for one explicit backend.
     credentials: {
-      os: { use: "@hypit/credential-store-os" },
+      platform: { use: "@hypit/credential-store-platform" },
     },
     endpoints: {
       "hypihub.default": {
         use: "@hypit/provider-hypihub",
         config: {
           baseUrl: "https://hypit.ai",
-          apiKey: { store: "os", key: "hypihub.oauth" },
+          apiKey: { store: "platform", key: "hypihub.oauth" },
         },
       },
       "media.local": {