@hypit/hypit 0.2.2 → 0.2.3

package/README.md

@@ -156,7 +156,7 @@ commands and the repository layout.
         </picture>
       </a>
     </td>
-    <td>Watcha is an innovative ecosystem and community built for AI builders, connecting great products with high-quality users to turn every Demo into reality. Starting from AI product discovery and genuine feedback, Watcha provides product publishing, distribution, and reputation tracking to support builders from launch to early adoption.</td>
+    <td><a href="https://watcha.cn">Watcha</a> is an innovative ecosystem and community built for AI builders, connecting great products with high-quality users to turn every Demo into reality. Starting from AI product discovery and genuine feedback, Watcha provides product publishing, distribution, and reputation tracking to support builders from launch to early adoption.</td>
   </tr>
   <tr>
     <td width="220" align="center">
@@ -167,13 +167,19 @@ commands and the repository layout.
         </picture>
       </a>
     </td>
-    <td>TokenDance offers builders a unified multi-model gateway with optimized inference costs. Through programs like the Billion-Token Subsidy and the Developer Program, TokenDance helps early-stage builders cut costs so they can focus on product validation and growth.</td>
+    <td><a href="https://tokendance.space/?utm_source=hypit">TokenDance</a> offers builders a unified multi-model gateway with optimized inference costs. Through programs like the Billion-Token Subsidy and the Developer Program, TokenDance helps early-stage builders cut costs so they can focus on product validation and growth.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://autoclaw.z.ai"><img alt="AutoClaw" src="./docs/public/autoclaw.png" width="180"></a>
+    </td>
+    <td><a href="https://autoclaw.z.ai">AutoClaw</a> is Z.ai’s desktop AI assistant for work, deeply optimized for GLM models and integrated with specialized knowledge bases and workflows for legal, finance, design, and more.</td>
   </tr>
   <tr>
     <td width="220" align="center">
       <a href="https://openagents.org/blog/posts/2026-09-08-pilot-user-program-zh-hypit"><img alt="OpenAgents" src="./docs/public/openagents.png" width="180"></a>
     </td>
-    <td>OpenAgents Workspace is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes (<a href="https://openagents.org">https://openagents.org</a>)</td>
+    <td><a href="https://openagents.org">OpenAgents Workspace</a> is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes.</td>
   </tr>
   <tr>
     <td width="220" align="center">
@@ -184,13 +190,19 @@ commands and the repository layout.
         </picture>
       </a>
     </td>
-    <td>Monid is the OpenRouter for agent tools: one key, one wallet, hundreds of tools, billed per call. Hypit can route Seedance video, images, speech and word-level transcription to Monid.</td>
+    <td><a href="https://monid.ai?fpr=alvin-45480b">Monid</a> is the OpenRouter for agent tools: one key, one wallet, hundreds of tools, billed per call. Hypit can route Seedance video, images, speech and word-level transcription to Monid.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://www.hiapi.ai/invite/hypit"><img alt="HiAPI" src="./docs/public/hiapi.png" width="165"></a>
+    </td>
+    <td><a href="https://www.hiapi.ai/invite/hypit">HiAPI</a> is a unified API platform for AI image, video, audio, and language models. Connect GPT Image 2.5, Seedance 2.0, Veo 3.1, Kling, Wan, and other popular models through one platform. Pay as you go with no monthly fee, with free trial credits available for new users.</td>
   </tr>
   <tr>
     <td width="220" align="center">
-      <a href="https://www.hiapi.ai"><img alt="HiAPI" src="./docs/public/hiapi.png" width="165"></a>
+      <a href="https://api.pollo.ai/?utm_source=hypit"><img alt="Pollo API" src="./docs/public/pollo.jpg" width="120"></a>
     </td>
-    <td>HiAPI is a unified API platform for AI image, video, audio, and language models. Connect GPT Image 2.5, Seedance 2.0, Veo 3.1, Kling, Wan, and other popular models through one platform. Pay as you go with no monthly fee, with free trial credits available for new users.</td>
+    <td><a href="https://api.pollo.ai/?utm_source=hypit">Pollo API</a> gives developers access to 300+ AI image and video models through a single API, with competitive rates. One API key connects you to multiple model providers and scales from 10 to 10,000+ requests.</td>
   </tr>
 </table>
 

package/bin/hypit.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { register } from "tsx/esm/api";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 if (process.argv.length === 3 && ["--version", "-v"].includes(process.argv[2])) {
   const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -18,27 +18,30 @@ process.emitWarning = function hypitWarning(warning, ...args) {
   return emitWarning.call(process, warning, ...args);
 };
 
-const distributionRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// Bootstrap and package activation must agree on the physical Distribution root. Windows short
+// paths can survive Node's ordinary resolution while package lookup expands them through libuv.
+const distributionRoot = realpathSync.native(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
+const distributionUrl = pathToFileURL(distributionRoot + sep);
 register();
 const {
   installDistributionPackageResolution,
   installExternalPackageResolution,
-} = await import("../packages/package-loader-node/src/distribution-resolution.ts");
+} = await import(new URL("packages/package-loader-node/src/distribution-resolution.ts", distributionUrl).href);
 installDistributionPackageResolution([distributionRoot]);
-const { hypitHostPackageRoot } = await import("../packages/runtime-host-node/src/index.ts");
+const { hypitHostPackageRoot } = await import(new URL("packages/runtime-host-node/src/index.ts", distributionUrl).href);
 installExternalPackageResolution([hypitHostPackageRoot()]);
 const args = process.argv.slice(2);
 if (args[0] === "studio" || (args[0] === "help" && args[1] === "studio")) {
-  const { runStudio } = await import("../packages/studio/start.ts");
+  const { runStudio } = await import(new URL("packages/studio/start.ts", distributionUrl).href);
   try {
     await runStudio(args[0] === "help" ? ["--help"] : args.slice(1).filter((arg) => arg !== "--debug"), {
       write: (text) => process.stdout.write(text),
     });
   } catch (error) {
-    const { renderCliError } = await import("../packages/cli/src/index.ts");
+    const { renderCliError } = await import(new URL("packages/cli/src/index.ts", distributionUrl).href);
     process.stderr.write(renderCliError(error, { debug: args.includes("--debug") }));
     process.exitCode = 1;
   }
 } else {
-  await import("../packages/video-cli/src/cli.ts");
+  await import(new URL("packages/video-cli/src/cli.ts", distributionUrl).href);
 }

package/dist/public/generation.d.ts

@@ -533,14 +533,13 @@ declare function selectWireModelForRequest(mapping: GenerationWireMapping, reque
  * only the mapping and the request, never the model package.
  */
 declare function compileWireRequest(mapping: GenerationWireMapping, request: GenerationRequest, resolve: GenerationArtifactUrlResolver): Promise<GenerationWireRequest>;
-/** Does this request only use ports this mapping can write? Needs no model package. */
+/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
 declare function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean;
 /**
- * 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.
  */
 declare function assertMappingCoversPorts(table: GenerationPortTable, mapping: GenerationWireMapping): void;
 

package/examples/provider-package/README.md

@@ -1,10 +1,23 @@
 # A project-owned Provider
 
-This complete package demonstrates an asynchronous image service through the public Hypit SDK.
-The service protocol below is **illustrative**, not a live vendor API. Replace its mapping and
-transport with the selected service's documented operations. The lifecycle test exercises the
-example without a paid request. Implement the capabilities needed by the production; a service's
-entire catalogue is not required.
+This example shows a service that Hypit's official Distribution does not ship, implemented as a
+project package through the public Hypit SDK. Two packages cover the two request shapes a service
+usually differs on:
+
+| Package | Model | Request | Lifecycle |
+| --- | --- | --- | --- |
+| `packages/provider-images` | `@hypit/gpt-image@1#gpt-image-2` | one image, optional references | asynchronous |
+| `packages/provider-videos` | `@hypit/seedance@1#seedance-2-mini` | one video, references and frames | asynchronous |
+
+Both service protocols are **illustrative**, not live vendor APIs. Replace the mapping and transport
+with the selected service's documented operations. The lifecycle tests exercise the examples without
+a paid request. Implement the capabilities needed by the production; a service's entire catalogue is
+not required.
+
+The video example is the one to read when the service renders **video**. A video request carries the
+whole reference vocabulary — images, videos, audio and first/last frames — and the result is a large
+remote task rather than a returned file. This is the shape most third-party video services use, and
+the shape the official Distribution cannot supply for a service it does not know.
 
 ## Follow one request
 
@@ -46,25 +59,84 @@ does not claim remote cancellation.
 source and preserves the response with a concise description. It reads no graph and invents no
 future media duration. Rates and credentials do not supply spending permission.
 
+## Follow a video request
+
+A Seedance request reaches `@hypit/seedance@1#seedance-2-mini` and returns a generated video-set.
+The Model declares the request; this Provider decides how the service receives it. Four things
+differ from the image example, and each is the reason the video example exists.
+
+**The reference vocabulary is wider, and each role maps to its own field.** The Model declares
+`referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
+to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
+reference also carries an optional `personReference` classification, which is why those ports use
+`itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
+
+```json
+{ "references": [{ "url": "https://…/reference.png", "person": true }] }
+```
+
+`firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
+This illustrative service accepts their optional person classification on `POST /uploads` through
+`x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
+and the URL resolver sends that header when supplied. Replace this with the real service’s
+documented transport; a field that the service cannot carry must be refused, never discarded.
+
+**The service's range is narrower than the Model's, and the Provider states that.** Seedance 2 Mini
+admits 480p/720p and 4–15 seconds; this illustrative service renders 720p up to 10 seconds. The
+Model is not edited for that. `supports` reports the difference before submission, so `plan` refuses
+the request with a reason instead of failing a paid job downstream:
+
+```
+This service renders at most 10 seconds, not 12
+```
+
+Do not widen the Model to fit one service. Do not silently clamp the author's number either — the
+author wrote 12 seconds, and a 10-second result is a different video.
+
+**Submission is an enqueue, not the render.** `start` returns as soon as the service acknowledges a
+task, and the HTTP bound covers the API call, not the minutes the render may take. `poll` returns
+`pending` while the task is `queued` or `running`, and the task id is checkpointed before `start`
+returns, so an interrupted Build still names the remote work it began.
+
+**The result is fetched in a separate `collect` step.** A finished task carries a signed URL; the
+account key goes only to the service's own API. `collect` downloads the media, stores it through
+`context.resources` and returns the Model's declared value. Because `poll` and `collect` are
+separate actions, download capacity is configured independently of task capacity.
+
+A task that reports `succeeded` without an output URL is a service contract violation, not a pending
+job, and fails loudly. A `failed` task keeps the service's own error code and the received task id
+as evidence, and redacts URLs from the message it republishes.
+
+`assertMappingCoversPorts` checks declared ports and required item fields. Optional fields need
+request-level checks and transport tests as well:
+a mapping that forgets a reference role or an item field fails at load rather than after a paid
+generation returns the wrong video. Where a Model port is genuinely optional, `whenAbsent` states
+what the service should receive when the author omits it — the service then gets the value the
+author's request implies, not a field left to its own default. The lifecycle test asserts the
+mapping against the Model's own port table.
+
 ## Make it a package in the production
 
-Copy `packages/provider-images` into the video's `packages/`. Choose your own package name and change
-`providerModule.name` with it. Implement the actual service protocol, including its request limits,
-upload/download limits and any OAuth or cancellation behavior it really offers. Configure the
-selected service address; `images.example` is a placeholder that cannot generate media.
+Copy the package matching your service's request shape — `packages/provider-images` or
+`packages/provider-videos` — into the video's `packages/`. Choose your own package name and change
+`providerModule.name` with it. A service that renders both images and video can implement both
+capabilities in one package; `defineEndpointPackage` accepts several. Implement the actual service
+protocol, including its request limits, upload/download limits and any OAuth or cancellation
+behavior it really offers. Configure the selected service address; `images.example` and
+`videos.example` are placeholders that cannot generate media.
 
 Use the active `@hypit/hypit` version as a development dependency. Build and install with the
-project's package manager. In this repository the example uses `workspace:*` for that dependency;
-replace it with your selected release when copying it out. The `@hypit/driver-node` and
-`@hypit/gpt-image` development dependencies serve the repository test only and can be removed from
-the copied package. For example:
+project's package manager. In this repository the examples use `workspace:*` for that dependency;
+replace it with your selected release when copying it out. The `@hypit/driver-node` and model
+development dependencies (`@hypit/gpt-image`, `@hypit/seedance`) serve the repository tests only and
+can be removed from the copied package. For example:
 
 ```bash
-cd packages/provider-images
+cd packages/provider-videos
 npm install
 npm run build
 cd ../..
-npm install ./packages/provider-images
+npm install ./packages/provider-videos
 ```
 
 The package ships JavaScript. Its `hypit.activation` exports a Profile-selected Runtime facet;
@@ -73,10 +145,14 @@ loading project packages. Keep the chosen package version and lockfile with the
 
 Merge the endpoint, credential store and binding from `hypit.runtime.json` into the project's
 chosen Profile. Preserve its other services and resolve bindings explicitly. Once the user chooses
-that account, `hypit auth login images.personal` securely enters the key into its declared store.
+that account, `hypit auth login videos.personal` securely enters the key into its declared store.
 `plan` checks the requested parameters; `pricing` supplies the service's rates. Submitting a real
 generation follows the agreed production scope and spending authority.
 
+The service decides whether an Endpoint needs its own credential slot at all. A service that
+authenticates through the platform it runs on, or one reached at a private address, may declare no
+credentials or a non-secret account name; `defineEndpointPackage` takes whichever the service has.
+
 ## Owners
 
 - `src/provider.ts`: exact capability, mapping, service support, task lifecycle, pricing and capacity.

package/examples/provider-package/hypit.runtime.json

@@ -6,7 +6,14 @@
     "images.personal": {
       "use": "@example/provider-images",
       "config": { "baseUrl": "https://images.example", "apiKey": { "store": "platform", "key": "images.personal" } }
+    },
+    "videos.personal": {
+      "use": "@example/provider-videos",
+      "config": { "baseUrl": "https://videos.example", "apiKey": { "store": "platform", "key": "videos.personal" } }
     }
   },
-  "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }
+  "bindings": {
+    "@hypit/gpt-image@1#gpt-image-2": "images.personal",
+    "@hypit/seedance@1#seedance-2-mini": "videos.personal"
+  }
 }

package/examples/provider-package/packages/provider-videos/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@example/provider-videos",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "hypit": { "activation": "./dist/activation.js" },
+  "exports": { ".": "./dist/provider.js" },
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json" },
+  "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@hypit/driver-node": "workspace:*", "@hypit/seedance": "workspace:*" }
+}

package/examples/provider-package/packages/provider-videos/src/activation.ts

@@ -0,0 +1,24 @@
+import {
+  createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigExact,
+  runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString,
+} from "@hypit/hypit/runtime-kit";
+import { createVideoProvider, providerModule } from "./provider.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createRuntimeEndpointAdapterFacet({
+    use: providerModule.name,
+    activate(context) {
+      const config = runtimeConfigObject(context.config, "Video service");
+      runtimeConfigExact(config, ["baseUrl", "apiKey", "concurrency", "pollIntervalMs"], "Video service");
+      const baseUrl = runtimeConfigString(config.baseUrl, "Video service baseUrl");
+      const apiKey = runtimeConfigCredentialRef(config.apiKey, "Video service apiKey");
+      if (!baseUrl || !apiKey || !context.pool) throw new Error("Video service requires baseUrl, apiKey and pool");
+      return { endpoint: createVideoProvider({
+        instance: context.instance, pool: context.pool, baseUrl, apiKey,
+        concurrency: runtimeConfigPositiveInteger(config.concurrency, "concurrency") ?? 1,
+        pollIntervalMs: runtimeConfigPositiveInteger(config.pollIntervalMs, "pollIntervalMs") ?? 5_000,
+      }) };
+    },
+  })],
+};

package/examples/provider-package/packages/provider-videos/src/provider.ts

@@ -0,0 +1,181 @@
+import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";
+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
+import {
+  compileWireRequest, generationTypes, mappingSupportsRequest,
+  sealGeneratedVideoSet, selectWireModelForRequest,
+} from "@hypit/hypit/generation";
+import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";
+
+export const providerModule = { name: "@example/provider-videos", version: "1" } as const;
+export const capability = { module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" } as const;
+
+// This example service implements only this subset of the model. Its API is described in README.
+export const mapping: GenerationWireMapping = {
+  capability, result: "video", routes: [{ model: "seedance-2-mini" }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    duration: { as: "value", field: "duration" },
+    resolution: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "ratio" },
+    generateAudio: { as: "value", field: "audio" },
+    webSearch: { as: "value", field: "search" },
+    referenceImage: { as: "itemObject", field: "references", urlKey: "url", fieldKeys: { personReference: "person" } },
+    referenceVideo: { as: "itemObject", field: "videoReferences", urlKey: "url", fieldKeys: { personReference: "person" } },
+    referenceAudio: { as: "urlArray", field: "audioReferences" },
+    firstFrame: { as: "url", field: "firstFrame", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "lastFrame", resourceFields: ["personReference"] },
+  },
+};
+
+// This service renders a narrower band than the model vocabulary allows, which it reports rather
+// than widening: Seedance 2 Mini declares 480p/720p and 4–15 seconds, and this service renders 720p
+// up to 10 seconds. The Model is unchanged; the difference belongs to this Endpoint.
+const SUPPORTED_RESOLUTION = "720p";
+const SUPPORTED_SECONDS = 10;
+
+function object(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected service object");
+  return value as Record<string, unknown>;
+}
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");
+  return value;
+}
+// This illustrative service documents these fields as its public failure evidence.
+function publicFailure(value: unknown): { code: string; message: string } | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const error = value as Record<string, unknown>;
+  if (typeof error.code !== "string" || typeof error.message !== "string") return undefined;
+  return { code: error.code, message: error.message.replace(/https?:\/\/\S+/giu, "[redacted-url]") };
+}
+function address(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
+    throw new Error("Service URLs require HTTPS or loopback HTTP");
+  }
+  return url.href;
+}
+
+function serviceSupport(request: EndpointRequest) {
+  const ports = (request.constraints as unknown as GenerationRequest).ports;
+  const duration = ports.duration?.[0];
+  if (typeof duration === "number" && duration > SUPPORTED_SECONDS) {
+    return { status: "unsupported" as const,
+      reason: `This service renders at most ${SUPPORTED_SECONDS} seconds, not ${duration}` };
+  }
+  const resolution = ports.resolution?.[0];
+  if (resolution !== undefined && String(resolution) !== SUPPORTED_RESOLUTION) {
+    return { status: "unsupported" as const,
+      reason: `This service renders at ${SUPPORTED_RESOLUTION}, not ${String(resolution)}` };
+  }
+  return mappingSupportsRequest(mapping, request.constraints)
+    ? { status: "supported" as const }
+    : { status: "unsupported" as const, reason: "This service does not accept one of the requested inputs" };
+}
+
+export function createVideoProvider(options: {
+  instance: string; pool: string; baseUrl: string; apiKey: CredentialRef;
+  concurrency?: number; pollIntervalMs?: number; fetch?: typeof globalThis.fetch;
+}) {
+  const base = address(options.baseUrl).replace(/\/$/u, "");
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const interval = options.pollIntervalMs ?? 5_000;
+  const key = (credentials: Readonly<Record<string, { secret: string }>>) => text(credentials.apiKey?.secret);
+  async function json(path: string, secret: string, init: RequestInit = {}) {
+    const response = await fetcher(`${base}${path}`, {
+      ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },
+      // Submission enqueues a remote job and answers immediately; the bound is for the API, not the render.
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!response.ok) {
+      let error: ReturnType<typeof publicFailure>;
+      try { error = publicFailure(object(await response.json()).error); }
+      catch { /* A missing public error body leaves the HTTP evidence intact. */ }
+      const requestId = response.headers.get("x-request-id");
+      throw Object.assign(new Error(`Video service ${init.method ?? "GET"} ${path} returned HTTP ${response.status}`
+        + (requestId === null ? "" : `; request=${requestId}`)
+        + (error === undefined ? "" : `; ${error.code}: ${error.message}`)),
+      error === undefined ? {} : { code: error.code });
+    }
+    return object(await response.json());
+  }
+  const endpoint: AsyncEndpoint = {
+    async start(context) {
+      const supported = serviceSupport(context.need);
+      if (supported.status === "unsupported") throw new Error(supported.reason);
+      const secret = key(context.credentials);
+      const authored = context.need.constraints as unknown as GenerationRequest;
+      const model = selectWireModelForRequest(mapping, authored);
+      // This service has no catalogue query; its known request limits were checked above.
+      await context.reportProgress?.({ phase: `Preparing video request: ${model}` });
+      const request = await compileWireRequest(mapping, authored,
+        async (artifact, fields) => {
+          const bytes = await context.resources.get(artifact.resource);
+          if (bytes === undefined) throw new Error("Reference media is unavailable");
+          const upload = await fetcher(`${base}/uploads`, {
+            method: "POST", headers: { "content-type": artifact.mediaType, authorization: `Bearer ${secret}`,
+              ...(fields?.personReference === undefined ? {} : { "x-person-reference": String(fields.personReference) }),
+            },
+            body: new Blob([new Uint8Array(bytes)]), signal: AbortSignal.timeout(120_000),
+          });
+          if (!upload.ok) throw new Error(`Video service POST /uploads returned HTTP ${upload.status}`);
+          return address(text(object(await upload.json()).url));
+        });
+      await context.reportProgress?.({ phase: `Submitting video request: ${model}` });
+      const task = await json("/videos", secret, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),
+      });
+      const id = text(task.id), handle = { id }, receipt = { id };
+      await context.checkpoint?.({ handle, receipt });
+      return { ...wakeAfter(handle, interval), receipt };
+    },
+    async poll(context) {
+      const id = text(object(context.handle).id);
+      const task = await json(`/videos/${encodeURIComponent(id)}`, key(context.credentials));
+      const status = text(task.status);
+      if (status === "queued" || status === "running") {
+        return wakeAfter({ id }, interval, Date.now(), { phase: status });
+      }
+      if (status === "failed") {
+        const error = publicFailure(task.error);
+        return { status: "failed", receipt: { id }, failure: {
+          code: error?.code ?? "VIDEO_SERVICE_FAILED",
+          message: `Video service task ${id} failed${error === undefined ? "" : `: ${error.message}`}`,
+        } };
+      }
+      if (status !== "succeeded") throw new Error("Video service returned an unknown task state");
+      // A completed task without a result URL is a service contract violation, not a pending job.
+      return { status: "ready", handle: { id, url: address(text(task.output)) } };
+    },
+    async collect(context) {
+      // The service returns a signed asset URL; account credentials go only to its API.
+      const url = address(text(object(context.handle).url));
+      await context.reportProgress?.({ phase: "Receiving generated video" });
+      // One delivered video is bounded here; a larger file belongs with a streaming resource port.
+      const response = await fetcher(url, { signal: AbortSignal.timeout(600_000) });
+      if (!response.ok) throw new Error(`Video download returned HTTP ${response.status}`);
+      const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (!mediaType?.startsWith("video/")) throw new Error("Video service returned a non-video result");
+      const artifact = await context.resources.put(new Uint8Array(await response.arrayBuffer()), mediaType);
+      return { status: "completed", result: { value: {
+        kind: "inline", value: canonicalize(sealGeneratedVideoSet({ videos: [artifact] })),
+      } } };
+    },
+  };
+  return defineEndpointPackage({
+    module: providerModule, facet: "videos", instance: options.instance, pool: options.pool,
+    credentials: { apiKey: options.apiKey }, credentialInputs: { apiKey: { label: "Video service API key" } },
+    defaultConcurrency: options.concurrency ?? 1,
+    actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 2 } },
+    pricing: { kind: "page", url: `${base}/pricing` },
+    async readPricing(context) {
+      const model = selectWireModelForRequest(mapping, context.request.constraints as unknown as GenerationRequest,
+        context.request.pendingInputs?.map((input) => input.input));
+      const path = `/rates?model=${encodeURIComponent(model)}`;
+      const source = `${base}${path}`;
+      const rates = await json(path, key(await context.credentials()));
+      return [{ source, data: canonicalize(rates), summary: text(rates.description) }];
+    },
+    capabilities: [{ capability, returns: generationTypes.videoSet, lifecycle: "asynchronous", supports: serviceSupport, endpoint }],
+  });
+}

package/examples/provider-package/packages/provider-videos/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM"], "strict": true, "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true, "verbatimModuleSyntax": true,
+    "declaration": true, "rootDir": "src", "outDir": "dist", "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/build-result/package.json

@@ -9,6 +9,6 @@
   },
   "dependencies": {
     "@hypit/protocol": "workspace:*",
-    "koffi": "3.2.1"
+    "@hypit/file-io-node": "workspace:*"
   }
 }

package/packages/build-result/src/store.ts

@@ -43,7 +43,7 @@ import {
   encodeBuildResultManifest,
 } from "./decode.js";
 import { syncBuildResultOutputs } from "./writer.js";
-import { replaceFile } from "./replace-file.js";
+import { replaceFile } from "@hypit/file-io-node";
 
 const manifestName = "result.json";
 const writerStateName = ".writer.json";

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

@@ -1,10 +1,10 @@
+import { join, resolve } from "node:path";
 import {
   createRuntimeCredentialStoreAdapterFacet,
   runtimeConfigExact,
   runtimeConfigObject,
   runtimeConfigString,
 } from "@hypit/runtime-kit";
-import { resolveCredentialDirectory } from "./paths.js";
 import { FileCredentialStore } from "./store.js";
 
 const fileCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
@@ -18,7 +18,7 @@ const fileCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
     const config = runtimeConfigObject(context.config, "file CredentialStore");
     const path = runtimeConfigString(config.path, "file credential path");
     return { value: new FileCredentialStore(
-      resolveCredentialDirectory(context.hostStateRoot, path, "file CredentialStore"),
+      path === undefined ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path),
     ) };
   },
 });

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

@@ -1,2 +1 @@
 export { FileCredentialStore } from "./store.js";
-export { resolveCredentialDirectory } from "./paths.js";

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";
@@ -8,26 +9,6 @@ function missing(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-/**
- * One process reads a credential for one Endpoint action while another action's refresh replaces
- * it, so a read handle and a replacement can reach the same document at the same instant. Windows
- * refuses to replace a file any handle still holds. Each document's work takes its turn instead,
- * keyed by path so separate Store instances over one directory share the same order. Keys are
- * independent: a turn on one document never delays another.
- */
-const documentTurns = new Map<string, Promise<unknown>>();
-
-function onDocument<T>(path: string, work: () => Promise<T>): Promise<T> {
-  const turn = (documentTurns.get(path) ?? Promise.resolve()).then(work, work);
-  // The successor waits for this turn to settle, not to succeed, and the last turn clears the path.
-  const settled = turn.then(() => undefined, () => undefined);
-  documentTurns.set(path, settled);
-  void settled.then(() => {
-    if (documentTurns.get(path) === settled) documentTurns.delete(path);
-  });
-  return turn;
-}
-
 function credentialValue(value: unknown): CredentialValue {
   if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid credential value");
   const record = value as Record<string, unknown>;
@@ -64,10 +45,6 @@ export class FileCredentialStore implements WritableCredentialStore {
   async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
     if (!this.owns(ref)) return undefined;
     const path = this.#path(ref);
-    return await onDocument(path, async () => await this.#read(path));
-  }
-
-  async #read(path: string): Promise<CredentialValue | undefined> {
     try { await this.#privateDirectory(false); } catch (error) {
       if (missing(error)) return undefined;
       throw error;
@@ -93,25 +70,21 @@ export class FileCredentialStore implements WritableCredentialStore {
   async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
     const path = this.#path(ref);
     const contents = JSON.stringify(credentialValue(value));
-    await onDocument(path, async () => {
-      await this.#privateDirectory(true);
-      const temporary = join(this.directory, `.write-${randomUUID()}.tmp`);
-      const file = await open(temporary, "wx", 0o600);
-      try {
-        try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
-        await rename(temporary, path);
-      } finally { await rm(temporary, { force: true }); }
-    });
+    await this.#privateDirectory(true);
+    const temporary = join(this.directory, `.write-${randomUUID()}.tmp`);
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
+      await replaceFile(temporary, path);
+    } finally { await rm(temporary, { force: true }); }
   }
 
   async delete(ref: CredentialRef): Promise<boolean> {
     const path = this.#path(ref);
     // Deletion never opens or decodes the old document.
-    return await onDocument(path, async () => {
-      try { await unlink(path); return true; } catch (error) {
-        if (missing(error)) return false;
-        throw error;
-      }
-    });
+    try { await unlink(path); return true; } catch (error) {
+      if (missing(error)) return false;
+      throw error;
+    }
   }
 }

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,72 +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));
-
-const windowsCredentialTimeoutMs = 10_000;
-
-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;
-      clearTimeout(timer);
-      reject(error);
-    };
-    const timer = setTimeout(() => {
-      fail(new Error(`Windows credential ${operation} for ${account} timed out`));
-      child.kill("SIGKILL");
-    }, windowsCredentialTimeoutMs);
-    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;
-      clearTimeout(timer);
-      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;

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

@@ -1,10 +1,10 @@
+import { join, resolve } from "node:path";
 import {
   createRuntimeCredentialStoreAdapterFacet,
   runtimeConfigExact,
   runtimeConfigObject,
   runtimeConfigString,
 } from "@hypit/runtime-kit";
-import { resolveCredentialDirectory } from "@hypit/credential-store-file";
 import { PlatformCredentialStore } from "./store.js";
 
 const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
@@ -23,7 +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: resolveCredentialDirectory(context.hostStateRoot, path, "platform CredentialStore"),
+        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/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/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") {

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

@@ -1,16 +0,0 @@
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-
-/** Profile `path` is Host-state-relative; it must not write secrets outside that root. */
-export function resolveCredentialDirectory(
-  hostStateRoot: string,
-  path: string | undefined,
-  label: string,
-): string {
-  const root = resolve(hostStateRoot);
-  const directory = path === undefined ? join(root, "credentials") : resolve(root, path);
-  const relation = relative(root, directory);
-  if (relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) {
-    throw new Error(`${label} path must stay inside the Host state root`);
-  }
-  return directory;
-}