semantifold 0.9.0 → 0.11.0

package/docs/watch-build-pipeline.md

@@ -2,7 +2,7 @@
 
 ## Status and verified baseline
 
-This document is a roadmap contract, not an implemented CLI contract.
+Tasks 039–042 implement the strict project manifest, stable one-shot snapshot, deterministic generation orchestration, generic non-executing check-plan contract, Java/`javac`, the interpreted/managed cohort, the native/project cohort, human/NDJSON reporting, and packaged `semantifold build [--check]`. Task 043 implements the language-neutral deterministic watch coordinator and `semantifold watch [--check]`; Task 044 proves its packed JavaScript/JSDoc-to-Java checked vertical slice. Task 045 remains the terminal all-text matrix.
 
 The inspected baseline is `semantifold@0.7.0`, annotated tag `v0.7.0`, commit `8cd70c5a6c7de98df2d4a183d6555ad4f3d5ba5a`. At that revision:
 
@@ -11,31 +11,31 @@ The inspected baseline is `semantifold@0.7.0`, annotated tag `v0.7.0`, commit `8
 - `discoverCanonicalToolchain` finds the configured `javac` and `java` executables.
 - `runAcceptanceStages` materializes an artifact set in a temporary directory and runs caller-supplied exact argument arrays with bounded process execution.
 - A bounded direct proof parsed the 2,648-byte JSDoc fixture `spec/fixtures/compatibility/program.js`, generated `Main.java`, compiled it with `javac 25.0.4`, executed it with Java 25.0.4, and observed the canonical output `compat\nbranch-ok!\npresent\nabsent\n7\n2\n3\n5\n4\n`.
-- `package.json` has no `bin` entry. The public API does not persist generated artifacts, load a project manifest, derive compiler arguments from a target, or watch source files.
+- `package.json` had no `bin` entry. The public API did not persist generated artifacts, load a project manifest, derive compiler arguments from a target, or watch source files.
 - The only repository file-change watcher is a test helper; there is no product watch coordinator, incremental dependency graph, event coalescing policy, or long-lived compiler owner.
 
-The released baseline therefore already proves **JavaScript/JSDoc → semantic IR → Java → `javac`** as a one-shot composition. Task 038 now adds the public language-neutral `GeneratedArtifactPublisher`, immutable generation manifests, one atomic active pointer, pointer-once resolution, and journal-bounded recovery described below. Project configuration, target-owned check plans, CLI behavior, and watching remain Tasks 039 and later.
+That historical baseline proved **JavaScript/JSDoc → semantic IR → Java → `javac`** as a one-shot composition. Released `semantifold@0.9.0` supplies Task 038's public language-neutral `GeneratedArtifactPublisher`, immutable generation manifests, one atomic active pointer, pointer-once resolution, and journal-bounded recovery. Task 039 adds the package bin, project configuration, and one-shot CLI behavior; Task 040 productizes the generic plan/runner and Java compiler boundary; Task 041 adds PHP, Ruby, JavaScript, TypeScript, Kotlin/JVM, Python, and C# plans; Task 042 adds Go, C, C++, Rust, Swift, Dart, and Zig plans; Task 043 supplies generic watch coordination; and Task 044 supplies the packed credential-free watch proof and public example.
 
 ## Product outcome
 
-A project can declare explicit source modules, one or more generated targets, one publisher-owned project publication root, target-relative generated/build projections, and whether each target is checked with its real toolchain. It can then run:
+A project can declare explicit source modules, one or more generated targets, one publisher-owned project publication root, and target-relative generated/build projections. The one-shot CLI selects generation-only or all-target developer checking with `--check`. It can then run:
 
-- a planned one-shot `semantifold build`; or
-- a planned long-lived `semantifold watch`.
+- the implemented one-shot `semantifold build`; or
+- the implemented long-lived `semantifold watch`.
 
 For the first end-to-end slice, changing a JSDoc-typed JavaScript source regenerates Java and compiles the staged candidate with `javac`. A successful cycle publishes one coherent generated-source/compiler-output generation through one active-generation pointer switch. A parse, semantic, generation, tool-discovery, compiler, or publication failure reports a located diagnostic, keeps the process alive in watch mode, and leaves the previous successful generation usable. A later valid edit recovers without restarting the watcher.
 
-The architecture is target-neutral. Every current text backend eventually supplies one target-owned check plan. Every current source frontend participates through the existing parser/project APIs; the watcher never contains language syntax logic.
+The architecture is target-neutral. All fifteen text targets supply target-owned plans. Every current source frontend participates through the existing parser/project APIs; the watcher never contains language syntax logic.
 
 ## Architecture boundaries
 
-### Project manifest and loader
+### Project manifest and loader (Task 039 implemented)
 
 A versioned, strict manifest declares ordered source modules and target entries. Source language, module identity, entry identity, target language/role, one project publication root, and each target's generated/check subpaths inside an immutable project generation are explicit. These target paths are logical projections, not independently promoted filesystem roots. Version 1 uses explicit file paths rather than introducing a glob language or package-manager resolution.
 
-The loader owns path normalization and rejects unknown fields, duplicate module/target identities, ambiguous target roles, source/publication overlap, publication roots outside the project root, colliding or nested target projections, and symlink/path traversal across the owned publication root. It returns an immutable project request and never parses language syntax.
+The loader owns path normalization and rejects unknown fields, duplicate module/target identities, ambiguous target roles, source/publication overlap, publication roots outside the project root, colliding or nested target projections, symlink/path traversal across the owned publication root, and registered backend capabilities whose required configuration version 1 cannot express. It returns an immutable project request and never parses language syntax.
 
-### Snapshot builder
+### Snapshot builder (Task 039 implemented for one-shot builds)
 
 Each cycle reads a complete content snapshot of every declared source and the project manifest. File events are hints only. Before parsing, the coordinator re-reads and hashes the declared graph in stable order; it never assumes an event filename is complete or authoritative.
 
@@ -49,26 +49,40 @@ Frontends, semantic validation, linking, and backends remain pure with respect t
 
 `GeneratedArtifactPublisher` stages one complete project candidate as a new immutable generation beneath a dedicated publisher-owned publication directory inside the canonical project root. Every target carries an explicit language-neutral role, and its generated artifacts, mappings, and optional validator/compiler outputs live in generation-relative subtrees on the same filesystem. The publisher validates paths, mappings, hashes, hard-link identities, complete generation inventory, collisions, ownership, and manifests before touching committed state. Its public contract and caller obligations are documented in [transactional generated-artifact publication](generated-artifact-publication.md).
 
-When checking is enabled, target checks run against those staged generation subtrees. Only a fully generated and successfully checked project candidate may be published. The generation manifest is the explicit versioned authority for files the publisher created; it never authorizes mutation outside the publication root.
+When checking is enabled, target checks run against those staged generation subtrees. Each checked invocation owns a fresh immutable candidate identity, including for an unchanged or reverted source snapshot, so it cannot reuse retained compiler output instead of executing the declared checks. Generation-only snapshots retain deterministic same-ID verification and reactivation. Only a fully generated and successfully checked project candidate may be published. The generation manifest is the explicit versioned authority for files the publisher created; it never authorizes mutation outside the publication root.
 
 Publication commits exactly one small active-generation pointer by writing and syncing a sibling temporary pointer, atomically replacing the prior pointer on the same filesystem, and syncing the parent directory before reporting success. A host filesystem that cannot provide atomic same-directory regular-file replacement is rejected before publication; copying, truncating, or rewriting the live pointer in place is never a fallback. Readers resolve that pointer once and consume all generated/build paths from the referenced immutable generation. Configured generated-source and compiler-output names are logical projections returned from that resolved generation; they are never independent directories, symlinks, or manifests promoted one after another. The same rule covers every target in a multi-target cycle.
 
 An interruption before the pointer replacement leaves the previous generation active; an interruption after it leaves either the old or new complete pointer durably recoverable, never a composite state. A recovery journal may finish cleanup of unpublished candidates and temporary pointer files, but it is not used to claim atomicity across multiple filesystem operations. Candidate and temporary-pointer parent directories are synchronized before the proving journal is removed and its directory synchronized. Publication never removes a committed generation, because a reader may already hold its resolved snapshot; committed-generation retention/garbage collection is a separate explicit policy. A failed candidate is removed without changing the active pointer.
 
-### Target check-plan registry
+### Target check-plan registry (Tasks 040–042 implemented)
 
-The existing language registry remains authoritative for target identity, roles, declared acceptance stages, and required toolchain IDs. A planned target-check capability derives exact stage requests from a validated staged artifact set and its generation-scoped target build subtree.
+The existing language registry remains authoritative for target identity, roles, declared acceptance stages, and required toolchain IDs. Its explicit immutable `check` capability distinguishes generation-only targets from Java plus PHP, Ruby, JavaScript, TypeScript, Kotlin/JVM, Python, and C# developer checks without claiming execution. The target-owned factory derives exact stage requests from a validated staged artifact set and its generation-scoped target source/build subtrees.
 
-The generic runner owns process lifecycle, locale/timezone normalization, output capture, timeout/cancellation, and close observation. A target check plan owns filenames, exact argv, toolchain IDs, offline/cache policy, and which stages constitute a non-executing developer check. The watcher does not switch on language IDs.
+The generic runner validates immutable dense argv, complete artifact inputs, restore hashes, candidate-path ownership, exact discovered-tool environment bindings, nullable output ownership, and transient candidate directories before spawn. It owns process lifecycle, locale/timezone normalization, bounded output capture, timeout/cancellation, signal forwarding, first failure, close observation, and post-close transient cleanup. A target check plan owns filenames, exact argv, toolchain IDs, offline/cache policy, and which stages constitute a non-executing developer check. The builder and watcher do not switch on language IDs.
 
-The initial check plan is Java/`javac`. Later tasks add current text targets in two cohorts:
+Java/`javac` compiles every staged `.java` artifact together with `-d` directed at the candidate build subtree and never invokes `java`. Task 041 implements the interpreted/managed cohort:
 
-- interpreted/managed: PHP, Ruby, JavaScript, TypeScript, Kotlin/JVM, Python, and C# (Java is supplied by the initial slice);
-- native/project: Go, C, C++, Rust, Swift, Dart, and Zig.
+- PHP, Ruby, and JavaScript run real syntax checks once per generated language artifact;
+- TypeScript type-checks the complete set with no emit and isolated type roots;
+- Kotlin/JVM compiles all sources together to candidate-owned classes;
+- Python produces deterministic checked-hash bytecode at an explicit candidate build path and never creates source-adjacent `__pycache__`;
+- C# requires its exact producer-owned project, disables ancestor MSBuild props/targets, passes every staged `.cs` file in deterministic order, hashes project/lock restore inputs, restores from a local-only staged source into candidate-owned state, builds with `--no-restore`, and removes cache/home/intermediate state before publishing only `bin/` outputs.
 
-A watch check validates or compiles but does not execute generated application code by default. Restore/download behavior is never an implicit per-edit action; targets with project metadata use pinned, offline, isolated state and rerun prerequisite stages only when their declared inputs change.
+Task 042 implements the remaining cohort:
 
-### Watch coordinator
+- Go disables cgo, workspace/toolchain switching, VCS, and network resolution for its build, then vets read-only with isolated HOME/GOPATH/module/build/temp state.
+- C and C++ compile every translation unit and link through the strict Clang C17 or C++20/libstdc++ `-O0` developer profile. Object/temp state is transient; `-O2` and ASan/UBSan remain explicit CI acceptance profiles rather than watcher branches.
+- Rust accepts only the dependency-free generated Cargo manifest/lock, qualifies both Rustc and Cargo, binds Cargo's `RUSTC` to that exact discovered compiler, runs locked offline build/check with isolated Cargo home/target state, and removes that state before publication.
+- Swift type-checks and compiles with exact driver mode and warnings as errors while isolating home/cache/temp state.
+- Dart validates only the producer-owned dependency-free package/lock through an enforced offline dry run, compiles a native executable, verifies format, and analyzes fatally. The restore hash excludes ordinary source edits; `.dart_tool`, pub/home/temp state, and the absolute-source-URI-bearing native check output are transient.
+- Zig accepts only the producer-owned standard-library-only project, builds Debug with isolated local/global caches and an owned transient prefix, then verifies canonical formatting. Multi-mode builds/tests remain explicit acceptance profiles.
+
+None of these developer plans executes its generated program. A later validator does not hide an earlier declared compiler/linker output, and all candidate transient state is removed after child close on success, failure, timeout, or cancellation.
+
+A watch check validates or compiles but does not execute generated application code by default. A content-identical reconciliation admits no cycle and therefore performs no restore. Every fresh C# candidate uses its declared project/lock hash, generation-specific SDK assets, and local-only package source; it reruns restore without network access because checked generations do not share mutable restore state.
+
+### Watch coordinator (Task 043 implemented)
 
 One lifecycle-aware class owns filesystem subscriptions, content snapshots, cycle state, the active checker child, reporting, and shutdown. Its state machine is:
 
@@ -85,11 +99,13 @@ any live state -- SIGINT/SIGTERM --> stopping --> stopped
 
 `failed` means the last candidate failed; it does not discard the last successful output or terminate watch mode. A watcher event during `building`/`rebuilding` sets one dirty generation marker. The coordinator starts exactly one follow-up after the owned child closes. It never starts a retry while prior compiler work is still live.
 
-Native filesystem events require a bounded reconciliation strategy because Node and TypeScript both document platform-dependent watcher behavior. Version 1 watches the explicit manifest/source files and relevant parent directories, re-scans the declared graph after each hint, supports a documented polling fallback, and suppresses no-op cycles by content hash. The publication root and every generated/build projection are rejected as source roots and are never watched.
+Native filesystem events require a bounded reconciliation strategy because Node and TypeScript both document platform-dependent watcher behavior. Version 1 watches the explicit manifest/source files and their distinct parent directories without recursive watching, filters publisher-owned parent events, re-scans the complete graph after each coalesced hint, supplements native events with a bounded reconciliation interval, switches wholly to polling when native subscription creation or a live watcher fails, and suppresses no-op cycles by content hash. Polling metadata is only a reconciliation hint, and unchanged invalid graphs do not emit repeated failed cycles. The publication root and every generated/build projection are rejected as sources and are never direct subscriptions, preventing publication feedback cycles.
+
+The implemented pre-pointer currentness guard runs only after every target validator/checker has closed. It re-loads and hashes the complete graph; changed content rejects and cleans the stale staged candidate, while one dirty marker admits a single immediate latest-state follow-up. A later event in the narrow guard-to-pointer window cancels publication without cancelling a healthy checker earlier in the cycle.
 
 ### Reporting contract
 
-Human output is concise and stable. A machine-readable mode emits one JSON record per state transition with at least project identity, monotonically increasing cycle number, source snapshot hash, target ID/role, state, timing, changed paths, tool identity, exit status, and a structured diagnostic when present.
+Task 039 human output is concise and stable. Its machine-readable mode emits deterministic state records with project identity, cycle `1`, source snapshot hash, ordered target ID/role/results, exit status, and a structured diagnostic when present. Generation-only records deliberately report state rather than nondeterministic elapsed time. Task 040 checked-stage records add exact tool/process identity and lifecycle timing. Task 043 watch records add stable changed paths, cycle duration, succeeded/failed/recovered/superseded/cancelled classification, one terminal record per admitted cycle, and one separate watcher terminal. Task 044 adds the nonterminal `cycle-dirty` acknowledgement used to synchronize a controlled active-check burst with the coordinator's admitted follow-up ownership.
 
 Exactly one terminal cycle record is emitted per cycle. Process exit is non-zero for failed one-shot builds, but ordinary watch-cycle failures keep the watcher process alive. Startup/configuration failure exits. Signal-driven shutdown forwards cancellation to an active owned child, waits for `close`, removes subscriptions and staging state, and exits once.
 
@@ -115,7 +131,7 @@ Exactly one terminal cycle record is emitted per cycle. Process exit is non-zero
 - the same watcher/materializer/runner code handles every source/target pairing;
 - acceptance uses a bounded matrix: all frontends and all text targets are covered, with the JavaScript/JSDoc-to-Java path plus representative cross-family paths, not a quadratic promise that every semantic feature works for every pair.
 
-Binary and application targets use the same generation watcher only after explicit target policy is defined. Browser Wasm can validate/instantiate in its own lane. Android and Flutter checks are heavier platform builds and must be opt-in rather than an automatic keystroke default. iOS remains generation-only until the separately deferred Apple/Xcode acceptance work is authorized; this roadmap does not reopen Tasks 026 or 027.
+Binary and application targets use the same generation watcher only after explicit target policy is defined. Browser Wasm can validate/instantiate in its own lane. Android and Flutter checks are heavier platform builds and must be opt-in rather than an automatic keystroke default. Direct public iOS generation remains available with explicit configuration, but Task 039 manifest version 1 cannot express that configuration and rejects iOS targets; Apple/Xcode acceptance remains separately deferred. This roadmap does not reopen Tasks 026 or 027.
 
 ## Test strategy
 
@@ -147,7 +163,7 @@ Binary and application targets use the same generation watcher only after explic
                   046 later binary/application policies
 ```
 
-Task 038 is the implemented publication foundation. Tasks 039–045 are the remaining selected text-language delivery chain, with Task 045 as its single terminal acceptance task. Task 046 is a non-blocking later extension.
+Tasks 038–041 and 043–044 are the implemented publication, one-shot project-build, Java plus interpreted/managed checks, watch-orchestration foundation, and first packed checked slice. Tasks 042 and 045 remain the selected text-language check/watch delivery chain, with Task 045 as its single terminal acceptance task. Task 046 is a non-blocking later extension.
 
 ## Non-goals
 

package/docs/zig.md

@@ -26,6 +26,8 @@ Strings are immutable `[]const u8`. Literals borrow static storage; concatenatio
 
 `build.zig` exposes only Zig's standard optimization option and the host target. Acceptance copies validated artifacts to a fresh temporary project, uses distinct empty local/global caches per mode, blocks proxy/package-fetch variables, runs `zig fmt --check src/main.zig build.zig`, `zig build test`, `zig build`, and the installed executable in Debug, ReleaseSafe, and ReleaseFast, and verifies that input artifact hashes never change. Cross-compilation and package dependencies are outside this profile.
 
+The registered Task 042 developer plan accepts only that exact standard-library-only `build.zig` and generated Zig sources. It runs the Debug project build with generation-owned local/global caches and `--prefix`, then `zig fmt --check` over the complete staged set. HOME, TMPDIR, both caches, and the absolute-root-bearing Debug output prefix are removed after close, so no executable leaks or is published. `zig build test` plus build/run in Debug, ReleaseSafe, and ReleaseFast remain explicit acceptance/TensorBuzz profiles rather than automatic watcher branches.
+
 ## Provenance and diagnostics
 
 Function, parameter, local, type, assignment, operator/helper, callee, argument, literal, return, condition, output, and entry-statement occurrences retain exact or anchored semantic provenance in `src/main.zig`. The runtime, arena, output helpers, punctuation, ordered-region markers and signatures, typed ordering temporaries, conditional-right-hand plumbing, necessary unused/unmutated binding scaffolds, and entry shell are synthetic with related semantic origins. `build.zig` has artifact-level synthetic configuration provenance. The embedded Source Map v3 names `src/main.zig`; Zig source-map directives and alternate filenames are rejected.

package/examples/jsdoc-java-watch/expected-output.txt

@@ -0,0 +1,3 @@
+task-044
+5
+enabled

package/examples/jsdoc-java-watch/semantifold.json

@@ -0,0 +1,23 @@
+{
+  "schema": "SemantifoldProject",
+  "version": 1,
+  "id": "jsdoc-java-watch",
+  "publicationRoot": ".semantifold",
+  "sources": [
+    {
+      "id": "main",
+      "path": "src/main.js",
+      "language": "javascript",
+      "entry": true
+    }
+  ],
+  "targets": [
+    {
+      "id": "java-main",
+      "language": "java",
+      "role": "text",
+      "sourceProjection": "targets/java/source",
+      "buildProjection": "targets/java/classes"
+    }
+  ]
+}

package/examples/jsdoc-java-watch/src/main.js

@@ -0,0 +1,21 @@
+/**
+ * @param {number} left
+ * @param {number} right
+ * @returns {number}
+ */
+function add(left, right) {
+  return left + right
+}
+
+/**
+ * @param {boolean} enabled
+ * @returns {string}
+ */
+function label(enabled) {
+  if (enabled) return "enabled"
+  else return "disabled"
+}
+
+console.log("task-044")
+console.log(add(2, 3))
+console.log(label(true))

package/index.js

@@ -17,6 +17,14 @@ export {createCapabilityAuthority} from "./src/semantic/capabilities.js"
 export {languageCapabilities, supportedLanguages} from "./src/language-registry.js"
 export {createGeneratedArtifactSet} from "./src/artifacts.js"
 export {GeneratedArtifactPublisher} from "./src/publication.js"
+export {ProjectManifestLoader, SemantifoldProject} from "./src/project-manifest.js"
+export {ProjectSnapshot, ProjectSnapshotBuilder} from "./src/project-snapshot.js"
+export {ProjectBuilder} from "./src/project-build.js"
+export {parseSemantifoldCliArguments, SemantifoldCli} from "./src/project-cli.js"
+export {ProjectBuildReporter} from "./src/project-reporter.js"
+export {ProjectWatchCoordinator} from "./src/project-watch.js"
+export {ProjectWatchReporter} from "./src/project-watch-reporter.js"
+export {createTargetCheckPlan, TargetCheckRunner} from "./src/target-check.js"
 export {createStdlibContractRegistry, listStdlibModules, resolveStdlibModule} from "./src/semantic/stdlib.js"
 export {createStdlibProviderRegistry, listStdlibProviders} from "./src/stdlib-providers.js"
 export {negotiateStdlibProviders} from "./src/stdlib-negotiation.js"

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "semantifold",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Language-neutral semantic code analysis, transformation, generation, and execution toolkit",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
+  "bin": {
+    "semantifold": "bin/semantifold.js"
+  },
   "exports": {
     ".": {
       "types": "./build/index.d.ts",
@@ -13,7 +16,9 @@
   },
   "files": [
     "build/**",
+    "bin/**",
     "docs/**",
+    "examples/**",
     "index.js",
     "LICENSE",
     "README.md",

package/src/artifact-path.js

@@ -52,18 +52,47 @@ export function portableArtifactPathKey(value) {
   return value.toLowerCase()
 }
 
+/**
+ * Produces a deterministic case-fold comparison key for a validated source path.
+ * @param {string} value - Safe relative POSIX source path.
+ * @returns {string} Unicode case-fold comparison key.
+ */
+export function portableSourcePathKey(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) {
+  return findPortablePathConflict(paths, isSafeArtifactPath, portableArtifactPathKey)
+}
+
+/**
+ * Finds the first unsafe, duplicate, portable case-fold, or file/directory-prefix source conflict.
+ * @param {readonly string[]} paths - Ordered candidate source paths.
+ * @returns {{kind: "case-fold" | "duplicate" | "prefix" | "unsafe", path: string, other?: string} | null} First conflict.
+ */
+export function findPortableSourcePathConflict(paths) {
+  return findPortablePathConflict(paths, isSafeSourcePath, portableSourcePathKey)
+}
+
+/**
+ * Compares paths inside one explicitly selected validation domain.
+ * @param {readonly string[]} paths - Ordered candidate paths.
+ * @param {(value: unknown) => boolean} isSafe - Domain-specific path validator.
+ * @param {(value: string) => string} comparisonKey - Domain-specific portable comparison key.
+ * @returns {{kind: "case-fold" | "duplicate" | "prefix" | "unsafe", path: string, other?: string} | null} First conflict.
+ */
+function findPortablePathConflict(paths, isSafe, comparisonKey) {
   /** @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)
+    if (!isSafe(path)) return {kind: "unsafe", path: String(path)}
+    const key = comparisonKey(path)
 
     for (const previous of accepted) {
       if (path == previous.path) return {kind: "duplicate", other: previous.path, path}

package/src/backends/c-check.js

@@ -0,0 +1,80 @@
+// @ts-check
+
+import path from "node:path"
+import {SemantifoldDiagnostic} from "../diagnostic.js"
+import {
+  checkArtifacts,
+  checkOutput,
+  checkPlan,
+  checkStage,
+  checkTool,
+  environmentPath,
+  pathArgument
+} from "./check-plan.js"
+import {cRuntimeHeader} from "./c-runtime.js"
+
+const compilerFlags = Object.freeze([
+  "--no-default-config", "-std=c17", "-Wall", "-Wextra", "-Werror", "-pedantic-errors", "-Wconversion",
+  "-Wsign-conversion", "-Wshadow", "-Wstrict-prototypes", "-Wmissing-prototypes", "-Wformat=2", "-ftrapv",
+  "-finput-charset=UTF-8", "-fexec-charset=UTF-8", "-fno-color-diagnostics", "-O0"
+])
+
+/**
+ * Constructs C's strict Clang C17 compile/link plan.
+ * @param {import("../language-registry.js").TargetCheckPlanContext} context - Validated candidate context.
+ * @returns {import("../semantic/types.js").TargetCheckPlan} Immutable C plan.
+ */
+export function createCCheckPlan(context) {
+  const tool = checkTool(context, "clang", "c")
+  const artifacts = checkArtifacts(context, artifact => artifact.path.endsWith(".c") || artifact.path.endsWith(".h"),
+    "c", "only staged C translation units and headers")
+  const sources = artifacts.filter(artifact => artifact.endsWith(".c"))
+  const headers = artifacts.filter(artifact => artifact.endsWith(".h"))
+  const support = context.artifacts.artifacts.filter(artifact => artifact.path == "semantifold_runtime.h")
+
+  if (artifacts.length != 2 || sources.length != 1 || sources[0] != path.join(context.sourcePath, "program.c") ||
+    headers.length != 1 || support.length != 1 || support[0].contentKind != "text" || support[0].role != "support" ||
+    support[0].content != cRuntimeHeader) {
+    throw new SemantifoldDiagnostic({code: "INVALID_TARGET_CHECK_PLAN", language: "c",
+      message: "C developer checks require the exact producer-owned translation unit and support header."})
+  }
+  const objects = path.join(context.buildPath, "objects")
+  const temporary = path.join(context.buildPath, "tmp")
+  const environment = {TMPDIR: temporary}
+  const environmentPaths = [environmentPath("TMPDIR", "build")]
+  const objectPaths = sources.map((_, index) => path.join(objects, `${String(index).padStart(6, "0")}.o`))
+  const stages = sources.map((source, index) => {
+    const argv = [...compilerFlags, "-c", source, "-o", objectPaths[index]]
+
+    return checkStage({
+      argv,
+      cwd: context.sourcePath,
+      environment,
+      environmentPaths,
+      inputs: [source, ...headers],
+      output: null,
+      pathArguments: [pathArgument(argv.length - 3, "source"), pathArgument(argv.length - 1, "build")],
+      stage: /** @type {const} */ ("compile"),
+      tool,
+      transientPaths: [objects]
+    })
+  })
+  const binary = path.join(context.buildPath, "semantifold-c")
+  const linkArgv = ["--no-default-config", "-O0", ...objectPaths, "-o", binary]
+
+  stages.push(checkStage({
+    argv: linkArgv,
+    cwd: context.sourcePath,
+    environment,
+    environmentPaths,
+    inputs: objectPaths,
+    output: checkOutput(context.buildPath, "application/x-executable", "linker-output"),
+    pathArguments: [...objectPaths.map((_, index) => pathArgument(index + 2, "build")),
+      pathArgument(linkArgv.length - 1, "build")],
+    stage: "link",
+    tool,
+    transientPaths: [objects]
+  }))
+
+  return checkPlan(context, "c", artifacts, stages)
+}

package/src/backends/check-plan.js

@@ -0,0 +1,147 @@
+// @ts-check
+
+import path from "node:path"
+import {SemantifoldDiagnostic} from "../diagnostic.js"
+import {deterministicEnvironment} from "../toolchains.js"
+
+/**
+ * Resolves one target-declared discovered tool from immutable plan context.
+ * @param {Readonly<{tools: readonly import("../semantic/types.js").DiscoveredToolchain[]}>} context - Plan context.
+ * @param {string} id - Declared toolchain identity.
+ * @param {string} target - Target diagnostic identity.
+ * @returns {import("../semantic/types.js").DiscoveredToolchain} Exact tool.
+ */
+export function checkTool(context, id, target) {
+  const tool = context.tools.find(candidate => candidate.id == id)
+
+  if (!tool) {
+    throw new SemantifoldDiagnostic({
+      code: "INVALID_TARGET_CHECK_PLAN",
+      language: target,
+      message: `Target '${target}' developer checks require the declared '${id}' toolchain.`
+    })
+  }
+
+  return tool
+}
+
+/**
+ * Resolves all staged artifacts matching one target-owned predicate.
+ * @param {Readonly<{artifacts: import("../semantic/types.js").GeneratedArtifactSet, sourcePath: string}>} context - Plan context.
+ * @param {(artifact: import("../semantic/types.js").GeneratedSetArtifact) => boolean} accepts - Target-owned artifact predicate.
+ * @param {string} target - Target diagnostic identity.
+ * @param {string} description - Required artifact description.
+ * @returns {readonly string[]} Ordered absolute artifact paths.
+ */
+export function checkArtifacts(context, accepts, target, description) {
+  const accepted = context.artifacts.artifacts.filter(accepts)
+
+  if (accepted.length == 0 || accepted.length != context.artifacts.artifacts.length) {
+    throw new SemantifoldDiagnostic({
+      code: "INVALID_TARGET_CHECK_PLAN",
+      language: target,
+      message: `Target '${target}' developer checks require ${description}.`
+    })
+  }
+
+  return Object.freeze(accepted.map(artifact => path.join(context.sourcePath, artifact.path))
+    .sort((left, right) => left.localeCompare(right, "en")))
+}
+
+/**
+ * Freezes one closed target-check stage request.
+ * @param {object} input - Complete stage data.
+ * @param {readonly string[]} input.argv - Exact argv.
+ * @param {string} input.cwd - Candidate-owned working directory.
+ * @param {Readonly<Record<string, string | undefined>>} [input.environment] - Target-owned environment additions.
+ * @param {readonly import("../semantic/types.js").TargetCheckEnvironmentPath[]} [input.environmentPaths] - Owned environment paths.
+ * @param {string | null} [input.inputHash] - Restore-input hash when applicable.
+ * @param {readonly string[]} input.inputs - Exact staged inputs read by the tool.
+ * @param {import("../semantic/types.js").TargetCheckOutputOwnership | null} input.output - Produced build ownership.
+ * @param {readonly import("../semantic/types.js").TargetCheckPathArgument[]} input.pathArguments - Owned argv paths.
+ * @param {import("../semantic/types.js").AcceptanceStage} input.stage - Stage identity.
+ * @param {import("../semantic/types.js").DiscoveredToolchain} input.tool - Exact tool.
+ * @param {readonly string[]} [input.transientPaths] - Owned cache/intermediate directories.
+ * @returns {import("../semantic/types.js").TargetCheckStageRequest} Immutable stage.
+ */
+export function checkStage(input) {
+  return Object.freeze({
+    argv: Object.freeze([...input.argv]),
+    cwd: input.cwd,
+    environment: deterministicEnvironment(input.environment ?? {}),
+    environmentPaths: Object.freeze([...(input.environmentPaths ?? [])]),
+    executable: input.tool.executable,
+    inputHash: input.inputHash ?? null,
+    inputs: Object.freeze([...input.inputs]),
+    output: input.output,
+    pathArguments: Object.freeze([...input.pathArguments]),
+    stage: input.stage,
+    tool: input.tool,
+    transientPaths: Object.freeze([...(input.transientPaths ?? [])])
+  })
+}
+
+/**
+ * Freezes one closed target-owned plan.
+ * @param {Readonly<{buildPath: string, projectId: string, sourcePath: string, targetId: string}>} context - Plan context.
+ * @param {string} target - Target identity.
+ * @param {readonly string[]} artifactPaths - Complete staged artifact vector.
+ * @param {readonly import("../semantic/types.js").TargetCheckStageRequest[]} stages - Ordered stages.
+ * @returns {import("../semantic/types.js").TargetCheckPlan} Immutable plan.
+ */
+export function checkPlan(context, target, artifactPaths, stages) {
+  return Object.freeze({
+    artifactPaths,
+    buildPath: context.buildPath,
+    mode: /** @type {const} */ ("developer-check"),
+    projectId: context.projectId,
+    schema: /** @type {const} */ ("SemantifoldTargetCheckPlan"),
+    sourcePath: context.sourcePath,
+    stages: Object.freeze([...stages]),
+    target,
+    targetId: context.targetId,
+    version: /** @type {const} */ (1)
+  })
+}
+
+/**
+ * Freezes one owned argv-path declaration.
+ * @param {number} index - Exact argv index.
+ * @param {"source" | "build"} ownership - Owning candidate subtree.
+ * @param {string} [prefix] - Optional non-path argument prefix.
+ * @returns {import("../semantic/types.js").TargetCheckPathArgument} Immutable declaration.
+ */
+export function pathArgument(index, ownership, prefix) {
+  return Object.freeze({index, ownership, ...(prefix === undefined ? {} : {prefix})})
+}
+
+/**
+ * Freezes one owned environment-directory declaration.
+ * @param {string} name - Exact environment variable.
+ * @param {"source" | "build"} ownership - Owning candidate subtree.
+ * @returns {import("../semantic/types.js").TargetCheckEnvironmentPath} Immutable declaration.
+ */
+export function environmentPath(name, ownership) {
+  return Object.freeze({name, ownership})
+}
+
+/**
+ * Freezes one exact tool-executable environment binding.
+ * @param {string} name - Exact environment variable.
+ * @param {import("../semantic/types.js").DiscoveredToolchain} tool - Exact discovered tool.
+ * @returns {import("../semantic/types.js").TargetCheckEnvironmentPath} Immutable declaration.
+ */
+export function environmentTool(name, tool) {
+  return Object.freeze({name, ownership: /** @type {const} */ ("tool"), tool})
+}
+
+/**
+ * Freezes build-output ownership metadata.
+ * @param {string} buildPath - Exact candidate build root.
+ * @param {string} mediaType - Output media type.
+ * @param {string} role - Language-neutral output role.
+ * @returns {import("../semantic/types.js").TargetCheckOutputOwnership} Immutable ownership.
+ */
+export function checkOutput(buildPath, mediaType, role) {
+  return Object.freeze({mediaType, ownership: /** @type {const} */ ("build"), path: buildPath, role})
+}

package/src/backends/cpp-check.js

@@ -0,0 +1,73 @@
+// @ts-check
+
+import path from "node:path"
+import {SemantifoldDiagnostic} from "../diagnostic.js"
+import {
+  checkArtifacts,
+  checkOutput,
+  checkPlan,
+  checkStage,
+  checkTool,
+  environmentPath,
+  pathArgument
+} from "./check-plan.js"
+
+const compilerFlags = Object.freeze([
+  "--no-default-config", "--driver-mode=g++", "-std=c++20", "-stdlib=libstdc++", "-Wall", "-Wextra", "-Werror",
+  "-pedantic-errors", "-Wconversion", "-Wsign-conversion", "-Wshadow", "-Wformat=2", "-fno-exceptions", "-fno-rtti",
+  "-ftrapv", "-finput-charset=UTF-8", "-fexec-charset=UTF-8", "-fno-color-diagnostics", "-O0"
+])
+
+/**
+ * Constructs C++'s strict Clang C++20/libstdc++ compile/link plan.
+ * @param {import("../language-registry.js").TargetCheckPlanContext} context - Validated candidate context.
+ * @returns {import("../semantic/types.js").TargetCheckPlan} Immutable C++ plan.
+ */
+export function createCppCheckPlan(context) {
+  const tool = checkTool(context, "clangpp", "cpp")
+  const artifacts = checkArtifacts(context, artifact => artifact.path.endsWith(".cpp"), "cpp", "only staged '.cpp' translation units")
+
+  if (artifacts.length != 1 || artifacts[0] != path.join(context.sourcePath, "program.cpp")) {
+    throw new SemantifoldDiagnostic({code: "INVALID_TARGET_CHECK_PLAN", language: "cpp",
+      message: "C++ developer checks require the exact producer-owned 'program.cpp' translation unit."})
+  }
+  const objects = path.join(context.buildPath, "objects")
+  const temporary = path.join(context.buildPath, "tmp")
+  const environment = {TMPDIR: temporary}
+  const environmentPaths = [environmentPath("TMPDIR", "build")]
+  const objectPaths = artifacts.map((_, index) => path.join(objects, `${String(index).padStart(6, "0")}.o`))
+  const stages = artifacts.map((source, index) => {
+    const argv = [...compilerFlags, "-c", source, "-o", objectPaths[index]]
+
+    return checkStage({
+      argv,
+      cwd: context.sourcePath,
+      environment,
+      environmentPaths,
+      inputs: [source],
+      output: null,
+      pathArguments: [pathArgument(argv.length - 3, "source"), pathArgument(argv.length - 1, "build")],
+      stage: /** @type {const} */ ("compile"),
+      tool,
+      transientPaths: [objects]
+    })
+  })
+  const binary = path.join(context.buildPath, "semantifold-cpp")
+  const linkArgv = ["--no-default-config", "--driver-mode=g++", "-stdlib=libstdc++", "-O0", ...objectPaths, "-o", binary]
+
+  stages.push(checkStage({
+    argv: linkArgv,
+    cwd: context.sourcePath,
+    environment,
+    environmentPaths,
+    inputs: objectPaths,
+    output: checkOutput(context.buildPath, "application/x-executable", "linker-output"),
+    pathArguments: [...objectPaths.map((_, index) => pathArgument(index + 4, "build")),
+      pathArgument(linkArgv.length - 1, "build")],
+    stage: "link",
+    tool,
+    transientPaths: [objects]
+  }))
+
+  return checkPlan(context, "cpp", artifacts, stages)
+}