rewritable 0.3.0 → 0.6.0

package/src/create.mjs

@@ -0,0 +1,256 @@
+// `rwa create <task…>` (and the `draft` alias) — scaffold + agent-fill into a
+// SELF-CONTAINED rewritable in one shot (design 2026-05-31 §4). The task is a CLI
+// INPUT, never a file capability: the CLI bakes the generated content (and any
+// --data) into the INLINE_DOC snapshot, and the emitted file is thereafter an
+// ordinary, dependency-free rewritable. Recurrence = re-run the CLI.
+//
+// Pipeline (§4.6): scaffold in memory → runAgentLoop (authoring) → apply the
+// envelope to a temp file → assertSelfContained → write ONCE atomically. Nothing
+// is written to the destination unless the whole pipeline succeeds, so a failed
+// run never leaves a half-baked file on disk.
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { loadSeed, applySeedSubs, replaceInlineDoc, extractInlineDoc, kindOverrides, KNOWN_KINDS } from './seed.mjs';
+import { resolveBareWord } from './template.mjs';
+import { extractFromSeed } from './seed-extract.mjs';
+import { runAgentLoop } from './agent-loop.mjs';
+import { applyPlan, CliError } from './edit.mjs';
+import { assertSelfContained } from './self-contained.mjs';
+import { findFrozenZones } from './apply-edits.mjs';
+import { resolveApiKey, envBaseUrl } from './backend.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+
+// Hard cap on --data baked into the snapshot. The dataset lands inside INLINE_DOC
+// of a single self-contained file the user will ship; an unbounded paste would
+// bloat the artifact and the model context. Over the cap → fail loud (§4.3).
+const DATA_CAP = 200_000;
+
+const VALUE_FLAGS = new Set([
+  '--kind', '--from', '--data', '--out',
+  '--backend', '--model', '--base-url', '--api-key',
+]);
+
+/**
+ * Parse `rwa create` argv into flags + the positional task words. Pure: no IO,
+ * no kind resolution (that is resolveBareWord's job, §4.2 Stage 1). A value
+ * flag's argument is never collected as a task word.
+ *
+ * @param {string[]} argv — args after the `create`/`draft` verb
+ * @returns {{kind:string|null, from:string|null, data:string|null, out:string|null,
+ *            force:boolean, open:boolean,
+ *            backend:{name:string|null, model:string|null, baseUrl:string|null, apiKey:string|null},
+ *            words:string[]}}
+ */
+export function parseCreateArgs(argv) {
+  const get = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? (argv[i + 1] ?? null) : null;
+  };
+  const words = argv.filter((a, i) => {
+    if (a.startsWith('-')) return false;            // a flag itself
+    if (VALUE_FLAGS.has(argv[i - 1])) return false; // a value-flag's argument
+    return true;
+  });
+  return {
+    kind: get('--kind'),
+    from: get('--from'),
+    data: get('--data'),
+    out:  get('--out'),
+    force: argv.includes('--force') || argv.includes('-f'),
+    open:  argv.includes('--open')  || argv.includes('-o'),
+    backend: {
+      name:    get('--backend'),
+      model:   get('--model'),
+      baseUrl: get('--base-url'),
+      apiKey:  get('--api-key'),
+    },
+    words,
+  };
+}
+
+// The create-only generation contract (design §4.5): output must run with ZERO
+// external runtime dependencies. Appended to whichever per-kind system prompt the
+// resolved frame selects — this is CLI-exclusive framing, never shipped in the
+// seed bytes. assertSelfContained (below) is the code-level tripwire behind it.
+const SELF_CONTAINMENT_DIRECTIVE = `
+
+CRITICAL — the document you produce MUST be fully self-contained and run with NO external runtime dependencies:
+- Do NOT reference any external URL: no <script src=...> to a CDN, no <link href=...> stylesheet, no remote <img>, no @import or url() pointing off-document. Everything is inlined.
+- For any chart/graph/visualization, hand-roll it with inline <svg> or <canvas> + plain JavaScript. Do NOT use D3, Chart.js, or any library.
+- Embed every piece of data directly in the document (e.g. a <script type="application/json"> island or a JS const). Never fetch data at runtime.
+- Produce the COMPLETE document for the request — this is authoring from a starter, so a wholesale replace_document is appropriate.`;
+
+// Mirror of commands.mjs titleFromBasename (kept local — create.mjs is a peer of
+// commands.mjs, not a dependent). Filename → Title Case, with a safe fallback.
+function titleFromBasename(basename) {
+  return basename
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(w => w[0].toUpperCase() + w.slice(1))
+    .join(' ') || 'Untitled';
+}
+
+function rel(p, cwd) {
+  const r = path.relative(cwd, p);
+  return r || p;
+}
+
+// Resolve the creation FRAME — kind + scaffold body + the brief words — from the
+// parsed args (design §4.2). --kind wins and disables leading-word detection; an
+// explicit kind keeps the full word list as the brief. Otherwise the leading word
+// is matched template-first via resolveBareWord (the SAME resolver `rwa new` uses,
+// so the two surfaces never diverge), and that word is consumed from the brief.
+// A silent frame (no kind, no template match) defaults to document with the whole
+// word list as the brief — Stage 2 model inference is deferred to v2 (§9.2).
+async function resolveFrame(parsed, cwd) {
+  if (parsed.kind) {
+    if (!KNOWN_KINDS.includes(parsed.kind)) {
+      throw new CliError(1, 'unknown_kind', { kind: parsed.kind, known: KNOWN_KINDS });
+    }
+    return { kind: parsed.kind, scaffoldBody: kindOverrides(parsed.kind).body, briefWords: parsed.words, fromMsg: '' };
+  }
+  const lead = parsed.words[0];
+  const frame = lead ? await resolveBareWord(lead, cwd) : null;
+  if (frame && frame.source === 'template') {
+    return {
+      kind: 'document',                 // a cloned instance is a document
+      scaffoldBody: frame.body,         // already label-stripped by resolveBareWord
+      briefWords: parsed.words.slice(1),
+      fromMsg: ` (from template ${rel(frame.templatePath, cwd)})`,
+    };
+  }
+  if (frame && frame.source === 'kind') {
+    return { kind: frame.kind, scaffoldBody: kindOverrides(frame.kind).body, briefWords: parsed.words.slice(1), fromMsg: '' };
+  }
+  return { kind: 'document', scaffoldBody: null, briefWords: parsed.words, fromMsg: '' };
+}
+
+/**
+ * `rwa create` / `rwa draft`: scaffold a fresh container, drive the agent loop to
+ * author it, validate self-containment, and write ONCE — atomically. The emitted
+ * file is an ordinary self-contained rewritable; the task left no capability in it.
+ *
+ * @param {object} parsed — parseCreateArgs output
+ * @param {object} opts
+ * @param {string[]} opts.seedCandidates — seed search paths (loadSeed order)
+ * @param {string}   [opts.cwd] — base dir for relative paths + template scan
+ * @param {string}   [opts.stdinData] — content for `--data -` (caller drains stdin)
+ * @returns {Promise<{out:string, kind:string, fromMsg:string}>}
+ * @throws {CliError} exit 1 usage / 2 file / 3 envelope / 4 agent
+ */
+export async function createCmd(parsed, { seedCandidates, cwd = process.cwd(), stdinData } = {}) {
+  let { kind, scaffoldBody, briefWords, fromMsg } = await resolveFrame(parsed, cwd);
+
+  // --from: base the artifact on an existing rewritable's editable body. Reuses
+  // the same exit-2 surface (not_found / not_a_rewritable) as the rest of the CLI.
+  if (parsed.from) {
+    const fromPath = path.resolve(cwd, parsed.from);
+    let fromText;
+    try {
+      fromText = await readFile(fromPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: fromPath });
+      throw new CliError(2, 'read_error', { path: fromPath, errno: e && e.code, message: e && e.message });
+    }
+    try {
+      scaffoldBody = extractInlineDoc(fromText);
+    } catch {
+      throw new CliError(2, 'not_a_rewritable', { path: fromPath });
+    }
+    fromMsg = ` (from ${rel(fromPath, cwd)})`;
+  }
+
+  // --data: read the dataset to bake into the brief. `-` reads stdin (drained by
+  // the caller). Never fetched at runtime; embedded inline by the agent (§4.3).
+  let dataContent = null;
+  if (parsed.data === '-') {
+    dataContent = stdinData == null ? '' : stdinData;
+  } else if (parsed.data) {
+    const dataPath = path.resolve(cwd, parsed.data);
+    try {
+      dataContent = await readFile(dataPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: dataPath });
+      throw new CliError(2, 'read_error', { path: dataPath, errno: e && e.code, message: e && e.message });
+    }
+  }
+  if (dataContent != null && dataContent.length > DATA_CAP) {
+    throw new CliError(1, 'data_too_large', { bytes: dataContent.length, cap: DATA_CAP });
+  }
+
+  // Output path + clobber guard (matches new/import's --force semantics).
+  const dated = `./${kind}-${new Date().toISOString().slice(0, 10)}.html`;
+  const out = path.resolve(cwd, parsed.out || dated);
+  try {
+    await stat(out);
+    if (!parsed.force) throw new CliError(2, 'dest_exists', { path: out });
+  } catch (e) {
+    if (e instanceof CliError) throw e;
+    // ENOENT is the happy path (file doesn't exist yet); anything else is a real
+    // stat error worth surfacing.
+    if (!(e && e.code === 'ENOENT')) throw new CliError(2, 'read_error', { path: out, errno: e && e.code });
+  }
+
+  // Build the scaffold in memory — identical subs flow to newCmd.
+  const seed = await loadSeed(seedCandidates);
+  const overrides = kindOverrides(kind);
+  let scaffold = applySeedSubs(seed, {
+    uuid: crypto.randomUUID(),
+    title: titleFromBasename(path.basename(out, path.extname(out))),
+    fileMeta: path.basename(out),
+    lensPlaceholder:   overrides.lensPlaceholder,
+    palPlaceholder:    overrides.palPlaceholder,
+    productHeader:     overrides.productHeader,
+    productKind:       kind,
+    lensClickToAnchor: overrides.lensClickToAnchor,
+  });
+  const body = scaffoldBody != null ? scaffoldBody : overrides.body;
+  if (body != null) scaffold = replaceInlineDoc(scaffold, body);
+  const scaffoldDoc = extractInlineDoc(scaffold);
+
+  // Backend: flag → env → default. The key is used ONLY for the model call here;
+  // it is never written into the artifact (the file carries content, not creds).
+  const backendName = parsed.backend.name || process.env.RWA_BACKEND || 'openrouter';
+  const backend = {
+    baseUrl: parsed.backend.baseUrl || envBaseUrl(backendName),
+    model:   parsed.backend.model   || process.env.RWA_MODEL || 'google/gemini-3.5-flash',
+    apiKey:  resolveApiKey(backendName, parsed.backend.apiKey),
+  };
+
+  // Per-kind system prompt + the create-only self-containment directive; the brief
+  // carries any --data inline so the agent embeds it (never fetches).
+  const { SYSTEM_PROMPTS, TOOL_SCHEMAS } = extractFromSeed(seed);
+  const systemPrompt = (SYSTEM_PROMPTS[kind] || SYSTEM_PROMPTS.document) + SELF_CONTAINMENT_DIRECTIVE;
+  const frozenZoneNames = findFrozenZones(scaffoldDoc).map(z => z.name);
+  let instruction = briefWords.join(' ').trim() || `Author a complete ${kind} for this document.`;
+  if (dataContent != null) {
+    instruction += `\n\nUse this data — embed it inline in the document, do NOT fetch it at runtime:\n${dataContent}`;
+  }
+
+  let result;
+  try {
+    result = await runAgentLoop({ systemPrompt, toolSchemas: TOOL_SCHEMAS, currentDoc: scaffoldDoc, instruction, frozenZoneNames, backend });
+  } catch (e) {
+    throw new CliError(4, e.subcode || 'agent_error', e.details || { message: e && e.message });
+  }
+
+  // Atomicity (§4.6): apply + validate against a TEMP file, never the destination.
+  // The destination is written exactly once, only after self-containment passes —
+  // so any failure (envelope, frozen-zone, external-ref) leaves --out untouched.
+  const tmp = path.join(tmpdir(), `rwa-create-${crypto.randomUUID()}.html`);
+  try {
+    await atomicWrite(tmp, scaffold);
+    await applyPlan(tmp, result.envelope);                 // throws CliError on envelope/frozen issues
+    const filled = await readFile(tmp, 'utf8');
+    assertSelfContained(extractInlineDoc(filled));         // throws CliError(4) → out untouched
+    await atomicWrite(out, filled);
+  } finally {
+    await rm(tmp, { force: true });
+  }
+
+  return { out, kind, fromMsg };
+}

package/src/doc.mjs

@@ -0,0 +1,69 @@
+// Read-path entry for `rwa doc` — the counterpart to `rwa edit`'s applyPlan.
+// Where applyPlan WRITES the editable body of a rewritable, inspectDoc READS
+// it: it returns the exact LF-canonical text the rwa-edit contract operates
+// on, plus the metadata an agent needs to edit safely (uuid, product kind,
+// frozen-zone names).
+//
+// Error surface mirrors edit.mjs so callers dedupe file-error handling across
+// read and write:
+//   exitCode 2 / subcode: 'not_found', 'read_error', 'not_a_rewritable'
+
+import { readFile } from 'node:fs/promises';
+import { extractInlineDoc } from './seed.mjs';
+import { findFrozenZones } from './apply-edits.mjs';
+import { resolveSelfDescription } from './identity.mjs';
+import { CliError } from './edit.mjs';
+
+// The bootstrap bakes both consts at emit time (cli/src/seed.mjs applySeedSubs).
+// Reading them back is how we recover identity (uuid) and editing framing
+// (kind) without a full HTML parse. Patterns mirror seed.mjs UUID_RE /
+// PRODUCT_KIND_RE and rwa.mjs detectProductKind — keep them in step.
+const UUID_RE = /const DOC_UUID = '([0-9a-f-]{36})';/;
+const PRODUCT_KIND_RE = /const PRODUCT_KIND = '([^']*)';/;
+
+/**
+ * Read a rewritable's editable document body, contract metadata, and the
+ * `self-description/1` projection (the "what is this?" surface, computed from the
+ * bytes — kind/affordances/title/blocks/baseline). The projection applies the
+ * v1.1 precedence (declared > static): a trustworthy embedded #rwa-affordances
+ * declaration (edit-unreachable) wins over the kind-template guess
+ * (`source:"declared"`); otherwise the static kind-derived projection
+ * (`source:"static"`). No `live` block (the CLI executes no JS). See
+ * ./identity.mjs and docs/specs/rwa-self-description-spec.md §3.1.
+ *
+ * @param {string} filePath — path to the target .html
+ * @returns {Promise<{doc: string, uuid: string|null, kind: string, frozenZones: string[], self: object}>}
+ * @throws {CliError} exitCode 2 on file / non-rewritable errors
+ */
+export async function inspectDoc(filePath) {
+  let fileText;
+  try {
+    fileText = await readFile(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') throw new CliError(2, 'not_found', { path: filePath });
+    throw new CliError(2, 'read_error', { path: filePath, errno: e && e.code, message: e && e.message });
+  }
+
+  // A plain-text or non-rewritable target throws here — the same gate `rwa
+  // edit` uses. Surfacing it as not_a_rewritable gives agents a deterministic
+  // "is this a rewritable?" probe (clean non-zero exit, empty stdout).
+  let doc;
+  try {
+    doc = extractInlineDoc(fileText);
+  } catch (_e) {
+    throw new CliError(2, 'not_a_rewritable', { path: filePath });
+  }
+
+  const uuid = (fileText.match(UUID_RE) || [])[1] || null;
+  // Pre-PRODUCT_KIND containers (and any unknown kind) default to 'document',
+  // matching how the runtime and `rwa edit` resolve SYSTEM_PROMPTS.
+  const kind = (fileText.match(PRODUCT_KIND_RE) || [])[1] || 'document';
+  const frozenZones = findFrozenZones(doc).map(z => z.name);
+  // The self-description/1 projection — "what is this, what can be done with it".
+  // resolveSelfDescription applies the v1.1 precedence (declared > static): a
+  // trustworthy embedded #rwa-affordances declaration (edit-unreachable) wins over
+  // the kind-template guess; otherwise the static kind-derived projection.
+  const self = resolveSelfDescription({ fileText, doc, uuid, kind, frozenZones });
+
+  return { doc, uuid, kind, frozenZones, self };
+}

package/src/dsl-compiler.mjs

@@ -0,0 +1,357 @@
+// rwa-edit-dsl/1 compiler — turns a DSL plan into an apply_edits or
+// replace_document envelope. Read alongside rwa-edit-dsl-spec.md.
+//
+// Compile-down semantics:
+//   - replace_document plan → { tool: 'replace_document', envelope }
+//   - any other plan → { tool: 'apply_edits', envelope: { version, edits } }
+//
+// Multi-op plans apply sequentially against an evolving "shadow" doc — each
+// op's anchor is resolved against the doc as it would look after preceding
+// ops landed. The shadow is internal to compilation; the emitted edits are
+// applied sequentially by the runtime in the same order, so every emitted
+// `find` matches in turn.
+
+const SUPPORTED_VERSION = 'rwa-edit-dsl/1';
+
+class DslCompileError extends Error {
+  constructor(code, message, op) {
+    super(message);
+    this.code = code;
+    this.op = op;
+  }
+}
+
+function makeError(code, message, op) {
+  return new DslCompileError(code, message, op);
+}
+
+/**
+ * Compile a DSL plan against a doc. Returns:
+ *   { tool: 'apply_edits' | 'replace_document', envelope: <rwa-edit/1 envelope> }
+ *
+ * Throws DslCompileError on any spec violation.
+ */
+export function compileDslPlan(plan, doc) {
+  if (!plan || typeof plan !== 'object') {
+    throw makeError('op_malformed', 'plan must be an object');
+  }
+  if (plan.version !== SUPPORTED_VERSION) {
+    throw makeError('version_unsupported', `expected ${SUPPORTED_VERSION}, got ${plan.version}`);
+  }
+  if (!Array.isArray(plan.ops) || plan.ops.length === 0) {
+    throw makeError('op_malformed', 'plan.ops must be a non-empty array');
+  }
+
+  // replace_document is a sole-op escape hatch.
+  const hasReplaceDoc = plan.ops.some(op => op?.op === 'replace_document');
+  if (hasReplaceDoc) {
+    if (plan.ops.length !== 1) {
+      throw makeError('op_malformed', 'replace_document must be the sole op in a plan');
+    }
+    const op = plan.ops[0];
+    if (typeof op.doc !== 'string' || typeof op.reason !== 'string') {
+      throw makeError('op_malformed', 'replace_document requires doc and reason fields');
+    }
+    return {
+      tool: 'replace_document',
+      envelope: { version: 'rwa-edit/1', doc: op.doc, reason: op.reason },
+    };
+  }
+
+  // Otherwise: compile each op against an evolving shadow.
+  let shadow = doc;
+  const edits = [];
+  for (const op of plan.ops) {
+    const newEdits = compileOp(op, shadow);
+    for (const e of newEdits) {
+      validateEditApplies(shadow, e, op);
+      edits.push(e);
+      shadow = applyEditToShadow(shadow, e);
+    }
+  }
+  return {
+    tool: 'apply_edits',
+    envelope: { version: 'rwa-edit/1', edits },
+  };
+}
+
+function compileOp(op, doc) {
+  if (!op || typeof op !== 'object' || typeof op.op !== 'string') {
+    throw makeError('op_malformed', 'each op must be an object with a string `op` field');
+  }
+  switch (op.op) {
+    case 'replace': return compileReplace(op, doc);
+    case 'insert': return compileInsert(op, doc);
+    case 'delete': return compileDelete(op, doc);
+    case 'set_attr': return compileSetAttr(op, doc);
+    default: throw makeError('op_unknown', `unknown op: ${op.op}`, op);
+  }
+}
+
+// ---------- replace ----------
+
+function compileReplace(op, doc) {
+  const { find, replace, region, all } = op;
+  if (typeof find !== 'string' || typeof replace !== 'string') {
+    throw makeError('op_malformed', 'replace requires `find` and `replace` strings', op);
+  }
+
+  let windowStart = 0;
+  let windowEnd = doc.length;
+  if (typeof region === 'string') {
+    const matches = allOccurrences(doc, region);
+    if (matches.length === 0) throw makeError('region_not_found', `region not found: ${preview(region)}`, op);
+    if (matches.length > 1) throw makeError('region_not_unique', `region matches ${matches.length} times`, op);
+    windowStart = matches[0];
+    windowEnd = matches[0] + region.length;
+  }
+
+  const window = doc.slice(windowStart, windowEnd);
+  const localOccs = allOccurrences(window, find);
+  if (localOccs.length === 0) {
+    throw makeError(all ? 'all_with_zero_matches' : 'op_malformed', `find has zero matches in search window: ${preview(find)}`, op);
+  }
+  if (!all && localOccs.length > 1) {
+    throw makeError('op_malformed', `find has ${localOccs.length} matches in search window but all=false: ${preview(find)}`, op);
+  }
+
+  // For all=false, single match in window. If find is also globally unique, emit raw.
+  // Otherwise contextualize using surrounding doc bytes.
+  if (!all) {
+    const globalOccs = allOccurrences(doc, find);
+    if (globalOccs.length === 1) {
+      return [{ find, replace }];
+    }
+    // Disambiguate with surrounding context drawn from the window.
+    const absoluteStart = windowStart + localOccs[0];
+    return [contextualizeEdit(doc, absoluteStart, find, replace)];
+  }
+
+  // all=true: emit one edit per local occurrence, contextualized.
+  return localOccs.map(localStart => {
+    const absoluteStart = windowStart + localStart;
+    return contextualizeEdit(doc, absoluteStart, find, replace);
+  });
+}
+
+// Extend find/replace bytes outward until find is uniquely locatable in doc.
+// We extend backward by 1 char at a time then forward, alternating, until
+// the candidate find appears exactly once in doc.
+function contextualizeEdit(doc, absoluteStart, find, replace) {
+  const findEnd = absoluteStart + find.length;
+  let preLen = 0, postLen = 0;
+  // Bound: at most extend 200 chars in each direction. Most disambiguations
+  // need <20; 200 is a sanity cap.
+  const MAX = 200;
+  while (true) {
+    const ctxFind = doc.slice(absoluteStart - preLen, findEnd + postLen);
+    const ctxReplace = doc.slice(absoluteStart - preLen, absoluteStart) + replace + doc.slice(findEnd, findEnd + postLen);
+    const occs = allOccurrences(doc, ctxFind);
+    if (occs.length === 1) {
+      return { find: ctxFind, replace: ctxReplace };
+    }
+    if (preLen >= MAX && postLen >= MAX) {
+      throw makeError('op_malformed', `unable to disambiguate find within ${MAX} chars: ${preview(find)}`);
+    }
+    if (postLen <= preLen && findEnd + postLen < doc.length) postLen++;
+    else if (absoluteStart - preLen > 0) preLen++;
+    else postLen++;
+  }
+}
+
+// ---------- insert ----------
+
+function compileInsert(op, doc) {
+  const { content, after, before } = op;
+  if (typeof content !== 'string') {
+    throw makeError('op_malformed', 'insert requires `content` string', op);
+  }
+  const positionalCount = (typeof after === 'string' ? 1 : 0) + (typeof before === 'string' ? 1 : 0);
+  if (positionalCount !== 1) {
+    throw makeError('op_malformed', 'insert requires exactly one of `after` or `before`', op);
+  }
+  const anchor = typeof after === 'string' ? after : before;
+  const occs = allOccurrences(doc, anchor);
+  if (occs.length === 0) throw makeError('op_malformed', `insert anchor not found: ${preview(anchor)}`, op);
+  if (occs.length > 1) throw makeError('op_malformed', `insert anchor not unique: ${preview(anchor)} (${occs.length} matches)`, op);
+  if (typeof after === 'string') {
+    return [{ find: anchor, replace: anchor + content }];
+  }
+  return [{ find: anchor, replace: content + anchor }];
+}
+
+// ---------- delete ----------
+
+function compileDelete(op, doc) {
+  const { target } = op;
+  if (typeof target !== 'string') {
+    throw makeError('op_malformed', 'delete requires `target` string', op);
+  }
+  const occs = allOccurrences(doc, target);
+  if (occs.length === 0) throw makeError('op_malformed', `delete target not found: ${preview(target)}`, op);
+  if (occs.length > 1) throw makeError('op_malformed', `delete target not unique: ${preview(target)} (${occs.length} matches)`, op);
+  return [{ find: target, replace: '' }];
+}
+
+// ---------- set_attr ----------
+
+function compileSetAttr(op, doc) {
+  const { anchor, attr, value } = op;
+  if (typeof anchor !== 'string' || typeof attr !== 'string' || typeof value !== 'string') {
+    throw makeError('op_malformed', 'set_attr requires anchor, attr, value strings', op);
+  }
+  if (!anchor.startsWith('<')) {
+    throw makeError('anchor_unparseable', 'set_attr.anchor must start with `<`', op);
+  }
+  if (anchor.endsWith('>')) {
+    throw makeError('anchor_unparseable', 'set_attr.anchor must end before `>`', op);
+  }
+  const occs = allOccurrences(doc, anchor);
+  if (occs.length === 0) throw makeError('op_malformed', `set_attr anchor not found: ${preview(anchor)}`, op);
+  if (occs.length > 1) throw makeError('op_malformed', `set_attr anchor not unique: ${preview(anchor)} (${occs.length} matches)`, op);
+  const start = occs[0];
+  const closeIdx = doc.indexOf('>', start + anchor.length);
+  if (closeIdx < 0) throw makeError('anchor_unparseable', 'no `>` found after set_attr anchor', op);
+  const fullTag = doc.slice(start, closeIdx + 1);
+
+  // Reject attribute values containing chars that can't survive serialization.
+  if (/[--]/.test(value)) {
+    throw makeError('attr_value_unrepresentable', 'value contains control characters', op);
+  }
+  const escapedValue = value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+
+  // Detect whether attr already appears in fullTag. We respect quote state to
+  // avoid matching attribute substrings inside another attribute's value.
+  const existingMatch = findAttrInTag(fullTag, attr);
+  let newTag;
+  if (existingMatch) {
+    const [attrStart, attrEnd] = existingMatch;
+    newTag = fullTag.slice(0, attrStart) + `${attr}="${escapedValue}"` + fullTag.slice(attrEnd);
+  } else {
+    newTag = fullTag.slice(0, -1) + ` ${attr}="${escapedValue}">`;
+  }
+  return [{ find: fullTag, replace: newTag }];
+}
+
+// Locate `attr` inside a parsed opening tag, returning [start, end) byte
+// offsets within the tag of the attr's full `name="value"` substring (or
+// `name='value'`, or `name=value`, or boolean `name`). Returns null if absent.
+// Respects quote state to avoid false matches inside other attributes.
+function findAttrInTag(tag, attrName) {
+  // Walk attribute by attribute. The tag starts with <tagname or </tagname.
+  // Skip past tagname.
+  const nameMatch = tag.match(/^<\/?([a-zA-Z][a-zA-Z0-9_-]*)/);
+  if (!nameMatch) return null;
+  let i = nameMatch[0].length;
+  while (i < tag.length - 1) {
+    // Skip whitespace
+    while (i < tag.length && /\s/.test(tag[i])) i++;
+    if (i >= tag.length || tag[i] === '>' || tag[i] === '/') break;
+    const attrStart = i;
+    // Read attribute name
+    let nameEnd = i;
+    while (nameEnd < tag.length && !/[\s=>/]/.test(tag[nameEnd])) nameEnd++;
+    const name = tag.slice(attrStart, nameEnd);
+    i = nameEnd;
+    // Optional = followed by value
+    let attrEnd = nameEnd;
+    if (tag[i] === '=') {
+      i++;
+      if (tag[i] === '"') {
+        const close = tag.indexOf('"', i + 1);
+        if (close < 0) return null;
+        attrEnd = close + 1;
+        i = attrEnd;
+      } else if (tag[i] === "'") {
+        const close = tag.indexOf("'", i + 1);
+        if (close < 0) return null;
+        attrEnd = close + 1;
+        i = attrEnd;
+      } else {
+        // Unquoted value
+        while (i < tag.length && !/[\s>]/.test(tag[i])) i++;
+        attrEnd = i;
+      }
+    } else {
+      attrEnd = nameEnd;
+    }
+    if (name === attrName) return [attrStart, attrEnd];
+  }
+  return null;
+}
+
+// ---------- shared helpers ----------
+
+function allOccurrences(haystack, needle) {
+  const out = [];
+  if (needle.length === 0) return out;
+  let from = 0;
+  while (true) {
+    const idx = haystack.indexOf(needle, from);
+    if (idx < 0) break;
+    out.push(idx);
+    from = idx + 1; // overlapping matches allowed
+  }
+  return out;
+}
+
+function applyEditToShadow(doc, edit) {
+  const idx = doc.indexOf(edit.find);
+  if (idx < 0) {
+    throw makeError('op_malformed', `compiler shadow drift: emitted edit no longer matches: ${preview(edit.find)}`);
+  }
+  const next = doc.indexOf(edit.find, idx + 1);
+  if (next >= 0) {
+    throw makeError('op_malformed', `compiler shadow drift: emitted edit ambiguous (${allOccurrences(doc, edit.find).length} matches): ${preview(edit.find)}`);
+  }
+  return doc.slice(0, idx) + edit.replace + doc.slice(idx + edit.find.length);
+}
+
+function validateEditApplies(doc, edit, op) {
+  if (typeof edit.find !== 'string' || typeof edit.replace !== 'string') {
+    throw makeError('op_malformed', 'compiler bug: emitted non-string find/replace', op);
+  }
+  if (edit.find.length === 0) {
+    throw makeError('op_malformed', 'compiler bug: emitted empty find', op);
+  }
+}
+
+function preview(s) {
+  const trimmed = s.length > 60 ? s.slice(0, 57) + '...' : s;
+  return JSON.stringify(trimmed);
+}
+
+/**
+ * Apply an envelope (the compileDslPlan output, OR a model's apply_edits/replace_document)
+ * to a doc. Used by the fidelity-dsl runner's comparator to check round-trip
+ * equivalence between the DSL-compiled envelope and the scenario stub envelope.
+ *
+ * Mirrors the runtime's apply path: each find must match exactly once in turn.
+ *
+ * @param {string} doc — the input doc (LF-canonical)
+ * @param {{ tool: string, envelope: object }} env — { tool, envelope } pair
+ * @returns {string} the post-apply doc
+ */
+export function applyEnvelopeToDoc(doc, env) {
+  if (env.tool === 'replace_document') {
+    return env.envelope.doc;
+  }
+  if (env.tool !== 'apply_edits') {
+    throw new Error(`applyEnvelopeToDoc: unknown tool "${env.tool}"`);
+  }
+  let result = doc;
+  for (const e of env.envelope.edits) {
+    const idx = result.indexOf(e.find);
+    if (idx < 0) {
+      throw new Error(`apply: find not found: ${preview(e.find)}`);
+    }
+    const next = result.indexOf(e.find, idx + 1);
+    if (next >= 0) {
+      throw new Error(`apply: find not unique: ${preview(e.find)}`);
+    }
+    result = result.slice(0, idx) + e.replace + result.slice(idx + e.find.length);
+  }
+  return result;
+}
+
+export { DslCompileError };