@lincyaw/kernel 1.0.0-rc.0 → 1.0.0-rc.1

package/src/contracts/production-assets.ts

@@ -0,0 +1,61 @@
+import type { Asset, MediaClip, TimeRange } from './document.ts'
+import type { ProductionBinding, ProductionPlan, ProductionPlanQuery } from './production.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { DocumentChangeAnswer } from './workspace.ts'
+import { defineService } from './service.ts'
+
+/** Actual local audio metadata, derived from a bounded, regular file rather than authored duration. */
+export interface ProductionAssetInspection {
+  assetId: string
+  mediaId: string
+  kind: 'audio'
+  sha256: string
+  durationMs: number
+  byteLength: number
+  mediaType: string
+  codec: string
+  sampleRate: number
+  channels: number
+}
+export interface ProductionAssetQuery extends ProductionPlanQuery { assetId: string }
+export interface ProductionAssetAnswer extends ProductionPlanQuery { asset: ProductionAssetInspection }
+
+/** Multipart fields are change (this JSON) and file (the original bytes). Import does not attach a clip. */
+export const DOCUMENT_AUDIO_MAX_BYTES = 16 << 20
+export interface DocumentAudioImport { id: string, baseDocumentVersion: string }
+export interface DocumentAudioImportAnswer extends DocumentChangeAnswer { assetId: string, inspection: ProductionAssetInspection }
+/** Reads a declared asset directly from the saved document, including assets not yet used by a clip. */
+export interface DocumentAudioInspectionAnswer { document: string, version: string, fingerprint: string, inspection: ProductionAssetInspection }
+export type DocumentMediaClipChange =
+  | { id: string, baseDocumentVersion: string, binding: ProductionBinding, clip: MediaClip }
+  | { id: string, baseDocumentVersion: string, removeClipId: string }
+
+export class ProductionAudioRefusal extends Error {
+  readonly status: number
+  readonly code: string
+  constructor(status: number, code: string) { super(code); this.status = status; this.code = code }
+}
+/** Node-only media capabilities. Workspace authoring owns the transaction; the plugin owns real media inspection. */
+export interface ProductionAudioPlanQuery { source: CanonicalSource, irRevision?: string }
+export interface ProductionAudioAuthoring {
+  inspectBytes(assetId: string, bytes: Uint8Array, signal?: AbortSignal): Promise<{ inspection: ProductionAssetInspection, extension: string }>
+  inspectAsset(asset: Asset, signal?: AbortSignal): Promise<ProductionAssetInspection>
+  /** Cache-only projection of an existing real IR; this never compiles or synthesizes. */
+  readPlan(query: ProductionAudioPlanQuery, signal?: AbortSignal): Promise<ProductionPlan>
+  validateClips(binding: ProductionBinding, clips: MediaClip[], assets: Record<string, Asset>, signal?: AbortSignal): Promise<void>
+}
+export const PRODUCTION_AUDIO_AUTHORING = defineService<ProductionAudioAuthoring>('presmium.productionAudioAuthoring')
+
+/** One non-destructive use of an inspected file, placed inside an already confirmed step. */
+export interface ProductionAudioClip {
+  id: string
+  assetId: string
+  mediaId: string
+  sectionId: string
+  stepId: string
+  startMs: number
+  endMs: number
+  sourceRange: TimeRange
+  volume: number
+  muted: boolean
+}

package/src/contracts/production.ts

@@ -0,0 +1,109 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { TrackEvent } from './operations.ts'
+import type { TimeRange } from './document.ts'
+import type { ProductionAssetInspection } from './production-assets.ts'
+
+/** The same supported rates are used by the author controls and the actual production driver. */
+export const PRODUCTION_PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2] as const
+
+/** One immutable derived plan; a cache change can change planId without changing the saved document. */
+export interface ProductionBinding { source: CanonicalSource, irRevision: string, planId: string }
+export function sameProductionBinding(a: ProductionBinding, b: ProductionBinding): boolean {
+  return a.planId === b.planId && a.irRevision === b.irRevision && a.source.documentId === b.source.documentId && a.source.version === b.source.version && a.source.fingerprint === b.source.fingerprint
+}
+export interface ProductionPlaybackPosition {
+  timeMs: number
+  stepTimeMs?: number
+  sectionId?: string
+  stepId?: string
+  durationMs: number
+  playing: boolean
+  rate: number
+  trying: boolean
+  /** Exact missing utterance that paused this playback intent before its estimated interval. */
+  waitingFor?: string
+}
+export interface ProductionPlaybackState {
+  binding: ProductionBinding
+  status: 'loading' | 'ready' | 'estimated' | 'unavailable' | 'failed'
+  position?: ProductionPlaybackPosition
+  error?: string
+}
+export type ProductionPlaybackCommand =
+  | { binding: ProductionBinding, action: 'load' | 'pause' | 'play' }
+  | { binding: ProductionBinding, action: 'seek', timeMs: number }
+  /** Selects an event boundary even when several stable steps share the same time. */
+  | { binding: ProductionBinding, action: 'step', sectionId: string, stepId: string, utteranceId?: string }
+  | { binding: ProductionBinding, action: 'rate', rate: number }
+export interface ProductionPlanQuery { source: CanonicalSource, irRevision: string }
+/** clipId is a plan resource ID: either an exact speech key or an inspected asset mediaId. */
+export interface ProductionMediaQuery extends ProductionBinding { clipId: string }
+export type ProductionTiming = 'confirmed' | 'estimated' | 'unknown'
+
+/** All ranges use milliseconds in the single document-wide playback clock. Unknown boundaries are omitted. */
+export interface ProductionRange { startMs?: number, endMs?: number, timing: ProductionTiming }
+export interface ProductionAudio {
+  clipId: string
+  key: string
+  durationMs: number
+  /** Digest of the actual cached audio bytes, when available. Never inferred from a cache key. */
+  sha256?: string
+}
+export interface ProductionSegment extends ProductionRange {
+  id: string
+  sectionId: string
+  stepId: string
+  /** A cue can advance through several steps inside this one audio/caption segment. */
+  stepIds?: string[]
+  narrationIds?: string[]
+  sourceStepId?: string
+  blockId?: string
+  utteranceId?: string
+  label: string
+  status?: 'cached' | 'recorded' | 'silent' | 'missing' | 'blocked'
+  alignment?: 'words' | 'proportional' | 'none' | 'manual'
+  audio?: ProductionAudio
+  /** Imported media is distinct from a synthesized speech-cache entry. */
+  media?: ProductionAssetInspection
+  mediaClipId?: string
+  assetId?: string
+  sourceRange?: TimeRange
+  volume?: number
+  muted?: boolean
+  waveform?: number[]
+  waveformStatus?: 'available' | 'unavailable'
+}
+export interface ProductionTrack { kind: 'visual' | 'voice' | 'caption', segments: ProductionSegment[] }
+export interface CaptionTimingSource {
+  available: boolean
+  reason?: string
+  sourceFingerprint: string
+  playbackFingerprint?: string
+  durationMs?: number
+  narrationIds: string[]
+}
+export interface ProductionStep extends ProductionRange { captionTiming?: CaptionTimingSource, stepId: string, index: number, holdMs?: number, animationMs?: number }
+export interface ProductionPage extends ProductionRange { sectionId: string, title: string, steps: ProductionStep[] }
+export interface ProductionDiagnostic {
+  code: string
+  severity: 'info' | 'warning' | 'error'
+  message: string
+  sectionId?: string
+  stepId?: string
+  blockId?: string
+  narrationId?: string
+  assetId?: string
+  mediaClipId?: string
+}
+export interface ProductionPlan {
+  binding: ProductionBinding
+  durationMs?: number
+  timing: ProductionTiming
+  pages: ProductionPage[]
+  tracks: ProductionTrack[]
+  events: TrackEvent[]
+  diagnostics: ProductionDiagnostic[]
+  /** Preview may buffer at missing speech; export still requires a confirmed complete plan. */
+  canPreview: boolean
+  canExport: boolean
+}

package/src/contracts/projects.ts

@@ -0,0 +1,59 @@
+import type { DocumentOperation, OperationAnswer } from './workspace.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { Member } from './server.ts'
+
+export const PROJECT_MAX_REQUEST_CHARS = 4096
+export const PROJECT_MAX_RESPONSE_CHARS = 7168
+export const PROJECT_MAX_PLANS = 64
+export const PROJECT_PLAN_TTL_MS = 300_000
+export type ProjectOperation = DocumentOperation | { op: 'retitle', dir: string, title: string }
+export interface ProjectCaller { member: Member, origin: 'editor' | 'agent', boundDocument?: string }
+export interface ProjectObservation { snapshot?: string, configuration: string }
+export interface ProjectCapabilities {
+  available: boolean
+  actions: Record<ProjectOperation['op'], { available: boolean, reasons: string[] }>
+  reasons: string[]
+  observation: ProjectObservation
+  verification: 'configuration-only'
+  rootDirectoryOperations: false
+  limits: { requestChars: number, responseChars: number, backupEntries: number, backupBytes: number, plans: number, ttlMs: number }
+}
+export interface ProjectPlanRequest { id: string, operation: ProjectOperation }
+export interface ProjectPlan {
+  id: string
+  planId: string
+  digest: string
+  operation: ProjectOperation
+  observation: ProjectObservation
+  tree?: string
+  source?: CanonicalSource
+  documentId?: string
+  expiresAt: string
+  impact: { added: string[], removed: string[], files: number, bytes: number, referenceDocuments: string[], referencePolicy: 'preserve-or-refuse' }
+}
+export interface ProjectApply { planId: string, digest: string, confirmDeletion?: true }
+export interface ProjectApplied extends OperationAnswer {
+  id: string
+  planId: string
+  snapshot?: string
+  tree?: string
+  source?: CanonicalSource
+  documentId?: string
+  revisionTruncated?: true
+  fileCount?: number
+  verification: { saved: true, readback: 'verified', compiled: 'not-requested' }
+}
+/** Directory management borrows the Web writer; metadata retitle borrows canonical document CAS. */
+export interface ProjectAuthoring {
+  capabilities(caller: ProjectCaller): Promise<ProjectCapabilities>
+  plan(request: ProjectPlanRequest, caller: ProjectCaller): Promise<ProjectPlan>
+  readPlan(request: ProjectApply, caller: ProjectCaller): Promise<ProjectPlan>
+  apply(request: ProjectApply, caller: ProjectCaller, signal?: AbortSignal): Promise<ProjectApplied>
+}
+const text = { type: 'string', minLength: 1, maxLength: 200 } as const
+const dir = { type: 'string', maxLength: 200 } as const
+const operation = (op: string, properties: Record<string, unknown>, required: string[]) => ({ type: 'object', additionalProperties: false, properties: { op: { const: op }, dir, ...properties }, required: ['op', 'dir', ...required] })
+export const PROJECT_PLAN_SCHEMA = { type: 'object', additionalProperties: false, required: ['id', 'operation'], properties: {
+  id: text, operation: { oneOf: [operation('create', { title: text, template: text }, []), operation('copy', { to: text, title: text }, ['to']), operation('rename', { to: text }, ['to']), operation('delete', {}, []), operation('retitle', { title: text }, ['title'])] },
+} } as const
+export const PROJECT_APPLY_SCHEMA = { type: 'object', additionalProperties: false, required: ['planId', 'digest'], properties: { planId: text, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, confirmDeletion: { const: true } } } as const

package/src/contracts/server.ts

@@ -1,4 +1,4 @@
-import type { Logger } from '../contracts.ts'
+import type { Logger } from './plugin.ts'
 import { defineService } from './service.ts'
 import type { ServiceToken } from './service.ts'
 
@@ -27,14 +27,6 @@ export interface Route {
 
 export const MAX_BODY = 1 << 20
 
-export function json(data: unknown, status = 200, headers: Record<string, string> = {}): Response {
-  return new Response(JSON.stringify(data), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers } })
-}
-
-export function problem(status: number, message: string): Response {
-  return json({ error: message }, status)
-}
-
 export interface ProxySpec {
   path: string
   target: string
@@ -92,48 +84,6 @@ export interface Approvals {
 
 export const APPROVALS = defineService<Approvals>('presmium.approvals')
 
-export function eventStream(events: AsyncIterable<{ event?: string, data: unknown }>, signal?: AbortSignal): Response {
-  const encoder = new TextEncoder()
-  const iterator = events[Symbol.asyncIterator]()
-  let closed = false
-  const stop = (controller?: ReadableStreamDefaultController<Uint8Array>) => {
-    if (closed) return
-    closed = true
-    void iterator.return?.()
-    try {
-      controller?.close()
-    } catch {
-    }
-  }
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      if (signal?.aborted) stop(controller)
-      else signal?.addEventListener('abort', () => stop(controller), { once: true })
-    },
-    async pull(controller) {
-      if (closed) return
-      try {
-        const next = await iterator.next()
-        if (closed) return
-        if (next.done) {
-          stop(controller)
-          return
-        }
-        const { event, data } = next.value
-        const lines = `${event ? `event: ${event}\n` : ''}${JSON.stringify(data ?? null).split('\n').map(line => `data: ${line}`).join('\n')}\n\n`
-        controller.enqueue(encoder.encode(lines))
-      } catch (error) {
-        closed = true
-        controller.error(error)
-      }
-    },
-    cancel() {
-      stop()
-    },
-  })
-  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' } })
-}
-
 export type AgentMode = 'author'
 
 export interface McpAccess {

package/src/contracts/speech-settings.ts

@@ -0,0 +1,16 @@
+/** Operator configuration is separate from document voice choices. Secret values are write-only. */
+export interface SpeechSettingsAnswer {
+  provider: 'volcengine'
+  model: 'seed-tts-2.0'
+  revision: string
+  configured: boolean
+  appIdConfigured?: boolean
+  source: 'saved' | 'environment' | 'none'
+  stored: boolean
+  writable: boolean
+  verification: 'configuration-only'
+}
+
+export type SpeechSettingsChange =
+  | { action: 'save', revision: string, apiKey?: string, appId?: string }
+  | { action: 'clear', revision: string }

package/src/contracts/speech.ts

@@ -2,76 +2,6 @@ import { defineService } from './service.ts'
 
 export interface SpeechWord { text: string, start: number, end: number }
 
-const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u
-const LETTER = /[\p{L}\p{N}'’]/u
-
-export interface TextWord { text: string, start: number, end: number }
-
-export function splitWords(text: string): TextWord[] {
-  const words: TextWord[] = []
-  let run: TextWord | undefined
-  let at = 0
-  for (const char of text) {
-    if (CJK.test(char)) {
-      if (run) words.push(run)
-      run = undefined
-      words.push({ text: char, start: at, end: at + char.length })
-    } else if (LETTER.test(char)) {
-      run ??= { text: '', start: at, end: at }
-      run.text += char
-      run.end = at + char.length
-    } else if (run) {
-      words.push(run)
-      run = undefined
-    }
-    at += char.length
-  }
-  if (run) words.push(run)
-  return words
-}
-
-export interface WordSpan { from: number, to: number, start: number, end: number }
-
-export interface WrittenWord extends SpeechWord { offset?: number }
-
-export function remapWords(words: readonly SpeechWord[], written: string, spoken: string, spans: readonly WordSpan[]): WrittenWord[] {
-  const places: { start: number, end: number }[] = []
-  let at = 0
-  for (const word of words) {
-    const index = word.text ? spoken.indexOf(word.text, at) : -1
-    if (index < 0) return words.map(w => ({ ...w }))
-    places.push({ start: index, end: at = index + word.text.length })
-  }
-  const writtenAt = (offset: number) => {
-    let shift = 0
-    for (const span of spans) {
-      if (offset < span.from) break
-      if (offset < span.to) return span.start
-      shift += (span.end - span.start) - (span.to - span.from)
-    }
-    return offset + shift
-  }
-  const result: WrittenWord[] = []
-  let group: { span: WordSpan, word: WrittenWord } | undefined
-  words.forEach((word, i) => {
-    const { start, end } = places[i]!
-    const span = spans.find(s => start < s.to && end > s.from)
-    if (span && group?.span === span) {
-      group.word.end = Math.max(group.word.end, word.end)
-      return
-    }
-    group = undefined
-    if (span) {
-      const placed = { text: written.slice(span.start, span.end), start: word.start, end: word.end, offset: span.start }
-      group = { span, word: placed }
-      result.push(placed)
-    } else {
-      result.push({ ...word, offset: writtenAt(start) })
-    }
-  })
-  return result
-}
-
 export interface Synthesis {
   audio: Blob | string
   mime: string
@@ -81,9 +11,20 @@ export interface Synthesis {
   engine: string
   model: string
   voice: string
+  provider: string
   synthetic: true
 }
 
+export interface AigcLabel {
+  Label: '1'
+  ContentProducer: string
+  ProduceID: string
+  ReservedCode1: string
+  ContentPropagator: string
+  PropagateID: string
+  ReservedCode2: string
+}
+
 export interface TranscriptSegment { start: number, end: number, text: string, words: SpeechWord[] }
 
 export interface Transcript {
@@ -100,6 +41,17 @@ export interface SpeechEngineInfo {
   tts: boolean
   wordTimes: boolean
   local: boolean
+  /** The engine can train a cloned voice from a sample (`SpeechService.cloneVoice`); absent means it cannot. */
+  clone?: boolean
+  /** Absent means the provider has not declared a supported authoring range. */
+  parameters?: { rate?: { min: number, max: number, step?: number }, styles?: string[] }
+}
+
+export interface SpeechVoice {
+  engine?: string
+  voice: string
+  rate?: number
+  style?: string
 }
 
 export interface VoiceInfo {
@@ -109,6 +61,11 @@ export interface VoiceInfo {
   cloned?: boolean
 }
 
+/** A provider list may be empty. An unsupported catalogue must not be presented as an empty list. */
+export type VoiceCatalog =
+  | { status: 'available', source: 'provider' | 'bundled', voices: VoiceInfo[] }
+  | { status: 'unavailable', reason: 'not-configured' | 'unsupported' | 'unknown', voices: VoiceInfo[] }
+
 export interface SynthesisRequest {
   engine?: string
   voice: string
@@ -119,6 +76,33 @@ export interface SynthesisRequest {
   lexicon?: Record<string, string>
 }
 
+/**
+ * Training a cloned voice. The speaker's consent comes with the request and is registered before anything is sent:
+ * `statement` is their recording of the consent statement, kept by the operator, whose sha256 the record holds.
+ */
+export interface VoiceCloneRequest {
+  engine?: string
+  /** The voice to train: a slot the operator owns at the provider (Volcengine's S_…) or a new name, per the engine. */
+  voice: string
+  /** One speaker, mono, about 10–30 s. */
+  sample: Blob
+  lang?: string
+  /** What the sample says, when known: providers that compare it reject a mismatch. */
+  text?: string
+  consent: { speaker: string, scope: string, statement: Blob }
+}
+
+export type VoiceCloneState = 'training' | 'ready' | 'failed' | 'unknown'
+
+export interface VoiceCloneStatus {
+  engine: string
+  voice: string
+  state: VoiceCloneState
+  /** How many more trainings the provider allows for this voice. */
+  trainingsLeft?: number
+  message?: string
+}
+
 export interface TranscriptionRequest {
   engine?: string
   audio: Blob
@@ -128,10 +112,38 @@ export interface TranscriptionRequest {
 
 export interface SpeechService {
   engines(): Promise<SpeechEngineInfo[]>
+  /** The actual default in this document's scoped service; absent means its identity is unknown. */
+  defaultSynthesisEngine?(): Promise<string | undefined>
   voices(engine: string, lang?: string): Promise<VoiceInfo[]>
+  /** Lists registered voices without synthesis. Absence means catalogue availability is unknown. */
+  voiceCatalog?(engine?: string, lang?: string, signal?: AbortSignal): Promise<VoiceCatalog>
   synthesize(request: SynthesisRequest, signal?: AbortSignal): Promise<Synthesis>
+  /** Exact request/configuration lookup with verified audio bytes. Offline reuse requires an unambiguous lock. A miss never calls synthesis or transcription providers. */
+  lookup?(request: SynthesisRequest, signal?: AbortSignal): Promise<Synthesis | undefined>
+  /** Verifies the current configuration profile, or an explicit offline lock, and the actual audio SHA. */
   cached?(key: string, signal?: AbortSignal): Promise<Synthesis | undefined>
+  alignWords?(key: string, options: { lang: string, transcribe?: boolean }, signal?: AbortSignal): Promise<SpeechWord[] | undefined>
+  pruneLock?(keep: ReadonlySet<string>): Promise<number>
   transcribe(request: TranscriptionRequest, signal?: AbortSignal): Promise<Transcript>
+  /** Registers the consent, then starts training; only for the document's owner. Absent: the service cannot clone. */
+  cloneVoice?(request: VoiceCloneRequest, signal?: AbortSignal): Promise<VoiceCloneStatus>
+  cloneStatus?(engine: string, voice: string, signal?: AbortSignal): Promise<VoiceCloneStatus>
 }
 
 export const SPEECH = defineService<SpeechService>('presmium.speech')
+
+/** Stable author-facing reasons; provider payloads and credential values are never UI text. */
+export function speechFailureCode(error: unknown): string | undefined {
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : ''
+  if (/^speech-(authentication|permission|quota|busy|network|empty-audio|invalid-request|provider|cache-failed)$/.test(message)) return message
+  if (/quota exceeded.*concurrency|too many requests|answered 429|is busy: more requests/i.test(message)) return 'speech-busy'
+  if (/quota exceeded|insufficient.*(balance|credit)|payment required|balance.*insufficient/i.test(message)) return 'speech-quota'
+  if (/answered 401|45000010|unauthorized|invalid (?:(?:x-)?api.?key|token)|authentication failed/i.test(message)) return 'speech-authentication'
+  if (/EACCES|ENOSPC|EROFS|speech.*cache.*(write|failed)/i.test(message)) return 'speech-cache-failed'
+  if (/answered 403|resource.*mismatch|permission denied|access denied|service.*not.*(enabled|activated)/i.test(message)) return 'speech-permission'
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|UND_ERR|network error/i.test(message)) return 'speech-network'
+  if (/gave no audio|no audio data/i.test(message)) return 'speech-empty-audio'
+  if (/answered 4\d\d|45000001|4500200[01]|invalid argument/i.test(message)) return 'speech-invalid-request'
+  if (/answered 5\d\d|55000000/i.test(message)) return 'speech-provider'
+  return undefined
+}

package/src/contracts/steps.ts

@@ -0,0 +1,15 @@
+export interface StepRange {
+  from: number
+  to?: number
+}
+
+export interface StepState {
+  active: boolean
+  reached: boolean
+  done: boolean
+}
+
+export interface Cursor {
+  slide: number
+  step: number
+}

package/src/contracts/transcription-adoption.ts

@@ -0,0 +1,79 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { DocumentChangeAnswer } from './workspace.ts'
+import type { NarrationNode, TeachingDocument } from './document.ts'
+import type { Member } from './server.ts'
+
+export type TranscriptionAdoptionPart = { type: 'text', text: string } | { type: 'preserve', key: string }
+export interface TranscriptionAdoptionTarget {
+  sectionId: string
+  stepId: string
+  narrationId?: string
+  segmentIds: string[]
+  content?: TranscriptionAdoptionPart[]
+  discardAtoms?: string[]
+  shared?: 'edit-shared' | 'fork'
+  affectedStepIds?: string[]
+}
+export interface TranscriptionAdoptionDraft {
+  id: string
+  source: CanonicalSource
+  candidate: { id: string, revision: string }
+  draftRevision: number
+  targets: TranscriptionAdoptionTarget[]
+  /** Explicitly confirmed cleanup, only for cues actually removed by this adoption. */
+  removeCueTimings?: string[]
+}
+export interface TranscriptionAdoptionApply {
+  planId: string
+  source: CanonicalSource
+  candidate: { id: string, revision: string }
+  draftRevision: number
+}
+export interface TranscriptionAdoptionConflict { code: string, target?: number, key?: string, stepIds?: string[] }
+export interface TranscriptionAdoptionPreview {
+  targets: { sectionId: string, stepId: string, narrationId?: string, outputNarrationId: string, segmentIds: string[], sourceText: string, before: NarrationNode[], proposed: NarrationNode[], atoms: { key: string, node: Exclude<NarrationNode, { type: 'text' }> }[] }[]
+  conflicts: TranscriptionAdoptionConflict[]
+  impact: { narrationIds: string[], stepIds: string[], sharedStepIds: string[], forks: { from: string, to: string, stepId: string, cues: { from: string, to: string }[] }[], removedAtoms: string[], removedCueTimings: string[] }
+}
+export interface TranscriptionAdoptionPlan extends TranscriptionAdoptionPreview {
+  document: string
+  changeId: string
+  source: CanonicalSource
+  candidate: { id: string, revision: string }
+  draftRevision: number
+  planId?: string
+  expiresAt?: string
+  content?: TeachingDocument
+}
+export interface TranscriptionAdoptionAnswer extends DocumentChangeAnswer {
+  adoption: { planId: string, candidate: { id: string, revision: string }, draftRevision: number }
+}
+/** Agent-safe surface. An editor HTTP adapter receives its trusted write path separately. */
+export interface DocumentTranscriptionAdoption {
+  plan(document: string, draft: TranscriptionAdoptionDraft, member: Member): Promise<TranscriptionAdoptionPlan>
+  /** The adoption's checks without writing: plan, draft revision, candidate, current source; `apply` checks everything again. */
+  check(document: string, request: TranscriptionAdoptionApply, member: Member): Promise<void>
+  apply(document: string, request: TranscriptionAdoptionApply, member: Member): Promise<TranscriptionAdoptionAnswer>
+}
+
+const id = { type: 'string', minLength: 1, maxLength: 200, pattern: '^[^\u0000-\u001f]+$', not: { enum: ['__proto__', 'constructor', 'prototype'] } }
+const digest = { type: 'string', pattern: '^[a-f0-9]{64}$' }
+const key = { type: 'string', minLength: 1, maxLength: 512 }
+const source = { type: 'object', properties: { documentId: id, version: { type: 'string', pattern: '^[a-f0-9]{20}$' }, fingerprint: { type: 'string', pattern: '^[a-f0-9]{16}$' } }, required: ['documentId', 'version', 'fingerprint'], additionalProperties: false }
+const candidate = { type: 'object', properties: { id: digest, revision: digest }, required: ['id', 'revision'], additionalProperties: false }
+const draftRevision = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER }
+const unique = (items: object) => ({ type: 'array', items, uniqueItems: true, maxItems: 1000 })
+export const TRANSCRIPTION_ADOPTION_DRAFT_SCHEMA = {
+  type: 'object', additionalProperties: false, required: ['id', 'source', 'candidate', 'draftRevision', 'targets'],
+  properties: { id, source, candidate, draftRevision, removeCueTimings: unique(id), targets: { type: 'array', minItems: 1, maxItems: 100, items: {
+    type: 'object', additionalProperties: false, required: ['sectionId', 'stepId', 'segmentIds'], properties: {
+      sectionId: id, stepId: id, narrationId: id, segmentIds: { ...unique(id), minItems: 1 },
+      shared: { enum: ['edit-shared', 'fork'] }, affectedStepIds: unique(id), discardAtoms: unique(key),
+      content: { type: 'array', maxItems: 1000, items: { oneOf: [
+        { type: 'object', properties: { type: { const: 'text' }, text: { type: 'string', maxLength: 1_048_576 } }, required: ['type', 'text'], additionalProperties: false },
+        { type: 'object', properties: { type: { const: 'preserve' }, key }, required: ['type', 'key'], additionalProperties: false },
+      ] } },
+    },
+  } } },
+}
+export const TRANSCRIPTION_ADOPTION_APPLY_SCHEMA = { type: 'object', additionalProperties: false, properties: { planId: id, source, candidate, draftRevision }, required: ['planId', 'source', 'candidate', 'draftRevision'] }