@morshoto/framekit 0.1.0 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README.md +42 -17
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +86 -2
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -1
  4. package/dist-package/adapters/final-cut/typescript/src/export.js +231 -8
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +70 -9
  6. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  7. package/dist-package/adapters/final-cut/typescript/src/native.js +1000 -100
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +242 -30
  9. package/dist-package/adapters/final-cut/typescript/src/session.js +86 -9
  10. package/dist-package/apps/mcp-server/src/main.js +10 -1
  11. package/dist-package/apps/mcp-server/src/routing.js +172 -0
  12. package/dist-package/apps/mcp-server/src/server.js +867 -52
  13. package/dist-package/apps/mcp-server/src/version.js +34 -0
  14. package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
  15. package/dist-package/packages/runtime/src/application/media-analysis-service.js +473 -0
  16. package/dist-package/packages/runtime/src/application/project-service.js +146 -0
  17. package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
  18. package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
  19. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
  20. package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
  21. package/dist-package/packages/runtime/src/capabilities.js +187 -1
  22. package/dist-package/packages/runtime/src/color-correction.js +48 -0
  23. package/dist-package/packages/runtime/src/context/context-engine.js +20 -6
  24. package/dist-package/packages/runtime/src/context/context-service.js +30 -0
  25. package/dist-package/packages/runtime/src/context/revision.js +3 -0
  26. package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/context.js +1 -0
  28. package/dist-package/packages/runtime/src/domain/diff.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/duration.js +1 -0
  30. package/dist-package/packages/runtime/src/domain/editing.js +1 -0
  31. package/dist-package/packages/runtime/src/domain/index.js +12 -0
  32. package/dist-package/packages/runtime/src/domain/media.js +8 -0
  33. package/dist-package/packages/runtime/src/domain/ports.js +1 -0
  34. package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/project.js +1 -0
  36. package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
  37. package/dist-package/packages/runtime/src/domain/skills.js +33 -0
  38. package/dist-package/packages/runtime/src/domain/types.js +5 -1
  39. package/dist-package/packages/runtime/src/domain/verification.js +1 -0
  40. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
  41. package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
  42. package/dist-package/packages/runtime/src/editing/edit-service.js +449 -0
  43. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +361 -0
  44. package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
  45. package/dist-package/packages/runtime/src/index.js +14 -3
  46. package/dist-package/packages/runtime/src/planning/rough-cut.js +71 -0
  47. package/dist-package/packages/runtime/src/runtime.js +131 -826
  48. package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
  49. package/dist-package/packages/runtime/src/skills/index.js +3 -0
  50. package/dist-package/packages/runtime/src/skills/registry.js +74 -0
  51. package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
  52. package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
  53. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  54. package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
  55. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  56. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
  57. package/dist-package/packages/runtime/src/timeline/rational-time.js +63 -0
  58. package/dist-package/packages/runtime/src/verification/verification.js +712 -1
  59. package/dist-package/packages/testkit/src/fixture-analyzers.js +28 -0
  60. package/dist-package/packages/testkit/src/in-memory-editor.js +287 -3
  61. package/dist-package/packages/testkit/src/index.js +1 -0
  62. package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
  63. package/package.json +17 -8
  64. /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
  65. /package/dist-package/packages/runtime/src/{snapshot-digest.js → timeline/snapshot-digest.js} +0 -0
@@ -0,0 +1,239 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { sameRevision } from "../context/revision.js";
3
+ import { assertSkillRequirements, resolveSkillRequirements, } from "./requirements.js";
4
+ import { SkillRegistry } from "./registry.js";
5
+ export class SkillRuntime {
6
+ project;
7
+ analysis;
8
+ edits;
9
+ options;
10
+ registry = new SkillRegistry();
11
+ previews = new Map();
12
+ constructor(project, analysis, edits, options = {}) {
13
+ this.project = project;
14
+ this.analysis = analysis;
15
+ this.edits = edits;
16
+ this.options = options;
17
+ }
18
+ register(definition) {
19
+ this.registry.register(definition);
20
+ }
21
+ list() {
22
+ return this.registry.list();
23
+ }
24
+ inspect(skillId, version) {
25
+ return this.registry.inspect(skillId, version);
26
+ }
27
+ async listAvailability() {
28
+ const context = await this.currentResolutionContext();
29
+ return this.registry.list().map((manifest) => ({
30
+ manifest,
31
+ availability: resolveAvailability(manifest, context),
32
+ }));
33
+ }
34
+ async inspectAvailability(skillId, version) {
35
+ const manifest = this.registry.inspect(skillId, version);
36
+ const context = await this.currentResolutionContext();
37
+ return { manifest, availability: resolveAvailability(manifest, context) };
38
+ }
39
+ async preview(request) {
40
+ const definition = this.registry.lookup(request.skillId, request.version);
41
+ const before = await this.project.inspectProject();
42
+ if (!sameRevision(request.baseRevision, before.revision)) {
43
+ throw new Error("STALE_CONTEXT: Skill preview base revision does not match current editor state");
44
+ }
45
+ const inspected = await this.project.inspectEditor();
46
+ assertSkillRequirements(definition.manifest, {
47
+ capabilities: inspected.capabilities,
48
+ editor: inspected.identity,
49
+ revision: before.revision,
50
+ });
51
+ this.assertInputSchema(definition.manifest.inputSchema, request.input);
52
+ const normalizedInput = await normalizeInput(definition, request.input);
53
+ const handlerContext = Object.freeze({
54
+ project: structuredClone(before),
55
+ capabilities: structuredClone(inspected.capabilities),
56
+ baseRevision: structuredClone(before.revision),
57
+ analyzeSpeech: (mediaId, range) => this.analysis.analyzeSpeech(mediaId, range),
58
+ measureAudio: (mediaId, occurrenceId) => this.analysis.measureAudio(mediaId, occurrenceId),
59
+ measureNoise: (mediaId, occurrenceId) => this.analysis.measureNoise(mediaId, occurrenceId),
60
+ });
61
+ const planned = await definition.handler.plan(handlerContext, normalizedInput);
62
+ const plan = {
63
+ id: `plan-${randomUUID()}`,
64
+ skillId: definition.manifest.id,
65
+ skillVersion: definition.manifest.version,
66
+ baseRevision: structuredClone(before.revision),
67
+ normalizedInput: structuredClone(normalizedInput),
68
+ operations: structuredClone(planned.operations),
69
+ affectedRanges: structuredClone(planned.affectedRanges),
70
+ warnings: [...planned.warnings],
71
+ ...(planned.verification ? { verification: structuredClone(planned.verification) } : {}),
72
+ ...(planned.details ? { details: structuredClone(planned.details) } : {}),
73
+ };
74
+ const editPreview = plan.operations.length > 0
75
+ ? await this.edits.previewEdit({
76
+ baseRevision: before.revision,
77
+ operations: plan.operations,
78
+ verification: plan.verification ?? definition.manifest.verification,
79
+ })
80
+ : undefined;
81
+ const previewToken = `skill-preview-${randomUUID()}`;
82
+ const preview = {
83
+ previewToken,
84
+ plan,
85
+ ...(editPreview?.expectedDiff ? { expectedDiff: editPreview.expectedDiff } : {}),
86
+ expiresAt: editPreview?.expiresAt ?? new Date(this.now() + (this.options.previewTtlMs ?? 30_000)).toISOString(),
87
+ };
88
+ this.prunePreviews();
89
+ this.previews.set(previewToken, { preview, ...(editPreview ? { editPreviewToken: editPreview.previewToken } : {}) });
90
+ return structuredClone(preview);
91
+ }
92
+ async execute(previewToken) {
93
+ const session = this.previews.get(previewToken);
94
+ if (!session)
95
+ throw new Error(`SKILL_PREVIEW_TOKEN_INVALID: unknown or already used preview ${previewToken}`);
96
+ this.previews.delete(previewToken);
97
+ if (this.now() > Date.parse(session.preview.expiresAt)) {
98
+ throw new Error("SKILL_PREVIEW_TOKEN_EXPIRED: Skill preview has expired");
99
+ }
100
+ const definition = this.registry.lookup(session.preview.plan.skillId, session.preview.plan.skillVersion);
101
+ const before = await this.project.inspectProject();
102
+ if (!sameRevision(session.preview.plan.baseRevision, before.revision)) {
103
+ throw new Error("STALE_CONTEXT: Skill preview base revision does not match current editor state");
104
+ }
105
+ const inspected = await this.project.inspectEditor();
106
+ assertSkillRequirements(definition.manifest, {
107
+ capabilities: inspected.capabilities,
108
+ editor: inspected.identity,
109
+ revision: before.revision,
110
+ });
111
+ if (!session.editPreviewToken) {
112
+ return {
113
+ status: "SKIPPED",
114
+ plan: {
115
+ id: session.preview.plan.id,
116
+ skillId: session.preview.plan.skillId,
117
+ skillVersion: session.preview.plan.skillVersion,
118
+ baseRevision: structuredClone(session.preview.plan.baseRevision),
119
+ },
120
+ transactionIds: [],
121
+ rollback: { attempted: false, succeeded: true, transactionIds: [] },
122
+ };
123
+ }
124
+ const transaction = await this.edits.executeEdit(session.editPreviewToken);
125
+ const rolledBack = transaction.status === "ROLLED_BACK";
126
+ return {
127
+ status: rolledBack ? "ROLLED_BACK" : transaction.status === "VERIFIED" ? "VERIFIED" : "FAILED",
128
+ plan: {
129
+ id: session.preview.plan.id,
130
+ skillId: session.preview.plan.skillId,
131
+ skillVersion: session.preview.plan.skillVersion,
132
+ baseRevision: structuredClone(session.preview.plan.baseRevision),
133
+ },
134
+ transactionIds: [transaction.id],
135
+ diff: structuredClone(transaction.diff),
136
+ ...(transaction.verification ? { verification: structuredClone(transaction.verification) } : {}),
137
+ rollback: {
138
+ attempted: rolledBack,
139
+ succeeded: rolledBack,
140
+ transactionIds: rolledBack ? [transaction.id] : [],
141
+ },
142
+ };
143
+ }
144
+ assertInputSchema(schema, input) {
145
+ if (!isRecord(input))
146
+ throw new Error("SKILL_INPUT_INVALID: input must be an object");
147
+ for (const required of schema.required ?? []) {
148
+ if (!(required in input))
149
+ throw new Error(`SKILL_INPUT_INVALID: missing required input ${required}`);
150
+ }
151
+ if (schema.additionalProperties === false) {
152
+ for (const key of Object.keys(input)) {
153
+ if (!(key in schema.properties))
154
+ throw new Error(`SKILL_INPUT_INVALID: unknown input ${key}`);
155
+ }
156
+ }
157
+ for (const [key, property] of Object.entries(schema.properties)) {
158
+ if (key in input)
159
+ validateSchemaValue(property, input[key], key);
160
+ }
161
+ }
162
+ prunePreviews() {
163
+ const now = this.now();
164
+ for (const [token, session] of this.previews) {
165
+ if (now > Date.parse(session.preview.expiresAt))
166
+ this.previews.delete(token);
167
+ }
168
+ const limit = Number.isInteger(this.options.maxActivePreviews) && this.options.maxActivePreviews > 0
169
+ ? this.options.maxActivePreviews
170
+ : 128;
171
+ while (this.previews.size >= limit) {
172
+ const oldest = this.previews.keys().next().value;
173
+ if (oldest === undefined)
174
+ break;
175
+ this.previews.delete(oldest);
176
+ }
177
+ }
178
+ now() {
179
+ return this.options.now?.() ?? Date.now();
180
+ }
181
+ async currentResolutionContext() {
182
+ return { inspected: await this.project.inspectEditor() };
183
+ }
184
+ }
185
+ async function normalizeInput(definition, input) {
186
+ try {
187
+ const normalized = await definition.handler.normalize(input);
188
+ if (!isRecord(normalized))
189
+ throw new Error("normalized input must be an object");
190
+ return normalized;
191
+ }
192
+ catch (error) {
193
+ throw new Error(`SKILL_INPUT_INVALID: ${String(error)}`);
194
+ }
195
+ }
196
+ function validateSchemaValue(schema, value, path) {
197
+ if (schema.type === "object") {
198
+ if (!isRecord(value))
199
+ throw new Error(`SKILL_INPUT_INVALID: ${path} must be an object`);
200
+ return;
201
+ }
202
+ if (schema.type === "array") {
203
+ if (!Array.isArray(value))
204
+ throw new Error(`SKILL_INPUT_INVALID: ${path} must be an array`);
205
+ if (schema.minItems !== undefined && value.length < schema.minItems)
206
+ throw new Error(`SKILL_INPUT_INVALID: ${path} has too few items`);
207
+ value.forEach((item, index) => validateSchemaValue(schema.items, item, `${path}[${index}]`));
208
+ return;
209
+ }
210
+ const valid = schema.type === "string"
211
+ ? typeof value === "string"
212
+ : schema.type === "boolean"
213
+ ? typeof value === "boolean"
214
+ : typeof value === "number" && Number.isFinite(value) && (schema.type !== "integer" || Number.isInteger(value));
215
+ if (!valid)
216
+ throw new Error(`SKILL_INPUT_INVALID: ${path} has type ${schema.type}`);
217
+ if (schema.type === "string" && schema.minLength !== undefined && value.length < schema.minLength) {
218
+ throw new Error(`SKILL_INPUT_INVALID: ${path} is too short`);
219
+ }
220
+ if ((schema.type === "number" || schema.type === "integer") && schema.minimum !== undefined && value < schema.minimum) {
221
+ throw new Error(`SKILL_INPUT_INVALID: ${path} is below minimum`);
222
+ }
223
+ if ((schema.type === "number" || schema.type === "integer") && schema.maximum !== undefined && value > schema.maximum) {
224
+ throw new Error(`SKILL_INPUT_INVALID: ${path} is above maximum`);
225
+ }
226
+ if (schema.type === "string" && schema.enum && !schema.enum.includes(value)) {
227
+ throw new Error(`SKILL_INPUT_INVALID: ${path} is not an allowed value`);
228
+ }
229
+ }
230
+ function isRecord(value) {
231
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
232
+ }
233
+ function resolveAvailability(manifest, context) {
234
+ return resolveSkillRequirements(manifest, {
235
+ capabilities: context.inspected.capabilities,
236
+ editor: context.inspected.identity,
237
+ revision: context.project?.revision,
238
+ });
239
+ }
@@ -0,0 +1,301 @@
1
+ import { SPEECH_ANALYSIS_SCHEMA_VERSION } from "../domain/media.js";
2
+ import { sameMediaSourceIdentity } from "../domain/media.js";
3
+ import { parseRational } from "../timeline/rational-time.js";
4
+ export const DEFAULT_SPEECH_SOURCE_TIMEBASE = {
5
+ value: "1",
6
+ timescale: "1000",
7
+ };
8
+ /**
9
+ * Validate provider evidence and bind it to the current source and revision.
10
+ * Missing provenance is filled from the trusted runtime request; conflicting
11
+ * provenance is rejected before the evidence can authorize an edit.
12
+ */
13
+ export function bindSpeechAnalysis(value, context) {
14
+ const record = asRecord(value, "speech result must be an object");
15
+ if (record.schemaVersion !== undefined && record.schemaVersion !== SPEECH_ANALYSIS_SCHEMA_VERSION) {
16
+ throw new Error("ANALYSIS_INVALID: unsupported speech analysis schema version");
17
+ }
18
+ const inputIdentity = sourceIdentityOf(context.input.media);
19
+ const mediaId = optionalString(record.mediaId, "speech media ID");
20
+ if (mediaId !== undefined && mediaId !== inputIdentity.mediaId) {
21
+ throw new Error("TARGET_MISMATCH: speech analysis media identity does not match the requested media");
22
+ }
23
+ const sourceIdentity = record.sourceIdentity === undefined
24
+ ? inputIdentity
25
+ : validateSourceIdentity(record.sourceIdentity, inputIdentity);
26
+ const revision = record.revision === undefined
27
+ ? structuredClone(context.input.project.revision)
28
+ : validateRevision(record.revision, context.input.project.revision);
29
+ const provider = record.provider === undefined
30
+ ? context.provider ?? { id: "framekit.speech", provider: "unknown" }
31
+ : validateDescriptor(record.provider);
32
+ const requestedRange = resolveRequestedRange(record.requestedRange, context.range, context.input.media, record);
33
+ const observedRange = record.observedRange === undefined
34
+ ? structuredClone(requestedRange)
35
+ : validateRange(record.observedRange, "observed speech range");
36
+ validateRange(requestedRange, "requested speech range");
37
+ validateObservedRange(observedRange, requestedRange, context.input.media.duration);
38
+ const words = validateWords(record.words, observedRange, context.input.media.duration);
39
+ const vadSegments = validateOptionalSegments(record.vadSegments, "VAD", observedRange, context.input.media.duration);
40
+ const silenceSegments = validateOptionalSegments(record.silenceSegments, "silence", observedRange, context.input.media.duration);
41
+ const protectedSegments = validateOptionalSegments(record.protectedSegments, "protected", observedRange, context.input.media.duration);
42
+ const capability = validateCapability(record.capability, vadSegments);
43
+ const sourceTimebase = record.sourceTimebase === undefined
44
+ ? structuredClone(DEFAULT_SPEECH_SOURCE_TIMEBASE)
45
+ : validateSourceTimebase(record.sourceTimebase);
46
+ return {
47
+ schemaVersion: SPEECH_ANALYSIS_SCHEMA_VERSION,
48
+ mediaId: inputIdentity.mediaId,
49
+ sourceIdentity: structuredClone(sourceIdentity),
50
+ requestedRange: structuredClone(requestedRange),
51
+ observedRange: structuredClone(observedRange),
52
+ revision: structuredClone(revision),
53
+ provider: structuredClone(provider),
54
+ sourceTimebase,
55
+ capability,
56
+ words,
57
+ ...(vadSegments ? { vadSegments } : {}),
58
+ ...(silenceSegments ? { silenceSegments } : {}),
59
+ ...(protectedSegments ? { protectedSegments } : {}),
60
+ };
61
+ }
62
+ function sourceIdentityOf(media) {
63
+ return {
64
+ mediaId: media.mediaId,
65
+ source: media.source,
66
+ ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
67
+ ...(media.mediaKind ? { mediaKind: media.mediaKind } : {}),
68
+ ...(media.duration !== undefined ? { duration: media.duration } : {}),
69
+ };
70
+ }
71
+ function resolveRequestedRange(result, requested, media, record) {
72
+ if (result !== undefined) {
73
+ const resultRange = validateRange(result, "requested speech range");
74
+ if (requested && (resultRange.start !== requested.start || resultRange.end !== requested.end)) {
75
+ throw new Error("ANALYSIS_INVALID: speech requested range does not match the runtime request");
76
+ }
77
+ return resultRange;
78
+ }
79
+ if (requested)
80
+ return structuredClone(requested);
81
+ if (media.duration !== undefined)
82
+ return { start: 0, end: media.duration };
83
+ const evidenceEnd = evidenceMaximumEnd(record);
84
+ if (evidenceEnd <= 0)
85
+ throw new Error("ANALYSIS_INVALID: speech result needs a range or media duration");
86
+ return { start: 0, end: evidenceEnd };
87
+ }
88
+ function evidenceMaximumEnd(record) {
89
+ const values = [];
90
+ for (const key of ["words", "vadSegments", "silenceSegments", "protectedSegments"]) {
91
+ const entries = record[key];
92
+ if (!Array.isArray(entries))
93
+ continue;
94
+ for (const entry of entries) {
95
+ if (entry && typeof entry === "object" && typeof entry.end === "number") {
96
+ values.push(entry.end);
97
+ }
98
+ }
99
+ }
100
+ return values.length > 0 ? Math.max(...values) : 0;
101
+ }
102
+ function validateObservedRange(observed, requested, duration) {
103
+ if (observed.end <= requested.start || observed.start >= requested.end) {
104
+ throw new Error("ANALYSIS_INVALID: observed speech range does not overlap the requested range");
105
+ }
106
+ if (duration !== undefined && observed.end > duration) {
107
+ throw new Error("ANALYSIS_INVALID: observed speech range exceeds media duration");
108
+ }
109
+ }
110
+ function validateWords(value, observed, duration) {
111
+ if (!Array.isArray(value))
112
+ throw new Error("ANALYSIS_INVALID: speech result requires typed words");
113
+ const words = value.map((entry, index) => validateWord(entry, index));
114
+ validateOrderedRanges(words, "speech words");
115
+ validateEvidenceBounds(words, observed, duration, "speech word");
116
+ return words;
117
+ }
118
+ function validateWord(value, index) {
119
+ const word = asRecord(value, `speech word ${index + 1} must be an object`);
120
+ if (typeof word.text !== "string" || !word.text.trim()) {
121
+ throw new Error("ANALYSIS_INVALID: speech word text is required");
122
+ }
123
+ if (!isFiniteNumber(word.start) || !isFiniteNumber(word.end) || word.start < 0 || word.end <= word.start) {
124
+ throw new Error("ANALYSIS_INVALID: speech word boundaries are invalid");
125
+ }
126
+ if (!isFiniteNumber(word.confidence) || word.confidence < 0 || word.confidence > 1) {
127
+ throw new Error("ANALYSIS_INVALID: speech word confidence is invalid");
128
+ }
129
+ if (word.filler !== undefined && typeof word.filler !== "boolean") {
130
+ throw new Error("ANALYSIS_INVALID: speech word filler flag is invalid");
131
+ }
132
+ return {
133
+ text: word.text,
134
+ start: word.start,
135
+ end: word.end,
136
+ confidence: word.confidence,
137
+ ...(word.filler !== undefined ? { filler: word.filler } : {}),
138
+ };
139
+ }
140
+ function validateOptionalSegments(value, label, observed, duration) {
141
+ if (value === undefined)
142
+ return undefined;
143
+ if (!Array.isArray(value))
144
+ throw new Error(`ANALYSIS_INVALID: ${label} segments must be an array`);
145
+ const segments = value.map((entry, index) => validateSegment(entry, index, label));
146
+ validateOrderedRanges(segments, `${label} segments`);
147
+ validateEvidenceBounds(segments, observed, duration, `${label} segment`);
148
+ return segments;
149
+ }
150
+ function validateSegment(value, index, label) {
151
+ const segment = asRecord(value, `${label} segment ${index + 1} must be an object`);
152
+ if (!isFiniteNumber(segment.start) || !isFiniteNumber(segment.end)
153
+ || segment.start < 0 || segment.end <= segment.start) {
154
+ throw new Error(`ANALYSIS_INVALID: ${label} segment boundaries are invalid`);
155
+ }
156
+ if (!["speech", "silence", "breath", "laughter", "noise"].includes(String(segment.kind))) {
157
+ throw new Error(`ANALYSIS_INVALID: ${label} segment kind is invalid`);
158
+ }
159
+ if (segment.confidence !== undefined
160
+ && (!isFiniteNumber(segment.confidence) || segment.confidence < 0 || segment.confidence > 1)) {
161
+ throw new Error(`ANALYSIS_INVALID: ${label} segment confidence is invalid`);
162
+ }
163
+ return {
164
+ start: segment.start,
165
+ end: segment.end,
166
+ kind: segment.kind,
167
+ ...(segment.confidence !== undefined ? { confidence: segment.confidence } : {}),
168
+ };
169
+ }
170
+ function validateEvidenceBounds(evidence, observed, duration, label) {
171
+ for (const entry of evidence) {
172
+ if (entry.start < observed.start || entry.end > observed.end) {
173
+ throw new Error(`ANALYSIS_INVALID: ${label} is outside observed speech range`);
174
+ }
175
+ if (duration !== undefined && entry.end > duration) {
176
+ throw new Error(`ANALYSIS_INVALID: ${label} exceeds media duration`);
177
+ }
178
+ }
179
+ }
180
+ function validateOrderedRanges(evidence, label) {
181
+ for (let index = 1; index < evidence.length; index += 1) {
182
+ const previous = evidence[index - 1];
183
+ const current = evidence[index];
184
+ if (current.start < previous.start || (current.start === previous.start && current.end < previous.end)) {
185
+ throw new Error(`ANALYSIS_INVALID: ${label} must be ordered`);
186
+ }
187
+ if (current.start < previous.end) {
188
+ throw new Error(`ANALYSIS_INVALID: ${label} overlap`);
189
+ }
190
+ }
191
+ }
192
+ function validateCapability(value, vadSegments) {
193
+ const capability = value ?? (vadSegments ? "transcription-plus-vad" : "transcription-only");
194
+ if (capability !== "transcription-only" && capability !== "transcription-plus-vad") {
195
+ throw new Error("ANALYSIS_INVALID: speech capability is unsupported");
196
+ }
197
+ if (capability === "transcription-plus-vad" && !vadSegments) {
198
+ throw new Error("ANALYSIS_INVALID: transcription-plus-vad requires VAD segments");
199
+ }
200
+ if (capability === "transcription-only" && vadSegments) {
201
+ throw new Error("ANALYSIS_INVALID: VAD evidence requires transcription-plus-vad capability");
202
+ }
203
+ return capability;
204
+ }
205
+ function validateSourceIdentity(value, expected) {
206
+ const identity = asRecord(value, "speech source identity must be an object");
207
+ if (typeof identity.mediaId !== "string" || typeof identity.source !== "string") {
208
+ throw new Error("ANALYSIS_INVALID: speech source identity is incomplete");
209
+ }
210
+ const candidate = {
211
+ mediaId: identity.mediaId,
212
+ source: identity.source,
213
+ ...(identity.sourceDigest !== undefined
214
+ ? { sourceDigest: optionalString(identity.sourceDigest, "speech source digest") }
215
+ : expected.sourceDigest !== undefined ? { sourceDigest: expected.sourceDigest } : {}),
216
+ ...(identity.mediaKind !== undefined
217
+ ? { mediaKind: identity.mediaKind }
218
+ : expected.mediaKind !== undefined ? { mediaKind: expected.mediaKind } : {}),
219
+ ...(identity.duration !== undefined
220
+ ? { duration: numberValue(identity.duration, "speech source duration") }
221
+ : expected.duration !== undefined ? { duration: expected.duration } : {}),
222
+ };
223
+ if (!sameMediaSourceIdentity(candidate, expected)) {
224
+ throw new Error("TARGET_MISMATCH: speech analysis source identity does not match the requested media");
225
+ }
226
+ return candidate;
227
+ }
228
+ function validateRevision(value, expected) {
229
+ const revision = asRecord(value, "speech revision must be an object");
230
+ if (typeof revision.id !== "string" || !Number.isInteger(revision.sequence) || typeof revision.timestamp !== "string") {
231
+ throw new Error("ANALYSIS_INVALID: speech revision is incomplete");
232
+ }
233
+ if (revision.id !== expected.id || revision.sequence !== expected.sequence || revision.timestamp !== expected.timestamp) {
234
+ throw new Error("STALE_CONTEXT: speech analysis revision does not match the current editor state");
235
+ }
236
+ return { id: revision.id, sequence: revision.sequence, timestamp: revision.timestamp };
237
+ }
238
+ function validateDescriptor(value) {
239
+ const descriptor = asRecord(value, "speech provider must be an object");
240
+ if (typeof descriptor.id !== "string" || !descriptor.id.trim() || typeof descriptor.provider !== "string" || !descriptor.provider.trim()) {
241
+ throw new Error("ANALYSIS_INVALID: speech provider descriptor is incomplete");
242
+ }
243
+ if (descriptor.version !== undefined && typeof descriptor.version !== "string") {
244
+ throw new Error("ANALYSIS_INVALID: speech provider version is invalid");
245
+ }
246
+ return {
247
+ id: descriptor.id,
248
+ provider: descriptor.provider,
249
+ ...(descriptor.version !== undefined ? { version: descriptor.version } : {}),
250
+ };
251
+ }
252
+ function validateSourceTimebase(value) {
253
+ const timebase = asRecord(value, "speech source timebase must be an object");
254
+ if (typeof timebase.value !== "string" || typeof timebase.timescale !== "string") {
255
+ throw new Error("ANALYSIS_INVALID: speech source timebase is incomplete");
256
+ }
257
+ const parsed = parseRational({ value: timebase.value, timescale: timebase.timescale }, "ANALYSIS_INVALID");
258
+ if (parsed.value <= 0n)
259
+ throw new Error("ANALYSIS_INVALID: speech source timebase must be positive");
260
+ return { value: timebase.value, timescale: timebase.timescale };
261
+ }
262
+ function validateRange(value, label) {
263
+ const range = asRecord(value, `${label} must be an object`);
264
+ if (!isFiniteNumber(range.start) || !isFiniteNumber(range.end) || range.start < 0 || range.end <= range.start) {
265
+ throw new Error(`ANALYSIS_INVALID: ${label} is invalid`);
266
+ }
267
+ return {
268
+ start: range.start,
269
+ end: range.end,
270
+ ...(range.startTime !== undefined ? { startTime: validateRational(range.startTime, `${label} start time`) } : {}),
271
+ ...(range.durationTime !== undefined ? { durationTime: validateRational(range.durationTime, `${label} duration time`) } : {}),
272
+ };
273
+ }
274
+ function validateRational(value, label) {
275
+ const rational = asRecord(value, `${label} must be an object`);
276
+ if (typeof rational.value !== "string" || typeof rational.timescale !== "string") {
277
+ throw new Error(`ANALYSIS_INVALID: ${label} is incomplete`);
278
+ }
279
+ parseRational({ value: rational.value, timescale: rational.timescale }, "ANALYSIS_INVALID");
280
+ return { value: rational.value, timescale: rational.timescale };
281
+ }
282
+ function optionalString(value, label) {
283
+ if (value === undefined)
284
+ return undefined;
285
+ if (typeof value !== "string" || !value.trim())
286
+ throw new Error(`ANALYSIS_INVALID: ${label} is invalid`);
287
+ return value;
288
+ }
289
+ function numberValue(value, label) {
290
+ if (!isFiniteNumber(value))
291
+ throw new Error(`ANALYSIS_INVALID: ${label} is invalid`);
292
+ return value;
293
+ }
294
+ function asRecord(value, message) {
295
+ if (!value || typeof value !== "object" || Array.isArray(value))
296
+ throw new Error(`ANALYSIS_INVALID: ${message}`);
297
+ return value;
298
+ }
299
+ function isFiniteNumber(value) {
300
+ return typeof value === "number" && Number.isFinite(value);
301
+ }
@@ -0,0 +1,132 @@
1
+ import { createHash } from "node:crypto";
2
+ export const DEFAULT_FILLER_VOCABULARY = ["er", "erm", "hmm", "uh", "um"];
3
+ export const DEFAULT_FILLER_CONFIDENCE_THRESHOLD = 0.92;
4
+ const TRAILING_PUNCTUATION = ".,!?;:";
5
+ /** Turn analyzer speech evidence into deterministic, preview-scoped candidates. */
6
+ export class FillerDetector {
7
+ vocabulary;
8
+ confidenceThreshold;
9
+ constructor(options = {}) {
10
+ this.vocabulary = new Set((options.vocabulary ?? DEFAULT_FILLER_VOCABULARY).map(normalizeWord));
11
+ this.confidenceThreshold = options.confidenceThreshold ?? DEFAULT_FILLER_CONFIDENCE_THRESHOLD;
12
+ if (!Number.isFinite(this.confidenceThreshold)
13
+ || this.confidenceThreshold < 0
14
+ || this.confidenceThreshold > 1) {
15
+ throw new Error("INVALID_OPERATION: filler confidence threshold must be between 0 and 1");
16
+ }
17
+ }
18
+ detect(input) {
19
+ validateInput(input);
20
+ const words = orderAndValidateWords(input.analysis.words);
21
+ const source = input.occurrence.sourceRange;
22
+ const sequence = input.occurrence.sequenceRange;
23
+ const sourceDuration = source.end - source.start;
24
+ const sequenceDuration = sequence.end - sequence.start;
25
+ if (Math.abs(sourceDuration - sequenceDuration) > 0.000001) {
26
+ throw new Error("AMBIGUOUS_MAPPING: source and sequence occurrence durations differ");
27
+ }
28
+ return words.flatMap((word) => {
29
+ const analyzerMarkedFiller = word.filler === true;
30
+ const vocabularyMatch = this.vocabulary.has(normalizeWord(word.text));
31
+ if (!analyzerMarkedFiller && !vocabularyMatch)
32
+ return [];
33
+ if (word.start < source.start || word.end > source.end)
34
+ return [];
35
+ const sequenceRange = {
36
+ start: sequence.start + (word.start - source.start),
37
+ end: sequence.start + (word.end - source.start),
38
+ };
39
+ const withinTarget = containsRange(input.targetRange, sequenceRange);
40
+ if (!withinTarget)
41
+ return [];
42
+ const eligible = word.confidence >= this.confidenceThreshold;
43
+ const reasonCodes = [];
44
+ if (analyzerMarkedFiller)
45
+ reasonCodes.push("ANALYZER_MARKED_FILLER");
46
+ if (vocabularyMatch)
47
+ reasonCodes.push("VOCABULARY_MATCH");
48
+ if (!eligible)
49
+ reasonCodes.push("BELOW_CONFIDENCE_THRESHOLD");
50
+ const sourceRange = { start: word.start, end: word.end };
51
+ const candidate = {
52
+ id: stableCandidateId(input, sourceRange),
53
+ word: { ...word },
54
+ wordEvidence: { ...word },
55
+ confidence: word.confidence,
56
+ confidenceThreshold: this.confidenceThreshold,
57
+ eligible,
58
+ occurrenceId: input.occurrence.occurrenceId,
59
+ ...(input.occurrence.mediaId ? { mediaId: input.occurrence.mediaId } : {}),
60
+ sourceRange,
61
+ sequenceRange,
62
+ reasonCodes,
63
+ evidence: {
64
+ word: { ...word },
65
+ analyzerMarkedFiller,
66
+ vocabularyMatch,
67
+ withinTarget,
68
+ },
69
+ };
70
+ return [candidate];
71
+ });
72
+ }
73
+ }
74
+ function validateInput(input) {
75
+ if (!input.previewId.trim())
76
+ throw new Error("INVALID_OPERATION: filler preview ID is required");
77
+ validateRange(input.targetRange, "target range");
78
+ validateRange(input.occurrence.sourceRange, "source occurrence range");
79
+ validateRange(input.occurrence.sequenceRange, "sequence occurrence range");
80
+ if (!input.occurrence.occurrenceId.trim()) {
81
+ throw new Error("INVALID_OPERATION: filler occurrence ID is required");
82
+ }
83
+ }
84
+ function orderAndValidateWords(words) {
85
+ const ordered = words
86
+ .map((word) => ({ ...word }))
87
+ .sort((left, right) => left.start - right.start || left.end - right.end || left.text.localeCompare(right.text));
88
+ for (let index = 0; index < ordered.length; index += 1) {
89
+ const word = ordered[index];
90
+ if (!word.text.trim()
91
+ || !Number.isFinite(word.start)
92
+ || !Number.isFinite(word.end)
93
+ || word.start < 0
94
+ || word.end <= word.start
95
+ || !Number.isFinite(word.confidence)
96
+ || word.confidence < 0
97
+ || word.confidence > 1) {
98
+ throw new Error("ANALYSIS_INVALID: speech word boundaries or confidence");
99
+ }
100
+ const previous = ordered[index - 1];
101
+ if (previous && previous.end > word.start) {
102
+ throw new Error("ANALYSIS_INVALID: speech word boundaries overlap");
103
+ }
104
+ }
105
+ return ordered;
106
+ }
107
+ function validateRange(range, label) {
108
+ if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.end <= range.start) {
109
+ throw new Error(`INVALID_OPERATION: filler ${label} must be positive`);
110
+ }
111
+ }
112
+ function containsRange(container, candidate) {
113
+ return candidate.start >= container.start && candidate.end <= container.end;
114
+ }
115
+ function normalizeWord(text) {
116
+ const normalized = text.trim().toLocaleLowerCase();
117
+ let end = normalized.length;
118
+ while (end > 0 && TRAILING_PUNCTUATION.includes(normalized.charAt(end - 1))) {
119
+ end -= 1;
120
+ }
121
+ return normalized.slice(0, end);
122
+ }
123
+ function stableCandidateId(input, sourceRange) {
124
+ const identity = JSON.stringify({
125
+ previewId: input.previewId,
126
+ revisionId: input.revisionId ?? "",
127
+ occurrenceId: input.occurrence.occurrenceId,
128
+ mediaId: input.occurrence.mediaId ?? "",
129
+ sourceRange,
130
+ });
131
+ return `filler-candidate-${createHash("sha256").update(identity).digest("hex").slice(0, 24)}`;
132
+ }