semantifold 0.3.0 → 0.4.0

package/src/artifact-path.js

@@ -3,6 +3,7 @@
 import {hasOnlyUnicodeScalars} from "./semantic/scalars.js"
 
 const lineTerminatorPattern = /[\n\r\u2028\u2029]/u
+const portableArtifactComponentPattern = /^[A-Za-z0-9._-]+$/u
 
 /**
  * Validates filename metadata without imposing artifact-set path semantics.
@@ -14,11 +15,11 @@ export function isValidFilenameMetadata(value) {
 }
 
 /**
- * Validates a safe relative POSIX artifact path.
+ * Validates a safe relative POSIX source path while retaining Unicode filename metadata.
  * @param {unknown} value - Candidate path.
  * @returns {value is string} Whether the value is safe.
  */
-export function isSafeArtifactPath(value) {
+export function isSafeSourcePath(value) {
   if (typeof value != "string" || value.length == 0 || value.includes("\\") || value.includes("\0") ||
     !hasOnlyUnicodeScalars(value)) return false
   if (value.startsWith("/") || /^[A-Za-z]:/u.test(value)) return false
@@ -32,3 +33,47 @@ export function isSafeArtifactPath(value) {
       return codePoint != undefined && codePoint > 31 && codePoint != 127
     }))
 }
+
+/**
+ * Validates a safe portable artifact/resource path in the closed ASCII comparison domain.
+ * @param {unknown} value - Candidate path.
+ * @returns {value is string} Whether the value is safe and portably comparable.
+ */
+export function isSafeArtifactPath(value) {
+  return isSafeSourcePath(value) && value.split("/").every(part => portableArtifactComponentPattern.test(part))
+}
+
+/**
+ * Produces a conservative portable comparison key for a validated artifact path.
+ * @param {string} value - Safe relative POSIX path.
+ * @returns {string} Complete ASCII case-fold key.
+ */
+export function portableArtifactPathKey(value) {
+  return value.toLowerCase()
+}
+
+/**
+ * Finds the first unsafe, duplicate, portable case-fold, or file/directory-prefix conflict.
+ * @param {readonly string[]} paths - Ordered candidate artifact paths.
+ * @returns {{kind: "case-fold" | "duplicate" | "prefix" | "unsafe", path: string, other?: string} | null} First conflict.
+ */
+export function findPortableArtifactPathConflict(paths) {
+  /** @type {{key: string, path: string}[]} */
+  const accepted = []
+
+  for (const path of paths) {
+    if (!isSafeArtifactPath(path)) return {kind: "unsafe", path: String(path)}
+    const key = portableArtifactPathKey(path)
+
+    for (const previous of accepted) {
+      if (path == previous.path) return {kind: "duplicate", other: previous.path, path}
+      if (key == previous.key) return {kind: "case-fold", other: previous.path, path}
+      if (key.startsWith(`${previous.key}/`) || previous.key.startsWith(`${key}/`)) {
+        return {kind: "prefix", other: previous.path, path}
+      }
+    }
+    accepted.push({key, path})
+  }
+
+  return null
+}

package/src/artifacts.js

@@ -27,6 +27,9 @@ export function createGeneratedArtifactSet(candidate) {
       invalidArtifactSet("Artifact set requires a non-empty ordered artifact array.", candidate.target)
     }
     const target = candidate.target
+    const metadata = candidate.metadata === undefined
+      ? undefined
+      : snapshotMetadataObject(candidate.metadata, target)
 
     const paths = new Set()
     const directoryPaths = new Set()
@@ -102,6 +105,7 @@ export function createGeneratedArtifactSet(candidate) {
     return Object.freeze({
       artifacts: Object.freeze(artifacts),
       entry: entryPaths[0],
+      ...(metadata === undefined ? {} : {metadata}),
       schema: /** @type {const} */ ("GeneratedArtifactSet"),
       target,
       version: /** @type {const} */ (1)
@@ -113,6 +117,69 @@ export function createGeneratedArtifactSet(candidate) {
   }
 }
 
+/**
+ * Validates target-specific metadata as detached, immutable JSON.
+ * @param {unknown} value - Metadata candidate.
+ * @param {string} target - Artifact target.
+ * @returns {Readonly<Record<string, unknown>>} Metadata snapshot.
+ */
+function snapshotMetadataObject(value, target) {
+  if (!isPlainObject(value)) invalidArtifactSet("Artifact-set metadata must be a plain JSON object.", target)
+
+  return /** @type {Readonly<Record<string, unknown>>} */ (
+    deepFreeze(snapshotMetadataValue(value, target, new WeakSet())))
+}
+
+/**
+ * Recursively snapshots a JSON metadata value without retaining caller objects.
+ * @param {unknown} value - JSON candidate.
+ * @param {string} target - Artifact target.
+ * @param {WeakSet<object>} ancestors - Active object path for cycle rejection.
+ * @returns {unknown} Detached JSON value.
+ */
+function snapshotMetadataValue(value, target, ancestors) {
+  if (value === null || typeof value == "boolean") return value
+  if (typeof value == "string") {
+    if (!hasOnlyUnicodeScalars(value)) invalidArtifactSet("Artifact-set metadata contains a lone Unicode surrogate.", target)
+
+    return value
+  }
+  if (typeof value == "number") {
+    if (!Number.isFinite(value)) invalidArtifactSet("Artifact-set metadata numbers must be finite.", target)
+
+    return value
+  }
+  if (typeof value != "object") invalidArtifactSet("Artifact-set metadata must contain only JSON values.", target)
+  if (ancestors.has(value)) invalidArtifactSet("Artifact-set metadata must not contain cycles.", target)
+  ancestors.add(value)
+
+  if (Array.isArray(value)) {
+    if (!isDenseArray(value)) invalidArtifactSet("Artifact-set metadata arrays must be dense.", target)
+    /** @type {unknown[]} */
+    const result = []
+
+    for (let index = 0; index < value.length; index += 1) result.push(snapshotMetadataValue(value[index], target, ancestors))
+    ancestors.delete(value)
+
+    return result
+  }
+  if (!isPlainObject(value)) invalidArtifactSet("Artifact-set metadata must contain only plain JSON objects.", target)
+  /** @type {Record<string, unknown>} */
+  const result = {}
+
+  for (const key of Object.keys(value).sort()) {
+    Object.defineProperty(result, key, {
+      configurable: true,
+      enumerable: true,
+      value: snapshotMetadataValue(value[key], target, ancestors),
+      writable: true
+    })
+  }
+  ancestors.delete(value)
+
+  return result
+}
+
 /**
  * Validates artifact-level text, byte, or synthetic provenance.
  * @param {unknown} value - Provenance candidate.

package/src/backends/c-validation.js

@@ -73,7 +73,12 @@ export function validateCMemory(module) {
 
         for (const name of lengths.keys()) lengths.set(name, left.get(name) === right.get(name) ? left.get(name) : undefined)
         arena.bytes = leftArena.bytes < rightArena.bytes ? leftArena.bytes : rightArena.bytes
-      } else size(statement.expression, lengths, arena)
+      } else if (statement.kind == "ExpressionStatement" || statement.kind == "PrintStatement" ||
+        statement.kind == "ReturnStatement") {
+        const expression = statement.expression
+
+        if (expression) size(expression, lengths, arena)
+      }
     }
     return lengths
   }

package/src/backends/cpp-validation.js

@@ -51,7 +51,12 @@ class CppValueValidator {
         const right = statement.alternate ? this.block(statement.alternate, sizes) : sizes
 
         for (const name of sizes.keys()) sizes.set(name, left.get(name) === right.get(name) ? left.get(name) : undefined)
-      } else this.size(statement.expression, sizes)
+      } else if (statement.kind == "ExpressionStatement" || statement.kind == "PrintStatement" ||
+        statement.kind == "ReturnStatement") {
+        const expression = statement.expression
+
+        if (expression) this.size(expression, sizes)
+      }
     }
     return sizes
   }

package/src/backends/csharp.js

@@ -168,8 +168,10 @@ function emitStatement(writer, statement, indent, path) {
   if (statement.kind == "LocalDeclaration" || statement.kind == "AssignmentStatement") {
     return emitLocal(writer, statement, indent, path)
   }
+  if (statement.kind == "ExpressionStatement") throw new TypeError("C# Task 005 expression statement reached emission.")
   writer.synthetic(indent, "indentation", [statement], [path])
   if (statement.kind == "ReturnStatement") {
+    if (!statement.expression) throw new TypeError("C# bare return reached emission.")
     writer.mapped("return", {mappingKind: "anchor", node: statement, path})
     writer.synthetic(" ", "return spacing", [statement], [path])
     emitExpression(writer, statement.expression, `${path}/expression`, "csharp", identity)
@@ -185,6 +187,7 @@ function emitStatement(writer, statement, indent, path) {
     writer.synthetic("\n", "line break", [statement], [path])
     return
   }
+  if (statement.kind != "IfStatement") throw new TypeError("Unsupported C# statement reached emission.")
   writer.mapped("if", {mappingKind: "anchor", node: statement, path})
   writer.synthetic(" ", "conditional spacing", [statement], [path])
   writer.mapped("(", {mappingKind: "anchor", node: statement, path})

package/src/backends/dart-runtime.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+export const dartRuntime = `final BigInt _semantifoldMaxSafeInteger = BigInt.from(9007199254740991);
+final BigInt _semantifoldMinSafeInteger = BigInt.from(-9007199254740991);
+
+int _semantifoldInteger(BigInt value) {
+  final _ = _semantifoldIntegerAdd;
+  final _ = _semantifoldIntegerSubtract;
+  final _ = _semantifoldIntegerMultiply;
+  final _ = _semantifoldIntegerNegate;
+  final _ = _semantifoldBoolean;
+  final _ = _semantifoldUse;
+  if (value < _semantifoldMinSafeInteger ||
+      value > _semantifoldMaxSafeInteger) {
+    throw RangeError('Semantifold safe integer overflow');
+  }
+  return value.toInt();
+}
+
+bool _semantifoldBoolean(bool value) {
+  return value;
+}
+
+void _semantifoldUse(Object _) {}
+
+int _semantifoldIntegerAdd(int left, int right) {
+  return _semantifoldInteger(BigInt.from(left) + BigInt.from(right));
+}
+
+int _semantifoldIntegerSubtract(int left, int right) {
+  return _semantifoldInteger(BigInt.from(left) - BigInt.from(right));
+}
+
+int _semantifoldIntegerMultiply(int left, int right) {
+  return _semantifoldInteger(BigInt.from(left) * BigInt.from(right));
+}
+
+int _semantifoldIntegerNegate(int value) {
+  return _semantifoldInteger(-BigInt.from(value));
+}
+`

package/src/backends/dart.js

@@ -0,0 +1,326 @@
+// @ts-check
+
+import {unsupportedCapability} from "../diagnostic.js"
+import {finalizeMapping, toSourceMapV3} from "../mapping.js"
+import {emitExpression, validateBackendModule} from "./shared.js"
+import {dartRuntime} from "./dart-runtime.js"
+import {emitScalarType} from "./scalars.js"
+import {SourceWriter} from "./writer.js"
+
+const pubspec = "name: semantifold_generated\npublish_to: none\nenvironment:\n  sdk: 3.13.3\n"
+const lockfile = "# Generated by pub\n# See https://dart.dev/tools/pub/glossary#lockfile\npackages: {}\nsdks:\n  dart: \"3.13.3\"\n"
+
+/**
+ * Emits one deterministic dependency-free Dart package candidate.
+ * @param {{filename?: string, mapDirective?: unknown, module: import("../semantic/types.js").SemanticModule, sourceMapFilename?: unknown, sources?: {filename: string, content: string, language?: import("../semantic/types.js").SemanticLanguage}[]}} input Backend request.
+ * @returns {{artifacts: import("../semantic/types.js").GeneratedSetArtifact[], target: string}} Candidate artifact set.
+ */
+export function generateDartPackage({filename, mapDirective, module, sourceMapFilename, sources}) {
+  validateBackendModule(module, "dart")
+  if (filename !== undefined && filename != "bin/program.dart") {
+    unsupportedCapability("dart", "artifact filename other than bin/program.dart", module.location)
+  }
+  if (mapDirective !== undefined || sourceMapFilename !== undefined) {
+    unsupportedCapability("dart", "source-map filename or directive option", module.location)
+  }
+  const unreadLocals = findUnreadLocals(module)
+  const writer = new SourceWriter({filename: "bin/program.dart", language: "dart", module, sources})
+
+  emitProgram(module, writer, unreadLocals)
+  const mapping = finalizeMapping(writer.finish())
+  const root = mapping.nodes.find(({path}) => path == "")
+
+  if (!root) throw new Error("Validated Dart module omitted its canonical root provenance.")
+  const relatedOrigins = relatedRootOrigins(root)
+
+  return {
+    artifacts: [{
+      content: pubspec,
+      contentKind: "text",
+      mediaType: "application/yaml",
+      ownership: "generated",
+      path: "pubspec.yaml",
+      provenance: {
+        kind: "synthetic",
+        reason: "Fixed dependency-free Dart 3.13.3 package configuration.",
+        relatedOrigins
+      },
+      role: "manifest"
+    }, {
+      content: lockfile,
+      contentKind: "text",
+      mediaType: "application/yaml",
+      ownership: "generated",
+      path: "pubspec.lock",
+      provenance: {
+        kind: "synthetic",
+        reason: "Deterministic Dart pub lockfile for a package with no dependencies.",
+        relatedOrigins
+      },
+      role: "manifest"
+    }, {
+      content: mapping.generated.content,
+      contentKind: "text",
+      mediaType: "text/x-dart",
+      ownership: "generated",
+      path: "bin/program.dart",
+      provenance: {kind: "text", mapping, sourceMap: toSourceMapV3(mapping)},
+      role: "entry"
+    }],
+    target: "dart"
+  }
+}
+
+/**
+ * Emits the compiler-owned prefix and one complete program.
+ * @param {import("../semantic/types.js").SemanticModule} module Semantic module.
+ * @param {SourceWriter} writer Source-aware writer.
+ * @param {Set<import("../semantic/types.js").LocalDeclaration>} unreadLocals Locals requiring an analyzer-only read.
+ * @returns {void}
+ */
+function emitProgram(module, writer, unreadLocals) {
+  writer.synthetic(dartRuntime, "Checked Dart safe-integer support", [module], [""])
+  for (let index = 0; index < module.functions.length; index += 1) {
+    const declaration = module.functions[index]
+    const path = `/functions/${index}`
+
+    writer.synthetic("\n", "declaration separator", [declaration], [path])
+    writer.mapped(emitScalarType("dart", declaration.returnType), {
+      mappingKind: "exact", node: declaration.returnType, path: `${path}/returnType`, role: "type"
+    })
+    writer.synthetic(" ", "declaration spacing", [declaration], [path])
+    writer.mapped(declaration.name, {mappingKind: "exact", node: declaration, path, role: "name"})
+    const flatParameters = declaration.parameters.map((parameter) =>
+      `${emitScalarType("dart", parameter.type)} ${parameter.name}`).join(", ")
+    const multilineParameters = declaration.parameters.length > 0 &&
+      writer.column - 1 + `(${flatParameters}) {`.length > 80
+
+    writer.mapped("(", {mappingKind: "anchor", node: declaration, path})
+    declaration.parameters.forEach((parameter, parameterIndex) => {
+      const parameterPath = `${path}/parameters/${parameterIndex}`
+
+      if (multilineParameters) {
+        writer.synthetic(`${parameterIndex ? "" : "\n"}  `, "Dart parameter indentation", [parameter], [parameterPath])
+      } else if (parameterIndex) writer.synthetic(", ", "parameter separator", [parameter], [parameterPath])
+      writer.mapped(emitScalarType("dart", parameter.type), {
+        mappingKind: "exact", node: parameter.type, path: `${parameterPath}/type`, role: "type"
+      })
+      writer.synthetic(" ", "parameter spacing", [parameter], [parameterPath])
+      writer.mapped(parameter.name, {mappingKind: "exact", node: parameter, path: parameterPath, role: "name"})
+      if (multilineParameters) writer.synthetic(",\n", "Dart formatter parameter separator", [parameter], [parameterPath])
+    })
+    writer.mapped(")", {mappingKind: "anchor", node: declaration, path})
+    writer.synthetic(" ", "body spacing", [declaration], [path])
+    writer.mapped("{", {mappingKind: "anchor", node: declaration.body, path: `${path}/body`})
+    writer.synthetic("\n", "line break", [declaration], [path])
+    emitBlock(writer, declaration.body, "  ", `${path}/body`, unreadLocals)
+    writer.mapped("}", {mappingKind: "anchor", node: declaration.body, path: `${path}/body`})
+    writer.synthetic("\n", "line break", [declaration], [path])
+  }
+  writer.synthetic("\nvoid main() {\n", "Dart generated main scaffold", [module.entryPoint], ["/entryPoint"])
+  emitBlock(writer, module.entryPoint.body, "  ", "/entryPoint/body", unreadLocals)
+  writer.synthetic("}\n", "Dart generated main scaffold", [module.entryPoint], ["/entryPoint"])
+}
+
+/**
+ * Emits one ordered semantic block.
+ * @param {SourceWriter} writer Source-aware writer.
+ * @param {import("../semantic/types.js").Block} block Semantic block.
+ * @param {string} indent Current indentation.
+ * @param {string} path Exact semantic path.
+ * @param {Set<import("../semantic/types.js").LocalDeclaration>} unreadLocals Locals requiring an analyzer-only read.
+ * @returns {void}
+ */
+function emitBlock(writer, block, indent, path, unreadLocals) {
+  block.statements.forEach((statement, index) =>
+    emitStatement(writer, statement, indent, `${path}/statements/${index}`, unreadLocals))
+}
+
+/**
+ * Emits one Tasks 001-005 statement.
+ * @param {SourceWriter} writer Source-aware writer.
+ * @param {import("../semantic/types.js").Statement} statement Semantic statement.
+ * @param {string} indent Current indentation.
+ * @param {string} path Exact semantic path.
+ * @param {Set<import("../semantic/types.js").LocalDeclaration>} unreadLocals Locals requiring an analyzer-only read.
+ * @returns {void}
+ */
+function emitStatement(writer, statement, indent, path, unreadLocals) {
+  writer.synthetic(indent, "indentation", [statement], [path])
+  if (statement.kind == "LocalDeclaration") {
+    if (!statement.mutable) writer.mapped("final", {mappingKind: "anchor", node: statement, path})
+    else writer.mapped(emitScalarType("dart", statement.type), {
+      mappingKind: "exact", node: statement.type, path: `${path}/type`, role: "type"
+    })
+    writer.synthetic(" ", "local spacing", [statement], [path])
+    if (!statement.mutable) {
+      writer.mapped(emitScalarType("dart", statement.type), {
+        mappingKind: "exact", node: statement.type, path: `${path}/type`, role: "type"
+      })
+      writer.synthetic(" ", "local spacing", [statement], [path])
+    }
+    writer.mapped(statement.name, {mappingKind: "exact", node: statement, path, role: "name"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    writer.mapped("=", {mappingKind: "exact", node: statement, path, role: "operator"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    emitExpression(writer, statement.initializer, `${path}/initializer`, "dart", identity)
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    if (unreadLocals.has(statement)) {
+      writer.synthetic(`${indent}_semantifoldUse(${statement.name});\n`, "Dart analyzer unread-local use", [statement], [path])
+    }
+    return
+  }
+  if (statement.kind == "AssignmentStatement") {
+    writer.mapped(statement.target.name, {mappingKind: "exact", node: statement.target, path: `${path}/target`, role: "name"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    writer.mapped("=", {mappingKind: "exact", node: statement, path, role: "operator"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "dart", identity)
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  if (statement.kind == "IfStatement") return emitIf(writer, statement, indent, path, unreadLocals)
+  if (statement.kind == "ReturnStatement") {
+    writer.mapped("return", {mappingKind: "anchor", node: statement, path})
+    if (statement.expression) {
+      writer.synthetic(" ", "return spacing", [statement], [path])
+      emitExpression(writer, statement.expression, `${path}/expression`, "dart", identity)
+    }
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  if (statement.kind == "PrintStatement") {
+    writer.mapped("print", {mappingKind: "anchor", node: statement, path})
+    writer.mapped("(", {mappingKind: "anchor", node: statement, path})
+    emitExpression(writer, statement.expression, `${path}/expression`, "dart", identity)
+    writer.mapped(");", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  if (statement.kind == "ExpressionStatement") {
+    emitExpression(writer, statement.expression, `${path}/expression`, "dart", identity)
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  throw new TypeError("Unsupported Dart statement reached emission after preflight.")
+}
+
+/**
+ * Emits one strict Boolean conditional.
+ * @param {SourceWriter} writer Source-aware writer.
+ * @param {import("../semantic/types.js").IfStatement} statement Conditional.
+ * @param {string} indent Current indentation.
+ * @param {string} path Exact semantic path.
+ * @param {Set<import("../semantic/types.js").LocalDeclaration>} unreadLocals Locals requiring an analyzer-only read.
+ * @returns {void}
+ */
+function emitIf(writer, statement, indent, path, unreadLocals) {
+  writer.mapped("if", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic(" (", "Dart conditional scaffold", [statement], [path])
+  emitExpression(writer, statement.condition, `${path}/condition`, "dart", identity)
+  writer.synthetic(") ", "Dart conditional scaffold", [statement], [path])
+  writer.mapped("{", {mappingKind: "anchor", node: statement.consequent, path: `${path}/consequent`})
+  writer.synthetic("\n", "line break", [statement], [path])
+  emitBlock(writer, statement.consequent, `${indent}  `, `${path}/consequent`, unreadLocals)
+  writer.synthetic(indent, "indentation", [statement], [path])
+  writer.mapped("}", {mappingKind: "anchor", node: statement.consequent, path: `${path}/consequent`})
+  if (statement.alternate) {
+    writer.synthetic(" else ", "Dart alternate scaffold", [statement], [path])
+    writer.mapped("{", {mappingKind: "anchor", node: statement.alternate, path: `${path}/alternate`})
+    writer.synthetic("\n", "line break", [statement], [path])
+    emitBlock(writer, statement.alternate, `${indent}  `, `${path}/alternate`, unreadLocals)
+    writer.synthetic(indent, "indentation", [statement], [path])
+    writer.mapped("}", {mappingKind: "anchor", node: statement.alternate, path: `${path}/alternate`})
+  }
+  writer.synthetic("\n", "line break", [statement], [path])
+}
+
+/**
+ * Finds scalar locals that Dart would diagnose because no semantic expression reads them.
+ * @param {import("../semantic/types.js").SemanticModule} module Validated semantic module.
+ * @returns {Set<import("../semantic/types.js").LocalDeclaration>} Unread declaration identities.
+ */
+function findUnreadLocals(module) {
+  /** @type {Set<import("../semantic/types.js").LocalDeclaration>} */
+  const unread = new Set()
+
+  for (const root of [...module.functions.map(({body}) => body), module.entryPoint.body]) {
+    /** @type {import("../semantic/types.js").LocalDeclaration[]} */
+    const declarations = []
+    /** @type {Set<string>} */
+    const reads = new Set()
+
+    visitStatements(root, (statement) => {
+      if (statement.kind == "LocalDeclaration") {
+        declarations.push(statement)
+        collectIdentifierReads(statement.initializer, reads)
+      } else if (statement.kind == "IfStatement") collectIdentifierReads(statement.condition, reads)
+      else if (statement.kind == "AssignmentStatement" || statement.kind == "ExpressionStatement" ||
+        statement.kind == "PrintStatement" || statement.kind == "ReturnStatement") {
+        if (statement.expression) collectIdentifierReads(statement.expression, reads)
+      }
+    })
+    for (const declaration of declarations) if (!reads.has(declaration.name)) unread.add(declaration)
+  }
+  return unread
+}
+
+/**
+ * Visits every Tasks 001-005 statement in one semantic body.
+ * @param {import("../semantic/types.js").Block} block Semantic block.
+ * @param {(statement: import("../semantic/types.js").Statement) => void} callback Statement visitor.
+ * @returns {void}
+ */
+function visitStatements(block, callback) {
+  for (const statement of block.statements) {
+    callback(statement)
+    if (statement.kind == "IfStatement") {
+      visitStatements(statement.consequent, callback)
+      if (statement.alternate) visitStatements(statement.alternate, callback)
+    }
+  }
+}
+
+/**
+ * Collects identifier reads without treating assignment targets as reads.
+ * @param {import("../semantic/types.js").Expression} expression Semantic expression.
+ * @param {Set<string>} reads Collected binding names.
+ * @returns {void}
+ */
+function collectIdentifierReads(expression, reads) {
+  if (expression.kind == "IdentifierExpression") reads.add(expression.name)
+  else if (expression.kind == "CallExpression") {
+    for (const argument of expression.arguments) collectIdentifierReads(argument, reads)
+  } else if (expression.kind == "UnaryExpression") collectIdentifierReads(expression.operand, reads)
+  else if (expression.kind == "BinaryExpression") {
+    collectIdentifierReads(expression.left, reads)
+    collectIdentifierReads(expression.right, reads)
+  }
+}
+
+/**
+ * Converts root provenance to artifact-level related origins.
+ * @param {import("../semantic/types.js").SemanticNodeProvenance} root Root provenance.
+ * @returns {import("../semantic/types.js").RelatedOrigin[]} Related roots.
+ */
+function relatedRootOrigins(root) {
+  if (root.origin.kind == "source") {
+    return [{location: root.origin.location, nodeId: root.id, role: "module", sourceId: root.origin.sourceId}]
+  }
+  const origins = root.origin.kind == "derived" ? root.origin.origins : root.origin.relatedOrigins
+
+  return origins.map((origin) => ({...origin, nodeId: origin.nodeId ?? root.id, role: origin.role ?? "module"}))
+}
+
+/**
+ * Returns one prevalidated Dart identifier unchanged.
+ * @param {string} name Validated identifier.
+ * @returns {string} Same identifier.
+ */
+function identity(name) {
+  return name
+}