@lincyaw/kernel 0.0.0-stage → 1.0.0-rc.1

package/src/contracts/document-audio.ts

@@ -0,0 +1,150 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { Finding } from './checks.ts'
+import type { DocumentIssue, MediaClip, TimeRange } from './document.ts'
+import { DOCUMENT_AUDIO_MAX_BYTES } from './production-assets.ts'
+import type { DocumentAudioImportAnswer, DocumentAudioInspectionAnswer, ProductionAssetInspection, ProductionAudioPlanQuery } from './production-assets.ts'
+import type { ProductionBinding, ProductionPlan } from './production.ts'
+import type { Member } from './server.ts'
+import type { DocumentChangeAnswer } from './workspace.ts'
+
+export const DOCUMENT_AUDIO_REQUEST_MAX_BYTES = 16 << 10
+
+export interface DocumentAudioCapabilities {
+  source: CanonicalSource
+  available: boolean
+  status: 'available' | 'unavailable' | 'unknown'
+  reason?: 'audio-unavailable' | 'services-unavailable'
+  verification: 'configuration-only'
+  findings?: Finding[]
+  actions: { inspect: boolean, inspectWorkspace: boolean, importWorkspace: boolean, readProductionPlan: boolean, validateClipChange: boolean, changeClip: boolean, adoptRecording: boolean }
+  importUnavailableReason?: 'review-required' | 'operation-disabled'
+  clipChangeUnavailableReason?: 'review-required' | 'operation-disabled'
+  clips: { upsert: boolean, remove: true, upsertRequires: 'current-production-binding' }
+  limits: { audioBytes: number, requestBytes: number, receipts: number, concurrent: number }
+  workspaceFileScope: 'same-document'
+  idempotency: 'process-current-source'
+  review: 'required-unsupported' | 'locks-and-history' | 'locks-only'
+}
+export interface DocumentAudioInspect { source: CanonicalSource, assetId: string }
+/** Missing range adopts the whole file. A range edits only an already adopted same-asset step recording. */
+export interface DocumentRecordingAdoption { id: string, source: CanonicalSource, stepId: string, assetId: string, sha256: string, sourceRange?: TimeRange }
+export interface VerifiedDocumentRecordingAdoption extends DocumentChangeAnswer {
+  verification: { saved: true, source: CanonicalSource, stepId: string, assetId: string, sha256: string, durationMs: number, sourceRange?: TimeRange, usedDurationMs?: number, compiled: 'not-requested', runtime: 'not-requested' }
+}
+/** Inspect an existing real snapshot; an expected revision is optional during discovery. */
+export type DocProductionPlanQuery = ProductionAudioPlanQuery
+export interface DocumentWorkspaceAudioInspect { source: CanonicalSource, path: string }
+export interface WorkspaceAudioInspectionAnswer {
+  document: string
+  source: CanonicalSource
+  file: { path: string, sha256: string, byteLength: number }
+  inspection: Omit<ProductionAssetInspection, 'assetId' | 'mediaId'>
+}
+export interface DocumentWorkspaceAudioImport {
+  id: string
+  source: CanonicalSource
+  /** Workspace-relative regular file permitted by the selected document's existing source scope. */
+  file: { path: string, sha256: string, byteLength: number }
+}
+export interface VerifiedDocumentAudioImport extends DocumentAudioImportAnswer {
+  verification: {
+    saved: true
+    source: CanonicalSource
+    asset: { assetId: string, path: string, sha256: string, byteLength: number }
+    compiled: 'not-requested'
+    runtime: 'not-requested'
+  }
+}
+/** A repeatable check against saved content; no plan or write intent is retained. */
+export type DocumentMediaClipValidation =
+  | { source: CanonicalSource, binding: ProductionBinding, clip: MediaClip }
+  | { source: CanonicalSource, removeClipId: string }
+export type DocumentMediaClipEdit = DocumentMediaClipValidation & { id: string }
+export interface DocumentMediaClipValidationAnswer {
+  document: string
+  source: CanonicalSource
+  operation: 'add' | 'update' | 'remove'
+  clipId: string
+  before?: MediaClip
+  after?: MediaClip
+  impact: { stepIds: string[], assetIds: string[] }
+  issues: DocumentIssue[]
+  checked: { canonical: true, production: 'validated' | 'not-required', binding?: ProductionBinding }
+}
+export interface VerifiedDocumentMediaClipChange extends DocumentChangeAnswer {
+  verification: {
+    saved: true
+    source: CanonicalSource
+    production: 'validated-before-save' | 'not-required'
+    binding?: ProductionBinding
+    compiled: 'not-requested'
+    runtime: 'not-requested'
+  }
+}
+/** Workspace authoring boundary, distinct from the plugin's low-level ProductionAudioAuthoring. */
+export interface DocumentAudioAuthoring {
+  capabilities(document: string, member: Member): Promise<DocumentAudioCapabilities>
+  inspect(document: string, request: DocumentAudioInspect, member: Member, signal?: AbortSignal): Promise<DocumentAudioInspectionAnswer>
+  inspectWorkspace(document: string, request: DocumentWorkspaceAudioInspect, member: Member, signal?: AbortSignal): Promise<WorkspaceAudioInspectionAnswer>
+  readProductionPlan(document: string, request: DocProductionPlanQuery, member: Member, signal?: AbortSignal): Promise<ProductionPlan>
+  /** Agent entry. Origin and required review come from the host, never from this request. */
+  /** The import's checks without its transaction (scope, file bytes and SHA-256/length, audio format, current source or a replayable receipt); `importWorkspace` checks everything again. */
+  checkWorkspaceImport(document: string, request: DocumentWorkspaceAudioImport, member: Member, signal?: AbortSignal): Promise<void>
+  importWorkspace(document: string, request: DocumentWorkspaceAudioImport, member: Member, signal?: AbortSignal): Promise<VerifiedDocumentAudioImport>
+  validateClipChange(document: string, request: DocumentMediaClipValidation, member: Member, signal?: AbortSignal): Promise<DocumentMediaClipValidationAnswer>
+  /** Agent entry; the transaction rechecks source, real media and current production timing. */
+  changeClip(document: string, request: DocumentMediaClipEdit, member: Member, signal?: AbortSignal): Promise<VerifiedDocumentMediaClipChange>
+  /** The change's checks without writing (as validateClipChange, plus review and a replayable receipt). */
+  checkClipChange(document: string, request: DocumentMediaClipEdit, member: Member, signal?: AbortSignal): Promise<void>
+  /** The adoption's checks without writing: step, asset bytes and SHA-256, range, current source or a replayable receipt. */
+  checkRecordingAdoption(document: string, request: DocumentRecordingAdoption, member: Member, signal?: AbortSignal): Promise<void>
+  adoptRecording(document: string, request: DocumentRecordingAdoption, member: Member, signal?: AbortSignal): Promise<VerifiedDocumentRecordingAdoption>
+}
+
+const source = { type: 'object', additionalProperties: false, properties: { documentId: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', pattern: '^[a-f\\d]{20}$' }, fingerprint: { type: 'string', pattern: '^[a-f\\d]{16}$' } }, required: ['documentId', 'version', 'fingerprint'] } as const
+export const DOCUMENT_AUDIO_INSPECTION_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: { source, assetId: { type: 'string', minLength: 1, maxLength: 200 } },
+  required: ['source', 'assetId'],
+} as const
+export const DOCUMENT_RECORDING_ADOPTION_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: { id: { type: 'string', minLength: 1, maxLength: 200 }, source, stepId: { type: 'string', minLength: 1, maxLength: 200 }, assetId: { type: 'string', minLength: 1, maxLength: 200 }, sha256: { type: 'string', pattern: '^[a-f\\d]{64}$' }, sourceRange: { type: 'object', additionalProperties: false, properties: { startMs: { type: 'number', minimum: 0 }, endMs: { type: 'number', minimum: 0 } }, required: ['startMs', 'endMs'] } },
+  required: ['id', 'source', 'stepId', 'assetId', 'sha256'],
+} as const
+export const DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    id: { type: 'string', minLength: 1, maxLength: 200 }, source,
+    file: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', minLength: 1, maxLength: 1024 }, sha256: { type: 'string', pattern: '^[a-f\\d]{64}$' }, byteLength: { type: 'integer', minimum: 1, maximum: DOCUMENT_AUDIO_MAX_BYTES } }, required: ['path', 'sha256', 'byteLength'] },
+  },
+  required: ['id', 'source', 'file'],
+} as const
+
+export const DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: { source, path: { type: 'string', minLength: 1, maxLength: 1024 } },
+  required: ['source', 'path'],
+} as const
+
+const clipId = { type: 'string', minLength: 1, maxLength: 200, pattern: '^[^\\u0000-\\u001f]+$', not: { enum: ['__proto__', 'constructor', 'prototype'] } } as const
+const clip = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    id: clipId, assetId: clipId,
+    sourceRange: { type: 'object', additionalProperties: false, properties: { startMs: { type: 'number', minimum: 0 }, endMs: { type: 'number', minimum: 0 } }, required: ['startMs', 'endMs'] },
+    attachment: { type: 'object', additionalProperties: false, properties: { stepId: clipId, offsetMs: { type: 'number', minimum: 0 } }, required: ['stepId', 'offsetMs'] },
+    volume: { type: 'number', minimum: 0, maximum: 1 }, muted: { type: 'boolean' },
+  },
+  required: ['id', 'assetId', 'sourceRange', 'attachment', 'volume'],
+} as const
+const productionBinding = { type: 'object', additionalProperties: false, properties: { source, irRevision: { type: 'string', pattern: '^[a-f\\d]{16}$' }, planId: { type: 'string', pattern: '^[a-f\\d]{32}$' } }, required: ['source', 'irRevision', 'planId'] } as const
+export const DOCUMENT_PRODUCTION_PLAN_SCHEMA = { type: 'object', additionalProperties: false, properties: { source, irRevision: productionBinding.properties.irRevision }, required: ['source'] } as const
+const clipRequestSchema = (edit: boolean) => ({
+  oneOf: [
+    { type: 'object', additionalProperties: false, properties: { ...edit ? { id: clipId } : {}, source, binding: productionBinding, clip }, required: [...edit ? ['id'] : [], 'source', 'binding', 'clip'] },
+    { type: 'object', additionalProperties: false, properties: { ...edit ? { id: clipId } : {}, source, removeClipId: clipId }, required: [...edit ? ['id'] : [], 'source', 'removeClipId'] },
+  ],
+})
+export const DOCUMENT_MEDIA_CLIP_VALIDATION_SCHEMA = /* @__PURE__ */ clipRequestSchema(false)
+export const DOCUMENT_MEDIA_CLIP_CHANGE_SCHEMA = /* @__PURE__ */ clipRequestSchema(true)

package/src/contracts/document-comments.ts

@@ -0,0 +1,31 @@
+import type { DocumentThread, JsonObject, RichTextNode } from './document.ts'
+import type { Member } from './server.ts'
+
+/** Canonical comment intent; author identity, dates and new entity IDs are supplied by the adapter. */
+export type DocumentCommentAction =
+  | { type: 'comment.create', content: RichTextNode[], anchor?: DocumentThread['anchor'] | null, metadata?: JsonObject, commentMetadata?: JsonObject }
+  | { type: 'comment.reply', threadId: string, content: RichTextNode[], metadata?: JsonObject }
+  | { type: 'comment.update', threadId: string, commentId: string, content: RichTextNode[], metadata?: JsonObject }
+  | { type: 'comment.react', threadId: string, commentId: string, emoji: string, active: boolean }
+  | { type: 'comment.resolve' | 'comment.reopen', threadId: string }
+  | { type: 'comment.delete', threadId: string, commentId?: string }
+
+export interface DocumentCommentContext {
+  member?: Member
+  now: string
+  allocate(): string
+  /** MCP content IDs are only input placeholders; native projections retain their own stable rich IDs. */
+  allocateContentIds?: boolean
+}
+export interface DocumentCommentEffect {
+  threadId: string
+  commentId?: string
+  changed: boolean
+  anchored: boolean
+  /** The target thread’s prior anchor was invalid; the discussion remains explicitly unanchored. */
+  anchorDetached?: boolean
+  threadRemoved: boolean
+  removedComments: number
+  comments: number
+  reactions: number
+}

package/src/contracts/document-history.ts

@@ -0,0 +1,63 @@
+import type { Member } from './server.ts'
+import type { HistoryRevision, RevisionsAnswer } from './workspace.ts'
+
+export const DOCUMENT_HISTORY_MAX_REQUEST_CHARS = 2048
+export const DOCUMENT_HISTORY_MAX_RESPONSE_CHARS = 7168
+export const DOCUMENT_HISTORY_MAX_FILE_BYTES = 2 << 20
+export const DOCUMENT_HISTORY_PAGE_SIZE = 20
+
+/** Actual saved bytes; a malformed current JSON can still be inspected and undone. */
+export interface DocumentHistorySource { version: string, fingerprint: string }
+export interface DocumentHistoryBinding { source: DocumentHistorySource, snapshot: string }
+export interface DocumentHistoryQuery { offset?: number, snapshot?: string }
+export interface DocumentHistoryAnswer extends RevisionsAnswer {
+  document: string
+  available: boolean
+  unborn?: true
+  historyBinding?: DocumentHistoryBinding
+  nextOffset?: number
+  /** Compact summaries and file lists may be abbreviated, never commit IDs. */
+  truncated?: true
+}
+export interface DocumentHistoryRead { revision: string, path?: string, offset?: number }
+export interface DocumentHistoryFile {
+  document: string
+  revision: string
+  path: string
+  encoding: 'utf8-text-fragment'
+  text: string
+  offset: number
+  nextOffset?: number
+  totalChars: number
+  complete: boolean
+  sha256: string
+  verification: 'historical-file-only'
+}
+export interface DocumentHistoryChange extends DocumentHistoryBinding { id: string, expect: string }
+export interface DocumentHistoryChanged extends DocumentHistoryBinding {
+  document: string
+  ok: true
+  revision: Pick<HistoryRevision, 'id' | 'origin'>
+  verification: { saved: true, compiled: 'not-requested', runtime: 'not-requested' }
+}
+/** One workspace owner; HTTP and MCP do not implement reversion or write files. */
+export interface DocumentHistory {
+  list(document: string, query: DocumentHistoryQuery, member: Member): Promise<DocumentHistoryAnswer>
+  read(document: string, query: DocumentHistoryRead, member: Member): Promise<DocumentHistoryFile>
+  /** The change's checks without writing: binding, target, document scope, next undo/redo, conflicts and uncommitted files, or a replayable receipt. */
+  checkChange(document: string, which: 'undo' | 'redo' | 'revert', request: DocumentHistoryChange, member: Member, origin?: 'editor' | 'agent'): Promise<void>
+  change(document: string, which: 'undo' | 'redo' | 'revert', request: DocumentHistoryChange, member: Member, origin?: 'editor' | 'agent'): Promise<DocumentHistoryChanged>
+}
+const hash = { type: 'string', pattern: '^(?:[a-f0-9]{40}|[a-f0-9]{64})$' } as const
+export const DOCUMENT_HISTORY_QUERY_SCHEMA = { type: 'object', additionalProperties: false, properties: {
+  offset: { type: 'integer', minimum: 0 }, snapshot: hash,
+} } as const
+export const DOCUMENT_HISTORY_READ_SCHEMA = { type: 'object', additionalProperties: false, required: ['revision'], properties: {
+  revision: hash, path: { type: 'string', minLength: 1, maxLength: 500 }, offset: { type: 'integer', minimum: 0 },
+} } as const
+export const DOCUMENT_HISTORY_CHANGE_SCHEMA = { type: 'object', additionalProperties: false, required: ['id', 'source', 'snapshot', 'expect'], properties: {
+  id: { type: 'string', minLength: 1, maxLength: 200 }, snapshot: hash, expect: hash,
+  source: { type: 'object', additionalProperties: false, required: ['version', 'fingerprint'], properties: {
+    version: { type: 'string', minLength: 1, maxLength: 128 }, fingerprint: { type: 'string', minLength: 1, maxLength: 128 },
+  } },
+} } as const

package/src/contracts/document-image.ts

@@ -0,0 +1,32 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { Member } from './server.ts'
+import type { DocumentImageImportAnswer } from './workspace.ts'
+import { DOCUMENT_IMAGE_MAX_BYTES } from './workspace.ts'
+
+export interface DocumentWorkspaceImageInspect { source: CanonicalSource, path: string }
+export interface DocumentWorkspaceImageImport { id: string, source: CanonicalSource, file: { path: string, sha256: string, byteLength: number } }
+export interface WorkspaceImageInspection {
+  document: string, source: CanonicalSource
+  file: { path: string, sha256: string, byteLength: number }
+  image: { mediaType: string, dimensions: { width: number, height: number } }
+}
+export interface VerifiedDocumentImageImport extends DocumentImageImportAnswer {
+  verification: { saved: true, source: CanonicalSource, asset: { assetId: string, path: string, sha256: string, byteLength: number }, compiled: 'not-requested', runtime: 'not-requested' }
+}
+export interface DocumentImageCapabilities {
+  source: CanonicalSource, available: true, verification: 'configuration-only'
+  actions: { inspectWorkspace: true, importWorkspace: boolean }
+  importUnavailableReason?: 'review-required' | 'operation-disabled'
+  limits: { imageBytes: number, receipts: number, concurrent: number }, workspaceFileScope: 'same-document', idempotency: 'process-current-source'
+  review: 'required-unsupported' | 'locks-and-history' | 'locks-only'
+}
+export interface DocumentImageAuthoring {
+  capabilities(document: string, member: Member): Promise<DocumentImageCapabilities>
+  inspectWorkspace(document: string, request: DocumentWorkspaceImageInspect, member: Member, signal?: AbortSignal): Promise<WorkspaceImageInspection>
+  /** The import's checks without its transaction (scope, file bytes and SHA-256/length, current source or a replayable receipt), so a doomed import is refused before the author is asked; `importWorkspace` checks everything again. */
+  checkWorkspaceImport(document: string, request: DocumentWorkspaceImageImport, member: Member, signal?: AbortSignal): Promise<void>
+  importWorkspace(document: string, request: DocumentWorkspaceImageImport, member: Member, signal?: AbortSignal): Promise<VerifiedDocumentImageImport>
+}
+const source = { type: 'object', additionalProperties: false, properties: { documentId: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', pattern: '^[a-f\\d]{20}$' }, fingerprint: { type: 'string', pattern: '^[a-f\\d]{16}$' } }, required: ['documentId', 'version', 'fingerprint'] } as const
+export const DOCUMENT_WORKSPACE_IMAGE_INSPECTION_SCHEMA = { type: 'object', additionalProperties: false, properties: { source, path: { type: 'string', minLength: 1, maxLength: 1024 } }, required: ['source', 'path'] } as const
+export const DOCUMENT_WORKSPACE_IMAGE_IMPORT_SCHEMA = { type: 'object', additionalProperties: false, properties: { id: { type: 'string', minLength: 1, maxLength: 200 }, source, file: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', minLength: 1, maxLength: 1024 }, sha256: { type: 'string', pattern: '^[a-f\\d]{64}$' }, byteLength: { type: 'integer', minimum: 1, maximum: DOCUMENT_IMAGE_MAX_BYTES } }, required: ['path', 'sha256', 'byteLength'] } }, required: ['id', 'source', 'file'] } as const

package/src/contracts/document-reads.ts

@@ -0,0 +1,57 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { JsonValue } from './document.ts'
+
+export const DOCUMENT_READ_MAX_REQUEST_CHARS = 2048
+/** Includes JSON escaping and indentation used by the MCP text result. */
+export const DOCUMENT_READ_MAX_RESPONSE_CHARS = 7168
+export const DOCUMENT_ENTITY_COLLECTIONS = ['sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions', 'comments'] as const
+export const DOCUMENT_ROOT_FIELDS = ['schemaVersion', 'id', 'metadata', 'sectionOrder', 'production'] as const
+export type DocumentEntityCollection = typeof DOCUMENT_ENTITY_COLLECTIONS[number]
+export type DocumentPartTarget = { collection: DocumentEntityCollection, id: string, path?: string[] } | { collection: typeof DOCUMENT_ROOT_FIELDS[number], path?: string[] }
+export interface DocumentOutlineQuery { source?: CanonicalSource, collection?: DocumentEntityCollection, offset?: number }
+export interface DocumentPartQuery { source: CanonicalSource, target: DocumentPartTarget, offset?: number }
+export interface DocumentOutlineEntry {
+  id: string
+  type?: string
+  sectionId?: string
+  title?: { preview: string, complete: boolean, totalChars: number }
+  counts?: { children?: number, steps?: number, narrations?: number }
+}
+export interface DocumentOutlineAnswer {
+  source: CanonicalSource
+  documentSchemaVersion: number
+  counts: Record<DocumentEntityCollection, number>
+  collection: DocumentEntityCollection
+  present: boolean
+  offset: number
+  nextOffset?: number
+  total: number
+  complete: boolean
+  entries: DocumentOutlineEntry[]
+}
+interface DocumentPartAnswerBase {
+  source: CanonicalSource
+  target: DocumentPartTarget
+  /** FNV-1a 64 of JSON.stringify(selected canonical value), with no indentation. */
+  valueDigest: { algorithm: 'fnv1a64', serialization: 'JSON.stringify', value: string }
+}
+export type DocumentPartAnswer = DocumentPartAnswerBase & (
+  { encoding: 'value', complete: true, value: JsonValue } |
+  { encoding: 'json-text-fragment', offsetUnit: 'utf16', offset: number, nextOffset?: number, totalChars: number, complete: boolean, text: string }
+)
+
+const source = { type: 'object', additionalProperties: false, required: ['documentId', 'version', 'fingerprint'], properties: {
+  documentId: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', minLength: 1, maxLength: 128 }, fingerprint: { type: 'string', minLength: 1, maxLength: 128 },
+} } as const
+const offset = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER } as const
+const path = { type: 'array', maxItems: 64, items: { type: 'string', maxLength: 1024 } } as const
+export const DOCUMENT_OUTLINE_QUERY_SCHEMA = {
+  type: 'object', additionalProperties: false, properties: { source, collection: { enum: DOCUMENT_ENTITY_COLLECTIONS }, offset },
+  if: { required: ['offset'], properties: { offset: { minimum: 1 } } }, then: { required: ['source'] },
+} as const
+export const DOCUMENT_PART_QUERY_SCHEMA = {
+  type: 'object', additionalProperties: false, required: ['source', 'target'], properties: { source, offset, target: { oneOf: [
+    { type: 'object', additionalProperties: false, required: ['collection', 'id'], properties: { collection: { enum: DOCUMENT_ENTITY_COLLECTIONS }, id: { type: 'string', minLength: 1, maxLength: 200 }, path } },
+    { type: 'object', additionalProperties: false, required: ['collection'], properties: { collection: { enum: DOCUMENT_ROOT_FIELDS }, path } },
+  ] } },
+} as const

package/src/contracts/document-voice.ts

@@ -0,0 +1,44 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { Finding } from './checks.ts'
+import type { Member } from './server.ts'
+import type { SpeechEngineInfo } from './speech.ts'
+import type { VoiceCatalogAnswer, VoiceoverCancellation } from './voice.ts'
+import type { DocumentVoiceTasks, VoiceoverJobQuery, VoiceoverStart, VoicePreviewStart } from './voiceover-execution.ts'
+
+export interface DocumentVoiceCapabilities {
+  document: string
+  source: CanonicalSource
+  /** Configuration discovery does not prove provider authentication or synthesis success. */
+  verification: 'configuration-only'
+  status: 'configured' | 'unavailable' | 'unknown'
+  reason?: 'not-configured' | 'services-unavailable'
+  voiceover: boolean
+  preview: boolean
+  engines: SpeechEngineInfo[]
+  defaultEngine?: string
+  actions: { status: boolean, list: true, get: true, start: boolean, cancel: true, quotePreview: boolean, preview: boolean, readPreview: true }
+  tasks: { idempotency: 'process', limits: { intents: number, recentJobs: number, concurrent: number, quotes: number, quoteLifetimeMs: number, previewBytes: number, previewResources: number, retainedPreviewBytes: number } }
+  findings?: Finding[]
+}
+export interface DocumentVoiceCatalogQuery { source?: CanonicalSource, engine?: string, lang?: string }
+export interface DocumentVoiceCatalogAnswer extends VoiceCatalogAnswer { document: string, source: CanonicalSource, findings?: Finding[] }
+
+/** Shared voice discovery and explicitly authorized tasks; discovery never compiles or synthesizes. */
+export interface DocumentVoiceAuthoring extends DocumentVoiceTasks {
+  capabilities(document: string, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCapabilities>
+  catalog(document: string, query: DocumentVoiceCatalogQuery, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCatalogAnswer>
+  /** Checks a start or preview with the same path as the action, without synthesizing, so an agent asks only for one that would run. */
+  checkStart(document: string, request: VoiceoverStart, member: Member, signal?: AbortSignal): Promise<void>
+  checkPreview(document: string, request: VoicePreviewStart, member: Member, signal?: AbortSignal): Promise<void>
+  /** Undefined when there is something to cancel; otherwise the unchanged state that cancel would report. */
+  checkCancel(document: string, query: VoiceoverJobQuery, member: Member): Promise<VoiceoverCancellation | undefined>
+}
+
+export const DOCUMENT_VOICE_CATALOG_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    source: { type: 'object', additionalProperties: false, properties: { documentId: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', pattern: '^[a-f\\d]{20}$' }, fingerprint: { type: 'string', pattern: '^[a-f\\d]{16}$' } }, required: ['documentId', 'version', 'fingerprint'] },
+    engine: { type: 'string', minLength: 1, maxLength: 200 },
+    lang: { type: 'string', minLength: 1, maxLength: 100 },
+  },
+} as const

package/src/contracts/document.ts

@@ -0,0 +1,240 @@
+import type { ExecuteConfig } from './execution.ts'
+import type { SpeechVoice } from './speech.ts'
+
+export const DOCUMENT_SCHEMA_VERSION = 1 as const
+export const DOCUMENT_ENTRY = 'lecture.json'
+export const ASSET_TITLE_MAX_LENGTH = 200
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
+export interface JsonObject { [key: string]: JsonValue }
+export type JsonSchema = JsonObject | boolean
+export type DocumentId = string
+export type SectionId = string
+export type BlockId = string
+export type StepId = string
+export type NarrationId = string
+export type AssetId = string
+export type DefinitionId = string
+export type ClipId = string
+
+export interface DocumentMetadata {
+  title: string
+  lang: string
+  description?: string
+  tags?: string[]
+  plugins?: string[]
+  presmium?: Record<string, JsonObject>
+  renderers?: Record<string, JsonObject>
+  execute?: ExecuteConfig
+  checks?: JsonObject
+  translations?: Record<string, string>
+  translationOf?: { entry: string, digest: string }
+}
+
+/** Canonical authoring data. Runtime positions, resolved assets and playback plans are derived. */
+export interface TeachingDocument {
+  schemaVersion: typeof DOCUMENT_SCHEMA_VERSION
+  id: DocumentId
+  metadata: DocumentMetadata
+  sectionOrder: SectionId[]
+  sections: Record<SectionId, Section>
+  blocks: Record<BlockId, DocumentBlock>
+  steps: Record<StepId, Step>
+  narrations: Record<NarrationId, Narration>
+  assets: Record<AssetId, Asset>
+  definitions: Record<DefinitionId, Definition>
+  production: Production
+  comments?: Record<string, DocumentThread>
+}
+
+export interface Layout {
+  type: 'stack' | 'columns' | 'canvas' | 'scrolly'
+  properties?: JsonObject
+  renderers?: Record<string, JsonObject>
+}
+export interface Section {
+  id: SectionId
+  title: string
+  level?: 1 | 2 | 3 | 4 | 5 | 6
+  children: BlockId[]
+  stepOrder: StepId[]
+  layout: Layout
+  audience?: string[]
+  config?: Record<string, JsonObject>
+}
+
+export type TextAlignment = 'left' | 'center' | 'right' | 'justify'
+export interface TextStyle { alignment?: TextAlignment, color?: string, background?: string }
+export type TextMark =
+  | { type: 'bold' | 'italic' | 'underline' | 'strike' | 'code' }
+  | { type: 'color' | 'background', value: string }
+export type InlineNode =
+  | { type: 'text', text: string, marks?: TextMark[] }
+  | { type: 'link', href: string, children: InlineNode[] }
+  | { type: 'math', value: string }
+  | { type: 'break' }
+  | InlineExtensionNode
+
+/** A registered extension retains its own versioned semantics and an explicit readable fallback. */
+export interface InlineExtensionNode { type: 'extension', kind: string, schemaVersion: number, data: JsonObject, fallback: string }
+export interface RichTextExtensionNode { id: string, type: 'extension', kind: string, schemaVersion: number, data: JsonObject, fallback: RichTextNode[] }
+
+export interface ParagraphNode { id: string, type: 'paragraph', children: InlineNode[], style?: TextStyle }
+export interface HeadingNode { id: string, type: 'heading', level: 1 | 2 | 3 | 4 | 5 | 6, children: InlineNode[], style?: TextStyle }
+export interface ListItemNode { id: string, type: 'listItem', children: RichTextNode[], checked?: boolean }
+export interface ListNode { id: string, type: 'list', ordered: boolean, start?: number, children: ListItemNode[] }
+export interface QuoteNode { id: string, type: 'blockquote', children: RichTextNode[] }
+export interface CodeTextNode { id: string, type: 'code', language: string, value: string }
+export interface MathTextNode { id: string, type: 'math', value: string }
+export interface TableCellNode { id: string, type: 'tableCell', children: InlineNode[], style?: TextStyle, colspan?: number, rowspan?: number }
+export interface TableRowNode { id: string, type: 'tableRow', children: TableCellNode[] }
+export interface TableNode { id: string, type: 'table', children: TableRowNode[], headerRows?: number, headerColumns?: number, columnWidths?: number[] }
+export type RichTextNode = ParagraphNode | HeadingNode | ListNode | QuoteNode | CodeTextNode | MathTextNode | TableNode | RichTextExtensionNode
+
+export interface BlockScope { only?: string[], audience?: string[] }
+export interface TextBlock extends BlockScope { id: BlockId, type: 'text', content: RichTextNode[], reveal?: { type: 'items', order: string[] } }
+export interface ContainerProperties { title?: string, columnWidths?: number[], tabTitles?: string[] }
+export interface ContainerBlock extends BlockScope { id: BlockId, type: 'container', layout: 'stack' | 'columns' | 'tabs', children: BlockId[], properties: ContainerProperties }
+/** An image without an asset is an authored placeholder, not an asset with an empty location. */
+export interface ImageBlock extends BlockScope { id: BlockId, type: 'image', assetId?: AssetId, alt: string, caption?: InlineNode[], width?: number, alignment?: TextAlignment }
+export interface CodeReference { anchor: string, pin?: string, repo?: string, highlightRegions?: Record<StepId, string> }
+export interface CodeExecution { args?: Record<string, string>, stdin?: string, timeoutMs?: number, executor?: string, when: 'compile' | 'live' | 'both', session?: string }
+export interface CodeVariantSource { id: string, title: string, value?: string, origin?: Omit<CodeReference, 'highlightRegions'> }
+export interface CodeBlock extends BlockScope {
+  id: BlockId
+  type: 'code'
+  language: string
+  value?: string
+  origin?: CodeReference
+  title?: string
+  execution?: CodeExecution
+  highlight?: Record<StepId, number[]>
+  variants?: CodeVariantSource[]
+  echo?: boolean
+}
+export interface ComponentBlock extends BlockScope { id: BlockId, type: 'component', definitionId: DefinitionId, parameters: JsonObject, children?: BlockId[] }
+export type DocumentBlock = TextBlock | ContainerBlock | ImageBlock | CodeBlock | ComponentBlock
+
+/** State is independent from ordering and production timing. Omitted blocks are invisible. */
+export interface Step {
+  id: StepId
+  sectionId: SectionId
+  title?: string
+  visuals: VisualState[]
+  narrationIds: NarrationId[]
+  inherits?: StepId
+}
+export interface VisualState { blockId: BlockId, visible: boolean, state?: string, parameters?: JsonObject }
+export type NarrationNode =
+  | { type: 'text', text: string }
+  | { type: 'pronunciation', display: string, spoken: string }
+  | { id: string, type: 'cue', action: string, target?: { blockId: BlockId, element?: string }, parameters?: JsonObject }
+export interface Narration {
+  id: NarrationId
+  content: NarrationNode[]
+  /** Attribution of an explicit adoption; never a second caption or spoken-text source. */
+  provenance?: { type: 'transcription', transcriptionId: string, revision: string, assetId: AssetId, audioSha256: string, segmentIds: string[] }
+}
+
+export interface Asset { id: AssetId, kind: 'image' | 'audio' | 'video' | 'file', location: string, title?: string, fingerprint?: string, mediaType?: string }
+export type ImplementationRef =
+  | { type: 'file', path: string, exportName?: string, fingerprint?: string }
+  | { type: 'module', specifier: string, exportName?: string }
+  | { type: 'plugin', plugin: string, name: string }
+export interface StateDescriptor {
+  id: string
+  title?: string
+  parameterSchema?: JsonSchema
+  /** A migration must retain numerical implementation bindings explicitly, never invent semantic names. */
+  legacyIndex?: number
+}
+export interface Definition {
+  id: DefinitionId
+  kind: string
+  schemaVersion: number
+  implementation: ImplementationRef
+  parameterSchema: JsonSchema
+  states: StateDescriptor[]
+  data?: JsonObject
+}
+
+export type VoiceSource = { type: 'none' } | { type: 'tts', voice: SpeechVoice } | { type: 'recording', assetId: AssetId, sourceRange?: TimeRange }
+export interface StepProduction {
+  narrationStart?: 'with-animation' | 'after-animation'
+  minimumHoldMs?: number
+  trailingPauseMs?: number
+  voiceSource?: VoiceSource
+}
+export interface ProductionDefaults extends StepProduction {}
+export interface TimeRange { startMs: number, endMs: number }
+/** Explicit author times; offsets partition the original ordered step narration display in UTF16. */
+export interface CaptionTiming {
+  narrationIds: NarrationId[]
+  sourceFingerprint: string
+  playbackFingerprint: string
+  durationMs: number
+  segments: { id: string, from: number, to: number, startMs: number, endMs: number }[]
+}
+export interface MediaClip {
+  id: ClipId
+  assetId: AssetId
+  sourceRange: TimeRange
+  attachment: { stepId: StepId, offsetMs: number }
+  /** Output gain, from zero to one; muting does not replace this value. */
+  volume: number
+  muted?: boolean
+}
+export interface Production {
+  defaults: ProductionDefaults
+  sectionOverrides?: Record<SectionId, StepProduction>
+  stepOverrides: Record<StepId, StepProduction>
+  /** Migrated narration defaults: after page settings, before an explicit step override; shared narrations retain this source. */
+  narrationOverrides?: Record<NarrationId, { narrationStart: 'with-animation' | 'after-animation' }>
+  /** Cue placement is authored in narration; its delay is owned only here. */
+  cueTimings?: Record<string, { pauseMs: number }>
+  /** Stale mappings remain inspectable but never retime audio or replace changed narration. */
+  captionTimings?: Record<StepId, CaptionTiming>
+  mediaClips: MediaClip[]
+}
+
+/** A stable rich-text/code ID, or `page:${sectionId}` reserved for an existing section title. */
+export interface DocumentTextPoint { blockId: string, offset: number }
+export interface DocumentComment {
+  id: string
+  type: 'comment'
+  userId: string
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string
+  content?: RichTextNode[]
+  metadata?: JsonObject
+  reactions: { emoji: string, createdAt: string, userIds: string[] }[]
+}
+export interface DocumentThread {
+  id: string
+  type: 'thread'
+  createdAt: string
+  updatedAt: string
+  resolved: boolean
+  resolvedUpdatedAt?: string
+  resolvedBy?: string
+  metadata?: JsonObject
+  deletedAt?: string
+  anchor?: { from: DocumentTextPoint, to: DocumentTextPoint }
+  comments: DocumentComment[]
+}
+
+export interface DocumentIssue { path: string, code: string, message: string, severity: 'error' | 'warning' }
+export interface DocumentValidation { document?: TeachingDocument, issues: DocumentIssue[] }
+
+/** A source-document transaction. Its CAS version is unrelated to a compiled snapshot ID. */
+export type DocumentEditOperation =
+  | { type: 'insertBlock', sectionId: SectionId, parentId?: BlockId, index: number, block: DocumentBlock }
+  | { type: 'moveBlock', blockId: BlockId, sectionId: SectionId, parentId?: BlockId, index: number }
+  | { type: 'deleteBlock', blockId: BlockId }
+  | { type: 'updateText', blockId: BlockId, content: RichTextNode[] }
+  | { type: 'updateSection', sectionId: SectionId, title?: string, layout?: Layout }
+  | { type: 'setStepState', stepId: StepId, visuals: VisualState[], inherits?: StepId }
+  | { type: 'setNarration', narration: Narration, stepId?: StepId, index?: number }
+  | { type: 'setTiming', stepId?: StepId, sectionId?: SectionId, value: StepProduction }
+  | { type: 'replaceAsset', asset: Asset }