@hypit/hypit 0.0.1 → 0.1.0

package/packages/spatial/src/surface.ts

@@ -0,0 +1,319 @@
+import type { AuthorValueRef, GraphFragment } from "@hypit/elaborator";
+import type { CanonicalValue } from "@hypit/protocol";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import type {
+  SurfaceComponentDraft,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+
+import {
+  anchoredFrameFragment,
+  aspectFrameFragment,
+  canvasFrameFragment,
+  frameEdgesFragment,
+} from "./fragment.js";
+import { spatialTypes } from "./manifest.js";
+import { spatialRegionTimeline } from "./region-timeline.js";
+import { assertSpatialPath, sealCanvasSpace, sealIntrinsicExtent, sealSpatialPoint } from "./geometry.js";
+import type {
+  AnchoredFrameProgram,
+  AspectFrameProgram,
+  FrameEdgesProgram,
+  SpatialAnchor,
+  SpatialLength,
+  SpatialPath,
+  SpatialPathCommand,
+  CanvasSpace,
+} from "./types.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 exact(element: StructuredElement, allowed: readonly string[], required: readonly string[]): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+  if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}.`);
+  for (const child of element.children) {
+    if (child.kind === "element" || child.value.trim().length > 0) throw new Error(`${element.name} must be empty.`);
+  }
+}
+
+function text(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 text.`);
+  return value.trim();
+}
+
+function number(element: StructuredElement, name: string, fallback?: number): number {
+  if (element.attributes[name] === undefined && fallback !== undefined) return fallback;
+  const value = Number(text(element, name));
+  if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+  return value;
+}
+
+function positiveInteger(element: StructuredElement, name: string): number {
+  const value = number(element, name);
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${element.name}.${name} must be a positive integer.`);
+  return value;
+}
+
+function length(element: StructuredElement, name: string): SpatialLength {
+  const source = text(element, name);
+  const match = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(px|%)$/u.exec(source);
+  if (match === null) throw new Error(`${element.name}.${name} must use px or %.`);
+  const value = Number(match[1]);
+  if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+  return { unit: match[2] === "%" ? "percent" : "px", value };
+}
+
+function anchor(element: StructuredElement): SpatialAnchor {
+  const value = text(element, "anchor") as SpatialAnchor;
+  if (!["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"].includes(value)) {
+    throw new Error(`${element.name}.anchor is invalid.`);
+  }
+  return value;
+}
+
+function reference(
+  element: StructuredElement,
+  name: string,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const result = resolve(value.path);
+  if (result === undefined) throw new Error(`${element.name}.${name} cannot resolve ${value.path}.`);
+  return result;
+}
+
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+  if (value.record?.value.kind !== "inline") throw new Error(`${label} must reference an authored inline Record.`);
+  return value.record.value.value as unknown as T;
+}
+
+type ParentFrame = {
+  readonly ref: AuthorValueRef;
+  readonly components: readonly SurfaceComponentDraft[];
+  readonly fragments: readonly GraphFragment[];
+};
+
+function parentFrame(
+  id: string,
+  element: StructuredElement,
+  parent: SurfaceResolvedReference,
+): ParentFrame {
+  if (sameType(parent.type, spatialTypes.frame)) return { ref: parent.ref, components: [], fragments: [] };
+  if (!sameType(parent.type, spatialTypes.canvas)) throw new Error(`${element.name}.within must reference CanvasSpace or SpatialFrame.`);
+  const output = `${id}.__canvas-frame`;
+  const component = `${id}.__canvas-frame-component`;
+  return {
+    ref: { kind: "component-output", component, output: "frame" },
+    components: [{
+      id: component, fragment: canvasFrameFragment.id,
+      inputs: { canvas: parent.ref }, outputs: { frame: output }, range: element.range,
+    }],
+    fragments: [canvasFrameFragment],
+  };
+}
+
+export const decodeCanvasSurface: StructuredSurfaceHandler = ({ element }) => {
+  exact(element, ["id", "width", "height"], ["id", "width", "height"]);
+  const id = text(element, "id");
+  const canvas = sealCanvasSpace({
+    widthPx: positiveInteger(element, "width"), heightPx: positiveInteger(element, "height"),
+    origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+  });
+  return { records: [{ id, type: spatialTypes.canvas, value: { kind: "inline", value: canvas as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
+};
+
+export const decodePointSurface: StructuredSurfaceHandler = ({ element }) => {
+  exact(element, ["id", "x", "y"], ["id", "x", "y"]);
+  const id = text(element, "id");
+  const point = sealSpatialPoint({
+    xPx: number(element, "x"),
+    yPx: number(element, "y"),
+  });
+  return {
+    records: [{ id, type: spatialTypes.point, value: { kind: "inline", value: point as unknown as CanonicalValue }, range: element.range }],
+    components: [], fragments: [],
+  };
+};
+
+function commandNumber(element: StructuredElement, name: string): number {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be finite.`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`${element.name}.${name} must be finite.`);
+  return parsed;
+}
+
+function pathCommand(element: StructuredElement): SpatialPathCommand {
+  const name = element.name.slice(element.name.lastIndexOf(":") + 1);
+  if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
+    throw new Error(`${element.name} must be empty.`);
+  }
+  if (name === "Move" || name === "Line") {
+    exact(element, ["x", "y"], ["x", "y"]);
+    return { kind: name === "Move" ? "move" : "line", xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y") };
+  }
+  if (name === "Quadratic") {
+    exact(element, ["control-x", "control-y", "x", "y"], ["control-x", "control-y", "x", "y"]);
+    return {
+      kind: "quadratic",
+      controlX: commandNumber(element, "control-x"), controlY: commandNumber(element, "control-y"),
+      xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y"),
+    };
+  }
+  if (name === "Cubic") {
+    exact(element, ["control1-x", "control1-y", "control2-x", "control2-y", "x", "y"], ["control1-x", "control1-y", "control2-x", "control2-y", "x", "y"]);
+    return {
+      kind: "cubic",
+      control1X: commandNumber(element, "control1-x"), control1Y: commandNumber(element, "control1-y"),
+      control2X: commandNumber(element, "control2-x"), control2Y: commandNumber(element, "control2-y"),
+      xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y"),
+    };
+  }
+  if (name === "Close") {
+    exact(element, [], []);
+    return { kind: "close" };
+  }
+  throw new Error(`${element.name} is not a Spatial Path command.`);
+}
+
+export const decodePathSurface: StructuredSurfaceHandler = ({ element }) => {
+  const unknown = Object.keys(element.attributes).filter((name) => name !== "id");
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+  const id = text(element, "id");
+  const commands: SpatialPathCommand[] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Path commands.`);
+      continue;
+    }
+    commands.push(pathCommand(child));
+  }
+  const path: SpatialPath = { commands };
+  assertSpatialPath(path);
+  return {
+    records: [{ id, type: spatialTypes.path, value: { kind: "inline", value: path as unknown as CanonicalValue }, range: element.range }],
+    components: [], fragments: [],
+  };
+};
+
+export const decodeExtentSurface: StructuredSurfaceHandler = ({ element }) => {
+  exact(element, ["id", "width", "height"], ["id", "width", "height"]);
+  const id = text(element, "id");
+  const extent = sealIntrinsicExtent({
+    widthPx: positiveInteger(element, "width"),
+    heightPx: positiveInteger(element, "height"),
+  });
+  return { records: [{ id, type: spatialTypes.extent, value: { kind: "inline", value: extent as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
+};
+
+export const decodeRegionTimelineSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "within", "recipe"], ["id", "within", "recipe"]);
+  const id = text(element, "id");
+  const canvasReference = reference(element, "within", resolveReference);
+  if (!sameType(canvasReference.type, spatialTypes.canvas)) throw new Error(`${element.name}.within must reference CanvasSpace.`);
+  const recipeReference = reference(element, "recipe", resolveReference);
+  if (!sameType(recipeReference.type, svsRecipeType)) throw new Error(`${element.name}.recipe must reference an SVS Recipe.`);
+  const timeline = spatialRegionTimeline(
+    inline<SvsRecipe>(recipeReference, `${element.name}.recipe`),
+    inline<CanvasSpace>(canvasReference, `${element.name}.within`),
+  );
+  return {
+    records: [{ id, type: spatialTypes.regionTimeline, value: { kind: "inline", value: timeline as unknown as CanonicalValue }, range: element.range }],
+    components: [], fragments: [],
+  };
+};
+
+function frameSurface(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+  program: FrameEdgesProgram | AnchoredFrameProgram,
+  programType: SurfaceResolvedReference["type"],
+  fragment: typeof frameEdgesFragment | typeof anchoredFrameFragment,
+) {
+  const id = text(element, "id");
+  const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+  const programId = `${id}.__program`;
+  return {
+    records: [{ id: programId, type: programType, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range }],
+    components: [
+      ...parent.components,
+      { id, fragment: fragment.id, inputs: { parent: parent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+    ],
+    fragments: [...parent.fragments, fragment],
+    exports: [id],
+  };
+}
+
+export const decodeFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "within", "left", "top", "right", "bottom"], ["id", "within", "left", "top", "right", "bottom"]);
+  return frameSurface(element, resolveReference, {
+    left: length(element, "left"), top: length(element, "top"),
+    right: length(element, "right"), bottom: length(element, "bottom"),
+  }, spatialTypes.frameEdgesProgram, frameEdgesFragment);
+};
+
+export const decodeAnchoredFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "within", "x", "y", "width", "height", "anchor", "offset-x", "offset-y"], ["id", "within", "x", "y", "width", "height", "anchor"]);
+  return frameSurface(element, resolveReference, {
+    x: length(element, "x"), y: length(element, "y"),
+    width: length(element, "width"), height: length(element, "height"), anchor: anchor(element),
+    offsetPx: { x: number(element, "offset-x", 0), y: number(element, "offset-y", 0) },
+  }, spatialTypes.anchoredFrameProgram, anchoredFrameFragment);
+};
+
+function aspectExtent(
+  id: string,
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): { readonly ref: AuthorValueRef; readonly records: readonly { readonly id: string; readonly type: typeof spatialTypes.extent; readonly value: { readonly kind: "inline"; readonly value: CanonicalValue }; readonly range: StructuredElement["range"] }[] } {
+  const raw = element.attributes.aspect;
+  if (typeof raw === "object" && raw.kind === "reference") {
+    const resolved = resolveReference(raw.path);
+    if (resolved === undefined || !sameType(resolved.type, spatialTypes.extent)) throw new Error(`${element.name}.aspect must reference IntrinsicExtent.`);
+    return { ref: resolved.ref, records: [] };
+  }
+  const source = text(element, "aspect");
+  const match = /^(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)$/u.exec(source);
+  if (match === null) throw new Error(`${element.name}.aspect must be IntrinsicExtent or width/height.`);
+  const extent = sealIntrinsicExtent({ widthPx: Number(match[1]), heightPx: Number(match[2]) });
+  const extentId = `${id}.__extent`;
+  return { ref: { kind: "record", id: extentId }, records: [{ id: extentId, type: spatialTypes.extent, value: { kind: "inline", value: extent as unknown as CanonicalValue }, range: element.range }] };
+}
+
+export const decodeAspectFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "within", "x", "y", "width", "height", "aspect", "anchor", "offset-x", "offset-y"], ["id", "within", "x", "y", "aspect", "anchor"]);
+  const hasWidth = element.attributes.width !== undefined;
+  const hasHeight = element.attributes.height !== undefined;
+  if (hasWidth === hasHeight) throw new Error(`${element.name} requires exactly one of width or height.`);
+  const id = text(element, "id");
+  const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+  const extent = aspectExtent(id, element, resolveReference);
+  const program: AspectFrameProgram = {
+    x: length(element, "x"), y: length(element, "y"),
+    primary: hasWidth ? "width" : "height", size: length(element, hasWidth ? "width" : "height"),
+    anchor: anchor(element), offsetPx: { x: number(element, "offset-x", 0), y: number(element, "offset-y", 0) },
+  };
+  const programId = `${id}.__program`;
+  return {
+    records: [
+      ...extent.records,
+      { id: programId, type: spatialTypes.aspectFrameProgram, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range },
+    ],
+    components: [
+      ...parent.components,
+      { id, fragment: aspectFrameFragment.id, inputs: { parent: parent.ref, extent: extent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+    ],
+    fragments: [...parent.fragments, aspectFrameFragment],
+    exports: [id],
+  };
+};

package/packages/spatial/src/types.ts

@@ -0,0 +1,101 @@
+export type CanvasSpace = {
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly origin: "top-left";
+  readonly xDirection: "right";
+  readonly yDirection: "down";
+  readonly pixelAspect: "square";
+};
+
+export type SpatialPoint = {
+  readonly xPx: number;
+  readonly yPx: number;
+};
+
+export type SpatialFrame = {
+  readonly xPx: number;
+  readonly yPx: number;
+  readonly widthPx: number;
+  readonly heightPx: number;
+};
+
+/** One named, frame-exact sequence of measured regions in one Canvas. */
+export type SpatialRegionTrack = {
+  readonly id: string;
+  readonly frames: readonly (SpatialFrame | null)[];
+};
+
+/** External spatial evidence indexed directly by ProgramSpace Frame. */
+export type SpatialRegionTimeline = {
+  readonly canvas: CanvasSpace;
+  readonly frameCount: number;
+  readonly tracks: readonly SpatialRegionTrack[];
+};
+
+export type SpatialPathCommand =
+  | { readonly kind: "move"; readonly xPx: number; readonly yPx: number }
+  | { readonly kind: "line"; readonly xPx: number; readonly yPx: number }
+  | { readonly kind: "quadratic"; readonly controlX: number; readonly controlY: number; readonly xPx: number; readonly yPx: number }
+  | { readonly kind: "cubic"; readonly control1X: number; readonly control1Y: number; readonly control2X: number; readonly control2Y: number; readonly xPx: number; readonly yPx: number }
+  | { readonly kind: "close" };
+
+export type SpatialPath = {
+  readonly commands: readonly SpatialPathCommand[];
+};
+
+export type IntrinsicExtent = {
+  readonly widthPx: number;
+  readonly heightPx: number;
+};
+
+export type NormalizedPoint = {
+  readonly x: number;
+  readonly y: number;
+};
+
+export type ContentFit = {
+  readonly sizing: "contain" | "cover" | "fit-width" | "fit-height" | "native" | "scale-down" | "stretch";
+  readonly framePoint: NormalizedPoint;
+  readonly contentPoint: NormalizedPoint;
+  readonly offsetPx: { readonly x: number; readonly y: number };
+  readonly constraint: "bounded" | "free";
+};
+
+export type FittedContent = {
+  readonly contentFrame: SpatialFrame;
+};
+
+export type SpatialLength = {
+  readonly unit: "px" | "percent";
+  readonly value: number;
+};
+
+export type FrameEdgesProgram = {
+  readonly left: SpatialLength;
+  readonly top: SpatialLength;
+  readonly right: SpatialLength;
+  readonly bottom: SpatialLength;
+};
+
+export type SpatialAnchor =
+  | "top-left" | "top-center" | "top-right"
+  | "middle-left" | "center" | "middle-right"
+  | "bottom-left" | "bottom-center" | "bottom-right";
+
+export type AnchoredFrameProgram = {
+  readonly x: SpatialLength;
+  readonly y: SpatialLength;
+  readonly width: SpatialLength;
+  readonly height: SpatialLength;
+  readonly anchor: SpatialAnchor;
+  readonly offsetPx: { readonly x: number; readonly y: number };
+};
+
+export type AspectFrameProgram = {
+  readonly x: SpatialLength;
+  readonly y: SpatialLength;
+  readonly primary: "width" | "height";
+  readonly size: SpatialLength;
+  readonly anchor: SpatialAnchor;
+  readonly offsetPx: { readonly x: number; readonly y: number };
+};

package/packages/speech/README.md

@@ -0,0 +1,16 @@
+# `@hypit/speech`
+
+External components use `@hypit/hypit/speech` from their `@hypit/hypit` development dependency. The package
+owns the types and helpers below; Source imports retain the `@hypit/speech@1` Module identity.
+
+
+Public contracts for speech duration, normalized semantic Takes and provider-neutral evidence audio.
+A `SemanticTake` contains one normalized media product, one authored Segment, its words and local
+frame anchors. Ordered Takes are assembled by `@hypit/speech-track` into a `SemanticTrack`, which is
+the program's continuous semantic skeleton. `SpeechEvidenceAudio` carries canonical 16 kHz WAV bytes
+and their exact sample count; it never carries Script or Segment identity.
+
+The package also owns deterministic boundary materialization for a Segment with no Tokens. It maps
+the Segment start and end to the prepared media's frame domain and publishes the same
+`SemanticTake` type. The preview and real-media author surfaces both select this operation for an
+empty Segment. There are no word windows to predict or acoustic evidence to request.

package/packages/speech/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hypit/speech",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/speech/src/activation.ts

@@ -0,0 +1,7 @@
+import { speechComponent, speechManifest } from "./index.js";
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: speechManifest }],
+  components: [speechComponent],
+};
+export default hypitPackage;

package/packages/speech/src/component.ts

@@ -0,0 +1,43 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { SynchronizedMedia } from "@hypit/media";
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+
+import {
+  assertSemanticTakeIdentity,
+  assertSpeechDurationIdentity,
+  assertSpeechEvidenceAudioIdentity,
+} from "./identity.js";
+import { materializeSegmentBoundaryTake } from "./materialize.js";
+import { speechProducers, speechTypes } from "./manifest.js";
+import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";
+
+function inline<T>(value: StoredValue, subject: string): T {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);
+  return value.value as T;
+}
+
+export const speechComponent = {
+  validators: [
+    { type: speechTypes.duration, handler: ({ value }) => assertSpeechDurationIdentity(inline<SpeechDuration>(value, "SpeechDuration")) },
+    { type: speechTypes.evidenceAudio, handler: ({ value }) => assertSpeechEvidenceAudioIdentity(inline<SpeechEvidenceAudio>(value, "SpeechEvidenceAudio")) },
+    { type: speechTypes.semanticTake, handler: ({ value }) => assertSemanticTakeIdentity(inline<SemanticTake>(value, "SemanticTake")) },
+  ],
+  producers: [{
+    producer: speechProducers.materializeSegmentBoundaries,
+    handler: ({ inputs }) => ({
+      outputs: {
+        take: {
+          kind: "inline",
+          value: canonicalize(materializeSegmentBoundaryTake(
+            inline<Narrative>(inputs.narrative!.value, "Narrative"),
+            inline<NarrativeExcerpt>(inputs.segment!.value, "NarrativeExcerpt"),
+            inline<SynchronizedMedia>(inputs.media!.value, "SynchronizedMedia"),
+          )),
+        },
+      },
+      needs: {},
+    }),
+  }],
+} satisfies ComponentPackage;

package/packages/speech/src/identity.ts

@@ -0,0 +1,73 @@
+import { isResourceId } from "@hypit/protocol";
+import { verifySynchronizedMedia } from "@hypit/media";
+import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";
+export function sealSpeechDuration(value: SpeechDuration): SpeechDuration { return value; }
+export function assertSpeechDurationIdentity(value: SpeechDuration): void {
+  if (!Number.isFinite(value) || value <= 0) throw new Error("SpeechDuration is invalid.");
+}
+export function speechEvidenceSampleBoundary(masterSampleBoundary: number): number {
+  if (!Number.isSafeInteger(masterSampleBoundary) || masterSampleBoundary < 0) throw new Error("Speech evidence source sample boundary is invalid.");
+  const value = (BigInt(masterSampleBoundary) * 16_000n * 2n + 48_000n) / (48_000n * 2n);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Speech evidence sample boundary exceeds safe arithmetic.");
+  return Number(value);
+}
+export function sealSpeechEvidenceAudio(value: SpeechEvidenceAudio): SpeechEvidenceAudio { return structuredClone(value); }
+
+export function sealSemanticTake(value: SemanticTake): SemanticTake {
+  const take = structuredClone(value);
+  assertSemanticTakeIdentity(take);
+  return take;
+}
+
+export function assertSemanticTakeIdentity(take: SemanticTake): void {
+  if (!take.narrativeId.trim()) throw new Error("SemanticTake narrativeId must not be empty.");
+  verifySynchronizedMedia(take.media);
+  const frameCount = take.media.timeline.frameCount;
+  const { segment } = take;
+  if (!segment.segmentId || !segment.startAnchorId || !segment.endAnchorId
+    || segment.startFrame !== 0 || segment.endFrameExclusive !== frameCount) {
+    throw new Error("SemanticTake Segment must cover its local media frame domain.");
+  }
+  const anchorIds = new Set<string>();
+  const anchorFrames = new Map<string, number>();
+  for (const anchor of take.anchors) {
+    if (!anchor.identity || anchorIds.has(anchor.identity) || !Number.isSafeInteger(anchor.frame)
+      || anchor.frame < 0 || anchor.frame > frameCount) {
+      throw new Error(`SemanticTake anchor ${anchor.identity || "<unnamed>"} is invalid.`);
+    }
+    anchorIds.add(anchor.identity);
+    anchorFrames.set(anchor.identity, anchor.frame);
+  }
+  if (anchorFrames.get(segment.startAnchorId) !== 0
+    || anchorFrames.get(segment.endAnchorId) !== frameCount) {
+    throw new Error("SemanticTake Segment Anchors must equal its media boundaries.");
+  }
+  const tokenIds = new Set<string>();
+  let previousStart = 0;
+  let previousEnd = 0;
+  for (const token of take.tokens) {
+    if (!token.tokenId || !token.segmentId || token.segmentId !== segment.segmentId || !token.text
+      || !token.startAnchorId || !token.endAnchorId || tokenIds.has(token.tokenId)
+      || !Number.isSafeInteger(token.startFrame) || !Number.isSafeInteger(token.endFrameExclusive)
+      || token.startFrame < 0 || token.endFrameExclusive < 0
+      || token.startFrame > token.endFrameExclusive
+      || token.startFrame > frameCount || token.endFrameExclusive > frameCount
+      || token.startFrame < previousStart || token.endFrameExclusive < previousEnd) {
+      throw new Error(`SemanticTake token ${token.tokenId || "<unnamed>"} is invalid.`);
+    }
+    if (anchorFrames.get(token.startAnchorId) !== token.startFrame
+      || anchorFrames.get(token.endAnchorId) !== token.endFrameExclusive) {
+      throw new Error(`SemanticTake token ${token.tokenId} disagrees with its Anchors.`);
+    }
+    tokenIds.add(token.tokenId);
+    previousStart = token.startFrame;
+    previousEnd = token.endFrameExclusive;
+  }
+}
+export function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void {
+  if (value.artifact.kind !== "blob" || !isResourceId(value.artifact.resource)
+    || !Number.isSafeInteger(value.artifact.size) || value.artifact.size < 0 || value.artifact.mediaType !== "audio/wav"
+    || !Number.isSafeInteger(value.sampleFrames) || value.sampleFrames < 1) {
+    throw new Error("SpeechEvidenceAudio media identity is invalid.");
+  }
+}

package/packages/speech/src/index.ts

@@ -0,0 +1,6 @@
+export { assertSemanticTakeIdentity, assertSpeechDurationIdentity, assertSpeechEvidenceAudioIdentity, sealSemanticTake, sealSpeechDuration, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary } from "./identity.js";
+export { speechComponent } from "./component.js";
+export { materializeSegmentBoundaryTake, materializeSemanticTake } from "./materialize.js";
+export { speechDependency, speechManifest, speechModuleRef, speechProducers, speechTypes } from "./manifest.js";
+export { semanticTakeSchema, speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";
+export type * from "./types.js";

package/packages/speech/src/manifest.ts

@@ -0,0 +1,30 @@
+import { mediaDependency, mediaTypes } from "@hypit/media";
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { semanticTakeSchema, speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";
+export const speechModuleRef = { name: "@hypit/speech", version: "1" } as const;
+export const speechTypes = {
+  duration: { module: speechModuleRef, name: "SpeechDuration" },
+  evidenceAudio: { module: speechModuleRef, name: "SpeechEvidenceAudio" },
+  semanticTake: { module: speechModuleRef, name: "SemanticTake" },
+} satisfies Record<string, TypeRef>;
+export const speechProducers = {
+  materializeSegmentBoundaries: { module: speechModuleRef, name: "materialize-segment-boundaries" },
+} satisfies Record<string, ProducerRef>;
+export const speechManifest: ModuleManifest = { format: "hypit.module@1", name: speechModuleRef.name, version: speechModuleRef.version,
+  dependencies: [mediaDependency, narrativeDependency],
+  types: [{ name: speechTypes.duration.name },
+    { name: speechTypes.evidenceAudio.name },
+    { name: speechTypes.semanticTake.name }],
+  capabilities: [],
+  producers: [{
+    name: speechProducers.materializeSegmentBoundaries.name,
+    inputs: [
+      { name: "narrative", type: narrativeTypes.narrative },
+      { name: "segment", type: narrativeTypes.excerpt },
+      { name: "media", type: mediaTypes.synchronized },
+    ],
+    outputs: [{ name: "take", type: speechTypes.semanticTake }],
+    needs: [],
+  }] };
+export const speechDependency = { module: speechModuleRef } as const;