@hypit/hypit 0.0.1 → 0.1.0

package/packages/speech/src/materialize.ts

@@ -0,0 +1,103 @@
+import type { SynchronizedMedia } from "@hypit/media";
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+
+import { assertSemanticTakeIdentity, sealSemanticTake } from "./identity.js";
+import type { SemanticTake, SemanticTakeTiming } from "./types.js";
+
+function authoredSegment(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative["segments"][number] {
+  if (narrative.id !== excerpt.narrativeId) {
+    throw new Error(`NarrativeExcerpt ${excerpt.id} belongs to Narrative ${excerpt.narrativeId}, not ${narrative.id}.`);
+  }
+  if (excerpt.kind !== "segment") throw new Error("SemanticTake materialization requires a Segment excerpt.");
+  const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
+  if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
+  if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
+    throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
+  }
+  return segment;
+}
+
+function localFrame(frame: number, frameCount: number, label: string): number {
+  if (!Number.isSafeInteger(frame) || frame < 0 || frame > frameCount) {
+    throw new Error(`${label} lies outside its normalized Segment Take.`);
+  }
+  return frame;
+}
+
+/**
+ * Copy one Segment-local timing result into a self-contained semantic Take.
+ * How the timing was obtained remains the caller's explicit package meaning.
+ */
+export function materializeSemanticTake(
+  narrative: Narrative,
+  excerpt: NarrativeExcerpt,
+  media: SynchronizedMedia,
+  timing: SemanticTakeTiming,
+): SemanticTake {
+  const segment = authoredSegment(narrative, excerpt);
+  const localFrameCount = media.timeline.frameCount;
+  const timedById = new Map(timing.tokens.map((token) => [token.tokenId, token]));
+  const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive).map((token) => {
+    const timed = timedById.get(token.id);
+    if (timed === undefined || timed.segmentId !== segment.id) {
+      throw new Error(`Semantic timing does not locate authored Token ${token.id}.`);
+    }
+    const startFrame = localFrame(timed.startFrame, localFrameCount, `Token ${token.id}`);
+    const endFrameExclusive = localFrame(timed.endFrameExclusive, localFrameCount, `Token ${token.id}`);
+    if (endFrameExclusive <= startFrame) throw new Error(`Token ${token.id} has an empty or reversed frame window.`);
+    return {
+      tokenId: token.id,
+      segmentId: segment.id,
+      text: token.text,
+      startAnchorId: token.startAnchorId,
+      endAnchorId: token.endAnchorId,
+      startFrame,
+      endFrameExclusive,
+    };
+  });
+  const anchorsById = new Map(timing.anchors.map((anchor) => [anchor.identity, anchor]));
+  const anchors = narrative.semanticIndex.anchors
+    .filter((anchor) => anchor.segmentId === segment.id)
+    .map((anchor) => {
+      const measured = anchorsById.get(anchor.id);
+      if (measured === undefined) throw new Error(`Semantic timing does not locate authored Anchor ${anchor.id}.`);
+      return {
+        identity: anchor.id,
+        frame: localFrame(measured.frame, localFrameCount, `Anchor ${anchor.id}`),
+      };
+    });
+  const take = sealSemanticTake({
+    narrativeId: narrative.id,
+    media,
+    segment: {
+      segmentId: segment.id,
+      startAnchorId: segment.startAnchorId,
+      endAnchorId: segment.endAnchorId,
+      startFrame: 0,
+      endFrameExclusive: media.timeline.frameCount,
+    },
+    tokens,
+    anchors,
+  });
+  assertSemanticTakeIdentity(take);
+  return take;
+}
+
+/** Materialize the exact media boundaries of an authored Segment that contains no Tokens. */
+export function materializeSegmentBoundaryTake(
+  narrative: Narrative,
+  excerpt: NarrativeExcerpt,
+  media: SynchronizedMedia,
+): SemanticTake {
+  const segment = authoredSegment(narrative, excerpt);
+  if (segment.tokenStart !== segment.tokenEndExclusive) {
+    throw new Error(`Segment ${segment.id} contains spoken Tokens and needs token timing.`);
+  }
+  return materializeSemanticTake(narrative, excerpt, media, {
+    tokens: [],
+    anchors: [
+      { identity: segment.startAnchorId, frame: 0 },
+      { identity: segment.endAnchorId, frame: media.timeline.frameCount },
+    ],
+  });
+}

package/packages/speech/src/schema.ts

@@ -0,0 +1,42 @@
+import { synchronizedMediaSchema } from "@hypit/media";
+import type { ValueSchema } from "@hypit/protocol";
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const digest = { kind: "string", minLength: 5, maxLength: 256 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const audioBlobRef = object({
+  kind: { schema: { kind: "literal", value: "blob" } },
+  resource: { schema: digest },
+  size: { schema: integer },
+  mediaType: { schema: { kind: "literal", value: "audio/wav" } },
+});
+const semanticTakeToken = object({
+  tokenId: { schema: string },
+  segmentId: { schema: string },
+  text: { schema: string },
+  startAnchorId: { schema: string },
+  endAnchorId: { schema: string },
+  startFrame: { schema: integer },
+  endFrameExclusive: { schema: integer },
+});
+const semanticTakeAnchor = object({ identity: { schema: string }, frame: { schema: integer } });
+const semanticTakeSegment = object({
+  segmentId: { schema: string },
+  startAnchorId: { schema: string },
+  endAnchorId: { schema: string },
+  startFrame: { schema: integer },
+  endFrameExclusive: { schema: integer },
+});
+export const speechDurationSchema: ValueSchema = number;
+export const speechEvidenceAudioSchema: ValueSchema = object({
+  artifact: { schema: audioBlobRef },
+  sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
+});
+export const semanticTakeSchema: ValueSchema = object({
+  narrativeId: { schema: string },
+  media: { schema: synchronizedMediaSchema },
+  segment: { schema: semanticTakeSegment },
+  tokens: { schema: { kind: "array", items: semanticTakeToken } },
+  anchors: { schema: { kind: "array", items: semanticTakeAnchor } },
+});

package/packages/speech/src/types.ts

@@ -0,0 +1,54 @@
+import type { SynchronizedMedia } from "@hypit/media";
+import type { BlobRef } from "@hypit/protocol";
+/** Positive seconds. The graph port's TypeRef already carries the SpeechDuration identity. */
+export type SpeechDuration = number;
+export type SpeechEvidenceAudio = {
+  readonly artifact: BlobRef;
+  /** Exact 16 kHz mono PCM sample count. Format constants belong to this Type, not every value. */
+  readonly sampleFrames: number;
+};
+
+/** One authored Script token located in one normalized Take's local frame domain. */
+export type SemanticTakeToken = {
+  readonly tokenId: string;
+  readonly segmentId: string;
+  readonly text: string;
+  readonly startAnchorId: string;
+  readonly endAnchorId: string;
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+/**
+ * A self-contained semantic media product. Media bytes remain ordinary BlobRefs
+ * inside SynchronizedMedia; the authored word surface and its local frame
+ * coordinates travel with this Take instead of requiring a second Script edge.
+ */
+export type SemanticTake = {
+  /** Author-visible Script identity carried through every semantic projection. */
+  readonly narrativeId: string;
+  readonly media: SynchronizedMedia;
+  readonly segment: {
+    readonly segmentId: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+  };
+  readonly tokens: readonly SemanticTakeToken[];
+  readonly anchors: readonly { readonly identity: string; readonly frame: number }[];
+};
+
+/** One authored Token located in a Segment-local frame domain. */
+export type SemanticTakeTimedToken = {
+  readonly tokenId: string;
+  readonly segmentId: string;
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+/** Provider measurement and preview estimation both materialize through this narrow timing waist. */
+export type SemanticTakeTiming = {
+  readonly tokens: readonly SemanticTakeTimedToken[];
+  readonly anchors: readonly { readonly identity: string; readonly frame: number }[];
+};

package/packages/speech-alignment/README.md

@@ -0,0 +1,29 @@
+# `@hypit/speech-alignment`
+
+Provider-neutral deterministic timing locator for one normalized Segment Take. The package does not
+invoke Python, read audio, call a speech provider, use an LLM, infer speakers or retain multiple
+candidate paths. A runtime adapter preserves its raw provider artifact and supplies the normalized
+word, character, score and speech-activity evidence used here in exact 16 kHz sample coordinates.
+
+The locator aligns one explicitly connected Script Segment against the acoustic evidence from that
+same normalized Take. A bounded monotonic M:N dynamic
+program accepts exact, split, merge, replacement, source-omission and evidence-insertion groups.
+Within a selected group, timed evidence characters determine Script token boundaries; word times
+and speech-activity bounds are fallbacks. Missing token runs receive continuous weighted windows
+between their measured neighbors instead of invented point timestamps. The result is quantized once
+into the Take's local frame domain and contains one timing for every Script token plus the Segment
+and token boundary anchors. Segment anchors are exactly frame `0` and the Take frame count.
+
+The public Producer accepts Narrative, one Segment excerpt, `SynchronizedMedia` and
+`AlignedTranscriptEvidence` through explicit graph edges. Evidence carries no authored Segment
+identity; the deterministic semantic step performs that association locally.
+
+`speechAlignmentComponent` exposes this Segment-local projection as one enumerable deterministic Producer facet. Its
+identity is checked against `speechAlignmentManifest` and executes through the host-neutral compute
+port. The package depends only on public video
+contracts and protocol utilities; it has no Core, Driver, Provider, Artifact, queue or credential
+authority.
+
+Caption display is outside this package. `@hypit/caption` composes the resulting complete speech
+map with Script's explicit whole-Atom `CaptionCorrespondence`; it never asks this locator to infer
+display text or display-Word timing.

package/packages/speech-alignment/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hypit/speech-alignment",
+  "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/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/speech-evidence": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/script": "workspace:*"
+  }
+}

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

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

package/packages/speech-alignment/src/align.ts

@@ -0,0 +1,235 @@
+import type { NarrativeToken } from "@hypit/narrative";
+import type { SpeechWordEvidence } from "@hypit/speech-evidence";
+
+import { editDistance, normalizeForAlignment } from "./normalize.js";
+import type { AlignmentGroup, AlignmentRelation } from "./types.js";
+
+const EPSILON = 1e-9;
+const DEFAULT_MAX_GROUP = 4;
+
+type Cell = {
+  readonly cost: number;
+  readonly exactTokens: number;
+  readonly omissions: number;
+  readonly insertions: number;
+  readonly complexity: number;
+  readonly previousSource: number;
+  readonly previousEvidence: number;
+  readonly group: AlignmentGroup;
+};
+
+function comparisonText(values: readonly { readonly text: string }[]): string {
+  return values.map((value) => normalizeForAlignment(value.text)).join("");
+}
+
+function evidenceReliability(words: readonly SpeechWordEvidence[]): number {
+  const scores = words
+    .map((word) => word.score)
+    .filter((score): score is number => score !== undefined && Number.isFinite(score));
+  if (!scores.length) return 0.8;
+  const average = scores.reduce((sum, score) => sum + Math.max(0, Math.min(1, score)), 0) / scores.length;
+  return 0.5 + 0.5 * average;
+}
+
+function exactWordLcs(
+  source: readonly NarrativeToken[],
+  evidence: readonly SpeechWordEvidence[],
+): number {
+  const rows = Array.from({ length: source.length + 1 }, () =>
+    Array<number>(evidence.length + 1).fill(0));
+  for (let left = source.length - 1; left >= 0; left -= 1) {
+    for (let right = evidence.length - 1; right >= 0; right -= 1) {
+      rows[left]![right] = source[left]!.normalized === normalizeForAlignment(evidence[right]!.text)
+        ? rows[left + 1]![right + 1]! + 1
+        : Math.max(rows[left + 1]![right]!, rows[left]![right + 1]!);
+    }
+  }
+  return rows[0]![0]!;
+}
+
+function relation(
+  sourceCount: number,
+  evidenceCount: number,
+  exactOneToOne: boolean,
+): AlignmentRelation {
+  if (sourceCount === 0) return "evidence-insertion";
+  if (evidenceCount === 0) return "source-omission";
+  if (sourceCount === 1 && evidenceCount === 1 && exactOneToOne) return "exact";
+  if (sourceCount > 1 && evidenceCount === 1) return "merge";
+  if (sourceCount === 1 && evidenceCount > 1) return "split";
+  return "replacement";
+}
+
+function pairedCost(
+  source: readonly NarrativeToken[],
+  evidence: readonly SpeechWordEvidence[],
+): number {
+  const sourceText = comparisonText(source);
+  const evidenceText = comparisonText(evidence);
+  const width = Math.max([...sourceText].length, [...evidenceText].length, 1);
+  const distance = editDistance([...sourceText], [...evidenceText]) / width;
+  const grouping = 0.055 * Math.max(0, source.length + evidence.length - 2);
+  const exactWords = exactWordLcs(source, evidence);
+  const unmatchedWordBoundaries = source.length + evidence.length - 2 * exactWords;
+  return distance * evidenceReliability(evidence) + grouping + 0.06 * unmatchedWordBoundaries;
+}
+
+function better(candidate: Cell, current: Cell | undefined): boolean {
+  if (!current) return true;
+  if (candidate.cost < current.cost - EPSILON) return true;
+  if (candidate.cost > current.cost + EPSILON) return false;
+  if (candidate.exactTokens !== current.exactTokens) return candidate.exactTokens > current.exactTokens;
+  if (candidate.omissions !== current.omissions) return candidate.omissions < current.omissions;
+  if (candidate.insertions !== current.insertions) return candidate.insertions < current.insertions;
+  return candidate.complexity < current.complexity;
+}
+
+function extend(
+  previous: Cell | undefined,
+  group: AlignmentGroup,
+  sourceCount: number,
+  evidenceCount: number,
+  exactTokens: number,
+): Cell {
+  return {
+    cost: (previous?.cost ?? 0) + group.cost,
+    exactTokens: (previous?.exactTokens ?? 0) + exactTokens,
+    omissions: (previous?.omissions ?? 0) + (evidenceCount === 0 ? sourceCount : 0),
+    insertions: (previous?.insertions ?? 0) + (sourceCount === 0 ? evidenceCount : 0),
+    complexity: (previous?.complexity ?? 0) + Math.max(0, sourceCount + evidenceCount - 2),
+    previousSource: 0,
+    previousEvidence: 0,
+    group,
+  };
+}
+
+export function alignWordGroups(
+  sourceSegmentId: string,
+  source: readonly NarrativeToken[],
+  evidence: readonly SpeechWordEvidence[],
+  maxGroupSize = DEFAULT_MAX_GROUP,
+): AlignmentGroup[] {
+  const rows = Array.from({ length: source.length + 1 }, () =>
+    Array<Cell | undefined>(evidence.length + 1).fill(undefined));
+  rows[0]![0] = {
+    cost: 0,
+    exactTokens: 0,
+    omissions: 0,
+    insertions: 0,
+    complexity: 0,
+    previousSource: -1,
+    previousEvidence: -1,
+    group: {
+      sourceSegmentId,
+      sourceTokenIds: [],
+      evidenceWordStart: 0,
+      evidenceWordEndExclusive: 0,
+      relation: "exact",
+      cost: 0,
+    },
+  };
+
+  const update = (
+    sourceIndex: number,
+    evidenceIndex: number,
+    nextSource: number,
+    nextEvidence: number,
+    group: AlignmentGroup,
+    exactTokens: number,
+  ): void => {
+    const previous = rows[sourceIndex]![evidenceIndex];
+    if (!previous) return;
+    const candidate = {
+      ...extend(
+        sourceIndex === 0 && evidenceIndex === 0 ? undefined : previous,
+        group,
+        nextSource - sourceIndex,
+        nextEvidence - evidenceIndex,
+        exactTokens,
+      ),
+      previousSource: sourceIndex,
+      previousEvidence: evidenceIndex,
+    };
+    if (better(candidate, rows[nextSource]![nextEvidence])) {
+      rows[nextSource]![nextEvidence] = candidate;
+    }
+  };
+
+  for (let sourceIndex = 0; sourceIndex <= source.length; sourceIndex += 1) {
+    for (let evidenceIndex = 0; evidenceIndex <= evidence.length; evidenceIndex += 1) {
+      if (!rows[sourceIndex]![evidenceIndex]) continue;
+      for (let sourceCount = 1; sourceCount <= maxGroupSize && sourceIndex + sourceCount <= source.length; sourceCount += 1) {
+        for (let evidenceCount = 1; evidenceCount <= maxGroupSize && evidenceIndex + evidenceCount <= evidence.length; evidenceCount += 1) {
+          const sourceGroup = source.slice(sourceIndex, sourceIndex + sourceCount);
+          const evidenceGroup = evidence.slice(evidenceIndex, evidenceIndex + evidenceCount);
+          const exactOneToOne = sourceCount === 1
+            && evidenceCount === 1
+            && sourceGroup[0]!.normalized === normalizeForAlignment(evidenceGroup[0]!.text);
+          const cost = pairedCost(sourceGroup, evidenceGroup);
+          update(
+            sourceIndex,
+            evidenceIndex,
+            sourceIndex + sourceCount,
+            evidenceIndex + evidenceCount,
+            {
+              sourceSegmentId,
+              sourceTokenIds: sourceGroup.map((token) => token.id),
+              evidenceWordStart: evidenceIndex,
+              evidenceWordEndExclusive: evidenceIndex + evidenceCount,
+              relation: relation(sourceCount, evidenceCount, exactOneToOne),
+              cost,
+            },
+            exactOneToOne ? 1 : 0,
+          );
+        }
+      }
+      if (sourceIndex < source.length) {
+        const token = source[sourceIndex]!;
+        update(
+          sourceIndex,
+          evidenceIndex,
+          sourceIndex + 1,
+          evidenceIndex,
+          {
+            sourceSegmentId,
+            sourceTokenIds: [token.id],
+            evidenceWordStart: evidenceIndex,
+            evidenceWordEndExclusive: evidenceIndex,
+            relation: "source-omission",
+            cost: 0.5,
+          },
+          0,
+        );
+      }
+      if (evidenceIndex < evidence.length) {
+        update(
+          sourceIndex,
+          evidenceIndex,
+          sourceIndex,
+          evidenceIndex + 1,
+          {
+            sourceSegmentId,
+            sourceTokenIds: [],
+            evidenceWordStart: evidenceIndex,
+            evidenceWordEndExclusive: evidenceIndex + 1,
+            relation: "evidence-insertion",
+            cost: 0.35,
+          },
+          0,
+        );
+      }
+    }
+  }
+
+  const groups: AlignmentGroup[] = [];
+  let sourceIndex = source.length;
+  let evidenceIndex = evidence.length;
+  while (sourceIndex > 0 || evidenceIndex > 0) {
+    const cell = rows[sourceIndex]![evidenceIndex];
+    if (!cell) throw new Error("Word alignment failed to produce a complete path.");
+    groups.push(cell.group);
+    sourceIndex = cell.previousSource;
+    evidenceIndex = cell.previousEvidence;
+  }
+  return groups.reverse();
+}

package/packages/speech-alignment/src/component.ts

@@ -0,0 +1,37 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { SynchronizedMedia } from "@hypit/media";
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { alignSemanticTake } from "./local.js";
+import { speechAlignmentProducers } from "./manifest.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+  if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value as T;
+}
+
+/** Provider-neutral deterministic alignment; acoustic measurement remains an explicit upstream Need. */
+export const speechAlignmentComponent = {
+  producers: [
+    {
+      producer: speechAlignmentProducers.alignTake,
+      handler: ({ inputs }) => ({
+        outputs: {
+          take: {
+            kind: "inline",
+            value: canonicalize(alignSemanticTake(
+              inline<Narrative>(inputs.narrative?.value, "Narrative"),
+              inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
+              inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
+              inline<AlignedTranscriptEvidence>(inputs.evidence?.value, "AlignedTranscriptEvidence"),
+            )),
+          },
+        },
+        needs: {},
+      }),
+    },
+  ],
+} satisfies ComponentPackage;

package/packages/speech-alignment/src/error.ts

@@ -0,0 +1,9 @@
+export class SpeechAlignmentError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "SpeechAlignmentError";
+    this.code = code;
+  }
+}

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

@@ -0,0 +1,7 @@
+export { alignWordGroups } from "./align.js";
+export { speechAlignmentComponent } from "./component.js";
+export { SpeechAlignmentError } from "./error.js";
+export { alignSemanticTake } from "./local.js";
+export { speechAlignmentManifest, speechAlignmentModuleRef, speechAlignmentProducers } from "./manifest.js";
+export { alignCharacters, alignmentCharacters, normalizeForAlignment } from "./normalize.js";
+export type * from "./types.js";

package/packages/speech-alignment/src/local.ts

@@ -0,0 +1,64 @@
+import type { SynchronizedMedia } from "@hypit/media";
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import { sealProgramSpace } from "@hypit/program-space";
+import { materializeSemanticTake } from "@hypit/speech";
+import type { SemanticTake } from "@hypit/speech";
+import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
+
+import { locateAlignedSegmentTiming } from "./locate.js";
+import type { AlignmentBasis } from "./locate.js";
+
+function segmentNarrative(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative {
+  if (excerpt.kind !== "segment") throw new Error("SemanticTake alignment requires a Segment excerpt.");
+  const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
+  if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
+  if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
+    throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
+  }
+  const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);
+  return {
+    id: narrative.id,
+    segments: [{ ...segment, tokenStart: 0, tokenEndExclusive: tokens.length }],
+    tokens,
+    turns: narrative.turns
+      .filter((turn) => turn.segmentId === segment.id)
+      .map((turn) => ({
+        ...turn,
+        tokenStart: turn.tokenStart - segment.tokenStart,
+        tokenEndExclusive: turn.tokenEndExclusive - segment.tokenStart,
+      })),
+    selections: [],
+    moments: [],
+    semanticIndex: {
+      anchors: narrative.semanticIndex.anchors.filter((anchor) => anchor.segmentId === segment.id),
+    },
+  };
+}
+
+/** Align one normalized Take independently, then materialize its local semantic product. */
+export function alignSemanticTake(
+  narrative: Narrative,
+  excerpt: NarrativeExcerpt,
+  media: SynchronizedMedia,
+  evidence: AlignedTranscriptEvidence,
+): SemanticTake {
+  if (media.audio === undefined) throw new Error(`SemanticTake ${excerpt.id} has no normalized audio.`);
+  const localNarrative = segmentNarrative(narrative, excerpt);
+  const programSpace = sealProgramSpace({
+    id: `${excerpt.narrativeId}.segment.${excerpt.id}`,
+    durationSec: media.timeline.frameCount * media.timeline.frameRate.denominator
+      / media.timeline.frameRate.numerator,
+    frameRate: media.timeline.frameRate,
+  });
+  const basis: AlignmentBasis = {
+    programSpace,
+    audio: media.audio.artifact,
+    segments: [{ segmentId: excerpt.id, startFrame: 0, endFrameExclusive: media.timeline.frameCount }],
+  };
+  const timing = locateAlignedSegmentTiming(localNarrative, basis, evidence);
+  return materializeSemanticTake(localNarrative, {
+    ...excerpt,
+    tokenStart: 0,
+    tokenEndExclusive: localNarrative.tokens.length,
+  }, media, timing);
+}