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

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