@hypit/hypit 0.1.4 → 0.1.5

package/packages/ranking-studio/README.md

@@ -2,6 +2,10 @@
 
 Hypit Studio Companion for the Ranking module's Column, Tier and Top Three surfaces.
 
+Each surface has separate visual and audio Companion declarations in this one
+package. Film chooses `.visual` and `.audio` independently; selecting the visual
+output does not connect its sound.
+
 The root lane represents the board; `attachments` expose reveal or activation
 events on a detail lane. Both use Studio's ordinary item selection and overlap
 behavior. Their time ranges remain the authored event ranges.
@@ -12,3 +16,17 @@ entering or settled icon selects the same detail entity. The board and preset
 items without a detail event remain associated with the root. Studio measures
 the visible parts at the current frame; the Companion does not duplicate motion
 geometry or infer identities from rendered ID strings.
+
+The audio Companion presents a `Ranking Sounds` lane. Each emitted clip shows
+its item and phase (`Appear` or `Move`) with a waveform. It joins the board's
+exported `.events` to the rendered audio clips by exact event identity, so a
+phase without a supplied sound contributes no audio item. `Move` is the motion
+into the board, not an exit sound.
+
+Selecting a sound exposes the event trigger as a read-only fact and the shared
+Ranking Style's sound gains and fade-in length as editable fields. Gain is
+displayed as a percentage; edits write the original linear gain to the Style's
+recipe. These fields affect every matching event using that recipe. Event
+timing comes from the Ranking animation; changing the visual event timing
+updates its sound too. The visual Companion owns layout and motion controls,
+while the audio Companion owns the sound controls.

package/packages/ranking-studio/src/index.ts

@@ -1,7 +1,8 @@
 import { openFontStudioFields } from "@hypit/fonts-open/studio";
 import { rankingMarkupSurfaces, rankingModuleRef, rankingTypes } from "@hypit/ranking";
-import type { RankingProgram, RankingSchedule } from "@hypit/ranking";
+import type { RankingProgram, RankingSchedule, RankingSoundEventPlan } from "@hypit/ranking";
 import { compositionTypes } from "@hypit/composition";
+import type { AudioTrack } from "@hypit/composition";
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
 import { artifactPreview, authoredChildFor, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
 
@@ -13,9 +14,12 @@ const frameParameters: readonly StudioSourceBindingDeclaration[] = [
   ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
 ];
 
-function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style") {
-  return rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
-    ?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+const soundProperties = new Set(["appear-gain", "move-gain", "sound-fade-frames"]);
+
+function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style", audio = false) {
+  return (rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
+    ?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [])
+    .filter((property) => soundProperties.has(property.name) === audio);
 }
 
 function title(name: string): string {
@@ -92,11 +96,11 @@ function rankingInspector(surface: "column-style" | "tier-style" | "top-three-st
   })];
 }
 
-function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioSourceBindingDeclaration {
+function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style", audio = false): StudioSourceBindingDeclaration {
   return {
     name: "style",
-    referenced: [fontInspector.binding],
-    recipe: { through: ["recipe"], bindings: rankingProperties(surface).map(({ name, schema, fallback }) => ({
+    ...(audio ? {} : { referenced: [fontInspector.binding] }),
+    recipe: { through: ["recipe"], bindings: rankingProperties(surface, audio).map(({ name, schema, fallback }) => ({
       name,
       schema,
       ...(fallback === undefined ? {} : { fallback }),
@@ -159,10 +163,57 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
 
 const commonBindings: readonly StudioSourceBindingDeclaration[] = [
   { name: "frame", referenced: frameParameters },
-  { name: "appear-sound" },
-  { name: "move-sound" },
 ];
 
+function projectRankingAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const events = requiredSurfaceValue(context, "events") as RankingSoundEventPlan;
+  const byId = new Map(events.events.map((event) => [event.id, event]));
+  const clips = new Map((context.track.value as AudioTrack).clips.map((clip) => [clip.id, clip]));
+  const boardId = context.placement?.id ?? context.track.outputRef;
+  return context.spans.map((span): StudioEntityDraft => {
+    const event = byId.get(span.id);
+    const clip = clips.get(span.id);
+    if (event === undefined || clip === undefined) throw new Error(`Ranking sound ${span.id} has no event or audio clip.`);
+    const child = authoredChildFor(context, event.itemId, [rankingTypes.itemSpec, rankingTypes.textItemShell]);
+    const label = child?.attributes.label ?? event.itemId;
+    const phase = event.kind === "appear" ? "Appear" : "Move";
+    return {
+      id: `${context.track.outputRef}:entity:${event.id}`,
+      authoredId: boardId,
+      display: { title: `${label} · ${phase}`, layers: [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")] },
+      startFrame: span.startFrame, endFrameExclusive: span.endFrameExclusive, stackOrder: span.stackOrder,
+      ...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
+      presentation: { entity: "ranking-sound", chrome: "standard" },
+      inspector: [{
+        id: "trigger", label: "Trigger", domain: "when", page: { id: "sound", label: "Sound" }, section: { id: "event", label: "Event" },
+        value: `${label} · ${phase} · ${event.frame}f`,
+        summary: "Follows the Ranking item's animation event. Adjust its visual timing to move the sound with it.",
+      }],
+    };
+  });
+}
+
+function rankingAudioCompanion(surface: "column" | "tier" | "top-three"): StudioTrackCompanion {
+  const style = `${surface}-style` as const;
+  return {
+    id: `${surface}-audio`, role: "track",
+    output: { type: compositionTypes.audioTrack, surface, modules: [rankingModuleRef] },
+    family: "audio", tone: "green", label: "Ranking Sounds", icon: "waveform",
+    lane: { heightPx: 48 }, requiredValues: ["events"],
+    bindings: [{ name: "appear-sound" }, ...(surface === "top-three" ? [] : [{ name: "move-sound" }]), rankingStyle(style, true)],
+    inspector: rankingProperties(style, true).map((property) => ({
+      binding: `style.${property.name}`, label: property.name === "sound-fade-frames" ? "Fade In" : title(property.name),
+      ...rankingInspectorPlacement[property.name as keyof typeof rankingInspectorPlacement],
+      control: "number",
+      ...(property.name === "sound-fade-frames"
+        ? { unit: "f", number: { minimum: 0, step: 1 } }
+        : { unit: "%", number: { scale: 100, minimum: 0, step: 1 } }),
+      summary: "Shared by every matching sound event using this Ranking style.",
+    })),
+    project: projectRankingAudio,
+  };
+}
+
 const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParameters
   .filter(({ writable }) => writable === true)
   .map(({ name }) => ({
@@ -171,6 +222,7 @@ const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParamete
   }));
 
 export const rankingStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  ...(["column", "tier", "top-three"] as const).map(rankingAudioCompanion),
   {
     id: "column", role: "track",
     output: { type: compositionTypes.visualTrack, surface: "column", modules: [rankingModuleRef] },

package/packages/render-hyperframes/README.md

@@ -1,14 +1,14 @@
 # `@hypit/render-hyperframes`
 
-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 accepts `timeline={program.timeline}` and projects its complete ProgramSpace.
+Its Fragment receives that range as `space`; rendering works with partial, overlapping or absent
+semantic coverage through the same frame and audio pipeline.
 
 Explicit author and capability boundary for final HyperFrames video rendering.
 
 The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
 
-1. obtain the `ProgramSpace` from the semantic input and compile the referenced `Composition` into a `HyperframesDocument`;
+1. obtain the `ProgramSpace` from the Timeline input and compile the referenced `Composition` into a `HyperframesDocument`;
 2. request a silent, frame-exact `RenderedVisual`;
 3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
 4. request an exact 48 kHz `TimelineAudio`;
@@ -29,7 +29,7 @@ Core therefore sees three real byte-operation Needs, not one opaque mega-render.
 contiguous or interleaved chunks, retries and image-sequence assembly remain inside the selected
 visual Endpoint; clip decoding/mixing remains inside the audio Endpoint; container encoding remains
 inside the mux Endpoint. A single Provider package may implement all three locally, or a Runtime may
-bind them to separate Lambda-backed Endpoints. The author still sees one `<render:Video>` result.
+bind them to separate compatible Endpoints. The author still sees one `<render:Video>` result.
 
 Film is not a dependency of this author meaning. Any package that produces the common Composition
 contract can feed the render Surface. Conversely, targeting Composition never demands this package;
@@ -43,7 +43,7 @@ stream with the declared canvas, rational frame rate and frame count.
 Select a contiguous interval using zero-based, half-open frame bounds:
 
 ```xml
-<render:Video id="preview" composition={main.composition} semantic={speech.semantic}
+<render:Video id="preview" composition={main.composition} timeline={speech.timeline}
   start-frame="240" end-frame-exclusive="360"/>
 ```
 
@@ -54,5 +54,5 @@ Provider's Runtime configuration.
 
 In TypeScript, `hyperframesVisualRequest(document, { range })` constructs the visual request;
 `createRenderHyperframesFragment(true)` accepts a `MediaFrameRange` input and connects it to visual
-and audio requests. The AWS Lambda Provider currently declines range requests. Selection limits
+and audio requests. Provider support checks establish range support for other deployments. Selection limits
 final rendering work; it does not prune upstream generation dependencies.

package/packages/render-hyperframes/package.json

@@ -20,7 +20,7 @@
     "@hypit/media-pipeline": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/temporal-markup": "workspace:*"
   },

package/packages/render-hyperframes/src/component.ts

@@ -4,6 +4,7 @@ import type { ComponentPackage } from "@hypit/component-kit";
 import type { StoredValue } from "@hypit/protocol";
 
 import { hyperframesVisualRequest } from "./product.js";
+import type { HyperframesVisualRequest } from "./product.js";
 import { renderHyperframesCapabilities, renderHyperframesProducers } from "./manifest.js";
 
 /** Declares the visual Need. It contains no renderer, queue, credentials or deployment choice. */
@@ -26,7 +27,16 @@ export const renderHyperframesComponent = {
       return { constraints: {}, pendingInputs: plannedNeedInputs(state, step) };
     },
     present(specification) {
-      return { fields: {}, references: {} };
+      const request = specification.constraints as Partial<HyperframesVisualRequest>;
+      if (request.document === undefined) return { fields: {}, references: {} };
+      const { document, range } = request;
+      const startFrame = range?.startFrame ?? 0;
+      const endFrameExclusive = range?.endFrameExclusive ?? document.frameCount;
+      return { fields: {
+        width: [document.canvas.width], height: [document.canvas.height],
+        startFrame: [startFrame], endFrameExclusive: [endFrameExclusive],
+        frameRate: [`${document.frameRate.numerator}/${document.frameRate.denominator}`],
+      }, references: {} };
     },
   })),
 } satisfies ComponentPackage;

package/packages/render-hyperframes/src/fragment.ts

@@ -1,6 +1,7 @@
+import { timelineProducers, timelineTypes } from "@hypit/timeline";
 import { mediaTypes } from "@hypit/media";
 import { artifactTypes } from "@hypit/artifact";
-import { programSpaceTypes } from "@hypit/program-space";
+
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
 import { hyperframesProducers } from "@hypit/hyperframes";
@@ -17,14 +18,16 @@ export function createRenderHyperframesFragment(selectedRange = false) {
   return sealGraphFragment({
     inputs: [
       { name: "composition", type: compositionTypes.composition },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...(selectedRange ? [{ name: "range", type: mediaTypes.frameRange }] : []),
     ],
     operations: [
+      { id: "render-range", producer: timelineProducers.projectProgramSpace,
+        inputs: { track: input("timeline") }, result: { kind: "output", name: "space" } },
       {
         id: "compile-document",
         producer: hyperframesProducers.compile,
-        inputs: { composition: input("composition"), space: input("space") },
+        inputs: { composition: input("composition"), space: operation("render-range") },
         result: { kind: "output", name: "document" },
       },
       {
@@ -36,7 +39,7 @@ export function createRenderHyperframesFragment(selectedRange = false) {
       {
         id: "compile-audio-program",
         producer: mediaPipelineProducers.planAudio,
-        inputs: { composition: input("composition"), space: input("space") },
+        inputs: { composition: input("composition"), space: operation("render-range") },
         result: { kind: "output", name: "plan" },
       },
       {

package/packages/render-hyperframes/src/manifest.ts

@@ -2,7 +2,7 @@ import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { artifactDependency, artifactTypes } from "@hypit/artifact";
 import { mediaDependency, mediaTypes } from "@hypit/media";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import {
   hyperframesManifest,
   hyperframesModuleRef,
@@ -48,9 +48,9 @@ export const renderHyperframesMarkupSurfaces = [{
         { name: "video", type: artifactTypes.blob,
           summary: "The final muxed video Artifact, addressed as `<id>.video`." },
       ],
-      example: '<render:Video id="final" composition={main.composition} semantic={speech.semantic}/>',
+      example: '<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>',
       notes: [
-        "Supply id, composition and one time source: semantic or space. Write both frame bounds to select a range. The element is empty.",
+        "Supply id, composition and timeline. Write both frame bounds to select a range. The element is empty.",
         "The visual render, the audio render and the mux are three separate Needs, each realized by a Provider this package does not choose.",
         "The published Artifact carries no duration or lineage metadata, so a consumer that needs stream facts requests explicit media inspection.",
       ],
@@ -66,7 +66,7 @@ export const renderHyperframesManifest: ModuleManifest = {
     artifactDependency,
     mediaDependency,
     compositionDependency,
-    semanticTrackDependency,
+    timelineDependency,
     { module: hyperframesModuleRef },
     { module: mediaPipelineModuleRef },
   ],

package/packages/render-hyperframes/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { compositionTypes } from "@hypit/composition";
 import { mediaTypes, verifyMediaFrameRange } from "@hypit/media";
 import type {
@@ -25,7 +25,7 @@ function referenceAttribute(element: StructuredElement, name: string): string {
 
 export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
   const names = Object.keys(element.attributes).sort();
-  if (names.some((name) => !["composition", "id", "semantic", "space", "start-frame", "end-frame-exclusive"].includes(name))) {
+  if (names.some((name) => !["composition", "id", "timeline", "start-frame", "end-frame-exclusive"].includes(name))) {
     throw new Error(`${element.name} contains unsupported attributes`);
   }
   if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
@@ -40,7 +40,7 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
     || composition.type.name !== compositionTypes.composition.name) {
     throw new Error(`${element.name}.composition must reference Composition`);
   }
-  const time = createTemporalSpace({ id, element, ...resolveTemporalContext({ element, resolveReference }) });
+  const context = resolveTemporalContext({ element, resolveReference });
   const selected = element.attributes["start-frame"] !== undefined || element.attributes["end-frame-exclusive"] !== undefined;
   const frame = (name: string): number => {
     const text = stringAttribute(element, name);
@@ -53,13 +53,13 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
   const rangeId = `${id}.frame-range`;
   return {
     records: range === undefined ? [] : [{ id: rangeId, type: mediaTypes.frameRange, value: { kind: "inline", value: range }, range: element.range }],
-    components: [...time.components, {
+    components: [{
       id,
       fragment: fragment.id,
-      inputs: { composition: composition.ref, space: time.space.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
+      inputs: { composition: composition.ref, timeline: context.timeline.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
       outputs: { video: `${id}.video` },
       range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
   };
 };

package/packages/runtime/README.md

@@ -7,7 +7,7 @@ The package defines the small ports used by a runtime:
 * `BuildStore` keeps one active Build definition and its accepted facts until the Result is saved and active state is removed.
 * `OperationStore` keeps asynchronous external work only while the owning Build is active.
 * `PendingBuildStore` owns the short submission transaction before the Build becomes active.
-* `BuildExecutionStore` owns active scheduling facts, a stop request, the immutable decision, attention and shared capacity reservations.
+* `BuildExecutionStore` owns active scheduling facts, opaque Host execution choices, a stop request, the immutable decision, attention and shared capacity reservations.
 * `ResourceStore` is the transient byte gateway used during Provider execution.
 * `CredentialStore` resolves secrets outside source and build state.
 * `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.
@@ -37,3 +37,10 @@ Capacity claims describe occupancy; action rate budgets describe admissions over
 Operation holds its declared occupancy while Runtime manages the remote task. Its submit, poll and
 collect actions can have separate concurrency and rate limits. Waiting claims park until a resource
 release or their next eligible time; polling does not require rematerializing the whole Build.
+
+The local Host uses one code context per Build. `claim(owner, now, build)` limits an executor to its
+own work; `start` records launch, and `interrupt` concludes a lost executor after its owner confirms
+exit. These stores do not prescribe processes or module loading. They retain one active execution
+record, while components and Providers remain ordinary replaceable implementations.
+There is no turn-reclaim operation that makes a lost attempt runnable again. Result-writer ownership
+can be cleared independently so an already decided outcome can still be saved.

package/packages/runtime/src/execution.ts

@@ -10,7 +10,9 @@ export type BuildOutcome = "complete" | "failed" | "cancelled";
 
 export type BuildExecutionRequest = {
   readonly build: string;
-  /** Installed component packages loaded when a Worker takes an execution turn. */
+  /** Host-owned execution choices. Opaque to the graph and Core. */
+  readonly context?: import("@hypit/protocol").CanonicalValue;
+  /** Installed component packages loaded when this execution context starts. */
   readonly componentPackages: readonly string[];
   /** Exact project Result Repository selected at submission. */
   readonly result: BuildResultRepositoryLocation;
@@ -48,6 +50,8 @@ export type BuildResultWriteLease = BuildExecutionTurn;
  */
 export type BuildExecutionSnapshot = BuildExecutionRequest & {
   readonly createdAt: number;
+  /** An execution context has been assigned; losing it ends this attempt. */
+  readonly startedAt?: number;
   /** Absent when waiting for a resource release. */
   readonly wakeAt?: number;
   /** Only these Operations can advance the Build until their next outcome. */
@@ -79,10 +83,14 @@ export type BuildExecutionStore = {
   create(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<BuildExecutionSnapshot>;
   read(build: string): Promise<BuildExecutionSnapshot | undefined>;
   list(): Promise<readonly BuildExecutionSnapshot[]>;
+  /** Lightweight scheduling views; no Definition, Profile or Operation payloads are loaded. */
+  listUnstarted(): Promise<readonly string[]>;
+  listReady(now?: number): Promise<readonly string[]>;
   /** Atomically take one ready, undecided execution turn for this Worker owner. */
-  claim(owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
-  /** A new owning Worker clears turns left by the previous process; no external action is repeated here. */
-  reclaimTurns(now?: number): Promise<readonly string[]>;
+  claim(owner: string, now?: number, build?: string): Promise<BuildExecutionSnapshot | undefined>;
+  start(build: string, now?: number): Promise<BuildExecutionSnapshot>;
+  /** Conclude after the owner confirms this execution context has ended. Never repeats external work. */
+  interrupt(build: string, reason: string): Promise<BuildExecutionSnapshot>;
   /** An unobserved stop wakes the next turn immediately to finish the attempt. */
   releaseTurn(build: string, owner: string, wakeAt: number | undefined, operationWait?: readonly string[]): Promise<BuildExecutionSnapshot>;
   /** Freeze the one conclusion. An execution with a decision can never be claimed again. */
@@ -106,6 +114,8 @@ export type CommandExecutionReceipt = {
   readonly command: string;
   readonly status: "started" | "completed";
   readonly event?: CommandResult;
+  /** Current Provider-reported activity; discarded when this call completes. */
+  readonly activity?: { readonly endpoint: string; readonly progress: import("./operations.js").OperationProgress };
 };
 
 export type CommandExecutionBegin = {
@@ -119,6 +129,7 @@ export type CommandExecutionBegin = {
  */
 export type CommandExecutionStore = {
   begin(build: string, command: string): Promise<CommandExecutionBegin>;
+  reportProgress(build: string, command: string, activity: NonNullable<CommandExecutionReceipt["activity"]>): Promise<void>;
   complete(build: string, command: string, event: CommandResult): Promise<CommandExecutionReceipt>;
   list(build: string): Promise<readonly CommandExecutionReceipt[]>;
   removeBuild(build: string): Promise<void>;

package/packages/runtime/src/index.ts

@@ -14,7 +14,6 @@ export type * from "./capacity.js";
 export { capacityUnits } from "./capacity.js";
 export { buildExecutionActivity } from "./execution.js";
 export type * from "./execution.js";
-export type * from "./environment.js";
 export type * from "./operations.js";
 export { LocalBuildScheduler } from "./scheduler.js";
 export type * from "./submission.js";
@@ -22,3 +21,5 @@ export {
   isStreamingResourceStore,
 } from "./types.js";
 export type * from "./types.js";
+export type * from "./log.js";
+export { readExecutionLog } from "./log.js";

package/packages/runtime/src/log.ts

@@ -0,0 +1,51 @@
+/** Provider-authored diagnostic text suitable for users; never credentials or request bodies. */
+export type ExecutionDiagnostic = {
+  readonly level: "info" | "warning" | "error";
+  readonly message: string;
+  readonly stream?: "stdout" | "stderr";
+};
+
+export type ExecutionLogEvent = { readonly endpoint: string } & (
+  | { readonly kind: "started" | "completed" }
+  | { readonly kind: "failed"; readonly message: string }
+  | { readonly kind: "phase"; readonly phase: string }
+  | ({ readonly kind: "diagnostic" } & ExecutionDiagnostic)
+);
+
+export type ExecutionLogRecord = ExecutionLogEvent & {
+  readonly format: "hypit.execution-log@1";
+  readonly time: number;
+  readonly command: string;
+};
+
+export type ExecutionLogView = {
+  readonly records: readonly ExecutionLogRecord[];
+  readonly total: number;
+};
+
+/** Read a bounded tail without loading the whole log. Storage and transport remain caller-owned. */
+export async function readExecutionLog(chunks: AsyncIterable<Uint8Array>, limit: number): Promise<ExecutionLogView> {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("Log line count must be a positive integer");
+  const decoder = new TextDecoder();
+  const records: ExecutionLogRecord[] = [];
+  let pending = "";
+  let total = 0;
+  const consume = (line: string) => {
+    if (!line.trim()) return;
+    const record = JSON.parse(line) as ExecutionLogRecord;
+    if (record.format !== "hypit.execution-log@1") throw new Error("Unsupported execution log format");
+    records[total % limit] = record;
+    total++;
+  };
+  for await (const chunk of chunks) {
+    pending += decoder.decode(chunk, { stream: true });
+    let newline: number;
+    while ((newline = pending.indexOf("\n")) >= 0) {
+      consume(pending.slice(0, newline));
+      pending = pending.slice(newline + 1);
+    }
+  }
+  // A running writer may still be appending its last record; only complete lines are visible.
+  const offset = total > limit ? total % limit : 0;
+  return { records: [...records.slice(offset), ...records.slice(0, offset)], total };
+}

package/packages/runtime/src/types.ts

@@ -25,13 +25,6 @@ export type RuntimeRunnableCommand = {
 
 export type RuntimeResourceClaim = import("./capacity.js").CapacityResourceClaim;
 
-export type RuntimeWorkerRunOptions = {
-  readonly idlePollMs: number;
-  readonly signal?: AbortSignal;
-  /** Called after abandoned work is claimable and immediately before the claim loop starts. */
-  readonly ready?: () => void | Promise<void>;
-};
-
 export type RuntimePreparation = {
   readonly state: BuildState;
   readonly runnable: readonly RuntimeRunnableCommand[];
@@ -41,6 +34,10 @@ export type RuntimePreparation = {
 export type RuntimeExecutionContext = {
   /** Stable Run-local identity; two identical BuildRequests may still be distinct Builds. */
   readonly build: string;
+  /** Observational activity of this call; it never changes scheduling or Core facts. */
+  readonly reportProgress?: (activity: NonNullable<import("./execution.js").CommandExecutionReceipt["activity"]>) => Promise<void>;
+  /** Execution evidence; the Runtime owns persistence. Implementations keep logging failures out of Provider outcomes. */
+  readonly recordExecution?: (event: import("./log.js").ExecutionLogEvent) => Promise<void>;
   /** Release only the asynchronous Operation's occupancy after its remote end is confirmed. */
   readonly releaseOperationCapacity?: () => Promise<void>;
 };
@@ -72,7 +69,7 @@ export type RuntimeCommandExecutor = {
     state: BuildState,
     operation: OperationSnapshot,
   ): Promise<OperationSnapshot>;
-  advanceOperation?(operation: OperationSnapshot): Promise<OperationSnapshot>;
+  advanceOperation?(operation: OperationSnapshot, context?: RuntimeExecutionContext): Promise<OperationSnapshot>;
   /** Validate an already received result without invoking a Producer or contacting an Endpoint. */
   acceptOperation?(state: BuildState, operation: OperationSnapshot): Promise<CommandResult | undefined>;
 };

package/packages/runtime-host-node/README.md

@@ -23,3 +23,33 @@ over a graph state, deterministic Producers, validators and temporary Resources;
 Endpoint selection, handlers and concurrency for that disposable session private and returns the evaluated
 state. This is an execution boundary, not a second Runtime Profile, Build type, cross-Build scheduler or
 preview registry.
+
+`RuntimeHostControl.logs(build, lines)` optionally exposes a bounded tail of active Build evidence.
+Finished logs belong to `BuildResultManifest.executionLog` and are read through the project's Repository;
+reading a finished log needs no Runtime or execution Provider. Runtime process logs keep their separate
+process-control operation.
+
+`prepare`, `preflight`, `doctor` and Program lifecycle operations accept explicit Endpoint instance
+names. Build preflight uses resolved Endpoints, not every Provider offering the capability. Omitting
+a scope retains whole-Profile inspection or preparation.
+
+`prepareHostPackages` keeps exact releases in separate ordinary npm installations below the Host
+package home. `HostPackageProgress.logPath` identifies live and retained npm output; failures include
+that path. npm owns each installation's dependency tree and lockfile. No parallel package inventory is
+maintained. `RuntimeInvocationObservation` passes direct-call progress and diagnostics through the
+same Provider callbacks used in Builds, without giving immediate calls durable Operation semantics.
+
+## Execution choices and lifetime
+
+`createRuntime({ endpoints })` scopes a submission to the selected Endpoint instances. The local Host
+records those choices and its project package root with the active execution request. Its long-lived
+Worker supervises carriers with independent per-Build module and registry contexts. Managed
+Programs remain independently warm. `runWorker` accepts an internal carrier entry point; execution
+readiness and Endpoint capacity are independent of the number of unfinished Builds. Other Hosts own
+their choice of code-loading and physical execution mechanisms.
+
+Submission clients use `const controller = await host.controller(); await controller.worker.up()`
+to start execution, then `const runtime = await host.createRuntime(); await runtime.build(request)`
+to submit work. `RuntimeHostExecution` does not run a second embedded Worker loop. A local carrier
+may stop accepting new Builds and drain; its assigned Builds stay in place and all carriers continue
+using the same resource accounting. Process policy belongs to the local Runtime, not this Host ABI.

package/packages/runtime-host-node/package.json

@@ -11,6 +11,7 @@
     "@hypit/build-result": "workspace:*",
     "@hypit/build-result-kit": "workspace:*",
     "@hypit/driver-node": "workspace:*",
+    "@hypit/package-loader-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-kit": "workspace:*",