@visual-z/xeno 0.1.0

package/src/core/evidence-links.ts

@@ -0,0 +1,71 @@
+/** O.6: explicit evidence relationships are projections, never verification claims. */
+import type { LogEvent, ToolResultEvent } from "./events.ts";
+
+export type EvidenceLink = {
+  id: string; work: string; what: string; event: string;
+  resource?: string; version?: string;
+  freshness: "current" | "stale" | "unknown";
+  superseded_by?: string;
+};
+
+/** Normalize path spelling only; never infer basename, symlink or repository aliases. */
+export function resourceKey(path: string): string {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop(); else parts.push(part);
+  }
+  return (path.startsWith("/") ? "/" : "") + parts.join("/");
+}
+
+export function observationResources(event: ToolResultEvent, input: unknown): string[] {
+  if (event.effect && "path" in event.effect) return [resourceKey(event.effect.path)];
+  if (!event.ok || input === null || typeof input !== "object") return [];
+  const args = input as Record<string, unknown>;
+  const paths = typeof args["path"] === "string" ? [args["path"]] : Array.isArray(args["paths"]) ? args["paths"] : [];
+  return [...new Set(paths.filter((path): path is string => typeof path === "string").map(resourceKey))];
+}
+
+export function observedVersion(events: readonly LogEvent[], resource: string): string | null | undefined {
+  let version: string | null | undefined;
+  for (const event of events) {
+    if (event.t === "tool_result" && event.effect && "path" in event.effect && resourceKey(event.effect.path) === resource) {
+      version = event.effect.kind === "read" ? event.effect.sha256 : event.effect.sha256_after;
+    }
+    if (event.t === "snapshot") {
+      if (event.removed.map(resourceKey).includes(resource)) version = null;
+      for (const [path, value] of Object.entries({ ...event.added, ...event.changed })) if (resourceKey(path) === resource) version = value;
+    }
+  }
+  return version;
+}
+
+export function deriveEvidenceLinks(previous: readonly EvidenceLink[], events: readonly LogEvent[]): EvidenceLink[] {
+  const links = previous.map(link => ({ ...link }));
+  for (const event of events) {
+    if (event.t === "evidence_link") {
+      if (event.supersedes) for (const link of links) {
+        if (link.work === event.work && link.event === event.supersedes && link.superseded_by === undefined) link.superseded_by = event.id;
+      }
+      if (!links.some(link => link.id === event.id)) links.push({ id: event.id, work: event.work, what: event.what, event: event.source,
+        ...(event.resource !== undefined ? { resource: resourceKey(event.resource) } : {}),
+        ...(event.version !== undefined ? { version: event.version } : {}),
+        freshness: event.version === undefined || event.observed_version === undefined ? "unknown"
+          : event.version === event.observed_version ? "current" : "stale" });
+    }
+    for (const link of links) {
+      if (!link.resource || !link.version) continue;
+      if (event.t === "tool_result" && event.effect && "path" in event.effect && resourceKey(event.effect.path) === link.resource) {
+        const version = event.effect.kind === "read" ? event.effect.sha256 : event.effect.sha256_after;
+        link.freshness = version === link.version ? "current" : "stale";
+      }
+      if (event.t === "snapshot") {
+        if (event.removed.map(resourceKey).includes(link.resource)) link.freshness = "stale";
+        for (const [path, version] of Object.entries({ ...event.added, ...event.changed })) {
+          if (resourceKey(path) === link.resource) link.freshness = version === link.version ? "current" : "stale";
+        }
+      }
+    }
+  }
+  return links;
+}

package/src/core/evidence.ts

@@ -0,0 +1,89 @@
+/** Shared executed-evidence rules for handoff derivation and the turn watchdog. */
+import type { EvidenceQuery, LogEvent, ToolResultEvent } from "./events.ts";
+import type { Evidence } from "./handoff.ts";
+
+type CommandEffect = Extract<NonNullable<ToolResultEvent["effect"]>, { kind: "command" }>;
+export type CommandResult = ToolResultEvent & { effect: CommandEffect };
+export function isCommandResult(event: LogEvent): event is CommandResult {
+  return event.t === "tool_result" && event.effect?.kind === "command";
+}
+export function matchesQuery(query: EvidenceQuery, effect: CommandEffect): boolean {
+  return "gate" in query ? effect.gate === query.gate : effect.cmd === query.command;
+}
+export function evidenceStale(events: readonly LogEvent[], evidence: Evidence, initially = false): boolean {
+  const start = events.findIndex((event) => event.id === evidence.event_id);
+  let stale = initially;
+  for (const event of events.slice(start + 1)) {
+    if (event.t === "tool_result" && event.effect?.kind === "edit") stale = true;
+    const sha = event.t === "snapshot" ? event.workspace_sha256
+      : event.t === "tool_result" && event.effect?.kind === "command" ? event.effect.workspace_sha256 : undefined;
+    if (sha !== undefined && evidence.workspace_sha256 !== undefined) stale = sha !== evidence.workspace_sha256;
+    else if (event.t === "snapshot" && (Object.keys(event.added).length + Object.keys(event.changed).length + event.removed.length > 0)) stale = true;
+  }
+  return stale;
+}
+
+export type EvidenceResolution = { ok: true; evidence: Evidence } | {
+  ok: false; reason: "no_matching_event" | "nonzero_exit" | "stale_workspace"; exit?: number;
+};
+
+/** D11/O.2: callers supply only the current segment's prefix before the claim. */
+export function resolveEvidence(events: readonly LogEvent[], query: EvidenceQuery, afterEvent?: string): EvidenceResolution {
+  const start = afterEvent === undefined ? 0 : events.findIndex(event => event.id === afterEvent) + 1;
+  const result = events.slice(start).findLast(event => isCommandResult(event) && matchesQuery(query, event.effect));
+  if (!result || !isCommandResult(result)) return { ok: false, reason: "no_matching_event" };
+  if (result.effect.exit !== 0) return { ok: false, reason: "nonzero_exit", exit: result.effect.exit };
+  const evidence: Evidence = { command: result.effect.cmd, exit: result.effect.exit, at: result.at, event_id: result.id,
+    ...(result.effect.gate !== undefined ? { gate: result.effect.gate } : {}),
+    ...(result.effect.workspace_sha256 ? { workspace_sha256: result.effect.workspace_sha256 } : {}) };
+  return evidenceStale(events, evidence) ? { ok: false, reason: "stale_workspace" } : { ok: true, evidence };
+}
+
+export function eligibleProgressChecks(events: readonly LogEvent[], claimed: ReadonlySet<string>, failingGates: { has(gate: string): boolean }): Set<string> {
+  const eligible = new Set<string>();
+  for (const event of events) {
+    if (!isCommandResult(event)) continue;
+    const gate = event.effect.gate;
+    if (event.effect.exit !== 0 || (gate === undefined && !claimed.has(event.id)) || (gate !== undefined && failingGates.has(gate))) continue;
+    if (!evidenceStale(events, { command: event.effect.cmd, exit: 0, at: event.at, event_id: event.id,
+      ...(event.effect.workspace_sha256 === undefined ? {} : { workspace_sha256: event.effect.workspace_sha256 }) })) eligible.add(event.id);
+  }
+  return eligible;
+}
+
+/** An exchange can verify a gate or claim only an already executed command. */
+export function exchangeProgressChecks(events: readonly LogEvent[]): Set<string> {
+  const commands: CommandResult[] = [], claimed = new Set<string>(), gates = new Map<string, number>();
+  for (const event of events) {
+    if (isCommandResult(event)) {
+      commands.push(event);
+      if (event.effect.gate !== undefined) gates.set(event.effect.gate, event.effect.exit);
+    } else if (event.t === "claim") {
+      const command = commands.findLast((result) => matchesQuery(event.evidence, result.effect));
+      if (command?.effect.exit === 0) claimed.add(command.id);
+    }
+  }
+  return eligibleProgressChecks(events, claimed, new Set([...gates].filter(([, exit]) => exit !== 0).map(([gate]) => gate)));
+}
+
+/** D11: classify an actual verifier invocation, never a runner word in data. */
+export function classifyGate(gates: Readonly<Record<string, string>>, command: string): string | undefined {
+  if (/[\n\r;&|<>`$(){}'"\\]/.test(command)) return undefined;
+  const tokens = command.trim().split(/\s+/);
+  const informational = ["--version", "-V", "--help", "-h", "--collect-only", "--listTests", "--showConfig", "--init", "--fixtures", "--markers"];
+  if (tokens.some((t) => informational.includes(t))) return undefined;
+  let i = 0;
+  const first = tokens[0];
+  if (first === "python" || first === "python3") {
+    if (tokens[1] !== "-m") return undefined;
+    i = 2;
+  } else if (["npx", "bunx", "uvx"].includes(first ?? "")) i = 1;
+  else if (["uv", "poetry", "pdm", "pipenv"].includes(first ?? "")) {
+    if (tokens[1] !== "run") return undefined;
+    i = 2;
+  } else if (["bun", "npm", "pnpm", "yarn"].includes(first ?? "") && tokens[1] === "run") i = 2;
+  const executable = tokens[i];
+  if (executable === "cargo" && !["test", "check", "clippy", "build"].includes(tokens[i + 1] ?? "")) return undefined;
+  if (executable === "vitest" && ["list", "init"].includes(tokens[i + 1] ?? "")) return undefined;
+  return gates[executable ?? ""];
+}

package/src/core/execution.ts

@@ -0,0 +1,12 @@
+/** D5/D11: incomplete execution is unknown, never an instruction to run twice. */
+import type { LogEvent, AssistantBlock } from "./events.ts";
+
+export function pendingToolCalls(events: readonly LogEvent[]): Extract<AssistantBlock, { type: "tool_use" }>[] {
+  const pending = new Map<string, Extract<AssistantBlock, { type: "tool_use" }>>();
+  for (const event of events) {
+    if (event.t === "assistant") {
+      for (const block of event.blocks) if (block.type === "tool_use") pending.set(block.call_id, block);
+    } else if (event.t === "tool_result") pending.delete(event.call_id);
+  }
+  return [...pending.values()];
+}

package/src/core/exhaustive.ts

@@ -0,0 +1,18 @@
+/**
+ * Exhaustiveness for discriminated unions.
+ *
+ * `LogEvent` has ten variants and `Effect` three; the projection's claim to be
+ * a total function rests on every switch over them covering every case. In the
+ * default branch of such a switch the value narrows to `never`, so passing it
+ * here compiles only while the switch is complete -- adding a variant turns
+ * every incomplete switch into a type error rather than a silent fallthrough.
+ *
+ * This is the one exhaustiveness guarantee tsc will not give on its own: a
+ * switch that misses a case is legal TypeScript, it just falls through.
+ */
+export function assertNever(value: never, context: string): never {
+  throw new Error(
+    `${context}: unhandled variant ${JSON.stringify(value)} -- ` +
+      "a union gained a member without every switch over it being updated",
+  );
+}

package/src/core/experiment.ts

@@ -0,0 +1,40 @@
+/** Experimental projections never mutate the durable event stream (D8, L). */
+import type { Message } from "./project.ts";
+
+export type ContextArm = "node" | "replay" | "truncate" | "mask";
+
+export function experimentalContext(messages: readonly Message[], arm: ContextArm, keepRounds: number): Message[] {
+  if (!Number.isSafeInteger(keepRounds) || keepRounds < 1) throw new RangeError("keepRounds must be positive");
+  if (arm === "node" || arm === "replay") return [...messages];
+  const groups: Message[][] = [[]];
+  for (const message of messages) {
+    if (message.role === "assistant") groups.push([]);
+    groups.at(-1)!.push(message);
+  }
+  const recent = Math.max(1, groups.length - keepRounds);
+  if (arm === "truncate") return [...groups[0]!, ...groups.slice(recent).flat()];
+  return groups.flatMap((group, i) => i >= recent ? group : group.map((message) => ({
+    ...message,
+    content: message.content.map((block) => block.type === "tool_result"
+      ? { ...block, content: "[observation masked by experiment; original remains in log]" } : block),
+  })));
+}
+
+/** Fisher-Yates with a fixed seed; scheduling and intervals are reproducible. */
+export function seededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (Math.imul(1664525, state) + 1013904223) >>> 0;
+    return state / 4294967296;
+  };
+}
+
+export function shuffled<T>(items: readonly T[], seed: number): T[] {
+  const random = seededRandom(seed);
+  const out = [...items];
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [out[i], out[j]] = [out[j]!, out[i]!];
+  }
+  return out;
+}

package/src/core/export.ts

@@ -0,0 +1,169 @@
+/**
+ * Transcript serialisation. Pure: no I/O, no clock.
+ *
+ * The HTML has to be a single file a person can open offline. A stylesheet
+ * or font loaded from a CDN is blank in the one situation export is for, so
+ * nothing here emits a URL. Timestamps are passed in so this module cannot
+ * invent "now".
+ *
+ * User text is escaped as HTML text. A transcript that contains
+ * `<script>alert(1)</script>` must stay text; emitting it as a tag is XSS
+ * from the log (card: feat-session-flags-and-export).
+ */
+
+import type { AssistantBlock, LogEvent } from "./events.ts";
+import { assertNever } from "./exhaustive.ts";
+
+export interface HtmlMeta {
+  title: string;
+  /** ISO timestamp supplied by the caller. Never read from the clock here. */
+  exportedAt: string;
+  sessionId?: string;
+}
+
+export function toJsonl(events: readonly LogEvent[]): string {
+  if (events.length === 0) return "";
+  return events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+}
+
+export function toHtml(events: readonly LogEvent[], meta: HtmlMeta): string {
+  const title = escapeHtml(meta.title);
+  const when = escapeHtml(meta.exportedAt);
+  const id = meta.sessionId !== undefined ? escapeHtml(meta.sessionId) : "";
+  const body = events.map(eventHtml).join("\n");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+body{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;max-width:72rem;margin:1.5rem auto;padding:0 1rem;color:#111;background:#fff;line-height:1.45}
+header{border-bottom:1px solid #ddd;padding-bottom:0.75rem;margin-bottom:1rem}
+header p{color:#555;margin:0.25rem 0 0}
+.event{margin:0.85rem 0;padding:0.55rem 0.8rem;border-left:3px solid #ccc;background:#fafafa}
+.user{border-color:#1565c0}
+.assistant{border-color:#2e7d32}
+.tool{border-color:#ef6c00}
+.meta{color:#666;font-size:0.8rem;margin-bottom:0.35rem}
+pre{white-space:pre-wrap;word-break:break-word;margin:0;font:inherit}
+</style>
+</head>
+<body>
+<header>
+<h1>${title}</h1>
+<p>exported ${when}${id.length > 0 ? ` · ${id}` : ""}</p>
+</header>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Most recent assistant text block. `/copy` is this string, not a
+ * reconstruction of thinking or tool JSON.
+ */
+export function lastAssistantText(events: readonly LogEvent[]): string | null {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i]!;
+    if (e.t !== "assistant") continue;
+    const parts: string[] = [];
+    for (const b of e.blocks) {
+      if (b.type === "text") parts.push(b.text);
+    }
+    if (parts.length > 0) return parts.join("");
+  }
+  return null;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function eventHtml(e: LogEvent): string {
+  switch (e.t) {
+    case "user":
+      return wrap("user", "user", e.at, e.text);
+    case "guidance":
+      return wrap("event", `harness ${e.reason}`, e.at, e.text);
+    case "assistant":
+      return wrap("assistant", "assistant", e.at, assistantText(e.blocks));
+    case "interrupt":
+      return wrap("event", "interrupt", e.at, `cancelled ${e.user_id}`);
+    case "tool_result":
+      return wrap("tool", `tool_result ${e.ok ? "ok" : "fail"}`, e.at, e.content);
+    case "cut":
+      return wrap("event", "cut", e.at, `${e.reason} → ${e.handoff_ref}`);
+    case "snapshot":
+      return wrap(
+        "event",
+        "snapshot",
+        e.at,
+        [
+          ...Object.keys(e.added).map((p) => `+ ${p}`),
+          ...Object.keys(e.changed).map((p) => `~ ${p}`),
+          ...e.removed.map((p) => `- ${p}`),
+        ].join("\n") || "(no file changes)",
+      );
+    case "rewind":
+      return wrap("event", `rewind ${e.mode}`, e.at, e.prompt);
+    case "spawn":
+      return wrap("event", "spawn", e.at, e.purpose);
+    case "joined":
+      return wrap("event", "joined", e.at, e.summary);
+    case "adopt":
+      return wrap("event", "adopt", e.at, `branch ${e.branch.node}`);
+    case "discard":
+      return wrap("event", "discard", e.at, e.reason);
+    case "claim":
+      return wrap("event", "claim", e.at, e.what);
+    case "decision":
+      return wrap("event", "decision", e.at, `${e.chose} — ${e.because}`);
+    case "pitfall":
+      return wrap("event", "pitfall", e.at, `${e.tried} — ${e.failed_because}`);
+    case "blocked":
+      return wrap("event", "blocked", e.at, `${e.what} — ${e.reason}`);
+    case "question":
+      return wrap("event", "question", e.at, e.text);
+    case "next_action":
+      return wrap("event", "next_action", e.at, `${e.what} → ${e.next_action}`);
+    case "work_status":
+      return wrap("event", `work ${e.operation}`, e.at, `${e.work_id}: ${e.what}`);
+    case "evidence_link":
+      return wrap("event", "evidence link", e.at, `${e.work}: ${e.what} → ${e.source}`);
+    default:
+      return assertNever(e, "eventHtml");
+  }
+}
+
+function assistantText(blocks: readonly AssistantBlock[]): string {
+  const parts: string[] = [];
+  for (const b of blocks) {
+    switch (b.type) {
+      case "text":
+        parts.push(b.text);
+        break;
+      case "thinking":
+        parts.push(b.text);
+        break;
+      case "tool_use":
+        parts.push(`${b.name} ${JSON.stringify(b.input)}`);
+        break;
+      default:
+        return assertNever(b, "assistantText");
+    }
+  }
+  return parts.join("\n");
+}
+
+function wrap(cls: string, kind: string, at: string, text: string): string {
+  return `<article class="event ${cls}"><div class="meta">${escapeHtml(kind)} · ${escapeHtml(at)}</div><pre>${escapeHtml(text)}</pre></article>`;
+}

package/src/core/file-references.ts

@@ -0,0 +1,35 @@
+/** Explicit whitespace-delimited @ references; code literals and emails remain text. */
+export interface FileReference { readonly start: number; readonly end: number; readonly path: string }
+
+export function fileReferences(text: string): FileReference[] {
+  const refs: FileReference[] = [];
+  let codeTicks = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\\") { i++; continue; }
+    if (text[i] === "`") {
+      let end = i;
+      while (text[end] === "`") end++;
+      const count = end - i;
+      if (codeTicks === 0) codeTicks = count;
+      else if (count === codeTicks) codeTicks = 0;
+      i = end - 1;
+      continue;
+    }
+    if (codeTicks > 0 || text[i] !== "@" || (i > 0 && !/\s/.test(text[i - 1]!))) continue;
+    const start = i;
+    let end = i + 1;
+    let path: string;
+    if (text[end] === '"') {
+      const close = text.indexOf('"', end + 1);
+      if (close < 0 || text.slice(end, close).includes("\n")) continue;
+      path = text.slice(end + 1, close);
+      end = close + 1;
+    } else {
+      while (end < text.length && !/\s/.test(text[end]!)) end++;
+      path = text.slice(start + 1, end);
+    }
+    if (path.length > 0) refs.push({ start, end, path });
+    i = end - 1;
+  }
+  return refs;
+}

package/src/core/frontmatter.ts

@@ -0,0 +1,213 @@
+/**
+ * Restricted YAML frontmatter reader.
+ *
+ * Why hand-written instead of a YAML package: the emitter in yaml.ts already
+ * made that call for writes (AGENTS.md cites it as the example). This is the
+ * read side of the same choice. A full parser would pull in aliases, anchors
+ * and tags on a path that reads user and project files.
+ *
+ * Supported: `key: value`, quoted strings, booleans, and `[a, b]` arrays.
+ * Nested mappings and multiline blocks are named and skipped; siblings stay.
+ * The function does not throw — a broken header must not take down startup.
+ */
+
+export type FrontmatterValue = string | boolean | readonly string[];
+
+export interface FrontmatterParse {
+  readonly fields: { readonly [key: string]: FrontmatterValue };
+  readonly body: string;
+  readonly diagnostics: readonly string[];
+}
+
+const KEY = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/;
+const BOOL = /^(?:true|false)$/i;
+
+export function parseFrontmatter(text: string): FrontmatterParse {
+  try {
+    return parseInner(text);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { fields: {}, body: text, diagnostics: [`frontmatter: ${message}`] };
+  }
+}
+
+function parseInner(text: string): FrontmatterParse {
+  const normalized = stripBom(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const extracted = extract(normalized);
+  if (extracted.yaml === null) {
+    return { fields: {}, body: extracted.body, diagnostics: [] };
+  }
+
+  const fields: { [key: string]: FrontmatterValue } = {};
+  const diagnostics: string[] = [];
+  const lines = extracted.yaml.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim().length === 0 || line.trimStart().startsWith("#")) continue;
+
+    if (/^\s/.test(line)) {
+      diagnostics.push(`frontmatter: indented line is not a supported field`);
+      continue;
+    }
+
+    const match = KEY.exec(line);
+    if (!match) {
+      diagnostics.push(`frontmatter: unparseable line ${JSON.stringify(line)}`);
+      continue;
+    }
+
+    const key = match[1]!;
+    const raw = match[2] ?? "";
+
+    if (isNestedMarker(raw)) {
+      diagnostics.push(`frontmatter: nested mapping "${key}" is not supported`);
+      i = skipIndented(lines, i);
+      continue;
+    }
+
+    const parsed = parseValue(raw);
+    if (parsed === undefined) {
+      diagnostics.push(`frontmatter: nested mapping "${key}" is not supported`);
+      i = skipIndented(lines, i);
+      continue;
+    }
+    fields[key] = parsed;
+  }
+
+  return { fields, body: extracted.body, diagnostics };
+}
+
+function extract(text: string): { yaml: string | null; body: string } {
+  if (!text.startsWith("---")) return { yaml: null, body: text };
+  const lines = text.split("\n");
+  if (lines[0] !== "---") return { yaml: null, body: text };
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) return { yaml: null, body: text };
+  return {
+    yaml: lines.slice(1, end).join("\n"),
+    body: lines.slice(end + 1).join("\n").replace(/^\n+/, "").replace(/\s+$/, ""),
+  };
+}
+
+function isNestedMarker(raw: string): boolean {
+  const value = raw.trim();
+  return value.length === 0 || value === "|" || value === "|-" || value === "|+" ||
+    value === ">" || value === ">-" || value === ">+";
+}
+
+function parseValue(raw: string): FrontmatterValue | undefined {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) return undefined;
+  if (trimmed.startsWith("[")) return parseFlowArray(trimmed);
+  if (trimmed.startsWith('"') || trimmed.startsWith("'")) {
+    const quoted = parseQuoted(trimmed);
+    return quoted ?? trimmed;
+  }
+  const unquoted = stripInlineComment(trimmed);
+  if (BOOL.test(unquoted)) return unquoted.toLowerCase() === "true";
+  return unquoted;
+}
+
+/**
+ * Flow arrays of scalars only. A mapping inside the brackets is a nested
+ * structure we refuse, so the caller can name the field and keep going.
+ */
+function parseFlowArray(raw: string): readonly string[] | undefined {
+  if (!raw.startsWith("[") || !raw.endsWith("]")) return undefined;
+  const inner = raw.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  if (inner.includes("{") || inner.includes("[") || /(?:^|,)\s*[A-Za-z_][A-Za-z0-9_-]*\s*:/.test(inner)) {
+    return undefined;
+  }
+  const items: string[] = [];
+  let buf = "";
+  let quote: string | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (quote) {
+      if (quote === "'" && ch === "'" && inner[i + 1] === "'") {
+        buf += "'";
+        i++;
+        continue;
+      }
+      if (ch === quote && (quote === "'" || inner[i - 1] !== "\\")) {
+        quote = null;
+        continue;
+      }
+      buf += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ",") {
+      items.push(buf.trim());
+      buf = "";
+      continue;
+    }
+    buf += ch;
+  }
+  items.push(buf.trim());
+  return items;
+}
+
+function parseQuoted(raw: string): string | undefined {
+  const q = raw[0];
+  if (q !== '"' && q !== "'") return undefined;
+  let out = "";
+  for (let i = 1; i < raw.length; i++) {
+    const ch = raw[i]!;
+    if (q === "'" && ch === "'" && raw[i + 1] === "'") {
+      out += "'";
+      i++;
+      continue;
+    }
+    if (ch === q) {
+      const rest = raw.slice(i + 1).trim();
+      if (rest.length > 0 && !rest.startsWith("#")) return undefined;
+      return out;
+    }
+    if (q === '"' && ch === "\\" && i + 1 < raw.length) {
+      const next = raw[i + 1]!;
+      out += next === "n" ? "\n" : next === "t" ? "\t" : next;
+      i++;
+      continue;
+    }
+    out += ch;
+  }
+  return undefined;
+}
+
+function stripInlineComment(value: string): string {
+  const idx = value.indexOf(" #");
+  return (idx >= 0 ? value.slice(0, idx) : value).trim();
+}
+
+function skipIndented(lines: readonly string[], i: number): number {
+  let j = i + 1;
+  while (j < lines.length) {
+    const next = lines[j]!;
+    if (next.trim().length === 0) {
+      j++;
+      continue;
+    }
+    if (/^\s/.test(next)) {
+      j++;
+      continue;
+    }
+    break;
+  }
+  return j - 1;
+}
+
+function stripBom(text: string): string {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}