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

package/src/contracts/authoring.ts

@@ -0,0 +1,180 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { DocumentEditOperation, DocumentIssue, TeachingDocument } from './document.ts'
+import type { Member } from './server.ts'
+import type { DocumentAnswer, DocumentChange, DocumentChangeAnswer, RevisionOrigin } from './workspace.ts'
+import type { DocumentOutlineAnswer, DocumentOutlineQuery, DocumentPartAnswer, DocumentPartQuery } from './document-reads.ts'
+import type { AppliedDocumentAuthoringAction, DocumentAuthoringActionInspection, DocumentAuthoringActionPlan, DocumentAuthoringActionRead, DocumentAuthoringActionReference, DocumentAuthoringActionRequest, DocumentAuthoringAction, DocumentComponentImpactAnswer, DocumentComponentImpactQuery } from './authoring-actions.ts'
+
+export const AUTHORING_API_VERSION = 1 as const
+export const DOCUMENT_OPERATION_TYPES = ['insertBlock', 'moveBlock', 'deleteBlock', 'updateText', 'updateSection', 'setStepState', 'setNarration', 'setTiming', 'replaceAsset'] as const satisfies readonly DocumentEditOperation['type'][]
+
+export interface AuthoringCapabilities {
+  apiVersion: typeof AUTHORING_API_VERSION
+  documentSchemaVersion: number
+  available: boolean
+  reason?: 'host-unavailable' | 'permission-denied'
+  actions: { read: boolean, outline: boolean, readPart: boolean, plan: boolean, apply: boolean, planPageDuplication: boolean, applyPageDuplication: boolean, planPageChange: boolean, applyPageChange: boolean, planAction: boolean, applyAction: boolean }
+  applyUnavailableReason?: 'review-required' | 'operation-disabled'
+  readLimits?: { maxRequestChars: number, maxResponseChars: number, responseSerialization: 'JSON.stringify(value,null,2)', offsetUnit: 'utf16' }
+  pageLimits?: { maxRequestChars: number, maxResponseChars: number, responseSerialization: 'JSON.stringify(value,null,2)' }
+  actionLimits?: { maxRequestChars: number, maxResponseChars: number, responseSerialization: 'JSON.stringify(value,null,2)' }
+  semanticActions?: readonly DocumentAuthoringAction['type'][]
+  components?: { parameters: true, stepParameters: true, restoreStepParameters: true, useExistingDefinition: true, impactRead: true, maxChanges: number, maxPathDepth: number, independentCopy: { available: false, reason: 'implementation-closure-unavailable' } }
+  operations: readonly DocumentEditOperation['type'][]
+  replacement: boolean
+  fileChanges: boolean
+  limits?: { maxFiles: number, maxTextBytes: number, maxOperations: number, planLifetimeMs: number, maxPlans: number, maxReceipts: number }
+  idempotency: 'process-current-source' | 'unavailable'
+  review: 'required-unsupported' | 'locks-and-history' | 'locks-only' | 'unavailable'
+}
+
+/** A pure local preflight. Files include lecture.json and their predicted post-save versions. */
+export interface DocumentChangePlan {
+  apiVersion: typeof AUTHORING_API_VERSION
+  planId: string
+  changeId: string
+  document: string
+  source: CanonicalSource
+  digest: string
+  expiresAt: string
+  content: TeachingDocument
+  issues: DocumentIssue[]
+  files: { path: string, base: string | null, version: string }[]
+  impact: { sections: string[], blocks: string[], steps: string[], narrations: string[], assets: string[], definitions: string[], sectionOrder: boolean, production: boolean, comments: boolean, metadata: boolean }
+}
+
+export interface ApplyDocumentChange { change: DocumentChange, planId: string }
+export interface DocumentPageDuplicationRequest { id: string, source: CanonicalSource, sectionId: string, title: string }
+export type DocumentPageAction =
+  | { type: 'create', title: string, after?: string | null }
+  | { type: 'rename', sectionId: string, title: string }
+  | { type: 'move', sectionId: string, before: string | null }
+  | { type: 'delete', sectionId: string }
+export interface DocumentPageIds { sectionId: string, blockId: string, nodeId: string, stepId: string }
+export interface DocumentPageDeletionImpact {
+  sectionId: string
+  retainedEmpty: boolean
+  blocks: string[]
+  steps: string[]
+  narrations: string[]
+  retainedNarrations: string[]
+  cues: string[]
+  clips: string[]
+  detachedComments: string[]
+  references: ({ type: 'cue', narrationId: string, cueId: string, blockId: string, stepIds: string[] } | { type: 'inheritance', stepId: string, inheritedStepId: string })[]
+}
+export interface DocumentPageChangeRequest { id: string, source: CanonicalSource, action: DocumentPageAction }
+export interface DocumentPageChangePlan extends DocumentChangePlan {
+  action: DocumentPageAction
+  sectionId: string
+  created?: DocumentPageIds
+  deletion?: DocumentPageDeletionImpact
+  change: DocumentChange
+}
+export interface DocumentPageChangeReference extends DocumentPageDuplicationReference { confirmDeletion?: true }
+export interface DocumentPageChangeInspection { plan: DocumentPageChangePlan, currentSource: CanonicalSource, state: 'current' | 'applied' | 'old' }
+export interface AppliedDocumentPageChange extends Omit<AppliedDocumentChange, 'content' | 'issues' | 'verification' | 'commit'> {
+  commit?: { id: string, origin: RevisionOrigin['kind'] }
+  planId: string
+  digest: string
+  action: DocumentPageAction['type']
+  sectionId: string
+  retainedEmpty: boolean
+  changed: boolean
+  impact: Record<keyof DocumentChangePlan['impact'], number | boolean>
+  verification: AppliedDocumentChange['verification'] & { plannedVersion: string, pageStateVerified: true }
+}
+export interface DocumentPageDuplicationPlan extends DocumentChangePlan {
+  action: 'duplicatePage'
+  section: { from: string, to: string }
+  /** Only copied declared identities; assets, definitions, opaque payloads and comments retain their references. */
+  mapping: Record<string, string>
+  /** Pass this exact candidate with planId to the existing apply operation. */
+  change: DocumentChange
+}
+export interface DocumentPageDuplicationReference { planId: string, source: CanonicalSource, digest: string }
+export interface DocumentPageDuplicationRead { planId: string, digest: string }
+export interface DocumentPageDuplicationInspection {
+  plan: DocumentPageDuplicationPlan
+  currentSource: CanonicalSource
+  state: 'current' | 'applied' | 'old'
+}
+export interface AppliedDocumentPageDuplication extends Omit<AppliedDocumentChange, 'content' | 'issues' | 'verification'> {
+  planId: string
+  digest: string
+  section: DocumentPageDuplicationPlan['section']
+  copied: { identities: number, sections: number, blocks: number, steps: number, narrations: number }
+  verification: AppliedDocumentChange['verification'] & { plannedVersion: string, pagePresent: true }
+}
+export const DOCUMENT_PAGE_DUPLICATION_SCHEMA = {
+  type: 'object', additionalProperties: false, required: ['id', 'source', 'sectionId', 'title'],
+  properties: {
+    id: { type: 'string', minLength: 1, maxLength: 200 },
+    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 },
+    } },
+    sectionId: { type: 'string', minLength: 1, maxLength: 200 }, title: { type: 'string', minLength: 1, maxLength: 1000 },
+  },
+} as const
+export const DOCUMENT_PAGE_DUPLICATION_APPLY_SCHEMA = {
+  type: 'object', additionalProperties: false, required: ['planId', 'source', 'digest'], properties: {
+    planId: { type: 'string', minLength: 1, maxLength: 200 },
+    source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source,
+    digest: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+  },
+} as const
+export const DOCUMENT_PAGE_CHANGE_SCHEMA = {
+  type: 'object', additionalProperties: false, required: ['id', 'source', 'action'], properties: {
+    id: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.id,
+    source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source,
+    action: { oneOf: [
+      { type: 'object', additionalProperties: false, required: ['type', 'title'], properties: { type: { const: 'create' }, title: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.title, after: { type: ['string', 'null'], minLength: 1, maxLength: 200 } } },
+      { type: 'object', additionalProperties: false, required: ['type', 'sectionId', 'title'], properties: { type: { const: 'rename' }, sectionId: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.sectionId, title: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.title } },
+      { type: 'object', additionalProperties: false, required: ['type', 'sectionId', 'before'], properties: { type: { const: 'move' }, sectionId: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.sectionId, before: { type: ['string', 'null'], minLength: 1, maxLength: 200 } } },
+      { type: 'object', additionalProperties: false, required: ['type', 'sectionId'], properties: { type: { const: 'delete' }, sectionId: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.sectionId } },
+    ] },
+  },
+} as const
+export const DOCUMENT_PAGE_CHANGE_APPLY_SCHEMA = {
+  ...DOCUMENT_PAGE_DUPLICATION_APPLY_SCHEMA,
+  properties: { ...DOCUMENT_PAGE_DUPLICATION_APPLY_SCHEMA.properties, confirmDeletion: { const: true } },
+} as const
+export interface AppliedDocumentChange extends DocumentChangeAnswer {
+  verification: { saved: true, source: CanonicalSource, compiled: 'not-requested', runtime: 'not-requested' }
+}
+
+/**
+ * Injected by an authoring host. Neither MCP nor compilation owns file-writing semantics.
+ * Each `check*` runs its apply's checks (plan reference, review, current source or a replayable receipt, the dry-run transaction) without writing,
+ * so a doomed request is refused before the author is asked; the apply checks everything again.
+ */
+export interface DocumentAuthoring {
+  capabilities(document: string, member: Member): AuthoringCapabilities
+  read(document: string, member: Member): Promise<DocumentAnswer>
+  outline(document: string, query: DocumentOutlineQuery, member: Member): Promise<DocumentOutlineAnswer>
+  readPart(document: string, query: DocumentPartQuery, member: Member): Promise<DocumentPartAnswer>
+  plan(document: string, change: DocumentChange, member: Member): Promise<DocumentChangePlan>
+  planPageDuplication(document: string, request: DocumentPageDuplicationRequest, member: Member): Promise<DocumentPageDuplicationPlan>
+  readPageDuplicationPlan(document: string, reference: DocumentPageDuplicationRead, member: Member): Promise<DocumentPageDuplicationInspection>
+  checkPageDuplication(document: string, reference: DocumentPageDuplicationReference, member: Member): Promise<void>
+  applyPageDuplication(document: string, reference: DocumentPageDuplicationReference, member: Member): Promise<AppliedDocumentPageDuplication>
+  planPageChange(document: string, request: DocumentPageChangeRequest, member: Member): Promise<DocumentPageChangePlan>
+  readPageChangePlan(document: string, reference: DocumentPageDuplicationRead, member: Member): Promise<DocumentPageChangeInspection>
+  checkPageChange(document: string, reference: DocumentPageChangeReference, member: Member): Promise<void>
+  applyPageChange(document: string, reference: DocumentPageChangeReference, member: Member): Promise<AppliedDocumentPageChange>
+  planAction(document: string, request: DocumentAuthoringActionRequest, member: Member): Promise<DocumentAuthoringActionPlan>
+  readActionPlan(document: string, reference: DocumentAuthoringActionRead, member: Member): Promise<DocumentAuthoringActionInspection>
+  readActionImpact(document: string, query: DocumentComponentImpactQuery, member: Member): Promise<DocumentComponentImpactAnswer>
+  checkAction(document: string, reference: DocumentAuthoringActionReference, member: Member): Promise<void>
+  applyAction(document: string, reference: DocumentAuthoringActionReference, member: Member): Promise<AppliedDocumentAuthoringAction>
+  checkApply(document: string, request: ApplyDocumentChange, member: Member): Promise<void>
+  apply(document: string, request: ApplyDocumentChange, member: Member): Promise<AppliedDocumentChange>
+}
+
+export interface AuthoringFailure {
+  code: string
+  message: string
+  status: number
+  retryable: boolean
+  detail?: Record<string, unknown>
+}

package/src/contracts/checks.ts

@@ -0,0 +1,29 @@
+import type { IRDocument } from '../ir.ts'
+import type { AnchorLockFile, AnchorResolverRegistry, SourceReader } from './anchors.ts'
+import type { ServiceToken } from './service.ts'
+
+export type Severity = 'error' | 'warning' | 'info'
+
+export interface Finding {
+  checkId: string
+  severity: Severity
+  message: string
+  source?: { file: string; line?: number }
+  hint?: string
+}
+
+export interface CheckContext {
+  deckDir: string
+  workspaceRoot: string
+  headmatter: Record<string, unknown>
+  src: SourceReader
+  resolvers: AnchorResolverRegistry
+  lock: AnchorLockFile
+  ir: IRDocument
+  service?<T>(token: ServiceToken<T>): T | undefined
+}
+
+export interface Check {
+  id: string
+  run(ctx: CheckContext): Promise<Finding[]>
+}

package/src/contracts/classroom.ts

@@ -0,0 +1,49 @@
+import type { Unsubscribe } from './plugin.ts'
+import { defineService } from './service.ts'
+import type { Cursor } from './steps.ts'
+
+export type ParticipantRole = 'presenter' | 'learner'
+
+export interface Participant {
+  id: string
+  name: string
+  role: ParticipantRole
+}
+
+export type SessionStatus = 'idle' | 'active' | 'ended'
+
+export interface SessionSnapshot {
+  sessionId?: string
+  status: SessionStatus
+  me?: Participant
+  participants: Participant[]
+  presenterCursor?: Cursor
+}
+
+export interface SessionService {
+  snapshot(): SessionSnapshot
+  subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe
+  create(name: string): Promise<string>
+  join(sessionId: string, name: string): Promise<void>
+  end(): Promise<void>
+  leave(): void
+  archive?(): Promise<string>
+  readonly personal?: ClassroomStore
+}
+
+export const SESSION = defineService<SessionService>('presmium.session')
+
+export interface StoredItem<T> {
+  id: string
+  value: T
+}
+
+export interface ClassroomStore {
+  list<T>(collection: string): StoredItem<T>[]
+  get<T>(collection: string, id: string): T | undefined
+  put<T>(collection: string, id: string, value: T): void
+  remove(collection: string, id: string): void
+  subscribe(collection: string, listener: () => void): Unsubscribe
+}
+
+export const CLASSROOM_STORE = defineService<ClassroomStore>('presmium.classroomStore')

package/src/contracts/diagnostics.ts

@@ -0,0 +1,37 @@
+import type { Finding } from './checks.ts'
+import type { CanonicalSource } from '../ir.ts'
+
+export type DiagnosticOrigin = 'compile' | 'check' | 'preview' | 'runtime' | 'server' | 'authoring'
+
+/** A current problem. Source paths are relative to the workspace root. */
+export interface Diagnostic extends Finding {
+  id: string
+  document: string
+  origin: DiagnosticOrigin
+  renderer?: 'web' | 'slides'
+  revision?: string
+  /** Saved authoring baseline when this issue was observed, never a compiled IR revision. */
+  authoringSource?: CanonicalSource
+}
+
+/** Replaces the previous snapshot; it is not a history of diagnostic events. */
+export interface DiagnosticSnapshot {
+  version: number
+  diagnostics: Diagnostic[]
+}
+
+/** The current problems reported by one embedded preview. */
+export interface PreviewDiagnostics {
+  document: string
+  renderer: 'web' | 'slides'
+  instance: string
+  revision: string
+  findings: Finding[]
+}
+
+/** A selected author's window can report a failure before any runtime has compiled. */
+export interface AuthoringDiagnostics {
+  document: string
+  instance: string
+  findings: { checkId: string, severity: 'error', message: string, authoringSource?: CanonicalSource }[]
+}

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