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

package/src/contracts/server.ts

@@ -0,0 +1,108 @@
+import type { Logger } from './plugin.ts'
+import { defineService } from './service.ts'
+import type { ServiceToken } from './service.ts'
+
+export type MemberRole = 'reader' | 'editor' | 'owner'
+
+export interface Member {
+  id: string
+  name: string
+  email?: string
+  roles: MemberRole[]
+}
+
+export interface RequestContext {
+  member: Member
+  document: string
+  rest: string
+}
+
+export type RouteHandler = (request: Request, ctx: RequestContext) => Response | Promise<Response>
+
+export interface Route {
+  role?: MemberRole
+  maxBody?: number
+  handle: RouteHandler
+}
+
+export const MAX_BODY = 1 << 20
+
+export interface ProxySpec {
+  path: string
+  target: string
+  headers?: Record<string, string>
+  role?: MemberRole
+}
+
+export interface ServerContribution {
+  routes?: Record<string, Route>
+  proxies?: ProxySpec[]
+  close?(): void | Promise<void>
+}
+
+export interface ServerContext {
+  deckDir: string
+  workspaceRoot: string
+  config: Record<string, unknown>
+  settings: Record<string, unknown>
+  lang?: string
+  service<T>(token: ServiceToken<T>): T | undefined
+  secret(name: string): string | undefined
+  operatorDir?: string
+  home?: boolean
+  log: Logger
+}
+
+export interface NodeServiceContext {
+  deckDir: string
+  workspaceRoot: string
+  config: Record<string, unknown>
+  settings: Record<string, unknown>
+  lang?: string
+  secret(name: string): string | undefined
+  operatorDir?: string
+  service?<T>(token: ServiceToken<T>): T | undefined
+  log: Logger
+}
+
+export type ApprovalKind = 'operate' | 'spend' | 'write' | 'agent'
+
+export type ApprovalScope = 'content' | 'workspace'
+
+export interface ApprovalRequest {
+  kind: ApprovalKind
+  scope?: ApprovalScope
+  title: string
+  detail?: string
+  from: string
+  member?: string
+}
+
+export interface Approvals {
+  request(request: ApprovalRequest, signal?: AbortSignal): Promise<boolean>
+}
+
+export const APPROVALS = defineService<Approvals>('presmium.approvals')
+
+export type AgentMode = 'author'
+
+export interface McpAccess {
+  url: string
+  token: string
+}
+
+export interface McpGrant extends McpAccess {
+  revoke(): void
+}
+
+/** @experimental */
+export interface McpIssueOptions {
+  confirmed?: boolean
+  document?: string
+}
+
+export interface McpEndpoint {
+  issue(member: Member, mode: AgentMode, options?: McpIssueOptions): McpGrant
+}
+
+export const MCP_ENDPOINT = defineService<McpEndpoint>('presmium.mcpEndpoint')

package/src/contracts/service.ts

@@ -0,0 +1,8 @@
+export interface ServiceToken<T> {
+  readonly id: string
+  readonly __service?: T
+}
+
+export function defineService<T>(id: string): ServiceToken<T> {
+  return Object.freeze({ id }) as ServiceToken<T>
+}

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

@@ -0,0 +1,149 @@
+import { defineService } from './service.ts'
+
+export interface SpeechWord { text: string, start: number, end: number }
+
+export interface Synthesis {
+  audio: Blob | string
+  mime: string
+  duration: number
+  words?: SpeechWord[]
+  key: string
+  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 {
+  lang: string
+  duration: number
+  text: string
+  segments: TranscriptSegment[]
+}
+
+export interface SpeechEngineInfo {
+  id: string
+  provider: string
+  stt: boolean
+  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 {
+  id: string
+  label: string
+  lang: string[]
+  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
+  text: string
+  lang: string
+  rate?: number
+  style?: string
+  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
+  lang?: string
+  hints?: string[]
+}
+
+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'] }

package/src/contracts/transcription.ts

@@ -0,0 +1,112 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { TimeRange } from './document.ts'
+import type { Member } from './server.ts'
+import type { SpeechEngineInfo } from './speech.ts'
+import type { Finding } from './checks.ts'
+
+export const TRANSCRIPTION_REQUEST_MAX_BYTES = 32 << 10
+
+export interface TranscriptionCapabilities {
+  source: CanonicalSource
+  available: boolean
+  status: 'available' | 'unavailable' | 'unknown'
+  reason?: 'speech-unavailable' | 'engine-unavailable' | 'audio-unavailable' | 'services-unavailable'
+  /** Provider declaration and local configuration are known; authentication/recognition is not verified. */
+  verification: 'configuration-only'
+  findings?: Finding[]
+  engines: SpeechEngineInfo[]
+  range: 'whole-asset'
+  limits: { audioBytes: number, durationMs: number, tasks: number, requestBytes: number }
+}
+
+/** A confirmed recognition request; no script, clip or voice selection is changed. */
+export interface DocumentTranscriptionRequest {
+  intent: string
+  source: CanonicalSource
+  assetId: string
+  audioSha256: string
+  engine: string
+  lang?: string
+  hints?: string[]
+  confirmed: true
+}
+
+/** Agent input excludes host confirmation; HTTP and Node validate the confirmed form below. */
+export const DOCUMENT_TRANSCRIPTION_INPUT_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    intent: { type: 'string', pattern: '^[A-Za-z\\d_-]{16,128}$' },
+    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'] },
+    assetId: { type: 'string', minLength: 1, maxLength: 200 },
+    audioSha256: { type: 'string', pattern: '^[a-f\\d]{64}$' },
+    engine: { type: 'string', minLength: 1, maxLength: 128 },
+    lang: { type: 'string', minLength: 1, maxLength: 64 },
+    hints: { type: 'array', maxItems: 100, items: { type: 'string', maxLength: 200 } },
+  },
+  required: ['intent', 'source', 'assetId', 'audioSha256', 'engine'],
+} as const
+
+export const DOCUMENT_TRANSCRIPTION_REQUEST_SCHEMA = {
+  ...DOCUMENT_TRANSCRIPTION_INPUT_SCHEMA,
+  properties: { ...DOCUMENT_TRANSCRIPTION_INPUT_SCHEMA.properties, confirmed: { const: true } },
+  required: [...DOCUMENT_TRANSCRIPTION_INPUT_SCHEMA.required, 'confirmed'],
+} as const
+
+export interface TranscriptionRevision {
+  transcriptionId: string
+  revision: string
+  createdAt: string
+  source: CanonicalSource
+  audio: { assetId: string, sha256: string, sourceRange: TimeRange }
+  request: { engine: string, provider: string, local: boolean, lang?: string, hints: string[], fingerprint: string }
+  result: {
+    lang: string
+    text: string
+    segments: { id: string, text: string, startMs?: number, endMs?: number, words?: { text: string, startMs: number, endMs: number }[] }[]
+  }
+  timing: 'words' | 'segments' | 'none'
+  warnings: string[]
+}
+
+export type TranscriptionTaskState = 'queued' | 'running' | 'cancelling' | 'cancelled' | 'done' | 'failed'
+export interface TranscriptionTask {
+  kind: 'transcription'
+  id: string
+  intent: string
+  document: string
+  source: CanonicalSource
+  audio: { assetId: string, sha256: string }
+  sequence: number
+  state: TranscriptionTaskState
+  current: boolean
+  staleReason?: 'document-changed' | 'document-unavailable' | 'audio-changed'
+  progress: { phase: 'queued' | 'recognizing' | 'saving' | 'finished' }
+  createdAt: string
+  startedAt?: string
+  finishedAt?: string
+  result?: { transcriptionId: string, revision: string }
+  error?: string
+}
+
+export interface TranscriptionCancellation { intent: string, state: TranscriptionTaskState, task?: TranscriptionTask }
+export interface TranscriptionListAnswer {
+  tasks: TranscriptionTask[]
+  issues: { id: string, code: string }[]
+  truncated?: true
+}
+
+/** Workspace-owned authoring capability, shared by HTTP and agent adapters. */
+export interface DocumentTranscriptions {
+  capabilities(document: string, member: Member): Promise<TranscriptionCapabilities>
+  start(document: string, request: DocumentTranscriptionRequest, member: Member, signal?: AbortSignal): Promise<TranscriptionTask>
+  list(document: string, member: Member): Promise<TranscriptionListAnswer>
+  get(document: string, query: { id: string } | { intent: string }, member: Member): Promise<TranscriptionTask>
+  readResult(document: string, id: string, revision: string, member: Member): Promise<TranscriptionRevision>
+  /** Rechecks current canonical source and the exact original audio, without recognizing it again. */
+  verifyResult(document: string, id: string, revision: string, source: CanonicalSource, member: Member): Promise<TranscriptionRevision>
+  cancel(document: string, query: { id: string } | { intent: string }, member: Member): Promise<TranscriptionCancellation>
+  /** Checks a start with the same path, without storing a task or calling the provider, so an agent asks only for one that would run. */
+  checkStart(document: string, request: DocumentTranscriptionRequest, 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: { id: string } | { intent: string }, member: Member): Promise<TranscriptionCancellation | undefined>
+}

package/src/contracts/voice.ts

@@ -0,0 +1,97 @@
+import type { SpeechEngineInfo, SpeechVoice, VoiceCatalog } from './speech.ts'
+import type { CanonicalSource } from '../ir.ts'
+import { defineService } from './service.ts'
+
+/** A step number is usable only with the structure binding returned by the current snapshot. */
+export interface VoiceTarget { section: string, step: number, binding: string }
+export type VoiceScope = { kind: 'document' } | { kind: 'page', section: string } | { kind: 'step', target: VoiceTarget } | { kind: 'steps', targets: VoiceTarget[] }
+export interface StepVoiceOverride extends VoiceTarget { voice: SpeechVoice }
+export interface VoiceOverrides { pages: Record<string, SpeechVoice>, steps: StepVoiceOverride[] }
+export interface ResolvedVoice {
+  target: VoiceTarget
+  voice?: SpeechVoice
+  inheritedFrom: 'step' | 'page' | 'document' | 'unset'
+  override?: SpeechVoice
+  editable: boolean
+  reason?: 'cue-step' | 'step-binding-stale' | 'recording-unavailable'
+}
+/** Registered by the actual lecture plugin implementation, never inferred from authored configuration. */
+export const VOICEOVER = defineService<{ version: 1, preview: true }>('presmium.voiceover')
+export interface VoiceoverCapability {
+  available: boolean
+  reason?: 'not-configured' | 'voice-unset' | 'step-binding-stale' | 'speech-unavailable' | 'voice-unavailable' | 'catalog-unavailable'
+  providers: SpeechEngineInfo[]
+  defaultEngine?: string
+}
+export interface VoiceoverStepStatus {
+  target: VoiceTarget
+  stepId?: string
+  state: 'ready' | 'missing' | 'blocked' | 'empty'
+  utterances: number
+  cached: number
+  reason?: string
+}
+export interface VoiceoverSnapshot {
+  revision: string
+  source: CanonicalSource
+  capability: VoiceoverCapability
+  steps: VoiceoverStepStatus[]
+  jobs: VoiceoverJob[]
+  /** Real speech units whose source cannot yet be assigned to one full-document step. */
+  unboundByPage?: { section: string, state: VoiceoverStepStatus['state'], utterances: number, cached: number, reason?: string }[]
+}
+export type VoiceoverJobState = 'queued' | 'running' | 'cancelling' | 'cancelled' | 'done' | 'failed' | 'stale'
+export interface VoiceoverJob {
+  id: string
+  sequence: number
+  /** Client-owned generation intent, available before the job response is delivered. */
+  intent: string
+  revision: string
+  source: CanonicalSource
+  scope: VoiceScope
+  state: VoiceoverJobState
+  total: number
+  completed: number
+  failed: number
+  createdAt: string
+  startedAt?: string
+  finishedAt?: string
+  error?: string
+}
+export interface VoiceoverRequest { intent: string, revision: string, source: CanonicalSource, scope: VoiceScope, confirmed: boolean }
+/** Cancellation can precede admission; a pre-admission refusal is not a fabricated job. */
+export interface VoiceoverCancellation { intent: string, state: VoiceoverJobState, job?: VoiceoverJob }
+export interface VoicePreviewRequest {
+  revision: string
+  source: CanonicalSource
+  voice: SpeechVoice
+  mode: 'sample' | 'step'
+  target?: VoiceTarget
+  confirmed: boolean
+  quote: string
+}
+export type VoicePreviewQuery = Omit<VoicePreviewRequest, 'confirmed' | 'quote' | 'source'>
+export interface VoicePreviewQuote extends VoicePreviewQuery {
+  source: CanonicalSource
+  text: string
+  provider: string
+  local: boolean
+  cached: boolean
+  quote: string
+}
+export interface VoicePreviewAnswer {
+  revision: string
+  source: CanonicalSource
+  voice: SpeechVoice
+  text: string
+  cached: boolean
+  key: string
+  audio: string
+  duration: number
+  provider: string
+}
+export interface VoiceCatalogAnswer {
+  engines: SpeechEngineInfo[]
+  catalog: VoiceCatalog
+  engine?: string
+}

package/src/contracts/voiceover-execution.ts

@@ -0,0 +1,68 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { Member } from './server.ts'
+import type { VoiceoverCancellation, VoiceoverJob, VoiceoverRequest, VoiceoverSnapshot, VoicePreviewAnswer, VoicePreviewQuery, VoicePreviewQuote, VoicePreviewRequest } from './voice.ts'
+import { defineService } from './service.ts'
+
+export interface VoiceoverStatusQuery { source?: CanonicalSource, revision?: string }
+export type VoiceoverStart = Omit<VoiceoverRequest, 'confirmed'>
+export type VoicePreviewStart = Omit<VoicePreviewRequest, 'confirmed'>
+export type VoicePreviewCheck = VoicePreviewQuery & { source?: CanonicalSource }
+export type VoiceoverJobQuery = { id: string } | { intent: string }
+export interface VoiceoverProgress { completed: number, failed: number, error?: string }
+export interface VoiceoverRunResult extends VoiceoverProgress { state: 'done' | 'failed' | 'stale' | 'cancelled' }
+/** A claim on the existing generation lock. Dispose after execution or failed admission. */
+export interface PreparedVoiceover {
+  source: CanonicalSource
+  revision: string
+  scope: VoiceoverStart['scope']
+  total: number
+  run(signal: AbortSignal, progress: (value: VoiceoverProgress) => void): Promise<VoiceoverRunResult>
+  dispose(): void
+}
+export interface VoicePreviewMedia extends Omit<VoicePreviewAnswer, 'audio'> { bytes: Uint8Array, mediaType: string }
+/** Stateless plugin execution. The host owns intents and jobs; discovery creates neither. */
+export interface VoiceoverExecution {
+  status(query: VoiceoverStatusQuery, signal: AbortSignal): Promise<Omit<VoiceoverSnapshot, 'jobs'>>
+  prepare(request: VoiceoverStart, signal: AbortSignal): Promise<PreparedVoiceover>
+  quote(query: VoicePreviewCheck, signal: AbortSignal): Promise<VoicePreviewQuote>
+  preview(request: VoicePreviewStart, signal: AbortSignal): Promise<VoicePreviewMedia>
+}
+export const VOICEOVER_EXECUTION = defineService<VoiceoverExecution>('presmium.voiceoverExecution')
+
+export interface VoiceoverObservation extends VoiceoverCancellation { error?: string, current?: boolean | 'unknown' }
+export interface VoiceoverJobsAnswer { document: string, jobs: (VoiceoverJob & { current: boolean | 'unknown' })[], idempotency: 'process', limits: { intents: number, recentJobs: number } }
+export interface VoicePreviewResource extends Omit<VoicePreviewAnswer, 'audio'> { id: string, mediaType: string, byteLength: number, sha256: string }
+export interface VoicePreviewResourceData { resource: VoicePreviewResource, bytes: Uint8Array }
+/** Shared author entry. Adapters obtain spending approval; model input cannot supply confirmation. */
+export interface DocumentVoiceTasks {
+  snapshot(document: string, query: VoiceoverStatusQuery, member: Member, signal?: AbortSignal): Promise<VoiceoverSnapshot>
+  listJobs(document: string, member: Member): Promise<VoiceoverJobsAnswer>
+  getJob(document: string, query: VoiceoverJobQuery, member: Member): Promise<VoiceoverObservation>
+  start(document: string, request: VoiceoverStart, member: Member, signal?: AbortSignal): Promise<VoiceoverJob>
+  cancel(document: string, query: VoiceoverJobQuery, member: Member): Promise<VoiceoverCancellation>
+  quotePreview(document: string, query: VoicePreviewCheck, member: Member, signal?: AbortSignal): Promise<VoicePreviewQuote>
+  preview(document: string, request: VoicePreviewStart, member: Member, signal?: AbortSignal): Promise<VoicePreviewResource>
+  readPreview(document: string, id: string, member: Member): Promise<VoicePreviewResourceData>
+}
+export const DOCUMENT_VOICE_TASKS = defineService<DocumentVoiceTasks>('presmium.documentVoiceTasks')
+
+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
+const revision = { type: 'string', pattern: '^[a-f\\d]{16}$' } as const
+const target = { type: 'object', additionalProperties: false, properties: { section: { type: 'string', minLength: 1, maxLength: 200 }, step: { type: 'integer', minimum: 0 }, binding: revision }, required: ['section', 'step', 'binding'] } as const
+const scope = { oneOf: [
+  { type: 'object', additionalProperties: false, properties: { kind: { const: 'document' } }, required: ['kind'] },
+  { type: 'object', additionalProperties: false, properties: { kind: { const: 'page' }, section: target.properties.section }, required: ['kind', 'section'] },
+  { type: 'object', additionalProperties: false, properties: { kind: { const: 'step' }, target }, required: ['kind', 'target'] },
+  { type: 'object', additionalProperties: false, properties: { kind: { const: 'steps' }, targets: { type: 'array', items: target, minItems: 1, maxItems: 500 } }, required: ['kind', 'targets'] },
+] } as const
+const intent = { type: 'string', pattern: '^[A-Za-z\\d_-]{16,128}$' } as const
+export const VOICEOVER_STATUS_SCHEMA = { type: 'object', additionalProperties: false, properties: { source, revision } } as const
+export const VOICEOVER_START_SCHEMA = { type: 'object', additionalProperties: false, properties: { intent, source, revision, scope }, required: ['intent', 'source', 'revision', 'scope'] } as const
+export const VOICEOVER_JOB_QUERY_SCHEMA = { oneOf: [
+  { type: 'object', additionalProperties: false, properties: { id: { type: 'string', pattern: '^[a-f\\d]{8}-[a-f\\d]{4}-[a-f\\d]{4}-[a-f\\d]{4}-[a-f\\d]{12}$' } }, required: ['id'] },
+  { type: 'object', additionalProperties: false, properties: { intent }, required: ['intent'] },
+] } as const
+const voice = { type: 'object', additionalProperties: false, properties: { voice: { type: 'string', minLength: 1, maxLength: 200 }, engine: { type: 'string', minLength: 1, maxLength: 200 }, rate: { type: 'number', exclusiveMinimum: 0 }, style: { type: 'string', maxLength: 200 } }, required: ['voice'] } as const
+const preview = { revision, source, voice, mode: { enum: ['sample', 'step'] }, target } as const
+export const VOICE_PREVIEW_CHECK_SCHEMA = { type: 'object', additionalProperties: false, properties: preview, required: ['revision', 'voice', 'mode'], allOf: [{ if: { properties: { mode: { const: 'step' } } }, then: { required: ['target'] } }] } as const
+export const VOICE_PREVIEW_START_SCHEMA = { type: 'object', additionalProperties: false, properties: { ...preview, quote: { type: 'string', pattern: '^[a-f\\d]{64}$' } }, required: ['source', 'revision', 'voice', 'mode', 'quote'], allOf: VOICE_PREVIEW_CHECK_SCHEMA.allOf } as const