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

package/src/document-reads.ts

@@ -0,0 +1,81 @@
+import { DOCUMENT_ENTITY_COLLECTIONS, DOCUMENT_READ_MAX_RESPONSE_CHARS } from './contracts/document-reads.ts'
+import type { DocumentOutlineAnswer, DocumentOutlineEntry, DocumentOutlineQuery, DocumentPartAnswer, DocumentPartQuery } from './contracts/document-reads.ts'
+import type { JsonValue, TeachingDocument } from './contracts/document.ts'
+import type { CanonicalSource } from './ir.ts'
+import { fnv1a64 } from './fingerprint.ts'
+
+export class DocumentReadError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+const fits = (value: unknown) => JSON.stringify(value, null, 2).length <= DOCUMENT_READ_MAX_RESPONSE_CHARS
+const fail = (status: number, code: string): never => { throw new DocumentReadError(status, code) }
+/** Offsets index decoded UTF-16 text; a valid surrogate pair is always kept together. */
+function boundary(text: string, offset: number): boolean {
+  return !(offset > 0 && offset < text.length && /[\uD800-\uDBFF]/.test(text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(text[offset]!))
+}
+function preview(text: string): NonNullable<DocumentOutlineEntry['title']> {
+  let end = Math.min(text.length, 80)
+  if (!boundary(text, end)) end--
+  return { preview: text.slice(0, end), complete: end === text.length, totalChars: text.length }
+}
+
+export function documentOutline(content: TeachingDocument, source: CanonicalSource, query: DocumentOutlineQuery): DocumentOutlineAnswer {
+  const collection = query.collection ?? 'sections', offset = query.offset ?? 0
+  const records = content[collection] ?? {}, ids = collection === 'sections' ? content.sectionOrder : Object.keys(records)
+  if (offset > ids.length) return fail(400, 'document-read-offset-invalid')
+  const answer: DocumentOutlineAnswer = { source, documentSchemaVersion: content.schemaVersion,
+    counts: Object.fromEntries(DOCUMENT_ENTITY_COLLECTIONS.map(name => [name, Object.keys(content[name] ?? {}).length])) as DocumentOutlineAnswer['counts'],
+    collection, present: Object.hasOwn(content, collection), offset, total: ids.length, complete: offset === ids.length, entries: [] }
+  for (let i = offset; i < ids.length; i++) {
+    const id = ids[i]!, record = records[id] as unknown as Record<string, unknown>
+    const entry: DocumentOutlineEntry = { id }
+    if (typeof record.type === 'string') entry.type = record.type
+    if (typeof record.sectionId === 'string') entry.sectionId = record.sectionId
+    if (typeof record.title === 'string') entry.title = preview(record.title)
+    if (collection === 'sections') entry.counts = { children: (record.children as unknown[]).length, steps: (record.stepOrder as unknown[]).length }
+    if (collection === 'steps') entry.counts = { narrations: (record.narrationIds as unknown[]).length }
+    answer.entries.push(entry)
+    answer.complete = i + 1 === ids.length
+    if (answer.complete) delete answer.nextOffset
+    else answer.nextOffset = i + 1
+    if (fits(answer)) continue
+    answer.entries.pop(); answer.complete = false; answer.nextOffset = i
+    if (!answer.entries.length) return fail(413, 'document-read-response-too-large')
+    break
+  }
+  if (!fits(answer)) return fail(413, 'document-read-response-too-large')
+  return answer
+}
+
+export function documentPart(content: TeachingDocument, source: CanonicalSource, query: DocumentPartQuery): DocumentPartAnswer {
+  const { target } = query
+  let value: unknown = content[target.collection]
+  if ('id' in target) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, target.id)) return fail(404, 'document-entity-not-found')
+    value = (value as Record<string, unknown>)[target.id]
+  }
+  for (const field of target.path ?? []) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, field) || (Array.isArray(value) && (!/^(0|[1-9][0-9]*)$/.test(field) || !Number.isSafeInteger(Number(field))))) return fail(404, 'document-field-not-found')
+    value = (value as Record<string, unknown>)[field]
+  }
+  if (value === undefined) return fail(404, 'document-field-not-found')
+  const text = JSON.stringify(value), offset = query.offset ?? 0
+  if (offset > text.length || !boundary(text, offset)) return fail(400, 'document-read-offset-invalid')
+  const base = { source, target, valueDigest: { algorithm: 'fnv1a64' as const, serialization: 'JSON.stringify' as const, value: fnv1a64(text) } }
+  const whole: DocumentPartAnswer = { ...base, encoding: 'value', complete: true, value: value as JsonValue }
+  if (offset === 0 && fits(whole)) return whole
+  const fragment = (end: number): DocumentPartAnswer => ({ ...base, encoding: 'json-text-fragment', offsetUnit: 'utf16', offset, ...end < text.length ? { nextOffset: end } : {}, totalChars: text.length, complete: end === text.length, text: text.slice(offset, end) })
+  // Find the largest prefix whose fully escaped, indented response fits the actual text budget.
+  let low = offset, high = text.length
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2)
+    if (fits(fragment(mid))) low = mid
+    else high = mid - 1
+  }
+  if (!boundary(text, low)) low--
+  if (low === offset && offset < text.length) return fail(413, 'document-read-response-too-large')
+  const answer = fragment(low)
+  if (!fits(answer)) return fail(413, 'document-read-response-too-large')
+  return answer
+}

package/src/document-schema.ts

@@ -0,0 +1,85 @@
+import type { Schema } from '@cfworker/json-schema'
+import { ASSET_TITLE_MAX_LENGTH, DOCUMENT_SCHEMA_VERSION } from './contracts/document.ts'
+
+const ref = (name: string): Schema => ({ $ref: `#/$defs/${name}` })
+const string: Schema = { type: 'string' }
+const id: Schema = { type: 'string', minLength: 1, maxLength: 200, pattern: '^[^\\u0000-\\u001f]+$', not: { enum: ['__proto__', 'constructor', 'prototype'] } }
+const positive: Schema = { type: 'number', exclusiveMinimum: 0 }
+const nonnegative: Schema = { type: 'number', minimum: 0 }
+const integer: Schema = { type: 'integer', minimum: 0 }
+const list = (items: Schema): Schema => ({ type: 'array', items })
+const ids: Schema = { type: 'array', items: id, uniqueItems: true }
+const record = (value: Schema): Schema => ({ type: 'object', additionalProperties: value })
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', properties, required, additionalProperties: false })
+const tag = (type: string): Schema => ({ const: type })
+const scope = { only: list(string), audience: list(string) }
+const style = object({ alignment: { enum: ['left', 'center', 'right', 'justify'] }, color: string, background: string }, [])
+const exclusiveCode = [{ required: ['value'], not: { required: ['origin'] } }, { required: ['origin'], not: { required: ['value'] } }]
+const rich = (type: string, properties: Record<string, Schema>, required: string[] = Object.keys(properties)): Schema => object({ id, type: tag(type), ...properties }, ['id', 'type', ...required])
+const block = (type: string, properties: Record<string, Schema>, required: string[] = Object.keys(properties)): Schema => object({ id, type: tag(type), ...scope, ...properties }, ['id', 'type', ...required])
+
+/** Public authoring schema; domain graph checks are shared by the UI, agent and compiler validator. */
+export const DOCUMENT_JSON_SCHEMA: Schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'urn:presmium:teaching-document:1',
+  ...object({
+    schemaVersion: { const: DOCUMENT_SCHEMA_VERSION }, id,
+    metadata: object({ title: string, description: string, tags: list(string), lang: { type: 'string', minLength: 1 }, plugins: list(string), presmium: record(ref('JsonObject')), renderers: record(ref('JsonObject')), execute: ref('JsonObject'), checks: ref('JsonObject'), translations: record(string), translationOf: object({ entry: string, digest: string }) }, ['title', 'lang']),
+    sectionOrder: { ...ids, minItems: 1 }, sections: record(ref('Section')), blocks: record(ref('Block')),
+    steps: record(ref('Step')), narrations: record(ref('Narration')), assets: record(ref('Asset')),
+    definitions: record(ref('Definition')), production: ref('Production'), comments: record(ref('Thread')),
+  }, ['schemaVersion', 'id', 'metadata', 'sectionOrder', 'sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions', 'production']),
+  $defs: {
+    JsonValue: { anyOf: [{ type: ['null', 'boolean', 'number', 'string'] }, { type: 'array', items: ref('JsonValue') }, ref('JsonObject')] },
+    JsonObject: { type: 'object', additionalProperties: ref('JsonValue') },
+    JsonSchema: { anyOf: [{ type: 'boolean' }, ref('JsonObject')] },
+    Layout: object({ type: { enum: ['stack', 'columns', 'canvas', 'scrolly'] }, properties: ref('JsonObject'), renderers: record(ref('JsonObject')) }, ['type']),
+    Section: object({ id, title: string, level: { type: 'integer', minimum: 1, maximum: 6 }, children: ids, stepOrder: { ...ids, minItems: 1 }, layout: ref('Layout'), audience: list(string), config: record(ref('JsonObject')) }, ['id', 'title', 'children', 'stepOrder', 'layout']),
+    Mark: { oneOf: [object({ type: { enum: ['bold', 'italic', 'underline', 'strike', 'code'] } }), object({ type: { enum: ['color', 'background'] }, value: string })] },
+    Inline: { oneOf: [
+      object({ type: tag('text'), text: string, marks: list(ref('Mark')) }, ['type', 'text']),
+      object({ type: tag('link'), href: string, children: list(ref('Inline')) }),
+      object({ type: tag('math'), value: string }), object({ type: tag('break') }),
+      object({ type: tag('extension'), kind: id, schemaVersion: { type: 'integer', minimum: 1 }, data: ref('JsonObject'), fallback: string }),
+    ] },
+    RichTextNode: { oneOf: [
+      rich('paragraph', { children: list(ref('Inline')), style }, ['children']),
+      rich('heading', { level: { type: 'integer', minimum: 1, maximum: 6 }, children: list(ref('Inline')), style }, ['level', 'children']),
+      rich('list', { ordered: { type: 'boolean' }, start: { type: 'integer', minimum: 1 }, children: list(ref('ListItem')) }, ['ordered', 'children']),
+      rich('blockquote', { children: list(ref('RichTextNode')) }),
+      rich('code', { language: string, value: string }), rich('math', { value: string }),
+      rich('table', { children: list(ref('TableRow')), headerRows: integer, headerColumns: integer, columnWidths: list(positive) }, ['children']),
+      rich('extension', { kind: id, schemaVersion: { type: 'integer', minimum: 1 }, data: ref('JsonObject'), fallback: list(ref('RichTextNode')) }),
+    ] },
+    ListItem: rich('listItem', { children: list(ref('RichTextNode')), checked: { type: 'boolean' } }, ['children']),
+    TableRow: rich('tableRow', { children: list(ref('TableCell')) }),
+    TableCell: rich('tableCell', { children: list(ref('Inline')), style, colspan: { type: 'integer', minimum: 1 }, rowspan: { type: 'integer', minimum: 1 } }, ['children']),
+    CodeReference: object({ anchor: { type: 'string', minLength: 1 }, pin: string, repo: string, highlightRegions: record({ type: 'string', minLength: 1 }) }, ['anchor']),
+    VariantReference: object({ anchor: { type: 'string', minLength: 1 }, pin: string, repo: string }, ['anchor']),
+    CodeVariant: { ...object({ id, title: string, value: string, origin: ref('VariantReference') }, ['id', 'title']), oneOf: exclusiveCode },
+    CodeExecution: object({ args: record(string), stdin: string, timeoutMs: positive, executor: string, when: { enum: ['compile', 'live', 'both'] }, session: string }, ['when']),
+    Block: { oneOf: [
+      block('text', { content: list(ref('RichTextNode')), reveal: object({ type: tag('items'), order: ids }) }, ['content']),
+      block('container', { layout: { enum: ['stack', 'columns', 'tabs'] }, children: ids, properties: object({ title: string, columnWidths: list(positive), tabTitles: list(string) }, []) }),
+      block('image', { assetId: id, alt: string, caption: list(ref('Inline')), width: positive, alignment: { enum: ['left', 'center', 'right', 'justify'] } }, ['alt']),
+      { ...block('code', { language: string, value: string, origin: ref('CodeReference'), title: string, execution: ref('CodeExecution'), highlight: record(list({ type: 'integer', minimum: 1 })), variants: list(ref('CodeVariant')), echo: { type: 'boolean' } }, ['language']), oneOf: exclusiveCode },
+      block('component', { definitionId: id, parameters: ref('JsonObject'), children: ids }, ['definitionId', 'parameters']),
+    ] },
+    Visual: object({ blockId: id, visible: { type: 'boolean' }, state: id, parameters: ref('JsonObject') }, ['blockId', 'visible']),
+    Step: object({ id, sectionId: id, title: string, visuals: list(ref('Visual')), narrationIds: ids, inherits: id }, ['id', 'sectionId', 'visuals', 'narrationIds']),
+    NarrationNode: { oneOf: [object({ type: tag('text'), text: string }), object({ type: tag('pronunciation'), display: string, spoken: string }), object({ id, type: tag('cue'), action: { type: 'string', minLength: 1 }, target: object({ blockId: id, element: string }, ['blockId']), parameters: ref('JsonObject') }, ['id', 'type', 'action'])] },
+    Narration: object({ id, content: list(ref('NarrationNode')), provenance: object({ type: tag('transcription'), transcriptionId: { type: 'string', pattern: '^[a-f0-9]{64}$' }, revision: { type: 'string', pattern: '^[a-f0-9]{64}$' }, assetId: id, audioSha256: { type: 'string', pattern: '^[a-f0-9]{64}$' }, segmentIds: { ...ids, minItems: 1 } }) }, ['id', 'content']),
+    Asset: object({ id, kind: { enum: ['image', 'audio', 'video', 'file'] }, location: { type: 'string', minLength: 1 }, title: { type: 'string', minLength: 1, maxLength: ASSET_TITLE_MAX_LENGTH }, fingerprint: string, mediaType: string }, ['id', 'kind', 'location']),
+    Implementation: { oneOf: [object({ type: tag('file'), path: { type: 'string', minLength: 1 }, exportName: string, fingerprint: string }, ['type', 'path']), object({ type: tag('module'), specifier: { type: 'string', minLength: 1 }, exportName: string }, ['type', 'specifier']), object({ type: tag('plugin'), plugin: id, name: id })] },
+    State: object({ id, title: string, parameterSchema: ref('JsonSchema'), legacyIndex: integer }, ['id']),
+    Definition: object({ id, kind: { type: 'string', minLength: 1 }, schemaVersion: { type: 'integer', minimum: 1 }, implementation: ref('Implementation'), parameterSchema: ref('JsonSchema'), states: list(ref('State')), data: ref('JsonObject') }, ['id', 'kind', 'schemaVersion', 'implementation', 'parameterSchema', 'states']),
+    VoiceSource: { oneOf: [object({ type: tag('none') }), object({ type: tag('tts'), voice: object({ voice: { type: 'string', minLength: 1 }, engine: string, rate: positive, style: string }, ['voice']) }), object({ type: tag('recording'), assetId: id, sourceRange: object({ startMs: nonnegative, endMs: nonnegative }) }, ['type', 'assetId'])] },
+    StepProduction: object({ narrationStart: { enum: ['with-animation', 'after-animation'] }, minimumHoldMs: nonnegative, trailingPauseMs: nonnegative, voiceSource: ref('VoiceSource') }, []),
+    MediaClip: object({ id, assetId: id, sourceRange: object({ startMs: nonnegative, endMs: nonnegative }), attachment: object({ stepId: id, offsetMs: nonnegative }), volume: { type: 'number', minimum: 0, maximum: 1 }, muted: { type: 'boolean' } }, ['id', 'assetId', 'sourceRange', 'attachment', 'volume']),
+    CaptionTiming: object({ narrationIds: ids, sourceFingerprint: { type: 'string', pattern: '^[a-f0-9]{16}$' }, playbackFingerprint: { type: 'string', pattern: '^[a-f0-9]{16}$' }, durationMs: { type: 'integer', minimum: 1 }, segments: { type: 'array', minItems: 1, maxItems: 32, items: object({ id, from: integer, to: integer, startMs: integer, endMs: integer }) } }),
+    Production: object({ defaults: ref('StepProduction'), sectionOverrides: record(ref('StepProduction')), stepOverrides: record(ref('StepProduction')), narrationOverrides: record(object({ narrationStart: { enum: ['with-animation', 'after-animation'] } })), cueTimings: record(object({ pauseMs: nonnegative })), captionTimings: record(ref('CaptionTiming')), mediaClips: list(ref('MediaClip')) }, ['defaults', 'stepOverrides', 'mediaClips']),
+    TextPoint: object({ blockId: { type: 'string', minLength: 1, maxLength: 205 }, offset: integer }),
+    Comment: object({ id, type: tag('comment'), userId: id, createdAt: string, updatedAt: string, deletedAt: string, content: list(ref('RichTextNode')), metadata: ref('JsonObject'), reactions: list(object({ emoji: string, createdAt: string, userIds: ids })) }, ['id', 'type', 'userId', 'createdAt', 'updatedAt', 'reactions']),
+    Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: object({ from: ref('TextPoint'), to: ref('TextPoint') }), comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
+  },
+}

package/src/document-voices.ts

@@ -0,0 +1,153 @@
+import type { StepProduction, TeachingDocument, VoiceSource } from './contracts/document.ts'
+
+/** Authoring scopes use stable source IDs, independent of compiled numerical step bindings. */
+export type DocumentVoiceScope = { kind: 'document' } | { kind: 'page', sectionId: string } | { kind: 'step', stepId: string } | { kind: 'steps', stepIds: readonly string[] }
+export interface DocumentVoiceOptions { replaceOverrides?: boolean }
+export interface DocumentStepVoice {
+  stepId: string
+  sectionId: string
+  value?: VoiceSource
+  inheritedFrom: 'step' | 'page' | 'document' | 'unset'
+}
+export interface DocumentVoiceImpact {
+  total: number
+  /** Steps whose effective value or inheritance source will change. */
+  updated: number
+  /** Steps protected by an existing local voiceSource, including none and recording. */
+  preserved: number
+  unchanged: number
+  /** Existing configuration slots, not steps: page + step counts equal none + tts + recording. */
+  overrides: { pages: number, steps: number, none: number, tts: number, recording: number }
+}
+
+function page(document: TeachingDocument, id: string) {
+  const section = Object.hasOwn(document.sections, id) && document.sections[id]
+  if (!section || !document.sectionOrder.includes(id)) throw new Error(`document-voice-page-missing: ${id}`)
+  return section
+}
+
+function step(document: TeachingDocument, id: string) {
+  const value = Object.hasOwn(document.steps, id) && document.steps[id]
+  if (!value || !page(document, value.sectionId).stepOrder.includes(id)) throw new Error(`document-voice-step-missing: ${id}`)
+  return value
+}
+
+/** Deduplicated in authored page/step order; every requested ID is checked before any change. */
+export function documentVoiceStepIds(document: TeachingDocument, scope: DocumentVoiceScope): string[] {
+  const ordered = () => [...new Set(document.sectionOrder.flatMap(id => page(document, id).stepOrder))]
+  switch (scope.kind) {
+    case 'document': return ordered()
+    case 'page': return [...page(document, scope.sectionId).stepOrder]
+    case 'step': step(document, scope.stepId); return [scope.stepId]
+    case 'steps': {
+      if (!scope.stepIds.length) throw new Error('document-voice-steps-empty')
+      scope.stepIds.forEach(id => step(document, id))
+      const selected = new Set(scope.stepIds)
+      return ordered().filter(id => selected.has(id))
+    }
+    default: throw new Error('document-voice-scope-invalid')
+  }
+}
+
+/** An absent voice remains unset; none and recording retain their canonical identities. */
+export function resolveDocumentStepVoice(document: TeachingDocument, stepId: string): DocumentStepVoice {
+  const { sectionId } = step(document, stepId), production = document.production
+  const layers = [[production.stepOverrides[stepId]?.voiceSource, 'step'], [production.sectionOverrides?.[sectionId]?.voiceSource, 'page'], [production.defaults.voiceSource, 'document']] as const
+  for (const [value, inheritedFrom] of layers) if (value !== undefined) return { stepId, sectionId, value, inheritedFrom }
+  return { stepId, sectionId, inheritedFrom: 'unset' }
+}
+
+function same(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object' || Array.isArray(left) !== Array.isArray(right)) return false
+  const a = Object.keys(left), b = Object.keys(right)
+  return a.length === b.length && a.every(key => Object.hasOwn(right, key) && same((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]))
+}
+
+function checkVoice(document: TeachingDocument, source: VoiceSource | null | undefined): void {
+  if (source === null || source === undefined) return
+  const keys = (value: object, allowed: string[]) => Object.keys(value).every(key => allowed.includes(key))
+  if (typeof source !== 'object' || Array.isArray(source)) throw new Error('document-voice-source-invalid')
+  if (source.type === 'none' && keys(source, ['type'])) return
+  if (source.type === 'tts' && keys(source, ['type', 'voice'])) {
+    const voice = source.voice
+    if (voice && typeof voice === 'object' && !Array.isArray(voice) && keys(voice, ['voice', 'engine', 'rate', 'style']) && typeof voice.voice === 'string' && voice.voice.length > 0
+      && (voice.engine === undefined || typeof voice.engine === 'string') && (voice.style === undefined || typeof voice.style === 'string')
+      && (voice.rate === undefined || typeof voice.rate === 'number' && Number.isFinite(voice.rate) && voice.rate > 0)) return
+  }
+  if (source.type === 'recording' && keys(source, ['type', 'assetId']) && typeof source.assetId === 'string') {
+    const asset = Object.hasOwn(document.assets, source.assetId) && document.assets[source.assetId]
+    if (!asset) throw new Error(`document-voice-asset-missing: ${source.assetId}`)
+    if (asset.kind === 'audio' || asset.kind === 'video') return
+    throw new Error(`document-voice-asset-kind: ${source.assetId}`)
+  }
+  throw new Error('document-voice-source-invalid')
+}
+
+function protectedStep(document: TeachingDocument, scope: DocumentVoiceScope, id: string): boolean {
+  if (scope.kind === 'step') return false
+  if (document.production.stepOverrides[id]?.voiceSource !== undefined) return true
+  return scope.kind === 'document' && document.production.sectionOverrides?.[document.steps[id]!.sectionId]?.voiceSource !== undefined
+}
+
+function settings(previous: StepProduction | undefined, source: VoiceSource | null | undefined): StepProduction | undefined {
+  if (same(previous?.voiceSource, source ?? undefined)) return previous
+  const next = { ...previous }
+  if (source === null || source === undefined) delete next.voiceSource
+  else next.voiceSource = structuredClone(source)
+  return Object.keys(next).length ? next : undefined
+}
+
+/**
+ * Page/document writes preserve descendant voice slots unless replaceOverrides is explicit.
+ * A single step always edits its own slot; a steps batch preserves existing step slots by default.
+ * null/undefined removes only voiceSource under the same scope/protection rules. Timing and opaque
+ * sibling fields survive, including when the last voice setting is removed. A no-op retains identity.
+ */
+export function changeDocumentVoice(document: TeachingDocument, scope: DocumentVoiceScope, source: VoiceSource | null | undefined, options: DocumentVoiceOptions = {}): TeachingDocument {
+  const ids = documentVoiceStepIds(document, scope)
+  checkVoice(document, source)
+  const previous = document.production
+  let defaults = previous.defaults, sectionOverrides = previous.sectionOverrides, stepOverrides = previous.stepOverrides
+  const writeStep = (id: string, value: VoiceSource | null | undefined) => {
+    const next = settings(stepOverrides[id], value)
+    if (next === stepOverrides[id]) return
+    if (stepOverrides === previous.stepOverrides) stepOverrides = { ...stepOverrides }
+    if (next) stepOverrides[id] = next
+    else delete stepOverrides[id]
+  }
+  const writePage = (id: string, value: VoiceSource | null | undefined) => {
+    const next = settings(sectionOverrides?.[id], value)
+    if (next === sectionOverrides?.[id]) return
+    if (sectionOverrides === previous.sectionOverrides) sectionOverrides = { ...sectionOverrides }
+    if (next) sectionOverrides![id] = next
+    else delete sectionOverrides![id]
+  }
+  if (scope.kind === 'document') {
+    defaults = settings(defaults, source) ?? {}
+    if (options.replaceOverrides) {
+      document.sectionOrder.forEach(id => writePage(id, undefined))
+      ids.forEach(id => writeStep(id, undefined))
+    }
+  } else if (scope.kind === 'page') {
+    writePage(scope.sectionId, source)
+    if (options.replaceOverrides) ids.forEach(id => writeStep(id, undefined))
+  } else for (const id of ids) if (options.replaceOverrides || !protectedStep(document, scope, id)) writeStep(id, source)
+  if (defaults === previous.defaults && sectionOverrides === previous.sectionOverrides && stepOverrides === previous.stepOverrides) return document
+  return { ...document, production: { ...previous, defaults, ...sectionOverrides !== undefined ? { sectionOverrides } : {}, stepOverrides } }
+}
+
+/** Override counts include every existing local slot, even a page slot shadowed by a step slot. */
+export function previewDocumentVoiceChange(document: TeachingDocument, scope: DocumentVoiceScope, source: VoiceSource | null | undefined, options: DocumentVoiceOptions = {}): DocumentVoiceImpact {
+  const ids = documentVoiceStepIds(document, scope), next = changeDocumentVoice(document, scope, source, options)
+  const impact: DocumentVoiceImpact = { total: ids.length, updated: 0, preserved: 0, unchanged: 0, overrides: { pages: 0, steps: 0, none: 0, tts: 0, recording: 0 } }
+  const count = (value: VoiceSource | undefined, kind: 'pages' | 'steps') => { if (value) { impact.overrides[kind]++; impact.overrides[value.type]++ } }
+  if (scope.kind === 'document') document.sectionOrder.forEach(id => count(document.production.sectionOverrides?.[id]?.voiceSource, 'pages'))
+  for (const id of ids) {
+    count(document.production.stepOverrides[id]?.voiceSource, 'steps')
+    if (!options.replaceOverrides && protectedStep(document, scope, id)) impact.preserved++
+    else if (!same(resolveDocumentStepVoice(document, id), resolveDocumentStepVoice(next, id))) impact.updated++
+    else impact.unchanged++
+  }
+  return impact
+}

package/src/document.ts

@@ -0,0 +1,252 @@
+import { Validator } from '@cfworker/json-schema'
+import { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
+import { isRecord } from './errors.ts'
+import { captionSourceFingerprint, captionTimingProblem, stepCaptionText } from './document-caption-timings.ts'
+import { validateDocumentParameters } from './parameters.ts'
+import type { DocumentIssue, DocumentValidation, RichTextNode, TeachingDocument } from './contracts/document.ts'
+
+export { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
+export { DOCUMENT_ENTRY, DOCUMENT_SCHEMA_VERSION } from './contracts/document.ts'
+
+const structural = new Validator(DOCUMENT_JSON_SCHEMA, '2020-12', false)
+const escape = (key: string) => key.replaceAll('~', '~0').replaceAll('/', '~1')
+const at = (path: string, key: string | number) => `${path}/${escape(String(key))}`
+const own = (table: object, key: string) => Object.hasOwn(table, key)
+
+/** The same structural and semantic checks serve agent changes, native editing and compilation. */
+export function validateDocument(value: unknown): DocumentValidation {
+  const issues: DocumentIssue[] = []
+  const issue = (path: string, code: string, message: string, severity: DocumentIssue['severity'] = 'error') => { issues.push({ path, code, message, severity }) }
+  const active = new WeakSet<object>()
+  let nodes = 0
+  const json = (item: unknown, path: string, depth = 0): boolean => {
+    if (++nodes > 1_000_000 || depth > 128) { issue(path, 'json.limit', 'The document exceeds the supported JSON size or nesting limit.'); return false }
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return true
+    if (typeof item === 'number') { if (Number.isFinite(item)) return true; issue(path, 'json.number', 'JSON numbers must be finite.'); return false }
+    if (typeof item !== 'object') { issue(path, 'json.value', 'A document contains only JSON values.'); return false }
+    if (active.has(item)) { issue(path, 'json.cycle', 'A JSON value cannot contain an object cycle.'); return false }
+    if (!Array.isArray(item) && ![Object.prototype, null].includes(Object.getPrototypeOf(item))) { issue(path, 'json.object', 'A JSON object cannot have a custom object prototype.'); return false }
+    active.add(item)
+    const valid = Object.entries(item).every(([key, child]) => json(child, at(path, key), depth + 1))
+    active.delete(item)
+    return valid
+  }
+  if (!json(value, '')) return { issues }
+  let checked
+  try { checked = structural.validate(value) }
+  catch (error) { issue('', 'schema.invalid', error instanceof Error ? error.message : 'Document schema validation failed.'); return { issues } }
+  if (!checked.valid) {
+    for (const error of checked.errors.slice(0, 100)) issue(error.instanceLocation.replace(/^#/, ''), `schema.${error.keyword}`, error.error)
+    return { issues }
+  }
+  const doc = value as TeachingDocument
+  const lectureRenderer = doc.metadata.renderers?.lecture
+  if (isRecord(lectureRenderer) && own(lectureRenderer, 'script')) issue('/metadata/renderers/lecture/script', 'narration.external-source', 'External lecture scripts are not supported. Author narration in lecture.json narrations and bind it through each step narrationIds.')
+  const titleTargets = new Map(Object.keys(doc.sections).map(id => [`page:${id}`, id]))
+  const ids = new Map<string, string>()
+  const identify = (id: string, path: string) => {
+    const section = titleTargets.get(id)
+    if (section !== undefined) issue(path, 'id.reserved', `ID ${id} is reserved for the title of section ${section}.`)
+    const prior = ids.get(id)
+    if (prior !== undefined) issue(path, 'id.duplicate', `ID ${id} is already used at ${prior}.`)
+    else ids.set(id, path)
+  }
+  identify(doc.id, '/id')
+  for (const name of ['sections', 'blocks', 'steps', 'narrations', 'assets', 'definitions'] as const) {
+    for (const [key, entity] of Object.entries(doc[name])) {
+      const path = at(`/${name}`, key)
+      if (entity.id !== key) issue(`${path}/id`, 'id.key', 'An entity ID must match its map key.')
+      identify(entity.id, `${path}/id`)
+    }
+  }
+  const reference = (table: object, id: string, path: string, kind: string): boolean => {
+    if (own(table, id)) return true
+    issue(path, 'reference.missing', `Unknown ${kind} ${id}.`)
+    return false
+  }
+  for (const [index, id] of doc.sectionOrder.entries()) reference(doc.sections, id, `/sectionOrder/${index}`, 'section')
+  for (const id of Object.keys(doc.sections)) if (!doc.sectionOrder.includes(id)) issue(at('/sections', id), 'section.order', 'Every section must appear once in sectionOrder.')
+  const parents = new Map<string, string>()
+  const sectionOf = new Map<string, string>()
+  const visiting = new Set<string>()
+  const visit = (id: string, path: string, section: string) => {
+    if (!reference(doc.blocks, id, path, 'block')) return
+    if (visiting.has(id)) { issue(path, 'block.cycle', 'Block ownership cannot contain a cycle.'); return }
+    if (parents.has(id)) { issue(path, 'block.parent', `Block ${id} already belongs to ${parents.get(id)}.`); return }
+    parents.set(id, path); sectionOf.set(id, section); visiting.add(id)
+    const block = doc.blocks[id]!
+    if (block.type === 'container' || block.type === 'component') for (const [index, child] of (block.children ?? []).entries()) visit(child, at(at('/blocks', id), `children`) + `/${index}`, section)
+    visiting.delete(id)
+  }
+  for (const [id, section] of Object.entries(doc.sections)) for (const [index, child] of section.children.entries()) visit(child, at('/sections', id) + `/children/${index}`, id)
+  for (const id of Object.keys(doc.blocks)) if (!parents.has(id)) issue(at('/blocks', id), 'block.orphan', 'Every content block must have one section or container parent.')
+  const richIds = new Map<string, Set<string>>()
+  const rich = (node: RichTextNode | { id: string, type: string, children?: unknown[] }, path: string, collected: Set<string>) => {
+    identify(node.id, `${path}/id`); collected.add(node.id)
+    if (node.type === 'table') {
+      const table = node as Extract<RichTextNode, { type: 'table' }>
+      if ((table.headerRows ?? 0) > table.children.length) issue(`${path}/headerRows`, 'table.header', 'Header rows cannot exceed table rows.')
+      let spans: { from: number, to: number, until: number }[] = []
+      const widths = table.children.map((row, rowIndex) => {
+        spans = spans.filter(span => span.until > rowIndex).sort((a, b) => a.from - b.from)
+        let column = 0, index = 0
+        const added: typeof spans = []
+        for (const [cellIndex, cell] of row.children.entries()) {
+          const cellPath = `${path}/children/${rowIndex}/children/${cellIndex}`
+          const colspan = cell.colspan ?? 1, rowspan = cell.rowspan ?? 1
+          if (!Number.isSafeInteger(colspan) || !Number.isSafeInteger(rowspan)) {
+            issue(cellPath, 'table.span', 'Cell spans must be safe positive integers.')
+            continue
+          }
+          while (spans[index] && spans[index]!.from <= column) { column = Math.max(column, spans[index]!.to); index++ }
+          const end = column + colspan
+          const overlap = spans[index] && spans[index]!.from < end
+          if (overlap) issue(cellPath, 'table.overlap', 'A cell cannot overlap a cell spanning from an earlier row.')
+          if (rowIndex + rowspan > table.children.length) issue(`${cellPath}/rowspan`, 'table.span', 'A row span cannot extend beyond the table rows.')
+          if (!Number.isSafeInteger(end) || table.columnWidths && end > table.columnWidths.length) issue(`${cellPath}/colspan`, 'table.span', 'A cell span cannot extend beyond the declared table columns.')
+          if (rowspan > 1 && !overlap) added.push({ from: column, to: end, until: rowIndex + rowspan })
+          column = end
+        }
+        const width = spans.reduce((width, span) => Math.max(width, span.to), column)
+        spans.push(...added)
+        return width
+      })
+      if (table.headerColumns !== undefined && widths.some(width => table.headerColumns! > width)) issue(`${path}/headerColumns`, 'table.header', 'Header columns cannot exceed table columns.')
+      if (table.columnWidths && widths.some(width => width !== table.columnWidths!.length)) issue(`${path}/columnWidths`, 'table.widths', 'Column widths must match the logical table columns.')
+    }
+    if ('children' in node && Array.isArray(node.children)) for (const [index, child] of node.children.entries()) if (isRecord(child) && typeof child.id === 'string') rich(child as unknown as RichTextNode, `${path}/children/${index}`, collected)
+    if (node.type === 'extension' && 'fallback' in node && Array.isArray(node.fallback)) node.fallback.forEach((child, index) => rich(child as RichTextNode, `${path}/fallback/${index}`, collected))
+  }
+  const schema = (value: JsonSchemaLike, parameters: unknown, path: string) => {
+    const result = validateDocumentParameters(value, parameters)
+    for (const error of result.issues) issue(path + error.path, result.available ? 'parameters.schema' : 'parameters.schema-unavailable', error.message)
+  }
+  for (const [id, block] of Object.entries(doc.blocks)) {
+    const path = at('/blocks', id)
+    if (block.type === 'text') {
+      const collected = new Set<string>(); richIds.set(id, collected)
+      block.content.forEach((node, index) => rich(node, `${path}/content/${index}`, collected))
+      for (const [index, item] of (block.reveal?.order ?? []).entries()) if (!collected.has(item)) issue(`${path}/reveal/order/${index}`, 'reveal.target', 'Reveal items must name rich-text nodes of this block.')
+    } else if (block.type === 'image') {
+      if (block.assetId !== undefined && reference(doc.assets, block.assetId, `${path}/assetId`, 'asset') && doc.assets[block.assetId]!.kind !== 'image') issue(`${path}/assetId`, 'asset.kind', 'An image block requires an image asset.')
+    } else if (block.type === 'component') {
+      if (reference(doc.definitions, block.definitionId, `${path}/definitionId`, 'definition')) schema(doc.definitions[block.definitionId]!.parameterSchema, block.parameters, `${path}/parameters`)
+    } else if (block.type === 'code') {
+      if (block.highlight && block.origin?.highlightRegions) issue(`${path}/highlight`, 'code.highlight-owner', 'Choose authored line numbers or tracked source regions, not both.')
+      for (const [field, values] of [['highlight', block.highlight], ['origin/highlightRegions', block.origin?.highlightRegions]] as const) for (const step of Object.keys(values ?? {})) {
+        if (reference(doc.steps, step, `${path}/${field}/${escape(step)}`, 'step') && doc.steps[step]!.sectionId !== sectionOf.get(id)) issue(`${path}/${field}/${escape(step)}`, 'code.highlight-section', 'A code highlight must belong to a step of its own section.')
+      }
+      for (const [index, variant] of (block.variants ?? []).entries()) identify(variant.id, `${path}/variants/${index}/id`)
+    } else if (block.type === 'container') {
+      if (block.properties.columnWidths && block.properties.columnWidths.length !== block.children.length) issue(`${path}/properties/columnWidths`, 'container.columns', 'Column widths must match the child count.')
+      if (block.layout === 'tabs' && block.properties.tabTitles && block.properties.tabTitles.length !== block.children.length) issue(`${path}/properties/tabTitles`, 'container.tabs', 'Tab titles must match the child count.')
+    }
+  }
+  for (const [id, definition] of Object.entries(doc.definitions)) {
+    const states = new Set<string>()
+    for (const [index, state] of definition.states.entries()) {
+      if (states.has(state.id)) issue(at('/definitions', id) + `/states/${index}/id`, 'state.duplicate', 'Definition state IDs must be unique within the definition.')
+      states.add(state.id)
+    }
+  }
+  const effectiveVisuals = (id: string, visiting = new Set<string>()): Map<string, TeachingDocument['steps'][string]['visuals'][number]> => {
+    if (visiting.has(id) || !own(doc.steps, id)) return new Map()
+    visiting.add(id)
+    const step = doc.steps[id]!
+    const result = step.inherits ? effectiveVisuals(step.inherits, visiting) : new Map<string, TeachingDocument['steps'][string]['visuals'][number]>()
+    for (const visual of step.visuals) result.set(visual.blockId, { ...result.get(visual.blockId), ...visual, parameters: { ...result.get(visual.blockId)?.parameters, ...visual.parameters } })
+    return result
+  }
+  const orderedSteps = new Set<string>()
+  for (const [id, section] of Object.entries(doc.sections)) for (const [index, stepId] of section.stepOrder.entries()) {
+    const path = at('/sections', id) + `/stepOrder/${index}`
+    if (orderedSteps.has(stepId)) issue(path, 'step.owner', 'A step belongs to one section order.')
+    orderedSteps.add(stepId)
+    if (reference(doc.steps, stepId, path, 'step') && doc.steps[stepId]!.sectionId !== id) issue(path, 'step.section', 'A step must belong to the section that orders it.')
+  }
+  for (const [id, step] of Object.entries(doc.steps)) {
+    const path = at('/steps', id)
+    if (!orderedSteps.has(id)) issue(path, 'step.orphan', 'Every step must appear in its section stepOrder.')
+    reference(doc.sections, step.sectionId, `${path}/sectionId`, 'section')
+    const visuals = new Set<string>()
+    for (const [index, visual] of step.visuals.entries()) {
+      const location = `${path}/visuals/${index}`
+      if (visuals.has(visual.blockId)) issue(`${location}/blockId`, 'visual.duplicate', 'A step has one override per block.')
+      visuals.add(visual.blockId)
+      if (!reference(doc.blocks, visual.blockId, `${location}/blockId`, 'block')) continue
+      if (sectionOf.get(visual.blockId) !== step.sectionId) issue(`${location}/blockId`, 'visual.section', 'Visual state must target a block owned by the same section.')
+      const actual = effectiveVisuals(id).get(visual.blockId)!
+      const block = doc.blocks[visual.blockId]!
+      if (block.type === 'component') {
+        const definition = doc.definitions[block.definitionId]
+        if (definition) {
+          if (actual.parameters) schema(definition.parameterSchema, { ...block.parameters, ...actual.parameters }, `${location}/parameters`)
+          const state = actual.state === undefined ? undefined : definition.states.find(state => state.id === actual.state)
+          if (actual.state !== undefined && !state) issue(`${location}/state`, 'state.missing', 'The component definition does not declare this state.')
+          if (state?.parameterSchema) schema(state.parameterSchema, { ...block.parameters, ...actual.parameters }, `${location}/parameters`)
+        }
+      } else if (visual.state !== undefined) issue(`${location}/state`, 'state.unsupported', 'Named animation states require a component definition.')
+    }
+    for (const [index, narration] of step.narrationIds.entries()) reference(doc.narrations, narration, `${path}/narrationIds/${index}`, 'narration')
+    const seen = new Set<string>([id]); let inherited = step.inherits
+    while (inherited !== undefined) {
+      if (seen.has(inherited)) { issue(`${path}/inherits`, 'step.cycle', 'Step inheritance cannot contain a cycle.'); break }
+      seen.add(inherited)
+      if (!reference(doc.steps, inherited, `${path}/inherits`, 'step')) break
+      if (doc.steps[inherited]!.sectionId !== step.sectionId) { issue(`${path}/inherits`, 'step.section', 'Inherited steps must belong to the same section.'); break }
+      inherited = doc.steps[inherited]!.inherits
+    }
+  }
+  const cues = new Set<string>()
+  for (const [id, narration] of Object.entries(doc.narrations)) if (narration.provenance) {
+    const path = at('/narrations', id) + '/provenance/assetId'
+    if (reference(doc.assets, narration.provenance.assetId, path, 'asset') && doc.assets[narration.provenance.assetId]!.kind !== 'audio') issue(path, 'asset.kind', 'Transcription provenance requires the original audio asset.')
+  }
+  for (const [id, narration] of Object.entries(doc.narrations)) for (const [index, node] of narration.content.entries()) if (node.type === 'cue') {
+    const path = at('/narrations', id) + `/content/${index}`
+    identify(node.id, `${path}/id`); cues.add(node.id)
+    if (node.target) reference(doc.blocks, node.target.blockId, `${path}/target/blockId`, 'block')
+    if (node.parameters && ['pauseMs', 'durationMs', 'delayMs'].some(key => own(node.parameters!, key))) issue(`${path}/parameters`, 'production.owner', 'Cue timing belongs to production.cueTimings.')
+  }
+  const voice = (production: TeachingDocument['production']['defaults'], path: string) => {
+    const source = production.voiceSource
+    if (source?.type === 'recording' && reference(doc.assets, source.assetId, `${path}/voiceSource/assetId`, 'asset') && !['audio', 'video'].includes(doc.assets[source.assetId]!.kind)) issue(`${path}/voiceSource/assetId`, 'asset.kind', 'Recorded speech requires audio or video.')
+    if (source?.type === 'recording' && source.sourceRange && source.sourceRange.endMs <= source.sourceRange.startMs) issue(`${path}/voiceSource/sourceRange`, 'media.range', 'A recording range must end after it starts.')
+  }
+  voice(doc.production.defaults, '/production/defaults')
+  for (const [id, override] of Object.entries(doc.production.sectionOverrides ?? {})) { reference(doc.sections, id, at('/production/sectionOverrides', id), 'section'); voice(override, at('/production/sectionOverrides', id)) }
+  for (const [id, override] of Object.entries(doc.production.stepOverrides)) { reference(doc.steps, id, at('/production/stepOverrides', id), 'step'); voice(override, at('/production/stepOverrides', id)) }
+  for (const id of Object.keys(doc.production.narrationOverrides ?? {})) reference(doc.narrations, id, at('/production/narrationOverrides', id), 'narration')
+  for (const id of Object.keys(doc.production.cueTimings ?? {})) if (!cues.has(id)) issue(at('/production/cueTimings', id), 'cue.missing', 'Cue timing must reference an authored narration cue.')
+  for (const [stepId, timing] of Object.entries(doc.production.captionTimings ?? {})) {
+    const step = doc.steps[stepId]
+    const stale = !step || JSON.stringify(step.narrationIds) !== JSON.stringify(timing.narrationIds) || captionSourceFingerprint(doc, stepId) !== timing.sourceFingerprint
+    const problem = stale ? 'caption-source-changed' : captionTimingProblem(timing, stepCaptionText(doc, stepId))
+    if (problem) issue(at('/production/captionTimings', stepId), 'caption.timing-stale', 'Manual caption timing requires review: ' + problem, 'warning')
+  }
+  for (const [index, clip] of doc.production.mediaClips.entries()) {
+    const path = `/production/mediaClips/${index}`
+    identify(clip.id, `${path}/id`)
+    if (reference(doc.assets, clip.assetId, `${path}/assetId`, 'asset') && !['audio', 'video'].includes(doc.assets[clip.assetId]!.kind)) issue(`${path}/assetId`, 'asset.kind', 'A media clip requires audio or video.')
+    reference(doc.steps, clip.attachment.stepId, `${path}/attachment/stepId`, 'step')
+    if (clip.sourceRange.endMs <= clip.sourceRange.startMs) issue(`${path}/sourceRange`, 'media.range', 'A media range must end after it starts.')
+  }
+  const lecture = doc.metadata.renderers?.lecture
+  if (lecture && ['voice', 'gap', 'script'].some(key => own(lecture, key))) issue('/metadata/renderers/lecture', 'production.owner', 'Voice, narration sources and playback timing belong only to production and narration entities.')
+  const textTargets = new Set([...richIds.values()].flatMap(values => [...values]))
+  for (const id of doc.sectionOrder) textTargets.add(`page:${id}`)
+  for (const [id, block] of Object.entries(doc.blocks)) if (block.type === 'code' && block.value !== undefined) textTargets.add(id)
+  for (const [id, thread] of Object.entries(doc.comments ?? {})) {
+    const path = at('/comments', id)
+    if (id !== thread.id) issue(`${path}/id`, 'id.key', 'A thread ID must match its map key.')
+    identify(thread.id, `${path}/id`)
+    for (const edge of ['from', 'to'] as const) if (thread.anchor && !textTargets.has(thread.anchor[edge].blockId)) issue(`${path}/anchor/${edge}/blockId`, 'comment.target', 'A comment anchor must name a stable rich-text node or section title.')
+    for (const [index, comment] of thread.comments.entries()) {
+      identify(comment.id, `${path}/comments/${index}/id`)
+      comment.content?.forEach((node, child) => rich(node, `${path}/comments/${index}/content/${child}`, new Set()))
+    }
+  }
+  return issues.some(issue => issue.severity === 'error') ? { issues } : { document: doc, issues }
+}
+
+type JsonSchemaLike = TeachingDocument['definitions'][string]['parameterSchema']

package/src/durations.ts

@@ -0,0 +1,7 @@
+/** A duration as authors write one (`{cue}` `pause`, `:durations:`): `1.2` and `1.2s` are seconds, `800ms` milliseconds; in milliseconds. */
+export function parseDuration(value: string): number | undefined {
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s)?$/.exec(value.trim())
+  if (!match) return undefined
+  const n = Number(match[1])
+  return Math.round(match[2] === 'ms' ? n : n * 1000)
+}

package/src/errors.ts

@@ -5,3 +5,11 @@ export function errorMessage(error: unknown): string {
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
+
+/** What a preview needs (the viewer app, the document's code) is still being built: ask again later; not a failure. */
+export class PreviewPreparing extends Error {
+  constructor(message = 'preview-preparing') {
+    super(message)
+    this.name = 'PreviewPreparing'
+  }
+}

package/src/execution.ts

@@ -1,4 +1,4 @@
-import type { RunResult } from './contracts.ts'
+import type { RunResult } from './contracts/execution.ts'
 
 const ALIASES: Record<string, string> = {
   py: 'python',
@@ -19,3 +19,7 @@ export function failedRun(executorId: string, stderr: string, durationMs = 0): R
 }
 
 export const CREDENTIAL_VARIABLE = /_(?:KEY|TOKEN|SECRET|PASSWORD|APPID)$/i
+
+export function environmentExecutor(name: string): string {
+  return `presmium.env.${name}`
+}