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

package/src/contracts/authoring-actions.ts

@@ -0,0 +1,60 @@
+import type { DocumentCaptionTimingAction } from '../document-caption-timings.ts'
+import type { DocumentCommentAction, DocumentCommentEffect } from './document-comments.ts'
+import type { JsonValue, VoiceSource } from './document.ts'
+import type { DocumentVoiceImpact, DocumentVoiceScope } from '../document-voices.ts'
+import type { CanonicalSource } from '../ir.ts'
+import type { DocumentChange, DocumentChangeAnswer, RevisionOrigin } from './workspace.ts'
+import type { DocumentChangePlan } from './authoring.ts'
+
+export const DOCUMENT_ACTION_MAX_REQUEST_CHARS = 4096
+export const DOCUMENT_ACTION_MAX_RESPONSE_CHARS = 7168
+export const DOCUMENT_AUTHORING_ACTION_TYPES = ['comment.create', 'comment.reply', 'comment.update', 'comment.react', 'comment.resolve', 'comment.reopen', 'comment.delete', 'voice.set', 'component.parameters.patch', 'component.step-parameters.patch', 'component.step-parameters.reset', 'component.definition.use', 'caption.timing.set', 'caption.timing.reset'] as const
+export const DOCUMENT_PARAMETER_MAX_CHANGES = 32
+export const DOCUMENT_PARAMETER_MAX_PATH_DEPTH = 16
+/** Paths belong only to this component's parameters; set replaces an array item or appends at its length. */
+export type DocumentParameterChange = { op: 'set', path: string[], value: JsonValue } | { op: 'remove', path: string[] }
+export type DocumentComponentAction =
+  | { type: 'component.parameters.patch', blockId: string, changes: DocumentParameterChange[] }
+  | { type: 'component.step-parameters.patch', blockId: string, stepId: string, changes: DocumentParameterChange[] }
+  | { type: 'component.step-parameters.reset', blockId: string, stepId: string }
+  | { type: 'component.definition.use', blockId: string, definitionId: string, changes?: DocumentParameterChange[] }
+export interface DocumentComponentEffect {
+  blockId: string
+  sectionId: string
+  layer: 'base' | 'step' | 'definition'
+  stepId?: string
+  definitionId: string
+  previousDefinitionId?: string
+  changed: boolean
+  paths: string[][]
+  affected: { blocks: string[], steps: string[], pages: string[] }
+  overrides: { preserved: string[], materialized: string[], reset: string[] }
+  references: { before: string[], after: string[] }
+}
+export const DOCUMENT_COMPONENT_IMPACT_COLLECTIONS = ['affected.blocks', 'affected.steps', 'affected.pages', 'overrides.preserved', 'overrides.materialized', 'overrides.reset', 'references.before', 'references.after'] as const
+export type DocumentComponentImpactCollection = typeof DOCUMENT_COMPONENT_IMPACT_COLLECTIONS[number]
+export interface DocumentComponentImpactQuery extends DocumentAuthoringActionRead { collection: DocumentComponentImpactCollection, offset?: number }
+export interface DocumentComponentImpactAnswer {
+  planId: string, digest: string, source: CanonicalSource, currentSource: CanonicalSource, state: 'current' | 'applied' | 'old'
+  collection: DocumentComponentImpactCollection, offset: number, total: number, entries: string[], nextOffset?: number, complete: boolean
+}
+/** New recording adoption belongs to the real-media service, never a raw settings action. */
+export type DocumentAuthoringAction = DocumentCommentAction | DocumentComponentAction | DocumentCaptionTimingAction | { type: 'voice.set', scope: DocumentVoiceScope, source: Exclude<VoiceSource, { type: 'recording' }> | null, replaceOverrides?: boolean }
+export interface DocumentAuthoringActionRequest { id: string, source: CanonicalSource, action: DocumentAuthoringAction }
+export type DocumentAuthoringActionEffect = { kind: 'caption', value: { stepId: string, segments: number, changed: boolean, mode: 'manual' | 'automatic' } } | { kind: 'comment', value: DocumentCommentEffect } | { kind: 'voice', scope: DocumentVoiceScope['kind'], value: DocumentVoiceImpact, recordings: { preserved: number, removed: number } } | { kind: 'component', value: DocumentComponentEffect }
+export interface DocumentAuthoringActionPlan extends DocumentChangePlan {
+  action: DocumentAuthoringAction
+  effect: DocumentAuthoringActionEffect
+  change: DocumentChange
+}
+export interface DocumentAuthoringActionReference { planId: string, source: CanonicalSource, digest: string, confirmDeletion?: true }
+export interface DocumentAuthoringActionRead { planId: string, digest: string }
+export interface DocumentAuthoringActionInspection { plan: DocumentAuthoringActionPlan, currentSource: CanonicalSource, state: 'current' | 'applied' | 'old' }
+export interface AppliedDocumentAuthoringAction extends Omit<DocumentChangeAnswer, 'content' | 'issues' | 'commit'> {
+  commit?: { id: string, origin: RevisionOrigin['kind'] }
+  planId: string
+  digest: string
+  action: DocumentAuthoringAction['type']
+  effect: DocumentAuthoringActionEffect
+  verification: { saved: true, source: CanonicalSource, plannedVersion: string, actionStateVerified: true, compiled: 'not-requested', runtime: 'not-requested' }
+}

package/src/contracts/authoring-clients.ts

@@ -0,0 +1,213 @@
+import type { Schema } from '@cfworker/json-schema'
+import type { CanonicalSource } from '../ir.ts'
+import type { Member } from './server.ts'
+import type { ProductionBinding, ProductionPlaybackState } from './production.ts'
+import { PRODUCTION_PLAYBACK_RATES } from './production.ts'
+import { DOCUMENT_PAGE_DUPLICATION_SCHEMA } from './authoring.ts'
+
+export const AUTHORING_CLIENT_MAX_REQUEST_CHARS = 4096
+export const AUTHORING_CLIENT_MAX_RESPONSE_CHARS = 7168
+export const AUTHORING_CLIENT_MAX_CLIENTS = 16
+export const AUTHORING_CLIENT_MAX_REQUESTS = 64
+export const AUTHORING_CLIENT_REQUEST_TIMEOUT_MS = 30000
+export const AUTHORING_CLIENT_ACK_MAX_BYTES = 32768
+export const AUTHORING_CLIENT_EVENT_MAX_BYTES = 8 << 10
+export const AUTHORING_CLIENT_ACTIONS = ['state.read', 'source.flush', 'preview.prepare', 'comment-drafts.inspect', 'comment-drafts.read', 'comment-drafts.restore', 'comment-drafts.discard', 'component-drafts.inspect', 'component-drafts.read', 'component-drafts.restore', 'component-drafts.discard', 'playback.pause', 'position.step', 'playback.play', 'playback.seek', 'playback.rate'] as const
+export type AuthoringClientActionType = typeof AUTHORING_CLIENT_ACTIONS[number]
+export type AuthoringClientAction =
+  | { type: 'state.read' }
+  | { type: 'source.flush' }
+  | { type: 'preview.prepare' }
+  | { type: 'comment-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
+  | { type: 'comment-drafts.read', draft: ClientCommentDraftReference, offset: number, maxChars?: number }
+  | { type: 'comment-drafts.restore', draft: ClientCommentDraftReference, composerId: string, expectedCurrent: ClientCommentDraftReference | null }
+  | { type: 'comment-drafts.discard', draft: ClientCommentDraftReference }
+  | { type: 'component-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
+  | { type: 'component-drafts.read', draft: ClientComponentDraftReference, offset: number, maxChars?: number }
+  | { type: 'component-drafts.restore', draft: ClientComponentDraftReference, expectedCurrent: ClientComponentDraftReference | null }
+  | { type: 'component-drafts.discard', draft: ClientComponentDraftReference, current: boolean }
+  | { type: 'playback.pause' }
+  | { type: 'position.step', sectionId: string, stepId: string }
+  | { type: 'playback.play', binding: ProductionBinding }
+  | { type: 'playback.seek', binding: ProductionBinding, timeMs: number }
+  | { type: 'playback.rate', binding: ProductionBinding, rate: number }
+
+export interface ClientCommentDraftReference { id: string, revision: number, token: string }
+export interface ClientComponentDraftReference { id: string, revision: number, token: string, blockId: string, stepId?: string }
+/** No parameter values, baselines, workspace identity or member IDs enter this metadata. */
+export interface ClientComponentDraftMetadata {
+  draft: ClientComponentDraftReference
+  definitionId: string
+  current: boolean
+  storage: 'durable' | 'session'
+  status: 'available' | 'pending' | 'session-only'
+  updatedAt: number
+  baseVersion: string
+  sourceCurrent: boolean
+  composing: boolean
+  reset: boolean
+}
+/** Explicit inspection deliberately excludes content, source signatures, comment baselines and pending values. */
+export interface ClientCommentDraftMetadata {
+  draft: ClientCommentDraftReference
+  kind: 'create' | 'reply' | 'edit'
+  storage: 'durable' | 'session'
+  updatedAt: number
+  baseVersion: string
+  composing: boolean
+  pendingSubmission: boolean
+  ownersKnown: boolean
+  active: boolean
+  discardable: boolean
+  restore?: { composerId: string, expectedCurrent: ClientCommentDraftReference | null }
+  threadId?: string
+  commentId?: string
+}
+export type AuthoringClientActionResult =
+  | { type: 'comment-drafts.inspect', family: 'comment', coverage: 'stored-and-session' | 'session-only', skippedInvalid: number, token: string, drafts: ClientCommentDraftMetadata[], next?: { after: string, token: string } }
+  | { type: 'comment-drafts.read', family: 'comment', draft: ClientCommentDraftReference, storage: 'durable' | 'session', format: 'presmium-rich-text-json-v1', offset: number, endOffset: number, totalUtf16: number, totalUtf8: number, sha256: string, jsonText: string }
+  | { type: 'comment-drafts.restore', family: 'comment', draft: ClientCommentDraftReference, composerId: string, restored: ClientCommentDraftReference, preservedCurrent: ClientCommentDraftReference | null, targetState: 'current' | 'changed' }
+  | { type: 'comment-drafts.discard', family: 'comment', draft: ClientCommentDraftReference, discarded: true }
+  | { type: 'component-drafts.inspect', family: 'component', coverage: 'stored-and-session' | 'session-only', skippedInvalid: number, token: string, drafts: ClientComponentDraftMetadata[], next?: { after: string, token: string } }
+  | { type: 'component-drafts.read', family: 'component', draft: ClientComponentDraftReference, storage: 'durable' | 'session', format: 'presmium-component-parameters-json-v1', offset: number, endOffset: number, totalUtf16: number, totalUtf8: number, sha256: string, jsonText: string }
+  | { type: 'component-drafts.restore', family: 'component', draft: ClientComponentDraftReference, restored: ClientComponentDraftMetadata, preservedCurrent: ClientComponentDraftReference | null }
+  | { type: 'component-drafts.discard', family: 'component', draft: ClientComponentDraftReference, current: boolean, discarded: true }
+
+/** Reports contain no editor text. Time is an observed sample, never a server-estimated playhead. */
+export interface AuthoringClientSnapshot {
+  revision: number
+  source: CanonicalSource
+  view: 'document' | 'present'
+  editing: { dirty: boolean, saving: boolean, composing: boolean, conflicted: boolean, locked: boolean, loading: boolean }
+  interaction: string
+  position?: { sectionId: string, stepId?: string }
+  binding?: ProductionBinding
+  preview?: { status: 'unprepared' | 'preparing' | 'prepared' | 'unavailable', source?: CanonicalSource, irRevision?: string, projectRevision?: number }
+  playback?: ProductionPlaybackState
+  actions: AuthoringClientActionType[]
+  unsubmittedContent: 'not-inspected'
+}
+export interface AuthoringClientConnection { clientId: string, epoch: string, connectionId: string }
+/** This credential belongs to the host-side transport; it is never returned by MCP client/state reads. */
+export interface AuthoringClientLease extends AuthoringClientConnection { credential: string }
+export interface AuthoringClientOpen { clientId: string, epoch: string, snapshot: AuthoringClientSnapshot }
+export interface AuthoringClientDescriptor extends AuthoringClientConnection {
+  document: string
+  connected: boolean
+  observedAt: string
+  verification: 'reported-state'
+  snapshot: AuthoringClientSnapshot
+}
+export interface AuthoringClientList { document: string, clients: AuthoringClientDescriptor[], nextAfter?: string, unavailable: readonly string[] }
+export interface AuthoringClientRequest {
+  clientId: string
+  epoch: string
+  requestId: string
+  source: CanonicalSource
+  expectedClientState: { connectionId: string, revision: number }
+  action: AuthoringClientAction
+}
+export type AuthoringClientRequestState = 'sent' | 'executing' | 'done' | 'refused' | 'failed' | 'expired'
+export interface AuthoringClientRequestResult extends AuthoringClientConnection {
+  document: string
+  requestId: string
+  action: AuthoringClientActionType
+  source: CanonicalSource
+  state: AuthoringClientRequestState
+  admittedAt: string
+  expiresAt: string
+  observedAt?: string
+  snapshot?: AuthoringClientSnapshot
+  result?: AuthoringClientActionResult
+  error?: { code: string }
+  verification: 'not-acknowledged' | 'browser-acknowledged'
+  current: boolean
+}
+export type AuthoringClientEvent =
+  | { type: 'connected', connectionId: string }
+  | { type: 'request', request: AuthoringClientRequest, expiresAt: string }
+  | { type: 'cancel', requestId: string, connectionId: string }
+export interface AuthoringClientReport { sequence: number, snapshot: AuthoringClientSnapshot }
+export interface AuthoringClientAcknowledgement extends AuthoringClientReport {
+  requestId: string
+  state: 'executing' | 'done' | 'refused' | 'failed'
+  error?: { code: string }
+  result?: AuthoringClientActionResult
+}
+export interface AuthoringClients {
+  list(document: string, query: { clientId?: string, after?: string }, member: Member): Promise<AuthoringClientList>
+  request(document: string, request: AuthoringClientRequest, member: Member): Promise<AuthoringClientRequestResult>
+  get(document: string, query: { clientId: string, epoch: string, requestId: string }, member: Member): Promise<AuthoringClientRequestResult>
+}
+
+/** Reserve the complete receipt and the host-only lease, rather than budgeting only the text fragment. */
+export function authoringClientResultFits(context: { request: AuthoringClientRequest, connection: AuthoringClientConnection, document: string, snapshot: AuthoringClientSnapshot }, result: AuthoringClientActionResult): boolean {
+  const { request, document, snapshot } = context, time = '2000-01-01T00:00:00.000Z'
+  const connection = { clientId: context.connection.clientId, epoch: context.connection.epoch, connectionId: context.connection.connectionId }
+  const receipt: AuthoringClientRequestResult = { ...connection, document, requestId: request.requestId, action: request.action.type, source: request.source,
+    state: 'done', admittedAt: time, expiresAt: time, observedAt: time, snapshot, result, verification: 'browser-acknowledged', current: false }
+  const body = { connection: { ...connection, credential: '0'.repeat(100) }, report: { sequence: Number.MAX_SAFE_INTEGER, snapshot, result, requestId: request.requestId, state: 'done' } }
+  const wire = JSON.stringify(body)
+  const frame = JSON.stringify({ type: 'authoring-client-publish', id: '0'.repeat(80), connectionId: connection.connectionId, sequence: Number.MAX_SAFE_INTEGER, kind: 'ack', value: body.report })
+  // Clock samples can change without changing the client revision; recheck the actual snapshot before sending.
+  return JSON.stringify(receipt, null, 2).length <= AUTHORING_CLIENT_MAX_RESPONSE_CHARS - 128
+    && wire.length <= AUTHORING_CLIENT_MAX_RESPONSE_CHARS - 128 && new TextEncoder().encode(wire).byteLength <= AUTHORING_CLIENT_ACK_MAX_BYTES
+    && new TextEncoder().encode(frame).byteLength <= AUTHORING_CLIENT_EVENT_MAX_BYTES - 128
+}
+
+const id: Schema = { type: 'string', minLength: 1, maxLength: 80, pattern: '^[a-zA-Z0-9.-]+$' }
+const entity: Schema = { type: 'string', minLength: 1, maxLength: 200 }
+const integer: Schema = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER }
+const number: Schema = { type: 'number', minimum: 0 }
+const bool: Schema = { type: 'boolean' }
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
+const digest: Schema = { type: 'string', pattern: '^[a-f0-9]{64}$' }
+const draftReference = object({ id: entity, revision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }, token: digest })
+const componentDraftReference = object({ id: entity, revision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }, token: digest, blockId: entity, stepId: entity }, ['id', 'revision', 'token', 'blockId'])
+const componentMetadata = object({ draft: componentDraftReference, definitionId: entity, current: bool, storage: { enum: ['durable', 'session'] }, status: { enum: ['available', 'pending', 'session-only'] }, updatedAt: integer, baseVersion: entity, sourceCurrent: bool, composing: bool, reset: bool })
+const nullableComponentReference: Schema = { oneOf: [componentDraftReference, { type: 'null' }] }
+const nullableCommentReference: Schema = { oneOf: [draftReference, { type: 'null' }] }
+const commentRestore = object({ composerId: id, expectedCurrent: nullableCommentReference })
+const cursor = object({ after: entity, token: digest })
+export const AUTHORING_CLIENT_ACTION_RESULT_SCHEMA: Schema = { oneOf: [
+  object({ type: { const: 'comment-drafts.inspect' }, family: { const: 'comment' }, coverage: { enum: ['stored-and-session', 'session-only'] }, skippedInvalid: integer,
+    token: digest, drafts: { type: 'array', maxItems: 10, items: object({ draft: draftReference, kind: { enum: ['create', 'reply', 'edit'] }, storage: { enum: ['durable', 'session'] }, updatedAt: integer, baseVersion: entity, composing: bool, pendingSubmission: bool, ownersKnown: bool, active: bool, discardable: bool, restore: commentRestore, threadId: entity, commentId: entity }, ['draft', 'kind', 'storage', 'updatedAt', 'baseVersion', 'composing', 'pendingSubmission', 'ownersKnown', 'active', 'discardable']) }, next: cursor }, ['type', 'family', 'coverage', 'skippedInvalid', 'token', 'drafts']),
+  object({ type: { const: 'comment-drafts.read' }, family: { const: 'comment' }, draft: draftReference, storage: { enum: ['durable', 'session'] }, format: { const: 'presmium-rich-text-json-v1' }, offset: integer, endOffset: integer, totalUtf16: integer, totalUtf8: integer, sha256: digest, jsonText: { type: 'string', maxLength: 2048 } }),
+  object({ type: { const: 'comment-drafts.restore' }, family: { const: 'comment' }, draft: draftReference, composerId: id, restored: draftReference, preservedCurrent: nullableCommentReference, targetState: { enum: ['current', 'changed'] } }),
+  object({ type: { const: 'comment-drafts.discard' }, family: { const: 'comment' }, draft: draftReference, discarded: { const: true } }),
+  object({ type: { const: 'component-drafts.inspect' }, family: { const: 'component' }, coverage: { enum: ['stored-and-session', 'session-only'] }, skippedInvalid: integer,
+    token: digest, drafts: { type: 'array', maxItems: 10, items: componentMetadata }, next: cursor }, ['type', 'family', 'coverage', 'skippedInvalid', 'token', 'drafts']),
+  object({ type: { const: 'component-drafts.read' }, family: { const: 'component' }, draft: componentDraftReference, storage: { enum: ['durable', 'session'] }, format: { const: 'presmium-component-parameters-json-v1' }, offset: integer, endOffset: integer, totalUtf16: integer, totalUtf8: integer, sha256: digest, jsonText: { type: 'string', maxLength: 2048 } }),
+  object({ type: { const: 'component-drafts.restore' }, family: { const: 'component' }, draft: componentDraftReference, restored: componentMetadata, preservedCurrent: nullableComponentReference }),
+  object({ type: { const: 'component-drafts.discard' }, family: { const: 'component' }, draft: componentDraftReference, current: bool, discarded: { const: true } }),
+] }
+const source = DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema
+const binding = object({ source, irRevision: entity, planId: entity })
+const position = object({ timeMs: number, stepTimeMs: number, sectionId: entity, stepId: entity, durationMs: number, playing: bool, rate: { type: 'number', exclusiveMinimum: 0, maximum: 16 }, trying: bool, waitingFor: entity }, ['timeMs', 'durationMs', 'playing', 'rate', 'trying'])
+const playback = object({ binding, status: { enum: ['loading', 'ready', 'estimated', 'unavailable', 'failed'] }, position, error: { type: 'string', maxLength: 300 } }, ['binding', 'status'])
+export const AUTHORING_CLIENT_SNAPSHOT_SCHEMA: Schema = object({
+  revision: integer, source, view: { enum: ['document', 'present'] }, editing: object({ dirty: bool, saving: bool, composing: bool, conflicted: bool, locked: bool, loading: bool }),
+  interaction: { type: 'string', maxLength: 200 }, position: object({ sectionId: entity, stepId: entity }, ['sectionId']), binding, playback,
+  preview: { oneOf: [object({ status: { enum: ['unprepared', 'preparing', 'unavailable'] } }), object({ status: { const: 'prepared' }, source, irRevision: entity, projectRevision: integer })] },
+  actions: { type: 'array', items: { enum: [...AUTHORING_CLIENT_ACTIONS] }, maxItems: AUTHORING_CLIENT_ACTIONS.length, uniqueItems: true }, unsubmittedContent: { const: 'not-inspected' },
+}, ['revision', 'source', 'view', 'editing', 'interaction', 'actions', 'unsubmittedContent'])
+const action = (type: string, properties: Record<string, Schema> = {}): Schema => object({ type: { const: type }, ...properties })
+export const AUTHORING_CLIENT_ACTION_SCHEMA: Schema = { oneOf: [
+  action('state.read'), action('source.flush'), action('preview.prepare'), action('playback.pause'), action('position.step', { sectionId: entity, stepId: entity }),
+  object({ type: { const: 'comment-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
+  object({ type: { const: 'comment-drafts.read' }, draft: draftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
+  action('comment-drafts.restore', { draft: draftReference, composerId: id, expectedCurrent: nullableCommentReference }),
+  action('comment-drafts.discard', { draft: draftReference }),
+  object({ type: { const: 'component-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
+  object({ type: { const: 'component-drafts.read' }, draft: componentDraftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
+  action('component-drafts.restore', { draft: componentDraftReference, expectedCurrent: nullableComponentReference }),
+  action('component-drafts.discard', { draft: componentDraftReference, current: bool }),
+  action('playback.play', { binding }), action('playback.seek', { binding, timeMs: number }), action('playback.rate', { binding, rate: { enum: [...PRODUCTION_PLAYBACK_RATES] } }),
+] }
+export const AUTHORING_CLIENT_REQUEST_SCHEMA: Schema = object({ clientId: id, epoch: id, requestId: id, source, expectedClientState: object({ connectionId: id, revision: integer }), action: AUTHORING_CLIENT_ACTION_SCHEMA })
+export const AUTHORING_CLIENT_QUERY_SCHEMA: Schema = object({ clientId: id, after: id }, [])
+export const AUTHORING_CLIENT_REQUEST_QUERY_SCHEMA: Schema = object({ clientId: id, epoch: id, requestId: id })
+export const AUTHORING_CLIENT_OPEN_SCHEMA: Schema = object({ clientId: id, epoch: id, snapshot: AUTHORING_CLIENT_SNAPSHOT_SCHEMA })
+export const AUTHORING_CLIENT_REPORT_SCHEMA: Schema = object({ sequence: integer, snapshot: AUTHORING_CLIENT_SNAPSHOT_SCHEMA })
+export const AUTHORING_CLIENT_ACK_SCHEMA: Schema = object({ sequence: integer, snapshot: AUTHORING_CLIENT_SNAPSHOT_SCHEMA, requestId: id, state: { enum: ['executing', 'done', 'refused', 'failed'] }, error: object({ code: { type: 'string', minLength: 1, maxLength: 160 } }), result: AUTHORING_CLIENT_ACTION_RESULT_SCHEMA }, ['sequence', 'snapshot', 'requestId', 'state'])
+export const AUTHORING_CLIENT_CONNECTION_SCHEMA: Schema = object({ clientId: id, epoch: id, connectionId: id, credential: { type: 'string', minLength: 32, maxLength: 100 } })

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 }[]
+}