@gpdoc/filekit 1.23.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gpdoc/filekit",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "type": "module",
   "description": "Headless GPDoc file format detection, validation, and text conversion",
   "repository": "https://github.com/repetere/gpdoc.git",
@@ -10,13 +10,17 @@
   "publishConfig": {
     "access": "public"
   },
-  "exports": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./markdown-edit": "./src/markdown-edit.js"
+  },
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
     "fflate": "^0.8.2",
-    "js-yaml": "^4.1.0",
-    "marked": "^12.0.0"
+    "js-yaml": "4.3.2",
+    "marked": "^12.0.0",
+    "yaml": "2.9.0"
   }
 }

package/src/index.js

@@ -4,6 +4,9 @@ import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
 import yaml from 'js-yaml';
 import { marked } from 'marked';
 
+// @spec CLI-TERMINAL-095, CLI-TERMINAL-096, CLI-TERMINAL-097, CLI-TERMINAL-098, CLI-TERMINAL-101
+export { prepareMarkdownEdit, createMarkdownDraftPolicy, serializeMarkdownEdit } from './markdown-edit.js';
+
 const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.gpdoc.md']);
 const HTML_EXTENSIONS = new Set(['.html', '.htm']);
 const TEXT_EXTENSIONS = new Set(['.txt', '.text']);
@@ -13,6 +16,52 @@ const FRONT_MATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
 const MAX_URL_RESPONSE_BYTES = 10 * 1024 * 1024;
 const URL_TIMEOUT_MS = 15_000;
 
+export const GPDOC_PAGE_BREAK = '<div style="page-break-after: always;"></div>';
+
+export function resolveSlideDelimiter(metadata = {}) {
+  const configured = typeof metadata?.slideDelimiter === 'string'
+    ? metadata.slideDelimiter.trim()
+    : '';
+  return configured || GPDOC_PAGE_BREAK;
+}
+
+export function splitMarkdownSlides(markdown, delimiter = GPDOC_PAGE_BREAK) {
+  // @spec FILE-MODEL-006, FILE-MODEL-007, FILE-MODEL-008, FILE-MODEL-009
+  const boundary = typeof delimiter === 'string' && delimiter.trim()
+    ? delimiter.trim()
+    : GPDOC_PAGE_BREAK;
+  const slides = [];
+  let current = [];
+  let fence = null;
+  for (const line of String(markdown ?? '').replace(/\r\n/g, '\n').split('\n')) {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/u)?.[1] ?? null;
+    if (marker) {
+      if (!fence) fence = { character: marker[0], length: marker.length };
+      else if (marker[0] === fence.character && marker.length >= fence.length) fence = null;
+      current.push(line);
+      continue;
+    }
+    if (!fence && line.trim() === boundary) {
+      slides.push(current.join('\n').trim());
+      current = [];
+      continue;
+    }
+    current.push(line);
+  }
+  slides.push(current.join('\n').trim());
+  return slides;
+}
+
+export function joinMarkdownSlides(slides, delimiter = GPDOC_PAGE_BREAK) {
+  // @spec FILE-MODEL-007, FILE-MODEL-008, FILE-MODEL-009
+  const boundary = typeof delimiter === 'string' && delimiter.trim()
+    ? delimiter.trim()
+    : GPDOC_PAGE_BREAK;
+  return (Array.isArray(slides) ? slides : [slides ?? ''])
+    .map((slide) => String(slide ?? '').trim())
+    .join(`\n\n${boundary}\n\n`);
+}
+
 export class FileKitError extends Error {
   constructor(code, message) {
     super(message);
@@ -284,8 +333,15 @@ function parseGpdocJson(source) {
   if (!isManagedMetadata(json) || !isPlainObject(json.content)) {
     throw new FileKitError('INVALID_GPDOC', 'Managed GPDoc metadata must include id, filename, and a supported filetype.');
   }
+  if (json.filetype === 'slides' && Array.isArray(json.content.slides)) {
+    return {
+      metadata: clone(json),
+      body: joinMarkdownSlides(json.content.slides, resolveSlideDelimiter(json)),
+      slides: json.content.slides.map((slide) => String(slide ?? '')),
+    };
+  }
   if (typeof json.content.document !== 'string') {
-    throw new FileKitError('INVALID_GPDOC', 'This CLI release supports document content only.');
+    throw new FileKitError('INVALID_GPDOC', 'This GPDoc file does not contain supported document or slide content.');
   }
   return { metadata: clone(json), body: json.content.document };
 }
@@ -306,11 +362,15 @@ export function readDocument(source, filePath = '') {
   }
   if (format === 'json') {
     const parsed = parseGpdocJson(source);
-    return { format: 'gpdoc-json', managed: true, filetype: parsed.metadata.filetype, title: parsed.metadata.filename, body: parsed.body, metadata: parsed.metadata, warnings: [] };
+    return { format: 'gpdoc-json', managed: true, filetype: parsed.metadata.filetype, title: parsed.metadata.filename, body: parsed.body, slides: parsed.slides, metadata: parsed.metadata, warnings: [] };
   }
   const parsed = parseManagedMarkdown(String(source));
   if (parsed) {
-    return { format: 'gpdoc-markdown', managed: true, filetype: parsed.metadata.filetype, title: parsed.metadata.filename, body: parsed.body, metadata: parsed.metadata, warnings: [] };
+    const document = { format: 'gpdoc-markdown', managed: true, filetype: parsed.metadata.filetype, title: parsed.metadata.filename, body: parsed.body, metadata: parsed.metadata, warnings: [] };
+    if (parsed.metadata.filetype === 'slides') {
+      document.slides = splitMarkdownSlides(parsed.body, resolveSlideDelimiter(parsed.metadata));
+    }
+    return document;
   }
   return { format: 'markdown', managed: false, filetype: 'document', title: filenameTitle(filePath), body: String(source), warnings: [] };
 }
@@ -327,6 +387,22 @@ export function createManagedDocument(title = 'Untitled', body = '') {
   };
 }
 
+export function createManagedSlides(title = 'Untitled', slides = ['# Slide 1']) {
+  // @spec CLI-074, FILE-MODEL-011
+  const now = new Date().toISOString();
+  const normalizedSlides = (Array.isArray(slides) && slides.length ? slides : ['# Slide 1'])
+    .map((slide) => String(slide ?? ''));
+  return {
+    id: `file_${randomUUID()}`,
+    filename: title,
+    filetype: 'slides',
+    slideDelimiter: GPDOC_PAGE_BREAK,
+    created: now,
+    updated: now,
+    content: { slides: normalizedSlides },
+  };
+}
+
 export function serializeManagedMarkdown(metadata, body) {
   // @spec CLI-001, CLI-066
   // Markdown has a separate body. `content.document` is reserved for GPDoc JSON.
@@ -347,7 +423,16 @@ function markdownToText(markdown) {
 export function convertDocument(document, targetFormat) {
   const target = String(targetFormat).toLowerCase();
   const metadata = document.managed ? clone(document.metadata) : createManagedDocument(document.title, document.body);
-  metadata.content = { document: document.body };
+  if (document.filetype === 'slides') {
+    metadata.slideDelimiter = resolveSlideDelimiter(metadata);
+    metadata.content = {
+      slides: Array.isArray(document.slides)
+        ? document.slides.map((slide) => String(slide ?? ''))
+        : splitMarkdownSlides(document.body, metadata.slideDelimiter),
+    };
+  } else {
+    metadata.content = { document: document.body };
+  }
   if (target === 'gpdoc') return serializeManagedMarkdown(metadata, document.body);
   if (target === 'markdown' || target === 'md') return document.body;
   if (target === 'html') return `<!doctype html>\n<html><head><meta charset="utf-8"><title>${escapeHtml(document.title)}</title></head><body>\n${marked.parse(document.body)}\n</body></html>\n`;

package/src/markdown-edit.js

@@ -0,0 +1,523 @@
+import { CST, Lexer } from 'yaml';
+import yaml from 'js-yaml';
+
+const MAX_BYTES = 1_048_576;
+const MAX_METADATA_DEPTH = 40;
+// Allow the document/envelope wrapper and transient scalar frames in the pinned
+// loader. yamlValue enforces the exact metadata-root depth, including implicit maps.
+const MAX_YAML_PARSER_FRAMES = MAX_METADATA_DEPTH + 4;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const FILE_TYPES = new Set(['document', 'notebook', 'slides', 'script', 'spreadsheet', 'drawing']);
+const MESSAGES = Object.freeze({
+  UNSUPPORTED_FORMAT: 'Terminal editing supports Markdown documents only.',
+  INVALID_ENCODING: 'The document must contain valid UTF-8 and Unicode text.',
+  INVALID_GPDOC: 'The managed envelope cannot be preserved safely. Use explicit conversion to change its format.',
+  FILE_TOO_LARGE: 'The complete encoded document exceeds the 1 MiB limit.',
+  PROTECTED_METADATA: 'Review or live metadata requires read-only Preview.',
+});
+const envelopes = new WeakMap();
+
+/** @template T @typedef {{ok: true, value: T} | {ok: false, error: {code: string, message: string}}} Result */
+/**
+ * @typedef {Readonly<{body: string, metadata: Readonly<Record<string, unknown>>,
+ * editable: boolean, format: string, byteLength: number,
+ * projectedByteLength: (body: string) => Result<number>}>} EditingEnvelope
+ */
+
+// Internal errors never retain parser messages, source excerpts, or stacks.
+function refuse(code) { throw code; }
+function failure(code) {
+  const known = Object.hasOwn(MESSAGES, code) ? code : 'INVALID_GPDOC';
+  return { ok: false, error: { code: known, message: MESSAGES[known] } };
+}
+function result(operation) {
+  try { return { ok: true, value: operation() }; }
+  catch (code) { return failure(typeof code === 'string' ? code : 'INVALID_GPDOC'); }
+}
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function unicode(text) {
+  if (typeof text !== 'string') refuse('INVALID_ENCODING');
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(++i);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) refuse('INVALID_ENCODING');
+    } else if (code >= 0xdc00 && code <= 0xdfff) refuse('INVALID_ENCODING');
+  }
+}
+function safeKey(key) {
+  unicode(key);
+  if (FORBIDDEN_KEYS.has(key)) refuse('INVALID_GPDOC');
+}
+function freeze(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+// @spec CLI-TERMINAL-099, CLI-TERMINAL-136, CLI-TERMINAL-137
+// Lexer tokens distinguish syntax from
+// comments/quoted/block text; this recognizes root keys without constructing the
+// offending value tree. The scan keeps counters and at most three key names.
+function hasManagedRootKey(raw) {
+  const keys = new Set();
+  const legacy = raw.trimStart().startsWith('{');
+  let root;
+  let rootIndent;
+  let flowDepth = 0;
+  let column = 0;
+  let indent = 0;
+  let lineStart = true;
+  let indentationEnded = false;
+  let scalarNext = false;
+  let flowKey = true;
+  let explicitKey = false;
+  let pendingKey;
+  let block;
+  const commitKey = () => {
+    if (['gpdoc_metadata', 'filetype', 'id', 'filename'].includes(pendingKey)) keys.add(pendingKey);
+    pendingKey = undefined;
+    return keys.has('gpdoc_metadata') || (legacy && (keys.has('filetype') || (keys.has('id') && keys.has('filename'))));
+  };
+  for (const source of new Lexer().lex(raw)) {
+    if (!scalarNext && source === CST.SCALAR) { scalarNext = true; continue; }
+    if (!scalarNext && [CST.DOCUMENT, CST.FLOW_END].includes(source)) continue;
+    const type = scalarNext ? 'scalar' : CST.tokenType(source);
+    scalarNext = false;
+    if (type === 'doc-end') return false;
+    const startColumn = column;
+    const atLineStart = lineStart;
+    const lastNewline = source.lastIndexOf('\n');
+    column = lastNewline < 0 ? column + source.length : source.length - lastNewline - 1;
+    if (type === 'newline') { indent = 0; lineStart = true; indentationEnded = false; continue; }
+    if (type === 'space') { if (lineStart && !indentationEnded) indent += source.length; continue; }
+    if (['anchor', 'tag'].includes(type)) { indentationEnded = true; continue; }
+    if (['comment', 'directive-line', 'byte-order-mark', 'doc-start'].includes(type)) continue;
+    indentationEnded = true;
+    lineStart = lastNewline >= 0 && column === 0;
+    const scalar = ['scalar', 'single-quoted-scalar', 'double-quoted-scalar'].includes(type);
+    if (!root) {
+      rootIndent = indent;
+      if (type === 'flow-map-start') root = 'flow';
+      else if (scalar || type === 'explicit-key-ind') root = 'block';
+      else return false; // A sequence or literal root cannot own managed metadata.
+    }
+    const keyPosition = root === 'flow' ? flowDepth === 1 && flowKey
+      : flowDepth === 0 && ((atLineStart && indent === rootIndent) || explicitKey);
+    if (type === 'explicit-key-ind' && flowDepth === 0 && indent === rootIndent) {
+      explicitKey = true;
+      continue;
+    }
+    if (type === 'block-scalar-header') {
+      block = { source, key: keyPosition, explicit: explicitKey, indent: rootIndent };
+      pendingKey = undefined;
+      continue;
+    }
+    if (scalar) {
+      if (block?.key || (!block && keyPosition)) {
+        const token = block ? {
+          type: 'block-scalar', source, indent: block.indent, offset: 0,
+          props: [{ type: 'block-scalar-header', source: block.source, offset: 0, indent: block.indent },
+            { type: 'newline', source: '\n', offset: 0, indent: block.indent }],
+        } : { type, source, offset: 0, indent: startColumn };
+        try { pendingKey = CST.resolveAsScalar(token)?.value; }
+        catch { pendingKey = undefined; }
+      }
+      if ((explicitKey || block?.explicit) && commitKey()) return true;
+      block = undefined;
+      explicitKey = false;
+      continue;
+    }
+    if (type === 'map-value-ind' && (root === 'block' ? flowDepth === 0 : flowDepth === 1)) {
+      if (commitKey()) return true;
+      flowKey = false;
+      explicitKey = false;
+    }
+    if (root === 'flow' && flowDepth === 1 && ['comma', 'flow-map-end'].includes(type)) {
+      if (commitKey()) return true;
+      flowKey = true;
+    }
+    if (type === 'flow-map-start' || type === 'flow-seq-start') { flowDepth++; pendingKey = undefined; }
+    else if (type === 'flow-map-end' || type === 'flow-seq-end') flowDepth = Math.max(0, flowDepth - 1);
+  }
+  // A missing flow terminator is a syntax error, not permission to demote a
+  // recognized managed key to editable plain text.
+  return root === 'flow' && flowDepth === 1 && flowKey && commitKey();
+}
+
+// @spec CLI-TERMINAL-099, CLI-TERMINAL-136, CLI-TERMINAL-137
+// Construct only values, never a full CST/AST alongside them. Lexical rejection
+// prevents alias expansion; the listener bounds parser frames before descent.
+function boundedYamlDocument(raw) {
+  let scalarNext = false;
+  for (const source of new Lexer().lex(raw)) {
+    if (scalarNext) { scalarNext = false; continue; }
+    if (source === CST.SCALAR) { scalarNext = true; continue; }
+    const type = CST.tokenType(source);
+    if (type === 'alias') refuse('INVALID_GPDOC');
+    if (type === 'directive-line' && !/^%YAML[ \t]+1\.2[ \t]*(?:#.*)?$/.test(source)) refuse('INVALID_GPDOC');
+  }
+  const frames = [];
+  const nextIndicator = (state) => {
+    let offset = state.position;
+    while (offset < state.input.length) {
+      if (' \t\r\n'.includes(state.input[offset])) offset++;
+      else if (state.input[offset] === '#') {
+        while (offset < state.input.length && state.input[offset] !== '\n') offset++;
+      } else break;
+    }
+    return state.input[offset];
+  };
+  return yaml.load(raw, {
+    schema: yaml.JSON_SCHEMA, json: false,
+    onWarning: () => refuse('INVALID_GPDOC'),
+    listener(event, state) {
+      if (event === 'open') {
+        if (frames.length >= MAX_YAML_PARSER_FRAMES) refuse('INVALID_GPDOC');
+        const parent = frames.at(-1);
+        frames.push({ value: parent?.expectValue === true, expectValue: false, nonStringKey: false, keyCandidate: undefined, distinctKeys: false });
+        if (parent) parent.expectValue = false;
+        return;
+      }
+      const frame = frames.pop();
+      // A wrapper frame returns the very same collection as its only child.
+      // An actual complex key is never the mapping that contains that key.
+      if (state.kind === 'mapping' && frame.nonStringKey
+        && (frame.distinctKeys || frame.keyCandidate !== state.result)) refuse('INVALID_GPDOC');
+      const parent = frames.at(-1);
+      if (!parent) return;
+      const indicator = nextIndicator(state);
+      if (indicator === ':') {
+        if (typeof state.result !== 'string') refuse('INVALID_GPDOC');
+        safeKey(state.result);
+        parent.expectValue = true;
+      } else if (!frame.value && typeof state.result !== 'string') {
+        // Bare flow-map and explicit block keys can omit the value indicator.
+        // A sequence/scalar parent ignores this marker when its frame closes.
+        if (parent.nonStringKey && parent.keyCandidate !== state.result) parent.distinctKeys = true;
+        if (!parent.nonStringKey) parent.keyCandidate = state.result;
+        parent.nonStringKey = true;
+      }
+    },
+  });
+}
+
+// @spec CLI-TERMINAL-098, CLI-TERMINAL-099, CLI-TERMINAL-137
+// Strict JSON grammar with decoded-key uniqueness and the original body token span.
+function parseJson(source) {
+  let offset = 0;
+  let bodySpan;
+  const number = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+  const whitespace = () => { while (' \t\r\n'.includes(source[offset]) && offset < source.length) offset++; };
+  const string = () => {
+    const start = offset;
+    if (source[offset++] !== '"') refuse('INVALID_GPDOC');
+    while (offset < source.length) {
+      const character = source[offset++];
+      if (character === '\\') { offset++; continue; }
+      if (character === '"') {
+        let value;
+        try { value = JSON.parse(source.slice(start, offset)); }
+        catch { refuse('INVALID_GPDOC'); }
+        unicode(value);
+        return value;
+      }
+    }
+    refuse('INVALID_GPDOC');
+  };
+  function value(depth, path) {
+    if (depth > MAX_METADATA_DEPTH) refuse('INVALID_GPDOC');
+    whitespace();
+    const start = offset;
+    if (source[offset] === '"') {
+      const parsed = string();
+      if (path.length === 2 && path[0] === 'content' && path[1] === 'document') bodySpan = [start, offset];
+      return parsed;
+    }
+    if (source[offset] === '{' || source[offset] === '[') {
+      const object = source[offset++] === '{';
+      const end = object ? '}' : ']';
+      const output = object ? {} : [];
+      const keys = new Set();
+      whitespace();
+      if (source[offset] === end) { offset++; return output; }
+      while (offset < source.length) {
+        let key = output.length;
+        if (object) {
+          whitespace();
+          key = string();
+          safeKey(key);
+          if (keys.has(key)) refuse('INVALID_GPDOC');
+          keys.add(key);
+          whitespace();
+          if (source[offset++] !== ':') refuse('INVALID_GPDOC');
+        }
+        output[key] = value(depth + 1, [...path, key]);
+        whitespace();
+        const separator = source[offset++];
+        if (separator === end) return output;
+        if (separator !== ',') refuse('INVALID_GPDOC');
+      }
+      refuse('INVALID_GPDOC');
+    }
+    for (const [token, parsed] of [['true', true], ['false', false], ['null', null]]) {
+      if (source.startsWith(token, offset)) { offset += token.length; return parsed; }
+    }
+    number.lastIndex = offset;
+    const match = number.exec(source);
+    if (!match) refuse('INVALID_GPDOC');
+    offset = number.lastIndex;
+    const parsed = Number(match[0]);
+    if (!Number.isFinite(parsed)) refuse('INVALID_GPDOC');
+    return parsed;
+  }
+  const parsed = value(0, []);
+  whitespace();
+  if (offset !== source.length) refuse('INVALID_GPDOC');
+  return { parsed, bodySpan };
+}
+
+// @spec CLI-TERMINAL-099, CLI-TERMINAL-136, CLI-TERMINAL-137
+// Validate the data-only value tree in place, without making a second copy.
+function yamlValue(value, depth = 0) {
+  if (depth > MAX_METADATA_DEPTH) refuse('INVALID_GPDOC');
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'string') unicode(value);
+    else if (value !== null && typeof value !== 'boolean'
+      && !(typeof value === 'number' && Number.isFinite(value))) refuse('INVALID_GPDOC');
+    return value;
+  }
+  if (Array.isArray(value)) {
+    for (const child of value) yamlValue(child, depth + 1);
+    return value;
+  }
+  if (!record(value)) refuse('INVALID_GPDOC');
+  for (const [key, child] of Object.entries(value)) {
+    safeKey(key);
+    yamlValue(child, depth + 1);
+  }
+  return value;
+}
+
+function validateMetadata(metadata, json = false) {
+  if (!record(metadata) || typeof metadata.id !== 'string' || !metadata.id.trim()
+    || typeof metadata.filename !== 'string' || !metadata.filename.trim()
+    || !FILE_TYPES.has(metadata.filetype)
+    || (metadata.meta != null && !record(metadata.meta))) refuse('INVALID_GPDOC');
+  if (metadata.filetype !== 'document') refuse('UNSUPPORTED_FORMAT');
+  if (json) {
+    if (!record(metadata.content) || typeof metadata.content.document !== 'string') refuse('INVALID_GPDOC');
+  } else if (Object.hasOwn(metadata, 'content')) refuse('INVALID_GPDOC');
+}
+
+// @spec CLI-TERMINAL-102, CLI-TERMINAL-138
+function safeReview(review, collection) {
+  if (review == null) return true;
+  if (!record(review)) return false;
+  if (Object.keys(review).length === 0) return true;
+  const allowed = collection === 'threads' ? [collection, 'metadata'] : [collection, 'enabled'];
+  if (Object.keys(review).some((key) => !allowed.includes(key))) return false;
+  if (!record(review[collection]) || Object.keys(review[collection]).length) return false;
+  if (collection === 'items') return !Object.hasOwn(review, 'enabled') || typeof review.enabled === 'boolean';
+  if (!Object.hasOwn(review, 'metadata')) return true;
+  if (!record(review.metadata)) return false;
+  return Object.entries(review.metadata).every(([key, value]) => {
+    if (key === 'totalComments' || key === 'resolvedComments') return value === 0;
+    if (key === 'lastCommentAt') return value === null || isoDate(value);
+    return false;
+  });
+}
+function isoDate(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+  if (!match) return false;
+  const [year, month, day, hour, minute, second, zoneHour, zoneMinute] = match.slice(1).map((part) => Number(part ?? 0));
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const monthDays = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return month >= 1 && month <= 12 && day >= 1 && day <= monthDays[month - 1]
+    && hour < 24 && minute < 60 && second < 60
+    && zoneHour < 24 && zoneMinute < 60;
+}
+function safeProvenance(value) {
+  if (!record(value)) return false;
+  return Object.entries(value).every(([key, entry]) => {
+    if (['liveDocId', 'shareId', 'serverVersion', 'provider'].includes(key)) return typeof entry === 'string' && entry.trim().length > 0;
+    if (['lastSyncedAt', 'detachedAt'].includes(key)) return isoDate(entry);
+    return false;
+  });
+}
+function safeLive(live) {
+  if (live == null) return true;
+  if (!record(live)) return false;
+  const keys = Object.keys(live);
+  if (!keys.length) return true;
+  for (const [key, value] of Object.entries(live)) {
+    if (key === 'enabled') { if (value !== false) return false; }
+    else if (key === 'liveDocId') return false;
+    else if (key === 'status') { if (!['detached', 'archived'].includes(value)) return false; }
+    else if (key === 'detachedFrom') { if (!safeProvenance(value)) return false; }
+    else if (key === 'lastSyncedAt') { if (!isoDate(value)) return false; }
+    else if (['shareId', 'serverVersion', 'provider'].includes(key)) {
+      if (typeof value !== 'string' || !value.trim()) return false;
+    } else return false;
+  }
+  // A share id by itself is provenance. Other nonempty descriptors must explicitly detach.
+  return keys.every((key) => key === 'shareId') || live.enabled === false
+    || live.status === 'detached' || live.status === 'archived';
+}
+function editableMetadata(metadata) {
+  const meta = metadata.meta;
+  if (!meta) return true;
+  if (meta.liveDocId != null && meta.liveDocId !== '') return false;
+  if (meta.shared != null && meta.shared !== false) return false;
+  return safeReview(meta.comments, 'threads') && safeReview(meta.suggestions, 'items') && safeLive(meta.live);
+}
+
+// @spec CLI-TERMINAL-023, CLI-TERMINAL-096, CLI-TERMINAL-097, CLI-TERMINAL-098, CLI-TERMINAL-136
+function parseSource(source, formatHint) {
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
+  const text = source.slice(bom.length);
+  if (formatHint === 'gpdoc-json') {
+    const { parsed: metadata, bodySpan } = parseJson(text);
+    validateMetadata(metadata, true);
+    if (!bodySpan) refuse('INVALID_GPDOC');
+    const body = metadata.content.document;
+    delete metadata.content.document;
+    return { format: 'gpdoc-json', body, metadata, protectedValue: metadata,
+      prefix: bom + text.slice(0, bodySpan[0]), suffix: text.slice(bodySpan[1]), token: text.slice(...bodySpan) };
+  }
+  const plain = { format: 'markdown', body: text, metadata: {}, protectedValue: {}, prefix: bom, suffix: '', token: text };
+  const opening = /^---[ \t]*\r?\n/.exec(text);
+  if (!opening) return plain;
+  const rest = text.slice(opening[0].length);
+  const closing = /^---[ \t]*(?:\r?\n|$)/m.exec(rest);
+  const raw = closing ? rest.slice(0, closing.index) : rest;
+  if (!hasManagedRootKey(raw)) return plain;
+  if (!closing || !closing[0].endsWith('\n')) refuse('INVALID_GPDOC');
+  const root = boundedYamlDocument(raw);
+  if (!record(root)) refuse('INVALID_GPDOC');
+  const managed = Object.hasOwn(root, 'gpdoc_metadata');
+  let metadata;
+  let protectedValue;
+  if (managed) {
+    // The metadata root is depth zero, independent of its YAML envelope wrapper.
+    protectedValue = {};
+    for (const [key, child] of Object.entries(root)) {
+      safeKey(key);
+      protectedValue[key] = yamlValue(child);
+    }
+    metadata = protectedValue.gpdoc_metadata;
+  } else {
+    metadata = parseJson(raw).parsed;
+    protectedValue = metadata;
+  }
+  validateMetadata(metadata);
+  const bodyOffset = opening[0].length + closing.index + closing[0].length;
+  const body = text.slice(bodyOffset);
+  return { format: 'gpdoc-markdown', body, metadata, protectedValue,
+    prefix: bom + text.slice(0, bodyOffset), suffix: '', token: body };
+}
+
+// @spec CLI-TERMINAL-080, CLI-TERMINAL-081, CLI-TERMINAL-137
+function projectedSize(state, body) {
+  unicode(body);
+  // This cheap lower bound avoids allocating an encoded copy of oversized input.
+  if (body.length > MAX_BYTES) refuse('FILE_TOO_LARGE');
+  if (body === state.body) return state.byteLength;
+  let size = state.overhead + Buffer.byteLength(body, 'utf8');
+  if (state.format === 'gpdoc-json') {
+    size += 2; // The two JSON string quotes.
+    for (let i = 0; i < body.length; i++) {
+      const code = body.charCodeAt(i);
+      if (code === 34 || code === 92 || [8, 9, 10, 12, 13].includes(code)) size++;
+      else if (code < 32) size += 5;
+    }
+  }
+  if (size > MAX_BYTES) refuse('FILE_TOO_LARGE');
+  return size;
+}
+
+// @spec CLI-TERMINAL-095, CLI-TERMINAL-096, CLI-TERMINAL-099, CLI-TERMINAL-102, CLI-TERMINAL-136, CLI-TERMINAL-137, CLI-TERMINAL-138
+/**
+ * Prepare an immutable, path-free source envelope without converting the document.
+ * Traces: CLI-TERMINAL-095 through 102, CLI-TERMINAL-136 through 138 (pure portions).
+ * Tests: TST-CLI-TERMINAL-095 through 102, TST-CLI-TERMINAL-136 through 138.
+ * @param {Uint8Array} bytes
+ * @param {'markdown'|'gpdoc-json'} formatHint
+ * @returns {Result<EditingEnvelope>}
+ */
+export function prepareMarkdownEdit(bytes, formatHint) {
+  return result(() => {
+    if (!['markdown', 'gpdoc-json'].includes(formatHint)) refuse('UNSUPPORTED_FORMAT');
+    if (!(bytes instanceof Uint8Array)) refuse('INVALID_ENCODING');
+    if (bytes.byteLength > MAX_BYTES) refuse('FILE_TOO_LARGE');
+    let source;
+    try { source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+    catch { refuse('INVALID_ENCODING'); }
+    unicode(source);
+    const parsed = parseSource(source, formatHint);
+    const state = { ...parsed, source, formatHint, byteLength: bytes.byteLength,
+      overhead: Buffer.byteLength(parsed.prefix + parsed.suffix, 'utf8'),
+      editable: editableMetadata(parsed.metadata) };
+    const envelope = Object.freeze({
+      body: state.body,
+      metadata: freeze(state.metadata),
+      editable: state.editable,
+      format: state.format,
+      byteLength: state.byteLength,
+      projectedByteLength: (body) => result(() => projectedSize(state, body)),
+    });
+    envelopes.set(envelope, state);
+    return envelope;
+  });
+}
+
+// @spec CLI-TERMINAL-016, CLI-TERMINAL-080, CLI-TERMINAL-081, CLI-TERMINAL-095, CLI-TERMINAL-102, CLI-TERMINAL-136, CLI-TERMINAL-137
+/**
+ * Validate candidate admission without parsing incomplete Markdown or acquiring I/O authority.
+ * Traces: CLI-TERMINAL-016, CLI-TERMINAL-080, CLI-TERMINAL-081, CLI-TERMINAL-095, CLI-TERMINAL-102, CLI-TERMINAL-136, CLI-TERMINAL-137.
+ * Tests: TST-CLI-TERMINAL-080, TST-CLI-TERMINAL-095, TST-CLI-TERMINAL-102, TST-CLI-TERMINAL-136, TST-CLI-TERMINAL-137.
+ * @param {EditingEnvelope} envelope
+ * @returns {Readonly<{editable: boolean, checkCandidate: (body: string) => Result<void>}>}
+ */
+export function createMarkdownDraftPolicy(envelope) {
+  const state = envelopes.get(envelope);
+  return Object.freeze({
+    editable: state?.editable === true,
+    checkCandidate: (body) => result(() => {
+      if (!state) refuse('INVALID_GPDOC');
+      if (!state.editable && body !== state.body) refuse('PROTECTED_METADATA');
+      projectedSize(state, body);
+    }),
+  });
+}
+
+// @spec CLI-TERMINAL-023, CLI-TERMINAL-095, CLI-TERMINAL-096, CLI-TERMINAL-097, CLI-TERMINAL-098, CLI-TERMINAL-100, CLI-TERMINAL-101, CLI-TERMINAL-102, CLI-TERMINAL-136, CLI-TERMINAL-137
+/**
+ * Replace only the body's bytes, then reparse and compare all protected envelope data.
+ * Traces: CLI-TERMINAL-023, CLI-TERMINAL-095 through 102 (pure portions), CLI-TERMINAL-136, CLI-TERMINAL-137.
+ * Tests: TST-CLI-TERMINAL-023, TST-CLI-TERMINAL-095 through 102, TST-CLI-TERMINAL-136, TST-CLI-TERMINAL-137.
+ * @param {EditingEnvelope} envelope
+ * @param {string} body
+ * @returns {Result<Uint8Array>}
+ */
+export function serializeMarkdownEdit(envelope, body) {
+  return result(() => {
+    const state = envelopes.get(envelope);
+    if (!state) refuse('INVALID_GPDOC');
+    if (!state.editable && body !== state.body) refuse('PROTECTED_METADATA');
+    projectedSize(state, body);
+    const token = body === state.body ? state.token : state.format === 'gpdoc-json' ? JSON.stringify(body) : body;
+    const source = state.prefix + token + state.suffix;
+    const reparsed = parseSource(source, state.formatHint);
+    if (reparsed.format !== state.format || reparsed.body !== body
+      || reparsed.prefix !== state.prefix || reparsed.suffix !== state.suffix
+      || JSON.stringify(reparsed.protectedValue) !== JSON.stringify(state.protectedValue)) refuse('INVALID_GPDOC');
+    return new TextEncoder().encode(source);
+  });
+}