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

package/README.md

@@ -2,7 +2,7 @@
 
 Presmium's shared kernel: the IR and the plugin contracts, the service registry, anchors and checks. Plain TypeScript, used by the compiler, the renderers, the IR runtime and every plugin.
 
-Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+Part of [Presmium](https://github.com/Lincyaw/presmium), which publishes structured teaching documents as web pages, slides, Jupyter notebooks and narrated lectures.
 
 ## Install
 
@@ -14,19 +14,19 @@ Plugins declare it as a peer dependency, so they share the application's copy:
 
 ## Entries
 
-- `@lincyaw/kernel`: the contracts (`PresmiumNodePlugin`, `PluginDefinition`, `DirectiveSpec`, `IRPass`, `Renderer`, `RenderContext`, `Check`, the service tokens), the IR types (`IRDocument` and its nodes), `KERNEL_VERSION`, `IR_VERSION`, and plain helpers such as `docBlocks`, `withProp`, `deckLocale`, `json` and `problem`.
-- `@lincyaw/kernel/contracts`, `@lincyaw/kernel/ir`: the contracts or the IR types alone.
-- `@lincyaw/kernel/reading`: plain functions that read compiled documents (`chapters`, `blockText`, `narrationAt`, `tokenize`).
-- `@lincyaw/kernel/node`: helpers for Node code: `copyPublished` (its other exports are internal).
+- `@lincyaw/kernel`: the contracts (`PresmiumNodePlugin`, `PluginDefinition`, `DirectiveSpec`, `IRPass`, `Renderer`, `RenderContext`, `Check`, the service tokens), the canonical authoring types (`TeachingDocument`, `DocumentEditOperation`), `DOCUMENT_ENTRY`, `DOCUMENT_SCHEMA_VERSION`, `DOCUMENT_JSON_SCHEMA`, `validateDocument`, the derived IR types (`IRDocument` and its nodes), `KERNEL_VERSION`, `IR_VERSION`, and plain helpers such as `docBlocks`, `withProp`, `deckLocale`, `jsonResponse` and `problemResponse`.
+- `@lincyaw/kernel/contracts`, `@lincyaw/kernel/ir`: the contracts (types, service tokens and the preview protocol's parsers) or the IR types alone; the helpers are only in `@lincyaw/kernel`.
+- `@lincyaw/kernel/reading`: plain functions that read a compiled document, the IR (`chapters`, `blockText`, `narrationAt`, `tokenize`); they do no I/O.
+- `@lincyaw/kernel/node`: helpers for Node code: `copyPublished` and `isInside` (its other exports are internal).
 - `@lincyaw/kernel/runner.py`: the shared Python runner of the executors.
 
 ## Versions
 
-`KERNEL_VERSION` is the version of the plugin contract, separate from the package version: 1.0.0 in Presmium 1.0, a minor version higher for each compatible addition to the contract, a major version (and a major version of the packages) for an incompatible change. Plugins declare `kernel: '^1.0.0'`, which any Presmium 1.x satisfies; a plugin whose range excludes it is not loaded. `IR_VERSION` is the version of the IR's JSON format.
+`KERNEL_VERSION` is the version of the plugin contract, separate from the package version: 1.0.0 in Presmium 1.0, a minor version higher for each compatible addition to the contract, a major version (and a major version of the packages) for an incompatible change. Plugins declare `kernel: '^1.0.0'`, which any Presmium 1.x satisfies; a plugin whose range excludes it is not loaded. `DOCUMENT_SCHEMA_VERSION` versions the authoritative authoring document; `IR_VERSION` separately versions derived runtime snapshots. Source CAS versions and runtime snapshot IDs have separate lifecycles.
 
 ## Documentation
 
-- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/lecture.en.md)
+- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/locales/en/lecture.json)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/kernel",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.1",
   "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
   "license": "Apache-2.0",
   "repository": {
@@ -33,8 +33,12 @@
     "src"
   ],
   "dependencies": {
+    "@cfworker/json-schema": "4.1.1",
     "@types/semver": "^7.8.0",
+    "fast-json-patch": "3.1.1",
+    "json-schema-library": "11.6.16",
     "parse5": "7.3.0",
-    "semver": "^7.8.5"
+    "semver": "^7.8.5",
+    "proper-lockfile": "4.1.2"
   }
 }

package/src/access.ts

@@ -0,0 +1,18 @@
+import type { ApprovalKind, Member, MemberRole } from './contracts.ts'
+
+const RANK: Record<MemberRole, number> = { reader: 0, editor: 1, owner: 2 }
+
+export const APPROVAL_KINDS: readonly ApprovalKind[] = ['operate', 'spend', 'write', 'agent']
+
+/** The person who runs presmium dev, presmium serve or presmium-mcp on their own machine. */
+export const LOCAL_AUTHOR: Member = { id: 'local', name: 'local author', roles: ['owner'] }
+
+/** Whether the member has the role or one above it (reader, editor, owner). */
+export function hasRole(member: Member, role: MemberRole): boolean {
+  return member.roles.some(own => RANK[own] >= RANK[role])
+}
+
+/** Whether a window that reports this view role shows the presentation: the presenter view or the audience's. */
+export function isPresentingRole(role: string | undefined): boolean {
+  return role === 'presenter' || role === 'audience'
+}

package/src/anchors.ts

@@ -1,4 +1,4 @@
-import type { AnchorResolver, AnchorResolverRegistry, Resolution } from './contracts.ts'
+import type { AnchorResolver, AnchorResolverRegistry, Resolution } from './contracts/anchors.ts'
 import { errorMessage } from './errors.ts'
 
 const SCHEME = /^[a-z][a-z0-9+.-]*$/i
@@ -52,3 +52,7 @@ export function createAnchorResolverRegistry(resolvers: AnchorResolver[] = []):
   for (const resolver of resolvers) registry.register(resolver)
   return registry
 }
+
+export function isRenderable(resolution: Resolution): boolean {
+  return resolution.status === 'exact' || resolution.status === 'moved'
+}

package/src/authoring.ts

@@ -0,0 +1,56 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
+import type { DocumentChange } from './contracts/workspace.ts'
+import type { DocumentIssue } from './contracts/document.ts'
+import { DOCUMENT_PAGE_CHANGE_APPLY_SCHEMA, DOCUMENT_PAGE_CHANGE_SCHEMA, DOCUMENT_PAGE_DUPLICATION_APPLY_SCHEMA, DOCUMENT_PAGE_DUPLICATION_SCHEMA } from './contracts/authoring.ts'
+import type { DocumentPageChangeReference, DocumentPageChangeRequest, DocumentPageDuplicationReference, DocumentPageDuplicationRequest } from './contracts/authoring.ts'
+
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', properties, required, additionalProperties: false })
+const ref = (name: string): Schema => ({ $ref: `#/$defs/${name}` })
+const id: Schema = { type: 'string', minLength: 1, maxLength: 200 }
+const index: Schema = { type: 'integer', minimum: 0 }
+const operation = (type: string, fields: Record<string, Schema>, required = Object.keys(fields)) => object({ type: { const: type }, ...fields }, ['type', ...required])
+const { $schema: _schema, $id: _id, $defs, ...documentSchema } = structuredClone(DOCUMENT_JSON_SCHEMA) as Exclude<Schema, boolean>
+
+/** Shared strict request schema; nested values reuse the canonical document definitions. */
+export const DOCUMENT_CHANGE_JSON_SCHEMA: Schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $ref: '#/$defs/DocumentChange',
+  $defs: {
+    ...$defs,
+    TeachingDocument: documentSchema,
+    DocumentOperation: { oneOf: [
+      operation('insertBlock', { sectionId: id, parentId: id, index, block: ref('Block') }, ['sectionId', 'index', 'block']),
+      operation('moveBlock', { blockId: id, sectionId: id, parentId: id, index }, ['blockId', 'sectionId', 'index']),
+      operation('deleteBlock', { blockId: id }),
+      operation('updateText', { blockId: id, content: { type: 'array', items: ref('RichTextNode') } }),
+      operation('updateSection', { sectionId: id, title: { type: 'string' }, layout: ref('Layout') }, ['sectionId']),
+      operation('setStepState', { stepId: id, visuals: { type: 'array', items: ref('Visual') }, inherits: id }, ['stepId', 'visuals']),
+      operation('setNarration', { narration: ref('Narration'), stepId: id, index }, ['narration']),
+      operation('setTiming', { stepId: id, sectionId: id, value: ref('StepProduction') }, ['value']),
+      operation('replaceAsset', { asset: ref('Asset') }),
+    ] },
+    DocumentChange: {
+      ...object({ id, baseDocumentVersion: { type: 'string', minLength: 1, maxLength: 128 }, replacement: ref('TeachingDocument'), operations: { type: 'array', minItems: 1, maxItems: 1000, items: ref('DocumentOperation') }, fileChanges: { type: 'array', maxItems: 15, items: object({ path: { type: 'string', minLength: 1 }, content: { type: 'string' }, base: { type: ['string', 'null'] } }) } }, ['id', 'baseDocumentVersion']),
+      oneOf: [{ required: ['replacement'], not: { required: ['operations'] } }, { required: ['operations'], not: { required: ['replacement'] } }],
+    },
+  },
+}
+
+const validator = new Validator(structuredClone(DOCUMENT_CHANGE_JSON_SCHEMA), '2020-12', false)
+const duplication = new Validator(structuredClone(DOCUMENT_PAGE_DUPLICATION_SCHEMA) as unknown as Schema, '2020-12', false)
+const duplicationApply = new Validator(structuredClone(DOCUMENT_PAGE_DUPLICATION_APPLY_SCHEMA) as unknown as Schema, '2020-12', false)
+const pageChange = new Validator(structuredClone(DOCUMENT_PAGE_CHANGE_SCHEMA) as unknown as Schema, '2020-12', false)
+const pageChangeApply = new Validator(structuredClone(DOCUMENT_PAGE_CHANGE_APPLY_SCHEMA) as unknown as Schema, '2020-12', false)
+
+export function validateDocumentPageDuplication(value: unknown): value is DocumentPageDuplicationRequest { return duplication.validate(value).valid }
+export function validateDocumentPageDuplicationApply(value: unknown): value is DocumentPageDuplicationReference { return duplicationApply.validate(value).valid }
+export function validateDocumentPageChange(value: unknown): value is DocumentPageChangeRequest { return pageChange.validate(value).valid }
+export function validateDocumentPageChangeApply(value: unknown): value is DocumentPageChangeReference { return pageChangeApply.validate(value).valid }
+
+export function validateDocumentChange(value: unknown): { change?: DocumentChange, issues: DocumentIssue[] } {
+  const checked = validator.validate(value)
+  const issues: DocumentIssue[] = checked.errors.slice(0, 100).map(error => ({ path: error.instanceLocation.replace(/^#/, ''), code: `schema.${error.keyword}`, message: error.error, severity: 'error' }))
+  return { ...checked.valid ? { change: value as DocumentChange } : {}, issues }
+}

package/src/blocks.ts

@@ -17,11 +17,3 @@ export function nodeMdast(node: IRNode): MdastNode[] {
   if (node.type === 'markdown') return [node.mdast]
   return node.type === 'component' && node.fallback ? [node.fallback] : []
 }
-
-export function withProp(props: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
-  const [key = '', ...rest] = path.split('.')
-  if (rest.length === 0) return { ...props, [key]: value }
-  const inner = props[key]
-  const object = inner !== null && typeof inner === 'object' && !Array.isArray(inner) ? inner as Record<string, unknown> : {}
-  return { ...props, [key]: withProp(object, rest.join('.'), value) }
-}

package/src/component-code.ts

@@ -0,0 +1,6 @@
+import type { CodeNode, ComponentNode } from './ir.ts'
+
+/** The code block among a component's child blocks, e.g. the code of a run panel. */
+export function componentCode(node: ComponentNode): CodeNode | undefined {
+  return node.children?.map(block => block.node).find((child): child is CodeNode => child.type === 'code')
+}

package/src/contracts/agent.ts

@@ -1,6 +1,7 @@
 import type { Member } from './server.ts'
 import { defineService } from './service.ts'
 import type { ServiceToken } from './service.ts'
+import type { Locale } from './locale.ts'
 
 export interface SourceRange { file: string, startLine: number, endLine: number }
 
@@ -9,6 +10,7 @@ export interface Focus {
   id: string
   from: 'source' | 'web' | 'slides'
   document: string
+  scope?: 'document' | 'workspace'
   source: SourceRange
   excerpt: string
   section?: string
@@ -21,6 +23,7 @@ export interface Focus {
 export interface FocusReport {
   id: string
   from: Focus['from']
+  scope?: Focus['scope']
   section?: string
   block?: string
   step?: number
@@ -68,86 +71,6 @@ export interface AgentTool {
   input: Record<string, unknown>
   kind: AgentToolKind
   run(input: Record<string, unknown>, ctx: AgentToolContext): Promise<unknown>
+  /** Text for the codes `run` throws as error messages, in the document's language; other messages pass on as they are. */
+  errors?: Record<Locale, Record<string, string>>
 }
-
-export type ReviewChangeKind = 'added' | 'modified' | 'deleted'
-
-export interface ReviewChange {
-  path: string
-  kind: ReviewChangeKind
-  binary: boolean
-  added: number
-  removed: number
-  diff?: string
-}
-
-export interface ReviewStep {
-  id: string
-  label: string
-  tool?: string
-  at: string
-  changes: ReviewChange[]
-}
-
-export interface ChangeReview {
-  readonly root: string
-  readonly visibility: 'immediate' | 'on-commit'
-  step(label: string, tool?: string): Promise<ReviewStep>
-  steps(): readonly ReviewStep[]
-  diff(): Promise<ReviewChange[]>
-  restoreTo?(stepId: string): Promise<void>
-  accept(reject?: string[]): Promise<string[]>
-  rollback(): Promise<void>
-  close(): Promise<void>
-}
-
-export interface ChangeReviewService {
-  readonly engine: string
-  open(options: { document: string, task: string, member: Member }): Promise<ChangeReview>
-}
-
-export const CHANGE_REVIEW = defineService<ChangeReviewService>('presmium.changeReview')
-
-export interface RevisionOrigin {
-  kind: 'agent' | 'document' | 'editor'
-  task?: string
-  member?: Member
-}
-
-export interface Revision {
-  id: string
-  message: string
-  author: string
-  date: string
-  origin: RevisionOrigin
-  files: string[]
-  revertedBy?: string
-}
-
-export type RevertResult = { ok: true, revision: Revision } | { ok: false, conflicts: string[] }
-
-export interface RevisionService {
-  commit(change: { files: string[], message: string, origin: RevisionOrigin }): Promise<Revision | undefined>
-  history(filter?: { document?: string, task?: string, limit?: number }): Promise<Revision[]>
-  revert(id: string, member: Member): Promise<RevertResult>
-}
-
-export const REVISIONS = defineService<RevisionService>('presmium.revisions')
-
-export interface DocumentLockService {
-  claim(document: string, holder: string): (() => void) | undefined
-  holder(document: string): string | undefined
-}
-
-export const DOCUMENT_LOCKS = defineService<DocumentLockService>('presmium.documentLocks')
-
-export type DocumentFileChange =
-  | { path: string, content: Uint8Array, executable?: boolean, at?: number }
-  | { path: string, link: string }
-  | { path: string, remove: true }
-
-export interface DocumentFiles {
-  write(changes: DocumentFileChange[]): Promise<void>
-}
-
-export const DOCUMENT_FILES = defineService<DocumentFiles>('presmium.documentFiles')

package/src/contracts/anchors.ts

@@ -0,0 +1,46 @@
+import type { Unsubscribe } from './plugin.ts'
+
+export type AnchorString = `${string}:${string}`
+
+export type ResolutionStatus = 'exact' | 'moved' | 'fuzzy' | 'lost'
+
+export interface ResolvedLocation {
+  file: string
+  startLine: number
+  endLine: number
+  text: string
+}
+
+export interface Resolution {
+  status: ResolutionStatus
+  location?: ResolvedLocation
+  fingerprint?: string
+  candidates?: ResolvedLocation[]
+  message?: string
+}
+
+export interface SourceReader {
+  read(file: string, ref?: string): Promise<string | undefined>
+}
+
+export interface RecordedAnchor {
+  fingerprint: string
+  file: string
+  startLine: number
+}
+
+export interface AnchorResolver {
+  scheme: string
+  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
+}
+
+export interface AnchorResolverRegistry {
+  register(resolver: AnchorResolver): Unsubscribe
+  resolve(anchor: AnchorString, src: SourceReader, recorded?: RecordedAnchor, ref?: string): Promise<Resolution>
+  schemes(): string[]
+}
+
+export interface AnchorLockFile {
+  version: 1
+  anchors: Record<string, RecordedAnchor>
+}

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 } })