@hraness/slopcamera 3.2.4

package/apps/desktop/core/spatial-project.ts

@@ -0,0 +1,169 @@
+import {
+  applySpatialScenePatch,
+  parseSpatialScene,
+  spatialSceneSha256,
+  validateSpatialShot,
+} from "../../../src/spatial-scene/index";
+import { z } from "zod";
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "../../../src/code/json-snapshot";
+import { SpatialDigestSchema, SpatialScenePatchV1Schema, SpatialShotV1Schema, type SpatialShotV1 } from "../../../src/spatial-scene/contracts";
+import {
+  SpatialCandidateSchema,
+  SpatialCandidateSelectionSchema,
+  SPATIAL_PROJECT_LIMITS,
+  SpatialProjectArtifactSchema,
+  SpatialProjectRevisionV2Schema,
+  SpatialProjectLegacySchema,
+  SpatialProjectSceneSourceSchema,
+  SpatialShotRetargetSchema,
+  type SpatialCandidate,
+  type SpatialProjectArtifact,
+  type SpatialProjectLegacy,
+  type SpatialProjectRevisionV2,
+  type SpatialProjectSceneSource,
+  type SpatialShotRetarget,
+} from "../contracts/spatial-project";
+import { canonicalJson, canonicalJsonSha256, sha256Hex } from "./canonical-json";
+import { hashProjectStructure } from "./project-plan";
+
+export interface SpatialProjectContents {
+  readonly legacy: SpatialProjectLegacy;
+  readonly scenes: readonly SpatialProjectSceneSource[];
+  readonly shots: readonly SpatialShotV1[];
+  readonly candidates: readonly SpatialCandidate[];
+  readonly selections: readonly { readonly shotId: string; readonly candidateId: string }[];
+}
+export const SpatialProjectContentsSchema = z.strictObject({
+  legacy: SpatialProjectLegacySchema,
+  scenes: z.array(SpatialProjectSceneSourceSchema).max(SPATIAL_PROJECT_LIMITS.scenes),
+  shots: z.array(SpatialShotV1Schema).max(SPATIAL_PROJECT_LIMITS.shots),
+  candidates: z.array(SpatialCandidateSchema).max(SPATIAL_PROJECT_LIMITS.candidates),
+  selections: z.array(SpatialCandidateSelectionSchema).max(SPATIAL_PROJECT_LIMITS.shots),
+});
+function capture(input: unknown, maximumBytes = SPATIAL_PROJECT_LIMITS.documentBytes) {
+  return createBoundedJsonValueSnapshot(input, maximumBytes, "spatial project value", { maximumDepth: 48, maximumValues: 2_000_000 }).value;
+}
+export function spatialProjectDocumentText(value: unknown): string {
+  return `${canonicalJson(capture(value))}\n`;
+}
+export function spatialProjectArtifact(area: "scenes" | "revisions" | "attempts" | "receipts", text: string): SpatialProjectArtifact {
+  const sha256 = sha256Hex(text);
+  return SpatialProjectArtifactSchema.parse({ path: `spatial/${area}/${sha256}.json`, sha256, bytes: new TextEncoder().encode(text).byteLength });
+}
+export function spatialProjectRevisionSha256(input: unknown): string {
+  return canonicalJsonSha256({ domain: "slopcamera.spatial-project-revision/v2", revision: SpatialProjectRevisionV2Schema.parse(capture(input)) });
+}
+export function spatialShotSha256(input: unknown): string {
+  return canonicalJsonSha256({ domain: "slopcamera.spatial-shot/v1", shot: SpatialShotV1Schema.parse(capture(input)) });
+}
+export function validateSpatialProjectContents(input: SpatialProjectContents): SpatialProjectContents {
+  const captured = SpatialProjectContentsSchema.parse(capture(input, SPATIAL_PROJECT_LIMITS.documentBytes + SPATIAL_PROJECT_LIMITS.totalSceneBytes));
+  const legacy = captured.legacy;
+  if (legacy.projectEditPlan.projectId !== legacy.project.projectId
+    || legacy.projectEditPlan.projectStructureSha256 !== hashProjectStructure(legacy.project)) {
+    throw new Error("Frozen V1 plan does not bind its exact project structure.");
+  }
+  const scenes = captured.scenes.map(source => {
+    const parsed = SpatialProjectSceneSourceSchema.parse(source);
+    const document = parseSpatialScene(parsed.document);
+    if (spatialSceneSha256(document) !== parsed.sceneSha256) throw new Error("Scene source digest mismatch.");
+    return SpatialProjectSceneSourceSchema.parse({ sceneSha256: parsed.sceneSha256, document });
+  });
+  const shots = captured.shots;
+  for (const shot of shots) {
+    const source = scenes.find(scene => scene.sceneSha256 === shot.sceneSha256);
+    if (source === undefined) throw new Error("Shot source is absent from the project.");
+    validateSpatialShot(source.document, shot);
+  }
+  // The admitted candidate owns its values across later asynchronous IO. A
+  // trusted caller retaining the original object cannot mutate this snapshot.
+  return deepFreezeJson({
+    legacy, scenes, shots,
+    candidates: captured.candidates,
+    selections: captured.selections,
+  });
+}
+export function spatialProjectLegacyProjection(contents: SpatialProjectContents): SpatialProjectLegacy {
+  validateSpatialProjectContents(contents);
+  return structuredClone(contents.legacy);
+}
+export function spatialCandidateStatus(contents: SpatialProjectContents, candidate: SpatialCandidate): "current" | "stale" {
+  const shot = contents.shots.find(value => value.shotId === candidate.derivation.shotId);
+  return shot !== undefined && shot.sceneSha256 === candidate.derivation.sceneSha256
+    && spatialShotSha256(shot) === candidate.derivation.shotSha256 ? "current" : "stale";
+}
+export interface SpatialProjectSceneDiff {
+  readonly beforeSceneSha256: string;
+  readonly afterSceneSha256: string;
+  readonly affectedShotIds: readonly string[];
+  readonly untouchedShotIds: readonly string[];
+  readonly selectedCandidates: readonly { readonly shotId: string; readonly candidateId: string; readonly status: "current" | "stale" }[];
+}
+function retargetSpatialProjectScene(current: SpatialProjectContents, beforeSceneSha256: string, afterSceneSha256: string, retargetInput: SpatialShotRetarget) {
+  const retarget = SpatialShotRetargetSchema.parse(capture(retargetInput));
+  const eligible = current.shots.filter(shot => shot.sceneSha256 === beforeSceneSha256);
+  const ids = retarget.kind === "all" ? eligible.map(shot => shot.shotId) : retarget.shotIds;
+  if (ids.length === 0 || new Set(ids).size !== ids.length || ids.some(id => !eligible.some(shot => shot.shotId === id))) {
+    throw new Error("Retarget must explicitly name unique shots of the exact source scene.");
+  }
+  const contents = validateSpatialProjectContents({ ...current, shots: current.shots.map(shot => ids.includes(shot.shotId) ? { ...shot, sceneSha256: afterSceneSha256 } : shot) });
+  return deepFreezeJson({ contents, diff: {
+    beforeSceneSha256, afterSceneSha256, affectedShotIds: [...ids].sort(),
+    untouchedShotIds: current.shots.filter(shot => !ids.includes(shot.shotId)).map(shot => shot.shotId).sort(),
+    selectedCandidates: contents.selections.map(selection => {
+      const candidate = contents.candidates.find(value => value.candidateId === selection.candidateId);
+      if (candidate === undefined) throw new Error("Selected candidate is absent.");
+      return { ...selection, status: spatialCandidateStatus(contents, candidate) };
+    }),
+  } });
+}
+/** Creates a revision candidate; project-level CAS is performed only by publication. */
+export function applySpatialProjectScenePatch(
+  input: SpatialProjectContents,
+  patchInput: unknown,
+  retargetInput: SpatialShotRetarget,
+): { readonly contents: SpatialProjectContents; readonly diff: SpatialProjectSceneDiff } {
+  const current = validateSpatialProjectContents(input);
+  const patch = SpatialScenePatchV1Schema.parse(capture(patchInput));
+  const source = current.scenes.find(scene => scene.sceneSha256 === patch.expectedSceneSha256);
+  if (source === undefined) throw new Error("Expected source scene is absent.");
+  const document = applySpatialScenePatch(source.document, patch).scene;
+  const sceneSha256 = spatialSceneSha256(document);
+  return retargetSpatialProjectScene({
+    ...current,
+    scenes: current.scenes.some(scene => scene.sceneSha256 === sceneSha256) ? current.scenes
+      : [...current.scenes, SpatialProjectSceneSourceSchema.parse({ sceneSha256, document })],
+  }, patch.expectedSceneSha256, sceneSha256, retargetInput);
+}
+/** Explicit rollback of selected shot source bindings, never automatic head rollback or replay. */
+export function restoreSpatialProjectScene(
+  input: SpatialProjectContents,
+  expectedSceneSha256Input: unknown,
+  restoreSceneSha256Input: unknown,
+  retargetInput: SpatialShotRetarget,
+): { readonly contents: SpatialProjectContents; readonly diff: SpatialProjectSceneDiff } {
+  const current = validateSpatialProjectContents(input);
+  const expectedSceneSha256 = SpatialDigestSchema.parse(capture(expectedSceneSha256Input));
+  const restoreSceneSha256 = SpatialDigestSchema.parse(capture(restoreSceneSha256Input));
+  const source = current.scenes.find(scene => scene.sceneSha256 === expectedSceneSha256);
+  const restored = current.scenes.find(scene => scene.sceneSha256 === restoreSceneSha256);
+  if (source === undefined || restored === undefined) throw new Error("Restore requires both exact scene revisions to be retained in the current project.");
+  if (source.document.sceneId !== restored.document.sceneId) throw new Error("Restore must select a retained revision of the same authored scene identity.");
+  if (expectedSceneSha256 === restoreSceneSha256) throw new Error("Restore requires a different retained scene revision.");
+  return retargetSpatialProjectScene(current, expectedSceneSha256, restoreSceneSha256, retargetInput);
+}
+/** Register exact provenance; this function neither generates nor buys media. */
+export function addSpatialCandidate(input: SpatialProjectContents, candidateInput: unknown): SpatialProjectContents {
+  const candidate = SpatialCandidateSchema.parse(capture(candidateInput));
+  if (input.candidates.some(value => value.candidateId === candidate.candidateId)) throw new Error("Candidate identity is immutable and already exists.");
+  if (spatialCandidateStatus(input, candidate) !== "current") throw new Error("New candidate must bind the exact current shot and source scene.");
+  return { ...input, candidates: [...input.candidates, candidate] };
+}
+export function selectSpatialCandidate(input: SpatialProjectContents, candidateId: string): SpatialProjectContents {
+  const candidate = input.candidates.find(value => value.candidateId === candidateId);
+  if (candidate === undefined || spatialCandidateStatus(input, candidate) !== "current") throw new Error("Only a current verified candidate can be selected.");
+  return { ...input, selections: [...input.selections.filter(selection => selection.shotId !== candidate.derivation.shotId), { shotId: candidate.derivation.shotId, candidateId }] };
+}
+export function spatialProjectContents(revision: SpatialProjectRevisionV2, scenes: readonly SpatialProjectSceneSource[]): SpatialProjectContents {
+  return validateSpatialProjectContents({ legacy: revision.legacy, scenes, shots: revision.shots, candidates: revision.candidates, selections: revision.selections });
+}

package/apps/desktop/core/spatial-shot-clock.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+import { deepFreezeJson } from "../../../src/code/json-snapshot";
+import { SPATIAL_SCENE_LIMITS, SpatialTimeUsSchema } from "../../../src/spatial-scene/contracts";
+import { parseSpatialValue, SpatialSceneError } from "../../../src/spatial-scene/identity";
+
+export const SpatialShotRenderClockSchema = z.strictObject({
+  kind: z.literal("shot"), sceneStartUs: SpatialTimeUsSchema,
+  playback: z.enum(["once", "loop", "freeze"]),
+});
+export type SpatialShotRenderClock = Readonly<z.infer<typeof SpatialShotRenderClockSchema>>;
+const RequestSchema = z.strictObject({
+  clock: SpatialShotRenderClockSchema,
+  relativeTimeUs: z.strictObject({ numerator: z.string().regex(/^(?:0|[1-9][0-9]{0,23})$/u), denominator: z.string().regex(/^[1-9][0-9]{0,12}$/u) }),
+  sceneDurationUs: SpatialTimeUsSchema.refine(value => value > 0),
+});
+
+/** Exact shot-local → scene clock mapping occurs before the sole author-time quantization. */
+export function spatialShotSceneTime(input: unknown) {
+  const request = parseSpatialValue(RequestSchema, input, "spatial shot clock");
+  const d = BigInt(request.relativeTimeUs.denominator), relative = BigInt(request.relativeTimeUs.numerator);
+  const end = BigInt(request.sceneDurationUs) * d;
+  if (request.clock.sceneStartUs >= request.sceneDurationUs || relative > BigInt(SPATIAL_SCENE_LIMITS.durationUs) * d) throw new SpatialSceneError("invalid-data", "Shot clock start or relative sample exceeds its bounded duration.");
+  let n = BigInt(request.clock.sceneStartUs) * d + relative;
+  if (request.clock.playback === "loop") n %= end;
+  else if (request.clock.playback === "freeze") n = n > end ? end : n;
+  else if (n >= end) throw new SpatialSceneError("invalid-data", "Once shot sample lies outside the exact half-open scene duration.");
+  let a = n, b = d;
+  while (b !== 0n) { const remainder = a % b; a = b; b = remainder; }
+  return deepFreezeJson({ exactTimeUs: { numerator: String(n / a), denominator: String(d / a) },
+    timeUs: Number((2n * n + d) / (2n * d)) });
+}

package/apps/desktop/core/speech-analysis.ts

@@ -0,0 +1,333 @@
+import {
+  FillerCandidateSchema,
+  SpeechAnalysisV1Schema,
+  TranscriptWordSchema,
+  type AnalysisSubject,
+  type FillerCandidate,
+  type MusicAnalysisV1,
+  type SpeechAnalysisV1,
+} from "../contracts/analysis";
+
+type SourceRange = { readonly endUs: number; readonly startUs: number };
+type TranscribedResult = Extract<SpeechAnalysisV1["result"], { readonly status: "transcribed" }>;
+type TranscriptWord = TranscribedResult["words"][number];
+type SpeechUtterance = TranscribedResult["utterances"][number];
+
+const FILLED_PAUSES = new Set(["ah", "eh", "er", "erm", "hm", "hmm", "mm", "uh", "uhh", "um", "umm"]);
+const CONTEXTUAL_FILLERS = new Set(["actually", "like", "well"]);
+const PHRASE_FILLERS = [
+  { confidence: 0.97, tokens: ["you", "know"] },
+  { confidence: 0.97, tokens: ["i", "mean"] },
+  { confidence: 0.93, tokens: ["sort", "of"] },
+  { confidence: 0.9, tokens: ["kind", "of"] },
+  { confidence: 0.92, tokens: ["basically"] },
+  { confidence: 0.91, tokens: ["literally"] },
+] as const;
+
+export interface SpeechWordInput {
+  readonly confidence: number;
+  readonly range: SourceRange;
+  readonly speaker?: string | null;
+  readonly text: string;
+}
+
+export interface MusicProtectionRegion {
+  readonly range: SourceRange;
+}
+
+export interface DetectedFillerSpan {
+  readonly classification: FillerCandidate["classification"];
+  readonly lexicalConfidence: number;
+  readonly wordEndExclusive: number;
+  readonly wordStart: number;
+}
+
+export interface AnalyzeSpeechInput {
+  readonly analysisId: string;
+  readonly config: SpeechAnalysisV1["config"];
+  readonly createdAt: string;
+  readonly detectedLanguage: string;
+  readonly durationUs: number;
+  readonly inputDigest: string;
+  readonly musicRegions?: readonly MusicProtectionRegion[] | MusicAnalysisV1["musicRegions"];
+  readonly subject: AnalysisSubject;
+  readonly tool: SpeechAnalysisV1["tool"];
+  readonly words: readonly SpeechWordInput[];
+}
+
+function clamp(value: number, minimum = 0, maximum = 1): number {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+function normalizedToken(text: string): string {
+  return text.normalize("NFKC").toLocaleLowerCase("en-US")
+    .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+}
+
+function hasFalseStartMarker(text: string): boolean {
+  return /(?:-|–|—|\.\.)$/u.test(text.trim());
+}
+
+function phraseAt(tokens: readonly string[], index: number): DetectedFillerSpan | null {
+  for (const phrase of PHRASE_FILLERS) {
+    if (phrase.tokens.every((token, offset) => tokens[index + offset] === token)) {
+      return {
+        classification: "phrase-filler",
+        lexicalConfidence: phrase.confidence,
+        wordEndExclusive: index + phrase.tokens.length,
+        wordStart: index,
+      };
+    }
+  }
+  return null;
+}
+
+function spansOverlap(left: DetectedFillerSpan, right: DetectedFillerSpan): boolean {
+  return left.wordStart < right.wordEndExclusive && right.wordStart < left.wordEndExclusive;
+}
+
+/** Merge adjacent detections of the same class without crossing a lexical gap. */
+export function mergeFillerSpans(
+  spans: readonly DetectedFillerSpan[],
+): readonly DetectedFillerSpan[] {
+  const ordered = [...spans].sort((left, right) => left.wordStart - right.wordStart
+    || right.wordEndExclusive - left.wordEndExclusive
+    || left.classification.localeCompare(right.classification));
+  const merged: DetectedFillerSpan[] = [];
+  for (const span of ordered) {
+    const prior = merged.at(-1);
+    if (
+      prior !== undefined
+      && prior.classification === span.classification
+      && span.wordStart <= prior.wordEndExclusive
+    ) {
+      merged[merged.length - 1] = {
+        classification: prior.classification,
+        lexicalConfidence: Math.min(prior.lexicalConfidence, span.lexicalConfidence),
+        wordEndExclusive: Math.max(prior.wordEndExclusive, span.wordEndExclusive),
+        wordStart: prior.wordStart,
+      };
+    } else if (prior === undefined || !spansOverlap(prior, span)) {
+      merged.push(span);
+    }
+  }
+  return merged;
+}
+
+/** Classify lexical filler spans. A standalone `like` is always contextual. */
+export function classifyFillerWords(words: readonly Pick<SpeechWordInput, "text">[]): readonly DetectedFillerSpan[] {
+  const tokens = words.map(word => normalizedToken(word.text));
+  const primary: DetectedFillerSpan[] = [];
+  for (let index = 0; index < words.length;) {
+    if (FILLED_PAUSES.has(tokens[index] ?? "")) {
+      let end = index + 1;
+      while (end < words.length && FILLED_PAUSES.has(tokens[end] ?? "")) end += 1;
+      primary.push({
+        classification: "filled-pause",
+        lexicalConfidence: 0.99,
+        wordEndExclusive: end,
+        wordStart: index,
+      });
+      index = end;
+      continue;
+    }
+    const phrase = phraseAt(tokens, index);
+    if (phrase !== null) {
+      primary.push(phrase);
+      index = phrase.wordEndExclusive;
+      continue;
+    }
+    if (hasFalseStartMarker(words[index]?.text ?? "")) {
+      primary.push({
+        classification: "false-start",
+        lexicalConfidence: 0.94,
+        wordEndExclusive: index + 1,
+        wordStart: index,
+      });
+      index += 1;
+      continue;
+    }
+    if (CONTEXTUAL_FILLERS.has(tokens[index] ?? "")) {
+      primary.push({
+        classification: "contextual",
+        lexicalConfidence: tokens[index] === "like" ? 0.82 : 0.76,
+        wordEndExclusive: index + 1,
+        wordStart: index,
+      });
+    }
+    index += 1;
+  }
+
+  const repetitions: DetectedFillerSpan[] = [];
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index] ?? "";
+    if (token === "" || token !== tokens[index - 1]) continue;
+    const repetition: DetectedFillerSpan = {
+      classification: "repetition",
+      lexicalConfidence: 0.96,
+      wordEndExclusive: index + 1,
+      wordStart: index,
+    };
+    if (!primary.some(span => spansOverlap(span, repetition))) repetitions.push(repetition);
+  }
+  return mergeFillerSpans([...primary, ...repetitions]);
+}
+
+function rangesOverlap(left: SourceRange, right: SourceRange): boolean {
+  return left.startUs < right.endUs && right.startUs < left.endUs;
+}
+
+function transcriptWords(words: readonly SpeechWordInput[], durationUs: number): readonly TranscriptWord[] {
+  const ordered = [...words].sort((left, right) => left.range.startUs - right.range.startUs
+    || left.range.endUs - right.range.endUs
+    || left.text.localeCompare(right.text));
+  const parsed = ordered.map((word, wordIndex) => TranscriptWordSchema.parse({
+    confidence: word.confidence,
+    range: word.range,
+    speaker: word.speaker ?? null,
+    text: word.text,
+    wordIndex,
+  }));
+  for (let index = 0; index < parsed.length; index += 1) {
+    const word = parsed[index]!;
+    if (word.range.endUs > durationUs) throw new RangeError("Transcript words must fit inside durationUs.");
+    if (index > 0 && word.range.startUs < parsed[index - 1]!.range.endUs) {
+      throw new RangeError("Transcript words must not overlap.");
+    }
+  }
+  return parsed;
+}
+
+function joinWords(words: readonly TranscriptWord[]): string {
+  return words.map(word => word.text).join(" ").replace(/\s+([,.;:!?])/gu, "$1");
+}
+
+/** Group words on speaker changes and one-second transcript gaps. */
+export function deriveSpeechUtterances(
+  words: readonly TranscriptWord[],
+  maximumGapUs = 1_000_000,
+): readonly SpeechUtterance[] {
+  if (!Number.isSafeInteger(maximumGapUs) || maximumGapUs < 0) {
+    throw new TypeError("maximumGapUs must be a nonnegative safe integer.");
+  }
+  const groups: { end: number; start: number }[] = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index]!;
+    const priorWord = words[index - 1];
+    const priorGroup = groups.at(-1);
+    if (
+      priorWord === undefined
+      || priorGroup === undefined
+      || word.range.startUs - priorWord.range.endUs > maximumGapUs
+      || word.speaker !== priorWord.speaker
+    ) {
+      groups.push({ end: index + 1, start: index });
+    } else {
+      priorGroup.end = index + 1;
+    }
+  }
+  return groups.map(group => {
+    const selected = words.slice(group.start, group.end);
+    return {
+      range: { endUs: selected.at(-1)!.range.endUs, startUs: selected[0]!.range.startUs },
+      text: joinWords(selected),
+      wordEndExclusive: group.end,
+      wordStart: group.start,
+    };
+  });
+}
+
+function fillerIdentifier(index: number): FillerCandidate["candidateId"] {
+  return `filler_candidate${String(index + 1).padStart(4, "0")}` as FillerCandidate["candidateId"];
+}
+
+/** Build conservative cut suggestions from lexical spans and acoustic gaps. */
+export function buildFillerCandidates(
+  words: readonly TranscriptWord[],
+  config: SpeechAnalysisV1["config"],
+  durationUs: number,
+  musicRegions: readonly MusicProtectionRegion[] = [],
+): readonly FillerCandidate[] {
+  const spans = classifyFillerWords(words);
+  const candidates: FillerCandidate[] = [];
+  for (const span of spans) {
+    const selected = words.slice(span.wordStart, span.wordEndExclusive);
+    const first = selected[0];
+    const last = selected.at(-1);
+    if (first === undefined || last === undefined) continue;
+    const range = { endUs: last.range.endUs, startUs: first.range.startUs };
+    const transcriptConfidence = Math.min(...selected.map(word => word.confidence));
+    const confidence = clamp(span.lexicalConfidence * transcriptConfidence);
+    if (confidence < config.minimumFillerConfidence) continue;
+    const prior = words[span.wordStart - 1];
+    const next = words[span.wordEndExclusive];
+    const beforeGapUs = prior === undefined ? range.startUs : Math.max(0, range.startUs - prior.range.endUs);
+    const afterGapUs = next === undefined ? Math.max(0, durationUs - range.endUs) : Math.max(0, next.range.startUs - range.endUs);
+    const boundaryScale = Math.max(1, config.speechHandleUs);
+    const acousticBoundaryConfidence = config.speechHandleUs === 0
+      ? 1
+      : Math.min(clamp(beforeGapUs / boundaryScale), clamp(afterGapUs / boundaryScale));
+    const contextual = span.classification === "contextual";
+    const proposedCut = {
+      endUs: Math.min(durationUs, range.endUs + Math.min(config.speechHandleUs, afterGapUs)),
+      startUs: Math.max(0, range.startUs - Math.min(config.speechHandleUs, beforeGapUs)),
+    };
+    const musicProtected = musicRegions.some(region =>
+      rangesOverlap(range, region.range) || rangesOverlap(proposedCut, region.range));
+    const recommendedCut = musicProtected || contextual ? null : proposedCut;
+    const autoApplicable = recommendedCut !== null
+      && !musicProtected
+      && !contextual
+      && confidence >= 0.9
+      && acousticBoundaryConfidence >= 0.8;
+    candidates.push(FillerCandidateSchema.parse({
+      acousticBoundaryConfidence,
+      autoApplicable,
+      candidateId: fillerIdentifier(candidates.length),
+      classification: span.classification,
+      confidence,
+      musicProtected,
+      range,
+      recommendedCut,
+      text: joinWords(selected),
+      wordEndExclusive: span.wordEndExclusive,
+      wordStart: span.wordStart,
+    }));
+  }
+  return candidates;
+}
+
+/** Analyze an owned word transcript into safe, inspectable filler suggestions. */
+export function analyzeSpeech(input: AnalyzeSpeechInput): SpeechAnalysisV1 {
+  if (!Number.isSafeInteger(input.durationUs) || input.durationUs < 0) {
+    throw new TypeError("durationUs must be a nonnegative safe integer.");
+  }
+  const base = {
+    analysisId: input.analysisId,
+    config: input.config,
+    createdAt: input.createdAt,
+    durationUs: input.durationUs,
+    inputDigest: input.inputDigest,
+    kind: "slopcamera.speech-analysis" as const,
+    schemaVersion: 1 as const,
+    subject: input.subject,
+    tool: input.tool,
+  };
+  if (input.words.length === 0) {
+    return SpeechAnalysisV1Schema.parse({
+      ...base,
+      result: { detectedLanguage: input.detectedLanguage || null, reason: "no-speech", status: "no-speech" },
+    });
+  }
+  const words = transcriptWords(input.words, input.durationUs);
+  return SpeechAnalysisV1Schema.parse({
+    ...base,
+    result: {
+      detectedLanguage: input.detectedLanguage,
+      fillers: buildFillerCandidates(words, input.config, input.durationUs, input.musicRegions ?? []),
+      status: "transcribed",
+      utterances: deriveSpeechUtterances(words),
+      words,
+    },
+  });
+}