@speclip/pi-subtitles 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Speclip contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @speclip/pi-subtitles
+
+给 [Pi](https://pi.dev) 使用的字幕决策插件包。它把 ASR 词级时间戳映射到完成 A-roll 剪辑后的成片时间轴，由 Agent 审阅断句、标点和换行，再导出可追溯的 UTF-8 SRT / ASS 字幕轨道。
+
+它不直接烧录视频，也不把任意 FFmpeg 参数塞进 Agent 工具。字幕判断与视频渲染保持分离：本包负责“字幕写什么、何时出现、如何分行”，支持字幕轨道的渲染器负责最终画面合成与视觉验收。
+
+## 能力边界
+
+- 输入：`pi-speech` 兼容的词级 JSON 转录，也兼容常见 `{ word, start, end }` 秒级结构。
+- A-roll 映射：按保留源片段压缩时间轴；字幕不会跨越剪辑点。
+- 自动分段：结合标点、停顿、字数、时长和阅读速度生成初稿。
+- Agent 审阅：通过不可变 revision 修正 ASR 文本、标点、断句和换行。
+- 导出：标准 SRT；可选带样式的 ASS；两者都不覆盖已有文件。
+- 溯源：绑定原转录哈希、精确 revision、输出哈希和持久化导出回执。
+
+B-roll 只覆盖画面而保留 A-roll 主音频时，不会改变字幕时间。若后续改变了语速、主音频或 A-roll 片段顺序，应新建字幕项目。
+
+## 环境要求
+
+- Node.js 22.19+
+- Pi 0.84.1–0.84.x
+- 一份含词级时间戳的 JSON 转录
+
+## 安装与验证
+
+```bash
+npm install
+npm run check
+pi install ./
+```
+
+也可以安装发布包：
+
+```bash
+pi install npm:@speclip/pi-subtitles
+```
+
+## 工具工作流
+
+### 1. 创建字幕项目
+
+无 A-roll 剪辑时，只传源时长：
+
+```js
+subtitles_create {
+  projectId: "launch-captions",
+  transcriptPath: "transcripts/launch.json",
+  sourceDurationMs: 93224
+}
+```
+
+有 A-roll 剪辑时，必须传最终保留的源区间：
+
+```js
+subtitles_create {
+  projectId: "launch-captions",
+  transcriptPath: "transcripts/launch.json",
+  sourceDurationMs: 93224,
+  timelineSegments: [
+    { id: "a-001", sourceStartMs: 0, sourceEndMs: 12400 },
+    { id: "a-002", sourceStartMs: 13100, sourceEndMs: 28700 },
+    { id: "a-003", sourceStartMs: 29400, sourceEndMs: 93224 }
+  ]
+}
+```
+
+计算关系为：
+
+```text
+成片时间 = 前面所有保留片段的累计时长 + 词源时间 - 当前片段源起点
+```
+
+若一个词跨过剪辑边界，工具会拒绝创建，要求回到 A-roll 调整到词间安全边界。
+
+### 2. 分页审阅全部字幕
+
+```js
+subtitles_get {
+  projectId: "launch-captions",
+  offset: 0,
+  limit: 100
+}
+```
+
+自动结果只是初稿。Agent 应结合实际音频检查文本、术语、标点、语义分组、阅读速度和两行布局，并继续翻页直到 `hasMore: false`。
+
+默认策略适合中文口播：每行最多 16 个可见字符、最多两行；目标 12–20 字、1.5–4.5 秒、约 9 字/秒。它们用于找更自然的解，不要求每条字幕机械一致。极端时间戳冲突只会局部放宽，不会让整段字幕坍缩为一条或退化成逐字闪烁。
+
+### 3. 写入 Agent 审阅版本
+
+```js
+subtitles_apply {
+  projectId: "launch-captions",
+  expectedRevision: 1,
+  changeReason: "核对音频后修正产品名和语义标点",
+  cues: [
+    { id: "cue-001", beginMs: 320, endMs: 2840, text: "这是修正后的\n第一条字幕。" }
+  ]
+}
+```
+
+`cues` 必须是完整列表，不是某一页。时间必须递增、不重叠，且不能超过成片时长。`expectedRevision` 防止并发审阅互相覆盖；每次成功都会产生新的不可变快照。
+
+### 4. 导出标准轨道
+
+```js
+subtitles_export {
+  projectId: "launch-captions",
+  revision: 2,
+  srtPath: "deliverables/launch.zh-CN.srt",
+  assPath: "deliverables/launch.zh-CN.ass",
+  assStyle: {
+    playResX: 3840,
+    playResY: 2160,
+    fontName: "Noto Sans CJK SC",
+    fontSize: 96,
+    outline: 5,
+    marginV: 180
+  }
+}
+```
+
+工具会返回 SRT / ASS 文件引用、SHA-256 和持久化导出回执。默认 ASS 字体是 `Noto Sans CJK SC`；实际渲染环境需要自行安装或嵌入该字体。
+
+本包的完成状态是“字幕轨道已生成并校验”，不是“字幕已经烧进视频”。最后应把轨道交给支持字幕的渲染器，并检查实际成片中的同步、遮挡、安全区、字体回退和漏字。
+
+## 工作区数据
+
+项目状态保存在：
+
+```text
+.subtitles/projects/<projectId>/
+├── project.json
+├── snapshots/<revision>.json
+└── exports/<exportId>.json
+```
+
+源转录与导出文件都不会被覆盖。源转录字节变化后，旧项目会拒绝继续导出，避免把新内容误配到旧时间轴。
+
+## 开发
+
+```bash
+npm ci
+npm run check
+npm pack --dry-run
+```
+
+GitHub Release 标签必须与 `package.json` 完全一致，例如 `v0.1.0`。发布工作流会在标签快照上重新执行检查并通过 npm OIDC 发布。
+
+## License
+
+MIT

package/extensions/subtitles/index.ts

@@ -0,0 +1,148 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	applySubtitleRevision,
+	createSubtitleProject,
+	exportSubtitleProject,
+	getSubtitleProject,
+} from "../../src/project.ts";
+
+function result(details: unknown) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
+		details,
+	};
+}
+
+const timelineSegment = Type.Object({
+	id: Type.String({ minLength: 1, maxLength: 128 }),
+	sourceStartMs: Type.Number({ minimum: 0 }),
+	sourceEndMs: Type.Number({ exclusiveMinimum: 0 }),
+}, { additionalProperties: false });
+
+const subtitleCue = Type.Object({
+	id: Type.String({ minLength: 1, maxLength: 128 }),
+	beginMs: Type.Number({ minimum: 0 }),
+	endMs: Type.Number({ exclusiveMinimum: 0 }),
+	text: Type.String({ minLength: 1, maxLength: 2_000 }),
+}, { additionalProperties: false });
+
+const policy = Type.Object({
+	maxLineChars: Type.Optional(Type.Integer({ minimum: 4, maximum: 80 })),
+	maxLines: Type.Optional(Type.Integer({ minimum: 1, maximum: 4 })),
+	targetMinChars: Type.Optional(Type.Integer({ minimum: 1, maximum: 160 })),
+	targetMaxChars: Type.Optional(Type.Integer({ minimum: 1, maximum: 320 })),
+	targetMinDurationMs: Type.Optional(Type.Integer({ minimum: 100, maximum: 20_000 })),
+	targetMaxDurationMs: Type.Optional(Type.Integer({ minimum: 100, maximum: 30_000 })),
+	minDurationMs: Type.Optional(Type.Integer({ minimum: 100, maximum: 20_000 })),
+	maxDurationMs: Type.Optional(Type.Integer({ minimum: 100, maximum: 30_000 })),
+	targetCps: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+	relaxedMaxCps: Type.Optional(Type.Number({ minimum: 1, maximum: 150 })),
+	weakPauseMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 10_000 })),
+	strongPauseMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 20_000 })),
+}, { additionalProperties: false });
+
+const assStyle = Type.Object({
+	playResX: Type.Optional(Type.Integer({ minimum: 1, maximum: 16_384 })),
+	playResY: Type.Optional(Type.Integer({ minimum: 1, maximum: 16_384 })),
+	fontName: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+	fontSize: Type.Optional(Type.Number({ minimum: 1, maximum: 500 })),
+	primaryColour: Type.Optional(Type.String({ pattern: "^&H[0-9A-Fa-f]{8}$" })),
+	outlineColour: Type.Optional(Type.String({ pattern: "^&H[0-9A-Fa-f]{8}$" })),
+	outline: Type.Optional(Type.Number({ minimum: 0, maximum: 20 })),
+	shadow: Type.Optional(Type.Number({ minimum: 0, maximum: 20 })),
+	alignment: Type.Optional(Type.Integer({ minimum: 1, maximum: 9 })),
+	marginV: Type.Optional(Type.Integer({ minimum: 0, maximum: 4_000 })),
+}, { additionalProperties: false });
+
+export default function subtitles(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "subtitles_create",
+		label: "Create subtitle project",
+		description: "Create an immutable workspace subtitle project from a word-timestamp JSON transcript. Optionally remaps retained A-roll source segments onto the final edited timeline, then generates readable cue groups without rendering video.",
+		parameters: Type.Object({
+			projectId: Type.String({ minLength: 1, maxLength: 128, pattern: "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" }),
+			transcriptPath: Type.String({ minLength: 1, description: "Existing workspace-relative word-timestamp JSON from pi-speech or a compatible ASR." }),
+			sourceDurationMs: Type.Number({ exclusiveMinimum: 0 }),
+			timelineSegments: Type.Optional(Type.Array(timelineSegment, {
+				minItems: 1,
+				maxItems: 1_000,
+				description: "Ordered retained A-roll source ranges. Omit only when the final timeline is identical to the source.",
+			})),
+			policy: Type.Optional(policy),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			signal?.throwIfAborted();
+			onUpdate?.({ content: [{ type: "text", text: "Mapping word timestamps onto the final timeline" }], details: { progress: 0.2 } });
+			const created = await createSubtitleProject(ctx.cwd, params);
+			signal?.throwIfAborted();
+			onUpdate?.({ content: [{ type: "text", text: "Subtitle project created" }], details: { progress: 1 } });
+			return result(created);
+		},
+	});
+
+	pi.registerTool({
+		name: "subtitles_get",
+		label: "Get subtitle project",
+		description: "Read one immutable subtitle revision and a bounded page of cues for Agent review.",
+		parameters: Type.Object({
+			projectId: Type.String({ minLength: 1, maxLength: 128 }),
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			offset: Type.Optional(Type.Integer({ minimum: 0, default: 0 })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, default: 100 })),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			signal?.throwIfAborted();
+			const loaded = await getSubtitleProject(ctx.cwd, params.projectId, params.revision);
+			const offset = params.offset ?? 0;
+			const limit = params.limit ?? 100;
+			return result({
+				project: loaded.project,
+				revision: loaded.snapshot.revision,
+				snapshotSha256: loaded.snapshot.snapshotSha256,
+				total: loaded.snapshot.cues.length,
+				offset,
+				limit,
+				hasMore: offset + limit < loaded.snapshot.cues.length,
+				cues: loaded.snapshot.cues.slice(offset, offset + limit),
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "subtitles_apply",
+		label: "Apply subtitle review",
+		description: "Create a new immutable subtitle revision from a complete Agent-reviewed cue list. Uses optimistic locking and requires a human-readable change reason.",
+		parameters: Type.Object({
+			projectId: Type.String({ minLength: 1, maxLength: 128 }),
+			expectedRevision: Type.Integer({ minimum: 1 }),
+			cues: Type.Array(subtitleCue, { minItems: 1, maxItems: 10_000 }),
+			changeReason: Type.String({ minLength: 1, maxLength: 2_000 }),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			signal?.throwIfAborted();
+			return result(await applySubtitleRevision(ctx.cwd, params));
+		},
+	});
+
+	pi.registerTool({
+		name: "subtitles_export",
+		label: "Export subtitle tracks",
+		description: "Export one exact reviewed revision as a new UTF-8 SRT file and optional styled ASS file. Never overwrites outputs and returns a persisted provenance receipt; video burn-in remains an explicit renderer handoff.",
+		parameters: Type.Object({
+			projectId: Type.String({ minLength: 1, maxLength: 128 }),
+			revision: Type.Integer({ minimum: 1 }),
+			srtPath: Type.String({ minLength: 5, pattern: "\\.srt$" }),
+			assPath: Type.Optional(Type.String({ minLength: 5, pattern: "\\.ass$" })),
+			assStyle: Type.Optional(assStyle),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			signal?.throwIfAborted();
+			onUpdate?.({ content: [{ type: "text", text: "Exporting standard subtitle tracks" }], details: { progress: 0.2 } });
+			const exported = await exportSubtitleProject(ctx.cwd, params);
+			signal?.throwIfAborted();
+			onUpdate?.({ content: [{ type: "text", text: "Subtitle tracks exported" }], details: { progress: 1 } });
+			return result(exported);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@speclip/pi-subtitles",
+  "version": "0.1.0",
+  "description": "Agent-reviewed subtitle timing, layout, and standard track export for Pi",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linyqh/pi-subtitles.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "extensions",
+    "prompts",
+    "skills",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "check": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "pi-package",
+    "subtitles",
+    "captions",
+    "srt",
+    "ass",
+    "video-editing"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/subtitles/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.1 <0.85.0",
+    "typebox": "^1.3.7"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@types/node": "22.20.1",
+    "typebox": "1.3.7",
+    "typescript": "7.0.2"
+  }
+}

package/prompts/add-subtitles.md

@@ -0,0 +1,7 @@
+---
+description: Add reviewed subtitles to an edited talking-head video
+---
+
+Use the `add-subtitles` skill to map a word-level transcript onto the final A-roll timeline, inspect every generated cue page, preserve spoken meaning, apply only evidence-backed text or grouping corrections, and export an exact SRT plus optional ASS track for this request: $@
+
+Finish A-roll first. Do not time subtitles from B-roll assets, submit a partial cue page as a complete revision, overwrite existing tracks, or claim that the video contains subtitles until a renderer has applied and visually reviewed the exported track.

package/skills/add-subtitles/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: add-subtitles
+description: Build and review subtitles from word-level ASR timestamps after A-roll editing, then export exact SRT and optional styled ASS tracks. Use when the user asks to add captions, subtitles, SRT, ASS, or Chinese talking-head text to an edited video.
+---
+
+# Add subtitles
+
+Use `pi-speech` for word timestamps and this package for final-timeline mapping, readable cue decisions, Agent review, and standard subtitle track export.
+
+1. Finish the A-roll edit before creating subtitles. Obtain the exact source duration and the ordered retained A-roll source ranges. B-roll overlays do not change subtitle timing while the primary A-roll audio remains unchanged.
+2. Use a `pi-speech`-compatible JSON transcript with word-level `beginMs` and `endMs`. Do not derive cue timing from sentence text, a summary, or B-roll asset timestamps.
+3. Call `subtitles_create` once. Pass `timelineSegments` when A-roll has cuts; omit it only when the final timeline is identical to the source. Each retained range must end on a word-safe edit boundary. The tool rejects a word that straddles a cut.
+4. Treat the generated cues as a proposal. Read every page with `subtitles_get`; do not review only the first page. Check the words against the spoken audio, then check punctuation, semantic grouping, reading speed, line breaks, and whether a cue crosses an editorial thought boundary.
+5. Keep speech meaning intact. Correct ASR spelling or punctuation only with audio evidence. Do not delete content merely to make a line shorter. Preserve intentional fillers, emphasis, terminology, numbers, names, and sentence-ending tone.
+6. Prefer one complete idea per cue, at most two balanced lines, and natural boundaries at strong punctuation or acoustic pauses. Avoid one-character orphan cues and rapid flashes. Do not force every cue to an identical duration; subtitle timing follows the actual delivery rhythm.
+7. If edits are needed, gather the complete cue list across all pages and call `subtitles_apply` with the current `expectedRevision` and a concrete `changeReason`. Never submit one paginated slice as if it were the full revision. If the revision changed, re-read and reconcile instead of overwriting another review.
+8. Call `subtitles_export` with the exact reviewed revision. SRT is the portable timing/text track. Request ASS only when positioning or typography is needed, and choose a font that exists in the render environment. The default ASS style names `Noto Sans CJK SC`; embedding or installing that font is the renderer's responsibility.
+9. Keep rendering explicit. This package does not burn subtitles into video and does not invent FFmpeg arguments. Hand the returned SRT or ASS artifact and provenance receipt to a renderer that supports subtitle tracks, then visually review the actual final video for safe-area placement, occlusion, glyph fallback, sync, and missing text.
+
+Never overwrite a transcript, subtitle track, or render. If the transcript hash changes, create a new subtitle project so timing decisions stay reproducible.
+
+Read [timing and layout](references/timing-and-layout.md) when reviewing dense, fast, bilingual, or unusually sparse speech.

package/skills/add-subtitles/references/timing-and-layout.md

@@ -0,0 +1,32 @@
+# Timing and layout review
+
+## Timeline truth
+
+For a retained A-roll source range, final cue time is:
+
+```text
+final_time = accumulated_retained_duration + source_word_time - range_source_start
+```
+
+A cut is also a subtitle boundary. Even when the two retained words become adjacent in the final video, a cue must not bridge across the edit because it can expose removed language or create misleading timing.
+
+## Default talking-head policy
+
+- Up to 16 visible characters per line, two lines per cue.
+- Aim for 12–20 visible characters, but preserve semantic grouping first.
+- Aim for 1.5–4.5 seconds; allow 0.833–7 seconds when the speech requires it.
+- Prefer about 9 visible characters per second and relax locally up to 11 before making a worse semantic break.
+- A pause near 250ms is useful weak boundary evidence; 450ms is strong boundary evidence.
+
+These are working defaults, not hard editorial targets. The hard requirements are monotonic non-overlapping timestamps, no cue beyond the final timeline, and preservation of the reviewed spoken content.
+
+## Review order
+
+1. Spoken text and terminology.
+2. Final-timeline sync after every A-roll cut.
+3. Semantic cue boundary.
+4. Reading speed and display duration.
+5. Balanced line wrapping and safe-area placement.
+6. Font availability and actual rendered glyphs.
+
+When timing evidence is mathematically inconsistent, relax only the affected cue. Do not collapse the full transcript into one cue or degrade into one character per cue.

package/src/contracts.ts

@@ -0,0 +1,94 @@
+export interface TranscriptWord {
+	text: string;
+	beginMs: number;
+	endMs: number;
+	punctuation: string;
+}
+
+export interface TimelineSegment {
+	id: string;
+	sourceStartMs: number;
+	sourceEndMs: number;
+}
+
+export interface TimelineWord extends TranscriptWord {
+	timelineSegmentId?: string;
+}
+
+export interface SubtitlePolicy {
+	maxLineChars: number;
+	maxLines: number;
+	targetMinChars: number;
+	targetMaxChars: number;
+	targetMinDurationMs: number;
+	targetMaxDurationMs: number;
+	minDurationMs: number;
+	maxDurationMs: number;
+	targetCps: number;
+	relaxedMaxCps: number;
+	weakPauseMs: number;
+	strongPauseMs: number;
+}
+
+export interface SubtitleCue {
+	id: string;
+	beginMs: number;
+	endMs: number;
+	text: string;
+}
+
+export interface FileRef {
+	path: string;
+	bytes: number;
+	sha256: string;
+	mimeType: string;
+}
+
+export interface AssStyle {
+	playResX: number;
+	playResY: number;
+	fontName: string;
+	fontSize: number;
+	primaryColour: string;
+	outlineColour: string;
+	outline: number;
+	shadow: number;
+	alignment: number;
+	marginV: number;
+}
+
+export interface SubtitleProject {
+	schemaVersion: 1;
+	projectId: string;
+	createdAt: string;
+	updatedAt: string;
+	currentRevision: number;
+	sourceDurationMs: number;
+	timelineDurationMs: number;
+	transcript: FileRef;
+	timelineSegments: TimelineSegment[];
+	policy: SubtitlePolicy;
+}
+
+export interface SubtitleSnapshot {
+	schemaVersion: 1;
+	projectId: string;
+	revision: number;
+	parentRevision: number | null;
+	createdAt: string;
+	changeReason: string;
+	cues: SubtitleCue[];
+	snapshotSha256: string;
+}
+
+export interface SubtitleExportReceipt {
+	schemaVersion: 1;
+	exportId: string;
+	projectId: string;
+	revision: number;
+	createdAt: string;
+	snapshotSha256: string;
+	tracks: { srt: FileRef; ass?: FileRef };
+	receiptPath: string;
+	receiptSha256: string;
+}

package/src/cues.ts

@@ -0,0 +1,255 @@
+import type {
+	SubtitleCue,
+	SubtitlePolicy,
+	TimelineSegment,
+	TimelineWord,
+	TranscriptWord,
+} from "./contracts.ts";
+
+export const DEFAULT_SUBTITLE_POLICY: SubtitlePolicy = {
+	maxLineChars: 16,
+	maxLines: 2,
+	targetMinChars: 12,
+	targetMaxChars: 20,
+	targetMinDurationMs: 1_500,
+	targetMaxDurationMs: 4_500,
+	minDurationMs: 833,
+	maxDurationMs: 7_000,
+	targetCps: 9,
+	relaxedMaxCps: 11,
+	weakPauseMs: 250,
+	strongPauseMs: 450,
+};
+
+interface TimedToken {
+	text: string;
+	beginMs: number;
+	endMs: number;
+	spaceBefore: boolean;
+}
+
+const STRONG_PUNCTUATION = new Set(["。", "！", "？", "?", "!", "."]);
+const WEAK_PUNCTUATION = new Set(["，", "、", "；", "：", ",", ";", ":"]);
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function validateWords(words: TranscriptWord[]): void {
+	let previousEnd = -1;
+	for (const word of words) {
+		if (typeof word.text !== "string" || !word.text.trim() || !finiteNonNegative(word.beginMs)
+			|| !finiteNonNegative(word.endMs) || word.endMs <= word.beginMs || typeof word.punctuation !== "string") {
+			throw new Error("Transcript contains an invalid word timestamp or text");
+		}
+		if (word.beginMs < previousEnd) throw new Error("Transcript word timestamps overlap or are out of order");
+		previousEnd = word.endMs;
+	}
+}
+
+function validateTimeline(segments: TimelineSegment[]): void {
+	if (segments.length === 0) throw new Error("Timeline must retain at least one A-roll segment");
+	let previousEnd = -1;
+	const ids = new Set<string>();
+	for (const segment of segments) {
+		if (!segment.id || ids.has(segment.id) || !finiteNonNegative(segment.sourceStartMs)
+			|| !finiteNonNegative(segment.sourceEndMs) || segment.sourceEndMs <= segment.sourceStartMs) {
+			throw new Error("Timeline contains an invalid or duplicate segment");
+		}
+		if (segment.sourceStartMs < previousEnd) throw new Error("Timeline source segments overlap or are out of order");
+		ids.add(segment.id);
+		previousEnd = segment.sourceEndMs;
+	}
+}
+
+export function remapWordsToTimeline(words: TranscriptWord[], segments: TimelineSegment[]): TimelineWord[] {
+	validateWords(words);
+	validateTimeline(segments);
+	const remapped: TimelineWord[] = [];
+	let outputOffsetMs = 0;
+	for (const segment of segments) {
+		for (const word of words) {
+			const overlaps = word.beginMs < segment.sourceEndMs && word.endMs > segment.sourceStartMs;
+			if (!overlaps) continue;
+			if (word.beginMs < segment.sourceStartMs || word.endMs > segment.sourceEndMs) {
+				throw new Error(`Word timestamp crosses A-roll edit boundary: ${word.text}`);
+			}
+			remapped.push({
+				...word,
+				beginMs: outputOffsetMs + word.beginMs - segment.sourceStartMs,
+				endMs: outputOffsetMs + word.endMs - segment.sourceStartMs,
+				timelineSegmentId: segment.id,
+			});
+		}
+		outputOffsetMs += segment.sourceEndMs - segment.sourceStartMs;
+	}
+	return remapped;
+}
+
+function isAsciiWord(value: string): boolean {
+	return value.length > 0 && [...value].every((character) => /[A-Za-z0-9'-]/u.test(character));
+}
+
+function splitTiming(word: TimelineWord, policy: SubtitlePolicy): TimedToken[] {
+	const text = word.text.trim();
+	if (!text) return [];
+	const durationMs = word.endMs - word.beginMs;
+	if (/\s/u.test(text)) {
+		const matches = [...text.matchAll(/\S+/gu)];
+		return matches.flatMap((match) => {
+			const start = match.index ?? 0;
+			const nested = splitTiming({
+				text: match[0],
+				beginMs: word.beginMs + durationMs * start / text.length,
+				endMs: word.beginMs + durationMs * (start + match[0].length) / text.length,
+				punctuation: "",
+			}, policy);
+			if (nested[0] && start > 0) nested[0].spaceBefore = true;
+			return nested;
+		});
+	}
+	const asciiWord = isAsciiWord(text);
+	const mustSplit = [...text].length > policy.maxLineChars * policy.maxLines || durationMs > policy.maxDurationMs;
+	const units = asciiWord && !mustSplit ? [text] : [...text];
+	const stepMs = durationMs / units.length;
+	return units.map((unit, index) => ({
+		text: `${unit}${index === units.length - 1 ? word.punctuation : ""}`,
+		beginMs: word.beginMs + index * stepMs,
+		endMs: Math.min(word.beginMs + (index + 1) * stepMs, word.beginMs + index * stepMs + policy.maxDurationMs),
+		spaceBefore: asciiWord && index === 0,
+	}));
+}
+
+function visibleChars(value: string): number {
+	return [...value].filter((character) => !/\s/u.test(character) && !/\p{Cf}/u.test(character)).length;
+}
+
+function joinTokens(tokens: TimedToken[]): string {
+	let value = "";
+	for (const token of tokens) value += `${value && token.spaceBefore ? " " : ""}${token.text}`;
+	return value;
+}
+
+function wrapTokens(tokens: TimedToken[], maxLineChars: number): string {
+	const whole = joinTokens(tokens);
+	if (visibleChars(whole) <= maxLineChars) return whole;
+	for (const lineLimit of [maxLineChars, maxLineChars + 2]) {
+		const candidates: Array<{ cost: number; first: string; second: string }> = [];
+		for (let split = 1; split < tokens.length; split += 1) {
+			const first = joinTokens(tokens.slice(0, split));
+			const second = joinTokens(tokens.slice(split));
+			const firstLength = visibleChars(first);
+			const secondLength = visibleChars(second);
+			if (firstLength > lineLimit || secondLength > lineLimit) continue;
+			const last = [...first].at(-1);
+			const punctuationBonus = last && STRONG_PUNCTUATION.has(last) ? -8 : last && WEAK_PUNCTUATION.has(last) ? -6 : 0;
+			candidates.push({
+				cost: Math.abs(firstLength - secondLength) + Math.max(0, firstLength - secondLength) * 0.5 + punctuationBonus,
+				first,
+				second,
+			});
+		}
+		if (candidates.length > 0) {
+			candidates.sort((left, right) => left.cost - right.cost);
+			return `${candidates[0]!.first}\n${candidates[0]!.second}`;
+		}
+	}
+	const characters = [...whole];
+	return `${characters.slice(0, maxLineChars).join("")}\n${characters.slice(maxLineChars).join("")}`;
+}
+
+function cueCost(tokens: TimedToken[], start: number, end: number, remainingCharacters: number, policy: SubtitlePolicy): number {
+	const cueTokens = tokens.slice(start, end);
+	const characters = visibleChars(joinTokens(cueTokens));
+	const durationMs = Math.max(1, cueTokens.at(-1)!.endMs - cueTokens[0]!.beginMs);
+	let cost = characters < policy.targetMinChars
+		? (policy.targetMinChars - characters) * 1.25
+		: characters > policy.targetMaxChars ? (characters - policy.targetMaxChars) * 1.6 : 0;
+	if (durationMs < policy.targetMinDurationMs) cost += (policy.targetMinDurationMs - durationMs) / 200;
+	if (durationMs > policy.targetMaxDurationMs) cost += (durationMs - policy.targetMaxDurationMs) / 500;
+	const cps = characters / (durationMs / 1_000);
+	cost += Math.max(0, cps - policy.targetCps) ** 2 * 0.8;
+	cost += Math.max(0, cps - policy.relaxedMaxCps) ** 2 * 2;
+	const lastCharacter = [...cueTokens.at(-1)!.text.trim()].at(-1);
+	cost += lastCharacter && STRONG_PUNCTUATION.has(lastCharacter) ? -10
+		: lastCharacter && WEAK_PUNCTUATION.has(lastCharacter) ? -4 : 12;
+	if (end === tokens.length) cost -= 6;
+	else {
+		const pauseMs = tokens[end]!.beginMs - tokens[end - 1]!.endMs;
+		if (pauseMs >= policy.strongPauseMs) cost -= 18;
+		else if (pauseMs >= policy.weakPauseMs) cost -= 10;
+	}
+	if (end < tokens.length && remainingCharacters <= 2) cost += 18;
+	if (characters <= 2 && (start > 0 || end < tokens.length)) cost += 18;
+	return cost;
+}
+
+function selectBoundaries(tokens: TimedToken[], policy: SubtitlePolicy): number[] {
+	const count = tokens.length;
+	const prefix = [0];
+	for (const token of tokens) prefix.push(prefix.at(-1)! + visibleChars(token.text));
+	const costs = Array<number>(count + 1).fill(Number.POSITIVE_INFINITY);
+	const previous = Array<number>(count + 1).fill(-1);
+	costs[0] = 0;
+	for (let start = 0; start < count; start += 1) {
+		if (!Number.isFinite(costs[start])) continue;
+		for (let end = start + 1; end <= count; end += 1) {
+			const characters = prefix[end]! - prefix[start]!;
+			const durationMs = Math.max(1, tokens[end - 1]!.endMs - tokens[start]!.beginMs);
+			if (end > start + 1 && (characters > (policy.maxLineChars + 2) * policy.maxLines || durationMs > policy.maxDurationMs)) break;
+			const shortPenalty = durationMs < policy.minDurationMs && !(start === 0 && end === count)
+				? policy.minDurationMs - durationMs : 0;
+			const candidate = costs[start]! + shortPenalty
+				+ cueCost(tokens, start, end, prefix[count]! - prefix[end]!, policy);
+			if (candidate < costs[end]!) {
+				costs[end] = candidate;
+				previous[end] = start;
+			}
+		}
+	}
+	if (previous[count]! < 0) return [count];
+	const boundaries: number[] = [];
+	for (let cursor = count; cursor > 0; cursor = previous[cursor]!) boundaries.push(cursor);
+	return boundaries.reverse();
+}
+
+function buildGroup(tokens: TimedToken[], policy: SubtitlePolicy): Omit<SubtitleCue, "id">[] {
+	const boundaries = selectBoundaries(tokens, policy);
+	const cues: Omit<SubtitleCue, "id">[] = [];
+	let start = 0;
+	for (const end of boundaries) {
+		const selected = tokens.slice(start, end);
+		cues.push({
+			beginMs: selected[0]!.beginMs,
+			endMs: Math.max(selected[0]!.beginMs + 1, selected.at(-1)!.endMs),
+			text: wrapTokens(selected, policy.maxLineChars),
+		});
+		start = end;
+	}
+	return cues;
+}
+
+export function buildSubtitleCues(
+	words: TimelineWord[],
+	timelineEndMs: number,
+	policy: Partial<SubtitlePolicy> = {},
+): SubtitleCue[] {
+	if (!finiteNonNegative(timelineEndMs)) throw new Error("timelineEndMs must be non-negative");
+	validateWords(words);
+	const resolved = { ...DEFAULT_SUBTITLE_POLICY, ...policy };
+	const groups: TimelineWord[][] = [];
+	for (const word of words) {
+		const previous = groups.at(-1);
+		if (!previous || previous[0]!.timelineSegmentId !== word.timelineSegmentId) groups.push([word]);
+		else previous.push(word);
+	}
+	const raw = groups.flatMap((group) => buildGroup(group.flatMap((word) => splitTiming(word, resolved)), resolved));
+	return raw.map((cue, index) => {
+		const nextStart = raw[index + 1]?.beginMs ?? Math.max(cue.endMs, timelineEndMs);
+		return {
+			id: `cue-${String(index + 1).padStart(3, "0")}`,
+			...cue,
+			endMs: Math.max(cue.endMs, Math.min(cue.beginMs + resolved.minDurationMs, cue.beginMs + resolved.maxDurationMs, nextStart)),
+		};
+	});
+}

package/src/export.ts

@@ -0,0 +1,86 @@
+import type { AssStyle, FileRef, SubtitleCue } from "./contracts.ts";
+import { rm } from "node:fs/promises";
+import { resolveExistingWorkspaceFile, writeNewWorkspaceFile } from "./workspace.ts";
+
+export const DEFAULT_ASS_STYLE: AssStyle = {
+	playResX: 1920,
+	playResY: 1080,
+	fontName: "Noto Sans CJK SC",
+	fontSize: 54,
+	primaryColour: "&H00FFFFFF",
+	outlineColour: "&H00000000",
+	outline: 3,
+	shadow: 0,
+	alignment: 2,
+	marginV: 90,
+};
+
+function pad(value: number, width: number): string {
+	return String(value).padStart(width, "0");
+}
+
+function srtTime(milliseconds: number): string {
+	const rounded = Math.max(0, Math.round(milliseconds));
+	const hours = Math.floor(rounded / 3_600_000);
+	const minutes = Math.floor(rounded % 3_600_000 / 60_000);
+	const seconds = Math.floor(rounded % 60_000 / 1_000);
+	return `${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)},${pad(rounded % 1_000, 3)}`;
+}
+
+function assTime(milliseconds: number): string {
+	const centiseconds = Math.max(0, Math.round(milliseconds / 10));
+	const hours = Math.floor(centiseconds / 360_000);
+	const minutes = Math.floor(centiseconds % 360_000 / 6_000);
+	const seconds = Math.floor(centiseconds % 6_000 / 100);
+	return `${hours}:${pad(minutes, 2)}:${pad(seconds, 2)}.${pad(centiseconds % 100, 2)}`;
+}
+
+function assertCues(cues: SubtitleCue[]): void {
+	let previousEnd = -1;
+	const ids = new Set<string>();
+	for (const cue of cues) {
+		if (!cue.id || ids.has(cue.id) || !Number.isFinite(cue.beginMs) || !Number.isFinite(cue.endMs)
+			|| cue.beginMs < 0 || cue.endMs <= cue.beginMs || !cue.text.trim()) {
+			throw new Error("Subtitle cues contain invalid timing, text, or duplicate IDs");
+		}
+		if (cue.beginMs < previousEnd) throw new Error("Subtitle cues overlap or are out of order");
+		ids.add(cue.id);
+		previousEnd = cue.endMs;
+	}
+}
+
+export function renderSrt(cues: SubtitleCue[]): string {
+	assertCues(cues);
+	return `${cues.map((cue, index) => `${index + 1}\n${srtTime(cue.beginMs)} --> ${srtTime(cue.endMs)}\n${cue.text}`).join("\n\n")}\n`;
+}
+
+function assText(value: string): string {
+	return value.replaceAll("\\", "\\\\").replaceAll("{", "\\{").replaceAll("}", "\\}").replaceAll("\n", "\\N");
+}
+
+export function renderAss(cues: SubtitleCue[], style: Partial<AssStyle> = {}): string {
+	assertCues(cues);
+	const resolved = { ...DEFAULT_ASS_STYLE, ...style };
+	const header = `[Script Info]\nScriptType: v4.00+\nPlayResX: ${resolved.playResX}\nPlayResY: ${resolved.playResY}\nWrapStyle: 2\nScaledBorderAndShadow: yes\n\n[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\nStyle: Default,${resolved.fontName},${resolved.fontSize},${resolved.primaryColour},${resolved.primaryColour},${resolved.outlineColour},&H00000000,0,0,0,0,100,100,0,0,1,${resolved.outline},${resolved.shadow},${resolved.alignment},40,40,${resolved.marginV},1\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text`;
+	const events = cues.map((cue) => `Dialogue: 0,${assTime(cue.beginMs)},${assTime(cue.endMs)},Default,,0,0,0,,${assText(cue.text)}`);
+	return `${header}\n${events.join("\n")}\n`;
+}
+
+export async function exportSubtitleTracks(
+	cwd: string,
+	cues: SubtitleCue[],
+	input: { srtPath: string; assPath?: string; assStyle?: Partial<AssStyle> },
+): Promise<{ srt: FileRef; ass?: FileRef }> {
+	assertCues(cues);
+	if (!input.srtPath.toLowerCase().endsWith(".srt")) throw new Error("srtPath must end in .srt");
+	if (input.assPath !== undefined && !input.assPath.toLowerCase().endsWith(".ass")) throw new Error("assPath must end in .ass");
+	const srt = await writeNewWorkspaceFile(cwd, input.srtPath, renderSrt(cues), "application/x-subrip; charset=utf-8");
+	if (!input.assPath) return { srt };
+	try {
+		const ass = await writeNewWorkspaceFile(cwd, input.assPath, renderAss(cues, input.assStyle), "text/x-ssa; charset=utf-8");
+		return { srt, ass };
+	} catch (error) {
+		await rm(await resolveExistingWorkspaceFile(cwd, srt.path), { force: true });
+		throw error;
+	}
+}

package/src/project.ts

@@ -0,0 +1,287 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildSubtitleCues, DEFAULT_SUBTITLE_POLICY, remapWordsToTimeline } from "./cues.ts";
+import type {
+	AssStyle,
+	SubtitleCue,
+	SubtitleExportReceipt,
+	SubtitlePolicy,
+	SubtitleProject,
+	SubtitleSnapshot,
+	TimelineSegment,
+	TranscriptWord,
+} from "./contracts.ts";
+import { exportSubtitleTracks, renderSrt } from "./export.ts";
+import {
+	readWorkspaceJson,
+	resolveExistingWorkspaceFile,
+	resolveNewWorkspaceFile,
+	snapshotExistingWorkspaceFile,
+	writeNewWorkspaceFile,
+} from "./workspace.ts";
+
+const PROJECT_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/u;
+
+interface RawTranscript {
+	words?: unknown[];
+	sentences?: Array<{ words?: unknown[] }>;
+}
+
+export interface CreateSubtitleProjectInput {
+	projectId: string;
+	transcriptPath: string;
+	sourceDurationMs: number;
+	timelineSegments?: TimelineSegment[];
+	policy?: Partial<SubtitlePolicy>;
+}
+
+export interface ApplySubtitleRevisionInput {
+	projectId: string;
+	expectedRevision: number;
+	cues: SubtitleCue[];
+	changeReason: string;
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`).join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+function sha256Json(value: unknown): string {
+	return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function assertProjectId(projectId: string): void {
+	if (!PROJECT_ID.test(projectId)) throw new Error("projectId must be 1-128 lowercase letters, numbers, dots, dashes, or underscores");
+}
+
+function projectRelative(projectId: string, path = ""): string {
+	assertProjectId(projectId);
+	return `.subtitles/projects/${projectId}${path ? `/${path}` : ""}`;
+}
+
+function normalizedWord(value: unknown): TranscriptWord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const item = value as Record<string, unknown>;
+	const text = typeof item.text === "string" ? item.text : typeof item.word === "string" ? item.word : undefined;
+	const beginMs = typeof item.beginMs === "number" ? item.beginMs : typeof item.start === "number" ? item.start * 1_000 : undefined;
+	const endMs = typeof item.endMs === "number" ? item.endMs : typeof item.end === "number" ? item.end * 1_000 : undefined;
+	if (!text || beginMs === undefined || endMs === undefined) return undefined;
+	const trimmed = text.trim();
+	if (!trimmed || /^(?:<sil>|\[sil\])$/iu.test(trimmed)) return undefined;
+	return {
+		text: trimmed,
+		beginMs,
+		endMs,
+		punctuation: typeof item.punctuation === "string" ? item.punctuation : "",
+	};
+}
+
+function transcriptWords(transcript: RawTranscript): TranscriptWord[] {
+	const raw = Array.isArray(transcript.sentences)
+		? transcript.sentences.flatMap((sentence) => Array.isArray(sentence.words) ? sentence.words : [])
+		: Array.isArray(transcript.words) ? transcript.words : [];
+	const words = raw.map(normalizedWord).filter((word): word is TranscriptWord => word !== undefined);
+	if (words.length === 0) throw new Error("Transcript contains no usable word timestamps");
+	return words;
+}
+
+function validateSourceAndTimeline(sourceDurationMs: number, timelineSegments: TimelineSegment[]): void {
+	if (!Number.isFinite(sourceDurationMs) || sourceDurationMs <= 0) throw new Error("sourceDurationMs must be positive");
+	if (timelineSegments.some((segment) => segment.sourceEndMs > sourceDurationMs)) {
+		throw new Error("Timeline segment exceeds sourceDurationMs");
+	}
+}
+
+function resolvedPolicy(input: Partial<SubtitlePolicy> | undefined): SubtitlePolicy {
+	const policy = { ...DEFAULT_SUBTITLE_POLICY, ...input };
+	for (const [name, value] of Object.entries(policy)) {
+		if (!Number.isFinite(value) || value < 0) throw new Error(`Subtitle policy ${name} must be a finite non-negative number`);
+	}
+	if (policy.maxLineChars < 1 || policy.maxLines < 1 || policy.targetMinChars > policy.targetMaxChars
+		|| policy.targetMinDurationMs > policy.targetMaxDurationMs || policy.minDurationMs > policy.maxDurationMs
+		|| policy.targetMaxDurationMs > policy.maxDurationMs || policy.targetCps > policy.relaxedMaxCps
+		|| policy.weakPauseMs > policy.strongPauseMs) {
+		throw new Error("Subtitle policy contains inconsistent minimum, target, or maximum values");
+	}
+	return policy;
+}
+
+function timelineDuration(segments: TimelineSegment[]): number {
+	return segments.reduce((total, segment) => total + segment.sourceEndMs - segment.sourceStartMs, 0);
+}
+
+function snapshot(projectId: string, revision: number, parentRevision: number | null, cues: SubtitleCue[], changeReason: string): SubtitleSnapshot {
+	const base = {
+		schemaVersion: 1 as const,
+		projectId,
+		revision,
+		parentRevision,
+		createdAt: new Date().toISOString(),
+		changeReason,
+		cues,
+	};
+	return { ...base, snapshotSha256: sha256Json(base) };
+}
+
+async function absoluteProjectDirectory(cwd: string, projectId: string): Promise<string> {
+	const marker = await resolveNewWorkspaceFile(cwd, `${projectRelative(projectId)}/.marker`).catch(async (error) => {
+		if (!/already exists/u.test((error as Error).message)) throw error;
+		return join(dirname(await resolveExistingWorkspaceFile(cwd, `${projectRelative(projectId)}/project.json`)), ".marker");
+	});
+	return dirname(marker);
+}
+
+async function writeInternalJson(cwd: string, relativePath: string, value: unknown): Promise<void> {
+	await writeNewWorkspaceFile(cwd, relativePath, `${JSON.stringify(value, null, 2)}\n`, "application/json");
+}
+
+export async function createSubtitleProject(cwd: string, input: CreateSubtitleProjectInput) {
+	assertProjectId(input.projectId);
+	const transcript = await snapshotExistingWorkspaceFile(cwd, input.transcriptPath, "application/json");
+	const rawTranscript = await readWorkspaceJson<RawTranscript>(cwd, input.transcriptPath, "word transcript");
+	const segments = input.timelineSegments ?? [{ id: "a-1", sourceStartMs: 0, sourceEndMs: input.sourceDurationMs }];
+	validateSourceAndTimeline(input.sourceDurationMs, segments);
+	const durationMs = timelineDuration(segments);
+	const policy = resolvedPolicy(input.policy);
+	const cues = buildSubtitleCues(remapWordsToTimeline(transcriptWords(rawTranscript), segments), durationMs, policy);
+	if (cues.length === 0) throw new Error("Retained A-roll timeline contains no transcribed words");
+	const now = new Date().toISOString();
+	const project: SubtitleProject = {
+		schemaVersion: 1,
+		projectId: input.projectId,
+		createdAt: now,
+		updatedAt: now,
+		currentRevision: 1,
+		sourceDurationMs: input.sourceDurationMs,
+		timelineDurationMs: durationMs,
+		transcript,
+		timelineSegments: segments,
+		policy,
+	};
+	const first = snapshot(input.projectId, 1, null, cues, "Initial subtitle generation from word timestamps");
+	const projectsMarker = await resolveNewWorkspaceFile(cwd, ".subtitles/projects/.marker");
+	const projectsRoot = dirname(projectsMarker);
+	await mkdir(projectsRoot, { recursive: true });
+	const target = join(projectsRoot, input.projectId);
+	const temporary = join(projectsRoot, `.${input.projectId}.${randomUUID()}.tmp`);
+	await mkdir(join(temporary, "snapshots"), { recursive: true });
+	try {
+		await writeFile(join(temporary, "project.json"), `${JSON.stringify(project, null, 2)}\n`, { flag: "wx" });
+		await writeFile(join(temporary, "snapshots/1.json"), `${JSON.stringify(first, null, 2)}\n`, { flag: "wx" });
+		await rename(temporary, target);
+	} catch (error) {
+		await rm(temporary, { recursive: true, force: true });
+		if ((error as NodeJS.ErrnoException).code === "ENOTEMPTY" || (error as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new Error(`Project already exists: ${input.projectId}`);
+		}
+		throw error;
+	}
+	return { project, snapshot: first };
+}
+
+export async function getSubtitleProject(cwd: string, projectId: string, revision?: number) {
+	assertProjectId(projectId);
+	const project = await readWorkspaceJson<SubtitleProject>(cwd, projectRelative(projectId, "project.json"), `subtitle project ${projectId}`);
+	if (project.schemaVersion !== 1 || project.projectId !== projectId || !Number.isInteger(project.currentRevision)) {
+		throw new Error(`Invalid subtitle project: ${projectId}`);
+	}
+	const selected = revision ?? project.currentRevision;
+	if (!Number.isInteger(selected) || selected < 1 || selected > project.currentRevision) throw new Error(`Invalid subtitle revision: ${projectId}@${selected}`);
+	const selectedSnapshot = await readWorkspaceJson<SubtitleSnapshot>(cwd, projectRelative(projectId, `snapshots/${selected}.json`), `subtitle snapshot ${projectId}@${selected}`);
+	const { snapshotSha256, ...unsigned } = selectedSnapshot;
+	if (selectedSnapshot.schemaVersion !== 1 || selectedSnapshot.projectId !== projectId || selectedSnapshot.revision !== selected
+		|| snapshotSha256 !== sha256Json(unsigned)) throw new Error(`Invalid subtitle snapshot: ${projectId}@${selected}`);
+	return { project, snapshot: selectedSnapshot };
+}
+
+function assertReviewedCues(cues: SubtitleCue[], timelineDurationMs: number): void {
+	if (cues.length === 0 || cues.length > 10_000) throw new Error("cues must contain 1-10000 items");
+	renderSrt(cues);
+	if (cues.at(-1)!.endMs > timelineDurationMs) throw new Error("Subtitle cue exceeds the final timeline duration");
+}
+
+async function withProjectLock<T>(cwd: string, projectId: string, action: (directory: string) => Promise<T>): Promise<T> {
+	const directory = await absoluteProjectDirectory(cwd, projectId);
+	const lock = join(directory, ".write-lock");
+	try {
+		await mkdir(lock);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Project is already being updated: ${projectId}`);
+		throw error;
+	}
+	try {
+		return await action(directory);
+	} finally {
+		await rm(lock, { recursive: true, force: true });
+	}
+}
+
+export async function applySubtitleRevision(cwd: string, input: ApplySubtitleRevisionInput) {
+	if (!input.changeReason.trim()) throw new Error("changeReason is required for an Agent-reviewed revision");
+	return await withProjectLock(cwd, input.projectId, async (directory) => {
+		const { project } = await getSubtitleProject(cwd, input.projectId);
+		if (project.currentRevision !== input.expectedRevision) {
+			throw new Error(`Project ${input.projectId} expected revision ${input.expectedRevision} but current revision is ${project.currentRevision}`);
+		}
+		assertReviewedCues(input.cues, project.timelineDurationMs);
+		const revision = project.currentRevision + 1;
+		const nextSnapshot = snapshot(input.projectId, revision, project.currentRevision, input.cues, input.changeReason.trim());
+		const snapshotPath = join(directory, `snapshots/${revision}.json`);
+		await writeFile(snapshotPath, `${JSON.stringify(nextSnapshot, null, 2)}\n`, { flag: "wx" });
+		const nextProject: SubtitleProject = { ...project, currentRevision: revision, updatedAt: new Date().toISOString() };
+		const temporary = join(directory, `project.${randomUUID()}.tmp`);
+		try {
+			await writeFile(temporary, `${JSON.stringify(nextProject, null, 2)}\n`, { flag: "wx" });
+			await rename(temporary, join(directory, "project.json"));
+		} catch (error) {
+			await rm(temporary, { force: true });
+			await rm(snapshotPath, { force: true });
+			throw error;
+		}
+		return { project: nextProject, snapshot: nextSnapshot };
+	});
+}
+
+async function assertTranscriptUnchanged(cwd: string, project: SubtitleProject): Promise<void> {
+	const current = await snapshotExistingWorkspaceFile(cwd, project.transcript.path, project.transcript.mimeType);
+	if (current.sha256 !== project.transcript.sha256 || current.bytes !== project.transcript.bytes) {
+		throw new Error("Source transcript has changed since subtitle project creation");
+	}
+}
+
+export async function exportSubtitleProject(cwd: string, input: {
+	projectId: string;
+	revision: number;
+	srtPath: string;
+	assPath?: string;
+	assStyle?: Partial<AssStyle>;
+}) {
+	const { project, snapshot: selectedSnapshot } = await getSubtitleProject(cwd, input.projectId, input.revision);
+	await assertTranscriptUnchanged(cwd, project);
+	const tracks = await exportSubtitleTracks(cwd, selectedSnapshot.cues, {
+		srtPath: input.srtPath,
+		...(input.assPath ? { assPath: input.assPath } : {}),
+		...(input.assStyle ? { assStyle: input.assStyle } : {}),
+	});
+	const exportId = randomUUID();
+	const receiptPath = projectRelative(input.projectId, `exports/${exportId}.json`);
+	const base = {
+		schemaVersion: 1 as const,
+		exportId,
+		projectId: input.projectId,
+		revision: input.revision,
+		createdAt: new Date().toISOString(),
+		snapshotSha256: selectedSnapshot.snapshotSha256,
+		tracks,
+		receiptPath,
+	};
+	const receipt: SubtitleExportReceipt = { ...base, receiptSha256: sha256Json(base) };
+	await writeInternalJson(cwd, receiptPath, receipt);
+	return { project, snapshot: selectedSnapshot, receipt };
+}

package/src/workspace.ts

@@ -0,0 +1,99 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { link, lstat, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { FileRef } from "./contracts.ts";
+
+function isWithin(root: string, candidate: string): boolean {
+	const value = relative(root, candidate);
+	return value === "" || (!value.startsWith(`..${sep}`) && value !== ".." && !isAbsolute(value));
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function nearestExistingAncestor(path: string): Promise<string> {
+	let current = path;
+	while (!(await exists(current))) current = dirname(current);
+	return current;
+}
+
+export async function resolveNewWorkspaceFile(cwd: string, inputPath: string): Promise<string> {
+	const root = await realpath(cwd);
+	const target = resolve(root, inputPath);
+	if (target === root || !isWithin(root, target)) throw new Error(`Path is outside the workspace: ${inputPath}`);
+	if (await exists(target)) throw new Error(`Output already exists: ${inputPath}`);
+	const ancestor = await realpath(await nearestExistingAncestor(dirname(target)));
+	if (!isWithin(root, ancestor)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	return target;
+}
+
+async function sha256(path: string): Promise<string> {
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+
+export async function resolveExistingWorkspaceFile(cwd: string, inputPath: string): Promise<string> {
+	const root = await realpath(cwd);
+	const lexical = resolve(root, inputPath);
+	if (!isWithin(root, lexical)) throw new Error(`Path is outside the workspace: ${inputPath}`);
+	if ((await lstat(lexical)).isSymbolicLink()) throw new Error(`Unsafe workspace-file symlink: ${inputPath}`);
+	const canonical = await realpath(lexical);
+	if (!isWithin(root, canonical)) throw new Error(`Path resolves outside the workspace: ${inputPath}`);
+	if (!(await stat(canonical)).isFile()) throw new Error(`Path is not a file: ${inputPath}`);
+	return canonical;
+}
+
+export async function snapshotExistingWorkspaceFile(cwd: string, inputPath: string, mimeType: string): Promise<FileRef> {
+	const root = await realpath(cwd);
+	const path = await resolveExistingWorkspaceFile(cwd, inputPath);
+	return {
+		path: relative(root, path).split(sep).join("/"),
+		bytes: (await stat(path)).size,
+		sha256: await sha256(path),
+		mimeType,
+	};
+}
+
+export async function readWorkspaceJson<T>(cwd: string, inputPath: string, label: string): Promise<T> {
+	const path = await resolveExistingWorkspaceFile(cwd, inputPath);
+	try {
+		return JSON.parse(await readFile(path, "utf8")) as T;
+	} catch (error) {
+		throw new Error(`Invalid ${label}: ${(error as Error).message}`);
+	}
+}
+
+export async function writeNewWorkspaceFile(cwd: string, inputPath: string, content: string, mimeType: string): Promise<FileRef> {
+	const target = await resolveNewWorkspaceFile(cwd, inputPath);
+	await mkdir(dirname(target), { recursive: true });
+	const temporary = `${target}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+		try {
+			await link(temporary, target);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Output already exists: ${inputPath}`);
+			throw error;
+		}
+		await rm(temporary);
+	} catch (error) {
+		await rm(temporary, { force: true });
+		throw error;
+	}
+	const root = await realpath(cwd);
+	return {
+		path: relative(root, target).split(sep).join("/"),
+		bytes: (await stat(target)).size,
+		sha256: await sha256(target),
+		mimeType,
+	};
+}