@hypit/hypit 0.1.12 → 0.1.13

package/dist/public/model-kit.d.ts

@@ -380,6 +380,15 @@ type GenerationMediaValue = {
 };
 type GenerationPortValue = string | number | boolean | GenerationMediaValue;
 
+/**
+ * The one request envelope every exact model uses. A Provider reads ports by
+ * name and never learns a model-specific field layout, so the same wire mapping
+ * mechanism serves every model and every service reselling it.
+ */
+type GenerationRequest = {
+    /** An absent port is an omitted key. A present port always carries at least one value. */
+    readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;
+};
 /**
  * A request while graph inputs are still being attached. It is deliberately a
  * Providers can only receive the finalized request after the exact model
@@ -423,6 +432,10 @@ type ExactModelEndpointSpec = {
     readonly requestTypeName: string;
     readonly producerName: string;
     readonly ports: GenerationPortTable;
+    /** Additional complete-request rules, after port and supplied-input validation. */
+    readonly validateRequest?: (request: GenerationRequest) => void;
+    /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
+    readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
 };
 type ExactModelEndpoint = {
     readonly key: string;
@@ -435,6 +448,9 @@ type ExactModelEndpoint = {
     readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
     readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
     readonly ports: GenerationPortTable;
+    readonly validateRequest: (request: unknown) => void;
+    readonly validateDraft: (draft: unknown) => void;
+    readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
     readonly fragment: ReturnType<typeof sealGraphFragment>;
 };
 type ExactModelMediaBindingEndpoint = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -168,6 +168,7 @@
   ],
   "scripts": {
     "pack:distribution": "node scripts/pack-distribution.mjs",
+    "check:distribution": "node scripts/check-distribution.mjs",
     "build:public-types": "node scripts/build-public-types.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
     "docs:dev": "vitepress dev docs",

package/packages/cli/README.md

@@ -148,6 +148,9 @@ from a lookup that still needs the Build's Runtime or correct project selection.
 Worker process log instead, for Runtime startup or process-level failures.
 
 Project context resolution is owned by [`@hypit/project-context-node`](../project-context-node/README.md).
+History Source filters resolve existing filesystem links before comparing project-relative Result
+paths. A deleted Source or directory remains queryable: only its existing ancestor is resolved and
+the missing path suffix is retained. This is local argument handling, with no saved alias inventory.
 CLI, Studio and creation tools call that same package; the CLI is not another environment owner.
 
 `doctor`, `programs up|status|down`, and `runtime up` accept repeated `--endpoint <instance>` values.

package/packages/cli/src/commands/results.ts

@@ -1,4 +1,5 @@
-import { resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 
 import type { BuildResultRepository } from "@hypit/build-result";
 
@@ -20,6 +21,21 @@ export function isProjectResultCommand(args: CliCommand): args is ProjectResultC
     || args.command === "get" || (args.command === "result" && args.action === "edit");
 }
 
+/** History can name a deleted Source. Resolve existing directory links, keeping the absent suffix. */
+async function historySourcePath(path: string): Promise<string> {
+  let existing = resolve(path);
+  const suffix: string[] = [];
+  while (true) {
+    try { return resolve(await realpath(existing), ...suffix); }
+    catch (error) {
+      const parent = dirname(existing);
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || parent === existing) throw error;
+      suffix.unshift(basename(existing));
+      existing = parent;
+    }
+  }
+}
+
 /** Execute commands that need only project-owned Result history, never a Runtime. */
 export async function runProjectResultCommand(input: {
   readonly args: ProjectResultCommand;
@@ -62,7 +78,7 @@ export async function runProjectResultCommand(input: {
   }
 
   if (args.command === "history") {
-    const source = args.source === undefined ? undefined : resolve(args.source);
+    const source = args.source === undefined ? undefined : await historySourcePath(args.source);
     const page = await browseBuildOutputHistory(repository, {
       projectRoot,
       output: args.outputName,
@@ -177,7 +193,7 @@ export async function runProjectResultCommand(input: {
     kind: exported.kind,
     path: exported.path,
   };
-  const path = projectPath(exported.path, projectRoot);
+  const path = projectPath(await realpath(exported.path), projectRoot);
   write(machine, `Exported ${exported.output} → ${path}`, "success",
     args.presentation.verbose ? [
       ["Build", exported.build],

package/packages/cli/src/output.ts

@@ -1,4 +1,4 @@
-import { relative, resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
 
 import type { CanonicalValue } from "@hypit/protocol";
 
@@ -279,7 +279,7 @@ function glyph(io: CliIo, unicode: string, ascii: string): string {
 function shortPath(path: string): string {
   const absolute = resolve(path);
   const local = relative(process.cwd(), absolute);
-  return local.length > 0 && !local.startsWith("..") ? local : absolute;
+  return local.length > 0 && local !== ".." && !local.startsWith(`..${sep}`) ? local : absolute;
 }
 
 function facts(rows: readonly (readonly [string, string])[], colors: Palette): string[] {

package/packages/cli/src/source-discovery.ts

@@ -1,5 +1,5 @@
 import { readFile, realpath } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 
 import { authorFrontendsFromHostFacets, prepareAuthorSource } from "@hypit/elaborator";
 import type { AuthorFrontend } from "@hypit/elaborator";
@@ -12,7 +12,7 @@ import { parseSourceHeader, sourceFrontendPackageAbi } from "@hypit/source";
 
 function isWithin(root: string, path: string): boolean {
   const relation = relative(root, path);
-  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
 
 function selectedPackage(request: string): string {

package/packages/model-kit/README.md

@@ -50,3 +50,31 @@ exact fields, constraints, model identity, capability name and validator. The he
 Provider routing, fallback, credentials or Runtime authority.
 
 This is a package-authoring utility, not an author-importable model by itself.
+
+## Model-owned request checks
+
+An endpoint may supply two synchronous, pure functions in addition to its port table:
+
+- `validateInputs(inputs)` checks values already supplied, both in drafts and complete requests.
+  Text and media may still be missing from a draft. Use this for rules such as a reference's media
+  type; do not require a future input to exist.
+- `validateRequest(request)` checks additional relationships that require the complete request.
+  It runs after the port table and `validateInputs`, when every required input is available.
+
+Both return `void` and throw a useful error to reject. They read the supplied values only: no IO,
+Provider selection, request mutation or saved validation result. Existing port rules remain in the
+port table. The helper supplies structural validation before calling either function.
+
+Register each rule once in the endpoint definition. The helper connects these functions to Type
+validators, media/Text bindings, finalization, generation and planning. Planning checks the known
+values and leaves future media on the existing graph edges. A directly supplied request or an
+existing Need receives full validation, just as it does during execution.
+
+For a public request builder, use `model.endpoints.image.sealRequest(ports)`: it canonicalizes the
+request and applies all model rules. `endpoint.validateRequest(value)` checks an existing complete
+request; `endpoint.validateDraft(value)` checks a partially assembled one. Calling the common
+generation port helpers alone applies only the port table, not these model-owned functions.
+
+Keep service-specific limits in the Provider. Its existing `supports` and pre-submission preparation
+should share its own checks, rejecting known unsupported values before resource transfer. This does
+not require the Provider to import the Model implementation or add any fields to the request.

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

@@ -13,13 +13,13 @@ import type { HostFacet } from "@hypit/host";
 import {
   bindGenerationMedia,
   bindGenerationText,
-  finalizeGenerationRequestDraft,
   generationModuleRef,
   generationProducers,
   generationTypes,
   mediaBindingSchemaFromPort,
   requestDraftSchemaFromPorts,
   requestSchemaFromPorts,
+  sealGenerationPortRequest,
   verifyGenerationMediaBinding,
   verifyRequestDraftAgainstPorts,
   verifyRequestAgainstPorts,
@@ -28,6 +28,7 @@ import type {
   GenerationMediaBinding,
   GenerationMediaPort,
   GenerationPortTable,
+  GenerationRequest,
   GenerationRequestDraft,
 } from "@hypit/generation";
 import { textDependency, textTypes } from "@hypit/text";
@@ -76,6 +77,10 @@ export type ExactModelEndpointSpec = {
   readonly requestTypeName: string;
   readonly producerName: string;
   readonly ports: GenerationPortTable;
+  /** Additional complete-request rules, after port and supplied-input validation. */
+  readonly validateRequest?: (request: GenerationRequest) => void;
+  /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
+  readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
 };
 
 export type ExactModelEndpoint = {
@@ -89,6 +94,9 @@ export type ExactModelEndpoint = {
   readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
   readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
   readonly ports: GenerationPortTable;
+  readonly validateRequest: (request: unknown) => void;
+  readonly validateDraft: (draft: unknown) => void;
+  readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
   readonly fragment: ReturnType<typeof sealGraphFragment>;
 };
 
@@ -267,7 +275,7 @@ export function plannedExactModelRequest(
 
   const knownNeed = state.needs.find((need) => need.id === binding.id);
   if (knownNeed !== undefined) {
-    verifyRequestAgainstPorts(endpoint.ports, knownNeed.constraints);
+    endpoint.validateRequest(knownNeed.constraints);
     return {
       model: endpoint.ports.model,
       ports: structuredClone((knownNeed.constraints as unknown as GenerationRequestDraft).ports),
@@ -281,6 +289,12 @@ export function plannedExactModelRequest(
     Object.values(step.outputs).map((record) => [record, step] as const)));
   const requestRecord = generationStep.inputs.request;
   if (requestRecord === undefined) return undefined;
+  const knownRequest = records.get(requestRecord);
+  if (knownRequest !== undefined) {
+    const request = inlineValue<GenerationRequest>(knownRequest.value, `${endpoint.ports.model} request`);
+    endpoint.validateRequest(request);
+    return { model: endpoint.ports.model, ports: structuredClone(request.ports), pendingMedia: [], complete: false };
+  }
   const finalize = producedBy.get(requestRecord);
   if (finalize === undefined || !sameReference(finalize.producer, endpoint.finalizeProducer)) return undefined;
   const finalDraft = finalize.inputs.draft;
@@ -295,7 +309,7 @@ export function plannedExactModelRequest(
       const record = records.get(recordId);
       if (record !== undefined) {
         const draft = inlineValue<GenerationRequestDraft>(record.value, `${endpoint.ports.model} request draft`);
-        verifyRequestDraftAgainstPorts(endpoint.ports, draft);
+        endpoint.validateDraft(draft);
         return draft;
       }
       const step = producedBy.get(recordId);
@@ -354,6 +368,8 @@ export function plannedExactModelRequest(
   };
 
   const draft = rebuildDraft(finalDraft);
+  endpoint.validateDraft(draft);
+  if (pendingMedia.length === 0) endpoint.validateRequest(draft);
   return {
     model: endpoint.ports.model,
     ports: structuredClone(draft.ports),
@@ -502,6 +518,15 @@ export function defineExactModelModule<const Key extends string>(
   };
 
   const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {
+    const validateRequest = (request: unknown): void => {
+      verifyRequestAgainstPorts(item.spec.ports, request);
+      item.spec.validateInputs?.(request);
+      item.spec.validateRequest?.(request);
+    };
+    const validateDraft = (draft: unknown): void => {
+      verifyRequestDraftAgainstPorts(item.spec.ports, draft);
+      item.spec.validateInputs?.(draft);
+    };
     const fragment = sealGraphFragment({
       inputs: [{ name: "request", type: item.requestType }],
       operations: [{
@@ -527,6 +552,14 @@ export function defineExactModelModule<const Key extends string>(
       mediaBindings: item.mediaBindings,
       textBindings: item.textBindings,
       ports: item.spec.ports,
+      validateRequest,
+      validateDraft,
+      sealRequest(ports) {
+        const request = sealGenerationPortRequest(item.spec.ports, ports);
+        item.spec.validateInputs?.(request);
+        item.spec.validateRequest?.(request);
+        return request;
+      },
       fragment,
     } satisfies ExactModelEndpoint];
   }));
@@ -540,12 +573,12 @@ export function defineExactModelModule<const Key extends string>(
       validators: endpointData.flatMap((item) => [{
         type: item.requestType,
         handler({ value }) {
-          verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));
+          endpoints[item.spec.key]!.validateRequest(inlineRequest(value, item.spec.key));
         },
       }, {
         type: item.draftType,
         handler({ value }) {
-          verifyRequestDraftAgainstPorts(item.spec.ports, inlineRequest(value, `${item.spec.key} draft`));
+          endpoints[item.spec.key]!.validateDraft(inlineRequest(value, `${item.spec.key} draft`));
         },
       }]),
       producers: endpointData.flatMap((item) => [
@@ -555,7 +588,7 @@ export function defineExactModelModule<const Key extends string>(
             const requestRecord = inputs.request;
             assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);
             const request = inlineRequest(requestRecord.value, item.spec.key);
-            verifyRequestAgainstPorts(item.spec.ports, request);
+            endpoints[item.spec.key]!.validateRequest(request);
             return { outputs: {}, needs: { generation: request } };
           },
         },
@@ -570,11 +603,13 @@ export function defineExactModelModule<const Key extends string>(
             verifyGenerationMediaBinding(port, value);
             const artifact = inputs.artifact!.value;
             assert(artifact.kind === "blob", `${binding.port} artifact must be a Blob`);
+            const bound = bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact);
+            endpoints[item.spec.key]!.validateDraft(bound);
             return {
               outputs: {
                 draft: {
                   kind: "inline" as const,
-                  value: canonicalize(bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact)),
+                  value: canonicalize(bound),
                 },
               },
               needs: {},
@@ -586,11 +621,13 @@ export function defineExactModelModule<const Key extends string>(
           handler: ({ inputs }: ProducerHandlerContext) => {
             const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
             const text = inlineValue<Text>(inputs.text!.value, `${binding.port} Text`);
+            const bound = bindGenerationText(item.spec.ports, draft, binding.port, text);
+            endpoints[item.spec.key]!.validateDraft(bound);
             return {
               outputs: {
                 draft: {
                   kind: "inline" as const,
-                  value: canonicalize(bindGenerationText(item.spec.ports, draft, binding.port, text)),
+                  value: canonicalize(bound),
                 },
               },
               needs: {},
@@ -599,18 +636,20 @@ export function defineExactModelModule<const Key extends string>(
         })),
         {
           producer: item.finalizeProducer,
-          handler: ({ inputs }) => ({
-            outputs: {
-              request: {
-                kind: "inline" as const,
-                value: canonicalize(finalizeGenerationRequestDraft(
-                  item.spec.ports,
-                  inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`),
-                )),
+          handler: ({ inputs }) => {
+            const endpoint = endpoints[item.spec.key]!;
+            const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
+            endpoint.validateDraft(draft);
+            return {
+              outputs: {
+                request: {
+                  kind: "inline" as const,
+                  value: canonicalize(endpoint.sealRequest(draft.ports)),
+                },
               },
-            },
-            needs: {},
-          }),
+              needs: {},
+            };
+          },
         },
       ]),
       plannedNeeds: Object.values(endpoints).map((endpoint) => exactModelPlannedNeedFacet(endpoint)),

package/packages/project-context-node/README.md

@@ -6,6 +6,8 @@ It does not load Providers, install programs, inspect credentials or select serv
 
 1. `resolveProjectRoot({ workspaceRoot?, cwd? })` uses the explicit Workspace, otherwise the nearest
    `package.json` above cwd, otherwise cwd itself. Source and Run filenames do not choose the project.
+   After selecting the existing directory, it returns its real filesystem path so project and Source
+   paths use the same representation. Symlinks do not redirect the preceding parent-project search.
 2. `findRuntimeProfile(projectRoot)` reads only that project's `.hypit/runtime` file and resolves its
    path relative to the project. An entrypoint's explicit `--runtime` overrides this read for that invocation.
 3. The selected Runtime implementation interprets the Profile, including `dataRoot`, Credentials,

package/packages/project-context-node/src/project-context.ts

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
 async function nearestProjectPackageRoot(start: string): Promise<string | undefined> {
@@ -28,8 +28,10 @@ export async function resolveProjectRoot(options: {
   readonly cwd?: string;
 } = {}): Promise<string> {
   const start = resolve(options.workspaceRoot ?? options.cwd ?? process.cwd());
-  if (options.workspaceRoot !== undefined) return start;
-  return await nearestProjectPackageRoot(start) ?? start;
+  const selected = options.workspaceRoot !== undefined ? start : await nearestProjectPackageRoot(start) ?? start;
+  // Select through the caller's directory first; following a link before discovery
+  // could choose a different parent project. Source readers also return real paths.
+  return await realpath(selected);
 }
 
 /** Project package discovery cannot escape an already resolved project. */

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

@@ -96,11 +96,20 @@ execution earlier. ResourceStore I/O and Surface probes receive the cancellation
 ResourceStore must implement the port's cancellation behavior, including streaming reads and writes.
 
 Browser launch, source extraction, capture and encoding run in one disposable child process per
-render. At cancellation it receives a stop request and has up to five seconds to clean up. The owner
-then terminates any remaining process tree, including Chrome's separate process groups, and awaits
-the child exit before removing temporary files and returning failure. This also covers engine calls
-that do not accept a signal. The deadline initiates shutdown; the call may spend additional time
-closing resources. Completed Outputs in the Build remain available for a new Run and Build.
+render. After successful capture closes its resources, the child sends its completion message,
+flushes that message and disconnects IPC so it can exit normally. The owner awaits exit and drains
+diagnostics before returning. Normal completion does not enumerate or forcibly terminate processes.
+On failure, cleanup may be incomplete: the child reports the error and keeps IPC open while the owner
+discovers and terminates the remaining process tree, before it can become orphaned.
+
+At cancellation the child receives a stop request and has up to five seconds to clean up. A child
+that remains after cancellation or its completion message is forcibly terminated along with its discovered
+process tree, including Chrome's separate process groups. Cleanup problems are reported through the
+existing diagnostic callback; they do not discard a render already reported as completed. If process
+enumeration fails, the owner still terminates the direct child but cannot confirm descendant cleanup.
+This also covers engine calls that do not accept a signal. The deadline initiates shutdown; the call
+may spend additional time closing resources. Completed Outputs in the Build remain available for a
+new Run and Build.
 
 Deployments may additionally set `initializationTimeoutMs` or `frameTimeoutMs` when they have a
 measured stage deadline. Initialization here means initializing an already created browser session;

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

@@ -75,6 +75,7 @@ export async function runCaptureProcess(
     });
     let failure: Error | undefined;
     let completed = false;
+    let closed = false;
     let outputBytes = 0;
     let stderr = "";
     let diagnostics = Promise.resolve();
@@ -84,14 +85,27 @@ export async function runCaptureProcess(
       if (grace !== undefined) clearTimeout(grace);
       killing ??= (child.pid === undefined ? Promise.resolve() : killRenderTree(child.pid)).catch((error) => {
         if (!completed) failure = new Error(`${failure?.message ?? "Render cleanup failed"}; ${String(error)}`);
+        diagnostic({ level: "warning", message: `Render process-tree cleanup could not be confirmed: ${String(error)}` });
         child.kill("SIGKILL");
       });
       return killing;
     };
     const stop = (error: Error) => {
       failure ??= error;
+      if (closed) return;
       if (child.connected) child.send({ type: "abort", error: failure.message }, () => {});
-      grace ??= setTimeout(() => { void kill(); }, cleanupMs);
+      awaitExit();
+    };
+    const diagnostic = (value: ExecutionDiagnostic) => {
+      if (onDiagnostic === undefined) return;
+      diagnostics = diagnostics.then(() => onDiagnostic(value))
+        .catch((error) => stop(error instanceof Error ? error : new Error(String(error))));
+    };
+    const awaitExit = () => {
+      grace ??= setTimeout(() => {
+        diagnostic({ level: "warning", message: `Render process did not exit within ${cleanupMs} ms; terminating its remaining process tree` });
+        void kill();
+      }, cleanupMs);
     };
     const abort = () => stop(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
     signal.addEventListener("abort", abort, { once: true });
@@ -104,10 +118,7 @@ export async function runCaptureProcess(
       pipe?.setEncoding("utf8");
       pipe?.on("data", (text: string) => {
         log(Buffer.from(text), stream === "stderr");
-        if (onDiagnostic !== undefined && text.trim()) {
-          diagnostics = diagnostics.then(() => onDiagnostic({ stream, level: "info", message: text.trimEnd() }))
-            .catch((error) => stop(error instanceof Error ? error : new Error(String(error))));
-        }
+        if (text.trim()) diagnostic({ stream, level: "info", message: text.trimEnd() });
       });
     }
     child.on("message", (value: { type: string; event?: HyperframesRenderProgress; error?: string }) => {
@@ -117,13 +128,20 @@ export async function runCaptureProcess(
         stop(new Error(value.error));
       } else if (value.type === "completed" || value.type === "failed") {
         completed = value.type === "completed";
-        if (!completed) failure ??= new Error(value.error);
-        // The worker has finished cleanup. Terminate any leftover descendants before releasing capacity.
-        void kill();
+        if (completed) {
+          // Successful capture has closed its resources and will disconnect after this message.
+          awaitExit();
+        } else {
+          failure ??= new Error(value.error);
+          // Resource cleanup may itself have failed. Keep the worker alive until
+          // its remaining descendants have been discovered and terminated.
+          void kill();
+        }
       }
     });
     child.on("error", (error) => { failure ??= error; void kill(); });
     child.on("close", () => {
+      closed = true;
       if (grace !== undefined) clearTimeout(grace);
       signal.removeEventListener("abort", abort);
       void (killing ?? Promise.resolve()).then(async () => {

package/packages/provider-hyperframes-local/src/capture-worker.ts

@@ -3,15 +3,34 @@ import type { CaptureInput } from "./capture.js";
 
 const controller = new AbortController();
 const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+const disconnected = () => controller.abort(new Error("Render owner disconnected"));
+const report = (value: object) => {
+  if (process.connected) process.send?.(value, undefined, undefined, (error) => { if (error) controller.abort(error); });
+};
+const finish = (value: { type: "completed" } | { type: "failed"; error: string }) => {
+  // Failure can leave descendants behind. Keep the owner connected until it has
+  // discovered and stopped that tree, rather than orphaning it by exiting first.
+  if (value.type === "failed") { report(value); return; }
+  // Successful capture has closed its resources. Flush the result before closing our IPC handle;
+  // our own disconnect is not a cancellation by the owner.
+  process.off("disconnect", disconnected);
+  process.off("message", receive);
+  if (!process.connected) return;
+  process.send?.(value, undefined, undefined, (error) => {
+    if (error) { console.error(message(error)); process.exitCode = 1; }
+    if (process.connected) process.disconnect();
+  });
+};
 controller.signal.addEventListener("abort", () => {
-  process.send?.({ type: "stopping", error: message(controller.signal.reason) });
+  report({ type: "stopping", error: message(controller.signal.reason) });
 }, { once: true });
-process.on("message", (value: { type: "start"; input: CaptureInput } | { type: "abort"; error: string }) => {
+const receive = (value: { type: "start"; input: CaptureInput } | { type: "abort"; error: string }) => {
   if (value.type === "abort") { controller.abort(new Error(value.error)); return; }
   void captureStagedVisual(value.input, controller,
-    (event) => process.send?.({ type: "progress", event })).then(
-    () => process.send?.({ type: "completed" }),
-    (error) => process.send?.({ type: "failed", error: message(error) }),
+    (event) => report({ type: "progress", event })).then(
+    () => finish({ type: "completed" }),
+    (error) => finish({ type: "failed", error: message(error) }),
   );
-});
-process.on("disconnect", () => controller.abort(new Error("Render owner disconnected")));
+};
+process.on("message", receive);
+process.on("disconnect", disconnected);

package/packages/provider-hypihub/README.md

@@ -118,6 +118,9 @@ Resource identity with the same declared person-reference classification is uplo
 cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
 the mapping declares it as a resource-transport field and the upload session receives
 `is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+This covers reference images, reference videos, and first/last frames for every declared Seedance
+variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
+so omission does not enable detection or person-reference preparation.
 HypiHub stores the authored classification and prepares the applicable upstream person reference;
 this Provider does not detect faces or select an upstream private-avatar group.
 

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

@@ -41,7 +41,7 @@ function nonNegativeInteger(value: number, subject: string): number {
 function projectPath(root: string, path: string): string {
   const absolute = isAbsolute(path) ? resolve(path) : resolve(root, path);
   const relation = relative(resolve(root), absolute);
-  assert(relation === "" || (!relation.startsWith("..") && !isAbsolute(relation)),
+  assert(relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation)),
     `Build Result source ${path} is outside project ${resolve(root)}`);
   return (relation || ".").split(sep).join("/");
 }

package/packages/seedance/README.md

@@ -18,6 +18,20 @@ the author's literal, in whole seconds inside the model's declared range; measur
 with `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan is
 complete before it starts.
 
+## Reference audio
+
+The Seedance package rejects reference audio declared as `audio/mp4` or `audio/x-m4a`. Convert the
+audio to WAV or MP3 before using it; `media:ExtractAudio` produces WAV and can consume an upstream
+component's media output. Renaming a file or changing its declared media type is not conversion.
+
+Known imports are checked during Surface decoding. Future audio stays a graph input and is checked
+when its Blob arrives. The same rule applies to drafts, complete requests, planning and direct
+generation Producers. `sealSeedanceRequest` uses the endpoint's model-aware request builder;
+`seedanceComponent` and `seedanceDefinition.component` expose the same implementation.
+
+This checks the Blob's declared media type, not its bytes or codec. The selected Provider remains
+responsible for any additional service-specific input limits.
+
 ## Visual reference metadata
 
 Declare whether each image or video contains a person/avatar reference, including an AI-generated
@@ -37,10 +51,38 @@ Inspect the actual reference when deciding the value. For `FrameVideo`, use
 `first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
 inputs. A last-frame classification requires a last-frame input.
 
+| Supplied visual input | Authored attribute | Request port |
+| --- | --- | --- |
+| Each `Reference image={...}` | `person-reference` | `referenceImage` |
+| Each `Reference video={...}` | `person-reference` | `referenceVideo` |
+| `FrameVideo` first frame | `first-frame-person-reference` | `firstFrame` |
+| `FrameVideo` last frame | `last-frame-person-reference` | `lastFrame` |
+
+These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
+
+```xml
+<seedance:FrameVideo id="turn" model="fast" prompt={direction} duration="5"
+  first-frame={presenter.image} first-frame-person-reference="true"
+  last-frame={empty-room.image} last-frame-person-reference="false"/>
+```
+
+Classify the material supplied to this request, not the intended result. A dance video with a person
+still needs `true` when used only for motion, even if the prompt asks for a different performer.
+An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
+excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
+Identity and action direction remain in the prompt and references.
+
+The SVML author declares this parameter on each reference input. Admitted files, generated
+images/videos and reused Results use the same attributes. For a future output, declare the intended
+reference classification explicitly; if its contents are uncertain, generate and inspect that
+material before using it downstream.
+
 The model's media ports carry this as `fields.personReference`. Providers interpret it through their
 service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
 `is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
 request. A project Provider maps it according to its own API.
+Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
+as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
 
 Video references can carry motion or camera behavior while image references carry the target
 appearance. Request duration and reference-clip duration are different limits. Check the selected

package/packages/seedance/src/index.ts

@@ -1,7 +1,4 @@
-import {
-  sealGenerationPortRequest,
-  sealGenerationPortTable,
-} from "@hypit/generation";
+import { sealGenerationPortTable } from "@hypit/generation";
 import type {
   GenerationPortTable,
   GenerationPortValue,
@@ -12,6 +9,7 @@ import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/m
 import { defineExactModelModule } from "@hypit/model-kit";
 import { textTypes } from "@hypit/text";
 import type { ResourceId } from "@hypit/protocol";
+import { validateSeedanceInputs } from "./validation.js";
 
 export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;
 export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;
@@ -93,7 +91,7 @@ export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>>
 export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;
 
 export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {
-  return sealGenerationPortRequest(seedancePorts[model], ports);
+  return seedanceEndpointsByModel[model].sealRequest(ports);
 }
 
 const seedanceBaseDefinition = defineExactModelModule({
@@ -110,6 +108,7 @@ const seedanceBaseDefinition = defineExactModelModule({
       : `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
     producerName: `request-${model}`,
     ports: seedancePorts[model],
+    validateInputs: validateSeedanceInputs,
   })),
 });
 
@@ -327,23 +326,7 @@ export const seedanceMarkupSurfaces = [
 /** The duration is an author literal on every Seedance Surface, so the manifest is the exact-model module's own. */
 export const seedanceManifest = seedanceBaseDefinition.manifest;
 
-const referenceAudioProducers = new Set(Object.values(seedanceEndpoints)
-  .map((endpoint) => endpoint.mediaBindings["referenceAudio"]!.producer.name));
-
-export const seedanceComponent = {
-  ...seedanceBaseDefinition.component,
-  producers: seedanceBaseDefinition.component.producers.map((facet) =>
-    referenceAudioProducers.has(facet.producer.name) ? {
-      ...facet,
-      handler: (context: Parameters<typeof facet.handler>[0]) => {
-        const artifact = context.inputs.artifact?.value;
-        if (artifact?.kind === "blob" && ["audio/mp4", "audio/x-m4a"].includes(artifact.mediaType)) {
-          throw new Error("Seedance reference audio does not accept m4a; convert to wav or mp3");
-        }
-        return facet.handler(context);
-      },
-    } : facet),
-};
+export const seedanceComponent = seedanceBaseDefinition.component;
 export const seedanceDefinition = seedanceBaseDefinition;
 
 export {

package/packages/seedance/src/surface.ts

@@ -23,6 +23,7 @@ import type {
 import { createSeedanceAssembledGenerationFragment } from "./fragment.js";
 import { seedanceEndpoints, seedancePorts } from "./index.js";
 import type { SeedanceModel, SeedancePortMap } from "./index.js";
+import { validateSeedanceAudio } from "./validation.js";
 
 type MediaInput = {
   readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";
@@ -109,9 +110,7 @@ function mediaReference(
   if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith(`${role}/`))) {
     throw new Error(`${subject} must reference ${role} media`);
   }
-  if (value !== undefined && value.kind === "blob" && role === "audio" && ["audio/mp4", "audio/x-m4a"].includes(value.mediaType)) {
-    throw new Error(`${subject} references m4a audio, which Seedance does not accept; convert to wav or mp3 and admit that file`);
-  }
+  if (value?.kind === "blob" && role === "audio") validateSeedanceAudio(value, subject);
   return reference;
 }
 

package/packages/seedance/src/validation.ts

@@ -0,0 +1,16 @@
+import type { GenerationRequestDraft } from "@hypit/generation";
+import type { BlobRef } from "@hypit/protocol";
+
+/** Seedance's reference-audio rule, shared by known imports and request assembly. */
+export function validateSeedanceAudio(artifact: BlobRef, subject = "Seedance reference audio"): void {
+  if (artifact.mediaType === "audio/mp4" || artifact.mediaType === "audio/x-m4a") {
+    throw new Error(`${subject} does not accept m4a; convert the reference audio to WAV or MP3 before using it (media:ExtractAudio produces WAV)`);
+  }
+}
+
+/** Missing references in a draft remain graph inputs; only supplied audio is checked. */
+export function validateSeedanceInputs(request: GenerationRequestDraft): void {
+  for (const value of request.ports.referenceAudio ?? []) {
+    if (typeof value === "object" && value.role === "audio") validateSeedanceAudio(value.artifact);
+  }
+}

package/packages/studio/src/server.ts

@@ -2,7 +2,7 @@ import { watch } from "node:fs";
 import type { FSWatcher } from "node:fs";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
@@ -207,7 +207,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       if (isAbsolute(patch.path)) throw new Error("Studio patches must use workspace-relative paths.");
       const absolute = resolve(options.workspaceRoot, patch.path);
       const rel = relative(options.workspaceRoot, absolute);
-      if (rel.startsWith("..") || isAbsolute(rel) || !allowedSourceFiles.has(absolute)) {
+      if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) || !allowedSourceFiles.has(absolute)) {
         throw new Error(`Studio cannot write source file ${patch.path}.`);
       }
       if (!Number.isInteger(patch.range.start) || !Number.isInteger(patch.range.end)

package/packages/workspace-fs-node/src/workspace.ts

@@ -2,7 +2,7 @@ import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readFile, realpath, stat } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 
 import type {
   Awaitable,
@@ -20,7 +20,7 @@ import type { BlobRef } from "@hypit/protocol";
 
 function isWithin(root: string, path: string): boolean {
   const relation = relative(root, path);
-  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
 
 export type NodeFilesystemExternalSource = {