@hypit/hypit 0.1.4 → 0.1.6

package/packages/driver-node/src/driver.ts

@@ -337,6 +337,22 @@ export class NodeDriver {
     operation: OperationSnapshot,
     registration: EndpointRegistration,
     runtimeContext: RuntimeExecutionContext,
+  ): Promise<OperationSnapshot> {
+    const result = await this.#advanceOperationStep(operation, registration, runtimeContext);
+    if (result.status === "failed" && operation.status !== "failed") {
+      await runtimeContext.recordExecution?.({ endpoint: operation.endpoint, kind: "failed", message: result.failure!.message });
+    } else if (result.completion !== undefined && operation.completion === undefined) {
+      await runtimeContext.recordExecution?.({ endpoint: operation.endpoint, kind: "completed" });
+    } else if (result.progress?.phase !== undefined && result.progress.phase !== operation.progress?.phase) {
+      await runtimeContext.recordExecution?.({ endpoint: operation.endpoint, kind: "phase", phase: result.progress.phase });
+    }
+    return result;
+  }
+
+  async #advanceOperationStep(
+    operation: OperationSnapshot,
+    registration: EndpointRegistration,
+    runtimeContext: RuntimeExecutionContext,
   ): Promise<OperationSnapshot> {
     const operations = this.operations!;
     if (registration.kind !== "asynchronous") throw new Error("Operation Endpoint is not asynchronous");
@@ -358,6 +374,10 @@ export class NodeDriver {
         command: structuredClone(command), need: structuredClone(command.need),
         resources: this.#resourceStore(operation.build), operation: operation.id,
         credentials: await this.#endpointCredentials({ ...registration, credentials: operation.credentials ?? registration.credentials ?? {} }),
+        ...(runtimeContext.recordExecution === undefined ? {} : {
+          reportDiagnostic: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) =>
+            runtimeContext.recordExecution!({ endpoint: operation.endpoint, kind: "diagnostic", ...diagnostic }),
+        }),
         checkpoint: async (checkpoint: import("@hypit/endpoint-kit").EndpointCheckpoint) => {
           await operations.update(operation.id, { status: "pending", ...checkpoint,
             submission: "accepted", acknowledgedAt: operation.acknowledgedAt ?? Date.now(), wakeAt: Date.now(), progress: { phase: checkpoint.remoteEnded ? "collecting" : "submitted" } });
@@ -366,10 +386,12 @@ export class NodeDriver {
       };
       if (action === "submit") {
         await operations.update(operation.id, { status: "pending", submission: "started", progress: { phase: "submitting" } });
+        await runtimeContext.recordExecution?.({ endpoint: operation.endpoint, kind: "started" });
         return await endpoint.start(context);
       }
       const pollContext = { ...context, handle: structuredClone(operation.handle!) };
       if (action === "collect") {
+        await runtimeContext.recordExecution?.({ endpoint: operation.endpoint, kind: "phase", phase: "collecting" });
         if (endpoint.collect === undefined) throw new Error(`Endpoint ${registration.id} declared artifacts ready but has no collect action`);
         return await endpoint.collect(pollContext);
       }
@@ -418,13 +440,13 @@ export class NodeDriver {
     });
   }
 
-  async advanceOperation(operation: OperationSnapshot): Promise<OperationSnapshot> {
+  async advanceOperation(operation: OperationSnapshot, context?: RuntimeExecutionContext): Promise<OperationSnapshot> {
     if (operation.request === undefined) throw new Error(`Operation ${operation.id} has no stored request`);
     const selected = this.endpoints.resolve(operation.request.need);
     if (selected.status !== "resolved" || selected.registration.id !== operation.endpoint) {
       throw new Error(`Operation ${operation.id} cannot change its selected Endpoint ${operation.endpoint}`);
     }
-    return await this.#advanceOperation(operation, selected.registration, { build: operation.build });
+    return await this.#advanceOperation(operation, selected.registration, context ?? { build: operation.build });
   }
 
   async #execute(
@@ -464,21 +486,37 @@ export class NodeDriver {
       try {
         return await this.#executeEndpoint(state, executable, context);
       } catch (error) {
+        await context.recordExecution?.({ endpoint: executable.endpointId, kind: "failed", message: failureMessage(error) });
         throw new Error(
           `Endpoint ${executable.endpointId} failed ${executable.command.need.capability.name}: ${failureMessage(error)}`,
           { cause: error },
         );
       }
     }
+    let phase: string | undefined;
+    await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "started" });
     try {
       const result = await executable.registration.handler({
         command: structuredClone(executable.command),
         need: structuredClone(executable.command.need),
         resources: this.#resourceStore(context?.build),
         credentials: await this.#endpointCredentials(executable.registration),
+        reportProgress: async (progress) => {
+          await context?.reportProgress?.({ endpoint: executable.endpointId, progress });
+          if (progress.phase !== phase) {
+            phase = progress.phase;
+            await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "phase", phase });
+          }
+        },
+        ...(context?.recordExecution === undefined ? {} : {
+          reportDiagnostic: (diagnostic) => context.recordExecution!({ endpoint: executable.endpointId, kind: "diagnostic", ...diagnostic }),
+        }),
       });
-      return { status: "completed", event: await this.#endpointEvent(state, executable, result) };
+      const event = await this.#endpointEvent(state, executable, result);
+      await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "completed" });
+      return { status: "completed", event };
     } catch (error) {
+      await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "failed", message: failureMessage(error) });
       throw new Error(
         `Endpoint ${executable.endpointId} failed ${executable.command.need.capability.name}: ${failureMessage(error)}`,
         { cause: error },

package/packages/elevenlabs-speech/README.md

@@ -0,0 +1,27 @@
+# `@hypit/elevenlabs-speech`
+
+Exact model contract and author Surface for ElevenLabs Voice Design.
+
+`eleven_ttv_v3` creates an ordinary audio voice reference from a natural-language description of
+20 to 1000 characters and an authored speech sample of 100 to 1000 characters. The service returns
+several candidate previews; the Surface exposes the primary member of the shared `GeneratedAudioSet`
+as `<id>.reference`.
+
+It contains no API URL, credential, retry, queue or ElevenLabs wire encoding. Those belong to a
+Runtime Endpoint such as `@hypit/provider-hypihub`.
+
+```xml
+<import as="eleven" from="@hypit/elevenlabs-speech@1"/>
+
+<eleven:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</eleven:VoiceDesign>
+```
+
+`host.reference` is not a special identity record. It is a normal audio Resource, so the same
+accepted reference can be supplied anywhere an audio reference is accepted.
+
+Official API reference: <https://elevenlabs.io/docs/api-reference/text-to-voice/design>
+
+The Source import selects author syntax and exact model semantics only. The Runtime Profile
+independently selects the Provider that fulfils the capability.

package/packages/{provider-xiaomi-mimo → elevenlabs-speech}/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@hypit/provider-xiaomi-mimo",
+  "name": "@hypit/elevenlabs-speech",
   "version": "0.0.0-dev",
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
@@ -11,14 +11,11 @@
     "activation": "./src/activation.ts"
   },
   "dependencies": {
-    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/artifact": "workspace:*",
     "@hypit/generation": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/runtime": "workspace:*",
-    "@hypit/runtime-kit": "workspace:*"
-  },
-  "devDependencies": {
-    "@hypit/driver-node": "workspace:*",
-    "@hypit/mimo-speech": "workspace:*"
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
   }
 }

package/packages/elevenlabs-speech/src/activation.ts

@@ -0,0 +1,26 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeElevenLabsVoiceDesignSurface,
+  elevenLabsSpeechComponent,
+  elevenLabsSpeechDefinition,
+  elevenLabsSpeechManifest,
+  elevenLabsSpeechMarkupSurfaces,
+  elevenLabsSpeechModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: elevenLabsSpeechManifest }],
+  components: [elevenLabsSpeechComponent],
+  hostFacets: [
+    elevenLabsSpeechDefinition.hostFacet,
+    createMarkupSurfaceHostFacet({
+      module: elevenLabsSpeechModuleRef,
+      declaration: elevenLabsSpeechMarkupSurfaces.find((item) => item.name === "voiceDesign")!,
+      handler: decodeElevenLabsVoiceDesignSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;

package/packages/elevenlabs-speech/src/fragment.ts

@@ -0,0 +1,11 @@
+import { createExactModelPrimaryGenerationFragment } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+
+/** Model result projection over the same graph-native request assembly as every exact model. */
+export function createElevenLabsSpeechAudioFragment(
+  endpoint: ExactModelEndpoint,
+  mediaInputs: readonly ExactModelMediaInput[] = [],
+  textInputs: readonly ExactModelTextInput[] = [],
+) {
+  return createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, textInputs);
+}

package/packages/elevenlabs-speech/src/index.ts

@@ -0,0 +1,111 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationRequestDraft, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const elevenLabsSpeechModuleRef = { name: "@hypit/elevenlabs-speech", version: "1" } as const;
+export const elevenLabsSpeechModels = ["eleven_ttv_v3"] as const;
+export type ElevenLabsSpeechModel = typeof elevenLabsSpeechModels[number];
+
+// ElevenLabs documents a 100 to 1000 character preview text. The port vocabulary
+// carries the ceiling; the floor is stated to authors and enforced by the service.
+const spokenText = { kind: "text", maxChars: 1000 } as const;
+// Voice descriptions have their own documented 20 to 1000 character bounds.
+const instruction = { kind: "text", maxChars: 1000 } as const;
+
+function table(model: ElevenLabsSpeechModel): GenerationPortTable {
+  return sealGenerationPortTable({
+    model,
+    result: "audio",
+    ports: [
+      { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+      { name: "voiceDescription", value: instruction, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const elevenLabsSpeechPorts: Readonly<Record<ElevenLabsSpeechModel, GenerationPortTable>> = {
+  "eleven_ttv_v3": table("eleven_ttv_v3"),
+};
+
+export function sealElevenLabsSpeechRequest(
+  model: ElevenLabsSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(elevenLabsSpeechPorts[model], ports);
+}
+
+export function sealElevenLabsSpeechRequestDraft(
+  model: ElevenLabsSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+) {
+  return sealGenerationRequestDraft(elevenLabsSpeechPorts[model], ports);
+}
+
+const base = defineExactModelModule({
+  module: elevenLabsSpeechModuleRef,
+  endpoints: ([
+    ["voiceDesign", "eleven_ttv_v3", "ElevenLabsVoiceDesignRequest"],
+  ] as const).map(([key, model, requestTypeName]) => ({
+    key,
+    requestTypeName,
+    producerName: `request-${model}`,
+    ports: elevenLabsSpeechPorts[model],
+  })),
+});
+
+export const elevenLabsSpeechEndpoints = base.endpoints;
+
+const spokenAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this speech request and prefixes the binding it publishes.",
+  },
+  {
+    name: "speech",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge whose exact words are spoken.",
+    accepts: [textTypes.text],
+  },
+];
+
+const referencePort: readonly SurfacePortVocabulary[] = [{
+  name: "reference",
+  type: artifactTypes.blob,
+  summary: "The designed voice reference, addressed as `<id>.reference`.",
+}];
+
+export const elevenLabsSpeechMarkupSurfaces = [
+  {
+    name: "voiceDesign", tag: "VoiceDesign", mode: "structured",
+    outputs: [elevenLabsSpeechEndpoints.voiceDesign.draftType],
+    vocabulary: {
+      summary: "Creates a reusable voice reference from a natural-language voice description.",
+      attributes: spokenAttributes,
+      ports: referencePort,
+      text: "The element's own text is the voice description and is required.",
+      example: `<eleven:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</eleven:VoiceDesign>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The spoken sample must be between 100 and 1000 characters.",
+        "The voice description must be between 20 and 1000 characters.",
+        "The result is an ordinary audio Resource that can be supplied anywhere an audio reference is accepted.",
+      ],
+    },
+  },
+] as const;
+
+export const elevenLabsSpeechManifest = { ...base.manifest } as const;
+export const elevenLabsSpeechComponent = base.component;
+export const elevenLabsSpeechDefinition = { ...base, manifest: elevenLabsSpeechManifest };
+
+export { createElevenLabsSpeechAudioFragment } from "./fragment.js";
+export { decodeElevenLabsVoiceDesignSurface } from "./surface.js";

package/packages/elevenlabs-speech/src/surface.ts

@@ -0,0 +1,167 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding } from "@hypit/generation";
+import type { GenerationMediaPort } from "@hypit/generation";
+import { exactModelMediaInputNames, exactModelTextInputName } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+import type { CanonicalValue } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+
+import { createElevenLabsSpeechAudioFragment } from "./fragment.js";
+import { elevenLabsSpeechEndpoints, sealElevenLabsSpeechRequestDraft } from "./index.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function attributes(element: StructuredElement, required: readonly string[]): void {
+  const allowed = new Set(required);
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.has(name));
+  if (unknown.length > 0 || required.some((name) => element.attributes[name] === undefined)) {
+    throw new Error(`${element.name} requires ${required.join(", ")}`);
+  }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function referencePath(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  return value.path;
+}
+
+function resolved(
+  element: StructuredElement,
+  name: string,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const path = referencePath(element, name);
+  const value = resolveReference(path);
+  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+  return value;
+}
+
+function speechText(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  if (!sameType(reference.type, textTypes.text)) throw new Error(`${subject} must reference Text`);
+  const value = reference.record?.value;
+  if (value !== undefined) {
+    if (value.kind !== "inline") throw new Error(`${subject} has an invalid authored Text value`);
+    verifyText(value.value);
+  }
+  return reference;
+}
+
+
+function body(element: StructuredElement, required: boolean): string | undefined {
+  if (element.children.some((child) => child.kind === "element")) {
+    throw new Error(`${element.name} accepts instruction text only`);
+  }
+  const lines = element.children.map((child) => child.kind === "text" ? child.value : "").join("")
+    .replaceAll("\r\n", "\n").split("\n");
+  while (lines[0]?.trim() === "") lines.shift();
+  while (lines.at(-1)?.trim() === "") lines.pop();
+  const indents = lines.filter((line) => line.trim()).map((line) => /^\s*/u.exec(line)?.[0].length ?? 0);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  const value = lines.map((line) => line.slice(indent).trimEnd()).join("\n").trim();
+  if (value.length === 0) {
+    if (required) throw new Error(`${element.name} requires a voice description in its body`);
+    return undefined;
+  }
+  return value;
+}
+
+function output(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  draft: ReturnType<typeof sealElevenLabsSpeechRequestDraft>,
+  outputName: "reference" | "audio",
+  text: readonly { readonly input: ExactModelTextInput; readonly source: SurfaceResolvedReference }[],
+  media: readonly { readonly input: ExactModelMediaInput; readonly source: SurfaceResolvedReference }[] = [],
+) {
+  const id = stringAttribute(element, "id");
+  const draftId = `${id}.draft`;
+  const records: Array<{
+    readonly id: string;
+    readonly type: SurfaceResolvedReference["type"];
+    readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+    readonly range: StructuredElement["range"];
+  }> = [{
+    id: draftId,
+    type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue },
+    range: element.range,
+  }];
+  const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {
+    draft: { kind: "record", id: draftId },
+  };
+  for (const item of text) inputs[exactModelTextInputName(item.input.name)] = item.source.ref;
+  for (const item of media) {
+    const binding = endpoint.mediaBindings[item.input.port];
+    if (binding === undefined) throw new Error(`${endpoint.ports.model} has no media port ${item.input.port}`);
+    const port = generationPort(endpoint.ports, item.input.port);
+    if (port.value.kind !== "media") throw new Error(`${endpoint.ports.model} port ${item.input.port} is not media`);
+    const names = exactModelMediaInputNames(item.input.name);
+    const bindingId = `${id}.${item.input.name}.binding`;
+    records.push({
+      id: bindingId,
+      type: binding.type,
+      value: {
+        kind: "inline",
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: "audio" }) as unknown as CanonicalValue,
+      },
+      range: element.range,
+    });
+    inputs[names.binding] = { kind: "record", id: bindingId };
+    inputs[names.artifact] = item.source.ref;
+  }
+  const fragment = createElevenLabsSpeechAudioFragment(
+    endpoint,
+    media.map((item) => item.input),
+    text.map((item) => item.input),
+  );
+  return {
+    records,
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs,
+      outputs: { audio: `${id}.${outputName}` },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+}
+
+function speechInput(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+) {
+  return {
+    input: { name: "speech", port: "text" },
+    source: speechText(resolved(element, "speech", resolveReference), `${element.name}.speech`),
+  } as const;
+}
+
+export const decodeElevenLabsVoiceDesignSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech"]);
+  return output(
+    element,
+    elevenLabsSpeechEndpoints.voiceDesign,
+    sealElevenLabsSpeechRequestDraft("eleven_ttv_v3", { voiceDescription: [body(element, true)!] }),
+    "reference",
+    [speechInput(element, resolveReference)],
+  );
+};

package/packages/endpoint-kit/README.md

@@ -13,6 +13,12 @@ import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit
 import { generationTypes, compileWireRequest, sealGeneratedImageSet } from "@hypit/hypit/generation";
 ```
 
+The shipped [project Provider example](../../examples/provider-package/README.md) follows an image
+request through configuration, support, upload, submission, receipt, polling, collection and pricing.
+It uses an explicitly illustrative service protocol and imports only public SDK subpaths.
+This SDK also exports `canonicalize`, `BlobRef`, `ResourceId`, `credentialRef` and
+`isStreamingResourceStore` for Providers that construct stored results or use streaming resource IO.
+
 For an existing model, name its exact versioned Capability and expected result Type. Map its request
 ports into the service's wire format; the Provider need not import the model's implementation.
 `@hypit/hypit/generation` supplies the common generated-media values and optional wire-mapping helpers.
@@ -29,6 +35,13 @@ without changing Core demand. Each resource declares a `limit` and optional `uni
 A capability may add `resources` and a pure `unitsForRequest(request)` resolver for quantities of
 already declared resources. Runtime admits all claims atomically for one `fulfill-need` Command.
 
+A long immediate call can report its current activity with
+`await context.reportProgress?.({ phase: "processing", completed: 12, total: 40, unit: "items" })`.
+The Provider chooses meaningful phases and quantities and reports non-secret, human-readable facts.
+The Runtime attaches them to the currently executing Command; they do not change its outcome,
+scheduling or Core facts. Completion clears the live activity. Direct callers may omit the callback.
+For asynchronous work, return `progress` in the existing pending outcome instead.
+
 Asynchronous execution moves forward through `start`, `poll`, and optional `collect`. `start` returns
 a task handle; `pending` means an acknowledged task is still running. `ready` records remote completion
 and hands its artifacts to `collect`, allowing download capacity to differ from task capacity.
@@ -109,3 +122,14 @@ represented by a semantic `pendingInputs` slot instead. A Provider may use the s
 media role to enforce support limits, but it never receives graph traversal rules or future bytes.
 It returns either `supported`, or `unsupported` with the Provider's reason. Selection infrastructure
 preserves that reason without interpreting request fields or maintaining a central limitation table.
+
+An Endpoint can additionally emit explicit, non-secret diagnostics:
+
+```ts
+await context.reportDiagnostic?.({ level: "info", message: "Encoder initialized" });
+```
+
+The Runtime binds each message to this call's Build, Command and Endpoint and owns persistence.
+The Provider does not select a log path or Result repository. Messages describe operational evidence;
+credentials, request bodies and opaque vendor payloads remain private. `reportProgress` continues to
+report current activity; repeated counters are not an append-only log. Phase names belong to the Provider.

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

@@ -20,7 +20,9 @@ import type {
 } from "@hypit/runtime";
 import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
 
-export type { CanonicalValue, CapabilityRef, ModuleRef, StoredValue, TypeRef } from "@hypit/protocol";
+export { canonicalize } from "@hypit/protocol";
+export type { BlobRef, CanonicalValue, CapabilityRef, ModuleRef, ResourceId, StoredValue, TypeRef } from "@hypit/protocol";
+export { credentialRef, isStreamingResourceStore } from "@hypit/runtime";
 export type {
   CapacityResourceClaim,
   CredentialAcquisition,
@@ -97,6 +99,10 @@ export type EndpointInvocationContext = {
   readonly resources: ResourceStore;
   /** Only slots explicitly declared by this configured Endpoint instance are present. */
   readonly credentials: Readonly<Record<string, EndpointCredential>>;
+  /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
+  readonly reportDiagnostic?: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) => Promise<void>;
+  /** Report non-secret activity of a long local call without creating a remote Operation. */
+  readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 
 export type ImmediateEndpointHandler = (

package/packages/film/README.md

@@ -1,8 +1,7 @@
 # `@hypit/film`
 
-The Surface accepts `semantic={speech.semantic}` for performance time or `space={animation}` for an
-authored ProgramSpace. Its Fragment receives `space` directly; rendering does not require Script
-or prepared performance media. Both time sources use the same frame and audio pipeline.
+The Surface, Fragment and assembly Producers receive the same Timeline through a `timeline` input.
+Partial, overlapping or absent semantic coverage all use that complete range.
 
 Official package-owned assembly layer between peer Tracks and the generic Composition waist.
 Film is an ordinary author component and an optional Target, not a Core root or a privileged video
@@ -21,9 +20,9 @@ belongs to each Present's absolute stacking key.
 
 The official Structured Surface validates an imported generic SVS Recipe into a nominal
 `FilmProgram`, receives CanvasSpace and the selected time source through separate explicit edges,
-projects ProgramSpace when that source is a SemanticTrack, type-checks
+passes the Timeline directly, type-checks
 each `<film:Track source={...}/>` reference and generates the finite fold. CanvasSpace is the only
-dimension truth, ProgramSpace is the only frame-rate truth, and FilmProgram owns only assembly
+dimension truth, Timeline is the only time-range truth, and FilmProgram owns only assembly
 identity and clear color.
 Child order is organizational: Track and Present identity, timing and absolute stacking remain in
 their own typed values. Final rendering is a separate author package and capability.
@@ -31,10 +30,16 @@ their own typed values. Final rendering is a separate author package and capabil
 For example, after the named inputs are declared:
 
 ```svml
-<film:Film id="main" canvas={vertical} semantic={speech.semantic}
+<import as="sound" from="@hypit/sound@1"/>
+<sound:Style id="voice-style"/>
+<sound:Track id="voice" timeline={speech.timeline}>
+  <sound:Use style={voice-style}/>
+</sound:Track>
+
+<film:Film id="main" canvas={vertical} timeline={speech.timeline}
   appearance={recipes.film.vertical}>
   <film:Track source={performance.visual}/>
-  <film:Track source={speech.audio}/>
+  <film:Track source={voice.audio}/>
   <film:Track source={coverage.visual}/>
   <film:Track source={captions.track}/>
   <film:Track source={music.track}/>

package/packages/film/package.json

@@ -16,7 +16,7 @@
     "@hypit/elaborator": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/markup": "workspace:*",

package/packages/film/src/component.ts

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CanvasSpace } from "@hypit/spatial";
 import type { AudioTrack, VisualTrack } from "@hypit/composition";
 import type { StoredValue } from "@hypit/protocol";
@@ -28,7 +28,7 @@ export const filmComponent = {
       handler: ({ inputs }) => ({
         outputs: { set: { kind: "inline", value: canonicalize(appendFilmVisualTrack(
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<VisualTrack>(inputs.track?.value, "VisualTrack"),
         )) } },
         needs: {},
@@ -39,7 +39,7 @@ export const filmComponent = {
       handler: ({ inputs }) => ({
         outputs: { set: { kind: "inline", value: canonicalize(appendFilmAudioTrack(
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<AudioTrack>(inputs.track?.value, "AudioTrack"),
         )) } },
         needs: {},
@@ -51,7 +51,7 @@ export const filmComponent = {
         outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(
           inline<FilmProgram>(inputs.program?.value, "FilmProgram"),
           inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
         )) } },
         needs: {},