semantifold 0.9.0 → 0.11.0

package/docs/language-support.md

@@ -6,9 +6,9 @@ The immutable registry is authoritative for both dispatch and discovery:
 
 | ID | Frontend | Text backend | Binary backend | Application backend | Interoperability | General functions/calls | Immutable collections | Optional values | Ordered list iteration | Ordered map iteration | Condition-controlled loops | Reference classes | Effects/resources | Closed records | Typed errors | Type parameters/generics | Artifacts | Round trip | Mapping | Acceptance |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `php` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, execute (`php`) |
-| `ruby` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, execute (`ruby`) |
-| `javascript` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, execute (`node`) |
+| `php` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, validate, execute (`php`) |
+| `ruby` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, validate, execute (`ruby`) |
+| `javascript` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, validate, execute (`node`) |
 | `typescript` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, compile, execute (`tsc`, `node`) |
 | `java` | yes | yes | no | no | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | single | yes | rich + v3 | parse, generate, compile, execute (`javac`, `java`) |
 | `kotlin` | yes | yes | no | no | no | no | no | no | no | no | no | no | no | no | no | no | single | yes | rich + v3 | parse, generate, compile, execute (`kotlinc`, `java25`) |
@@ -26,7 +26,33 @@ The immutable registry is authoritative for both dispatch and discovery:
 | `android` | no | no | no | yes | no | no | no | no | no | no | no | no | no | no | no | no | multiple | no | rich text + v3 + byte ranges | generate, compile, validate, instantiate, execute (`android`, TensorBuzz KVM) |
 | `flutter` | no | no | no | yes | no | no | no | no | no | no | no | no | no | no | no | no | multiple | no | rich text + v3 + byte ranges | generate, restore, compile, validate, instantiate, execute (`flutter`, `android`; Android qualified, iOS deferred) |
 
-`languageCapabilities` exposes all nineteen records as frozen data, including `features.generalFunctionsAndCalls`, `features.immutableCollections`, `features.optionalValues`, `features.orderedListIteration`, `features.orderedMapIteration`, `features.conditionControlledLoops`, `features.referenceClasses`, `features.effectfulCapabilitiesAndResources`, `features.closedRecords`, `features.typedErrors`, and `features.typeParametersAndGenerics`. A role or semantic feature is not inferred from another role: browser Wasm has binary/application backends without a frontend or text backend, while `ios`, `android`, and `flutter` have only application backends. None has a source round trip or general interoperability role; Android retains the Kotlin/JVM Tasks 001–004 function subset, while Flutter consumes the independent Dart Tasks 001–005 capability subset and both add resolved Task 010 linkage in their application shells. `supportedLanguages` is the derived list of fifteen records with both frontend and text generation. C#, Go, C, and Zig return two text artifacts; Rust and Dart return three; Wasm returns one binary and three text artifacts; iOS, Android, and Flutter return deterministic multi-artifact application projects. Their callers use `generateArtifactSet()`; the legacy single-artifact APIs reject unavailable roles with `UNSUPPORTED_ROLE`.
+`languageCapabilities` exposes all nineteen records as frozen data, including `features.generalFunctionsAndCalls`, `features.immutableCollections`, `features.optionalValues`, `features.orderedListIteration`, `features.orderedMapIteration`, `features.conditionControlledLoops`, `features.conditionalExpressions`, `features.stringInterpolation`, `features.referenceClasses`, `features.effectfulCapabilitiesAndResources`, `features.closedRecords`, `features.typedErrors`, and `features.typeParametersAndGenerics`. A role or semantic feature is not inferred from another role: browser Wasm has binary/application backends without a frontend or text backend, while `ios`, `android`, and `flutter` have only application backends. None has a source round trip or general interoperability role; Android retains the Kotlin/JVM Tasks 001–004 function subset, while Flutter consumes the independent Dart Tasks 001–005 capability subset and both add resolved Task 010 linkage in their application shells. `supportedLanguages` is the derived list of fifteen records with both frontend and text generation. C#, Go, C, and Zig return two text artifacts; Rust and Dart return three; Wasm returns one binary and three text artifacts; iOS, Android, and Flutter return deterministic multi-artifact application projects. Their callers use `generateArtifactSet()`; the legacy single-artifact APIs reject unavailable roles with `UNSUPPORTED_ROLE`.
+
+## Non-executing developer checks
+
+The immutable `languageCapabilities[].check` descriptor reports target-owned developer checks for all fifteen text targets. It reports only non-executing stage kinds and the exact canonical toolchain IDs; acceptance-stage execution remains separate.
+
+| Target | Check stages and tool | Candidate-owned policy |
+| --- | --- | --- |
+| PHP | `validate` with `php82` | Runs `php -n -l` once for every generated `.php` file. No PHP configuration is loaded and application statements are not executed. |
+| Ruby | `validate` with `ruby` | Runs `ruby --disable=gems -c` once for every generated `.rb` file. It loads neither user gems nor generated application behavior. |
+| JavaScript | `validate` with `node` | Runs `node --check` for every generated `.js` file. Candidate `package.json` manifests are declared inputs, and modules are parsed without evaluation. |
+| TypeScript | `compile` with `tsc` | Type-checks the complete `.ts` set as NodeNext/ES2024 with `--noEmit`, no incremental state, deterministic diagnostics, and a candidate-build-only `typeRoots`; it writes no compiler artifact. |
+| Java | `compile` with `javac` | Compiles every `.java` unit together with `-d` directed at the candidate build root. It never invokes `java`. |
+| Kotlin/JVM | `compile` with `kotlinc` | Compiles every `.kt` input together at language/API 2.4 and JVM target 25 with warnings as errors. Classes go only below candidate `classes/`; owned home/cache/temp directories are removed after the child closes. |
+| Python | `compile` with `python` | Uses isolated Python and `py_compile.compile(..., doraise=True)` with checked-hash invalidation, a stable display filename, and an explicit candidate-build `.pyc` path. No `__pycache__` is written beside source and generated code is not imported. |
+| C# | `restore`, then `compile`, with `dotnet` | Requires the exact producer-owned `Semantifold.csproj`, disables ancestor `Directory.Build.props`/`.targets`, and passes every staged `.cs` path through one deterministic compile-item property. It hashes project/lock restore inputs, restores only from the staged candidate source into isolated state, and builds Release with `--no-restore`; transient state is removed and only `bin/` is published. |
+| Go | `compile`, then `validate`, with `go` | Requires the exact dependency-free `go.mod`, disables cgo, workspace/toolchain switching, VCS lookup, proxies, and checksum/network lookup, then runs trimmed build and read-only vet. HOME, GOPATH, module/build caches, and temp state are candidate-owned and removed; the deterministic binary is published but never run. |
+| C | `compile`, then `link`, with `clang` | Compiles every `.c` unit with the strict Clang C17 warning/encoding/overflow profile at `-O0`, declares every staged header, links the complete object set, removes object/temp state, and publishes only the linked candidate executable. Sanitized and `-O2` variants remain explicit acceptance/CI profiles. |
+| C++ | `compile`, then `link`, with `clangpp` | Compiles every `.cpp` unit with Clang C++20, libstdc++, warnings as errors, no exceptions/RTTI, checked-overflow and UTF-8 flags at `-O0`; it removes object/temp state and publishes only the linked executable. Sanitized and `-O2` variants remain explicit acceptance/CI profiles. |
+| Rust | `compile`, then `validate`, with `cargo` | Accepts only the exact dependency-free Cargo manifest/lock and runs `cargo build --offline --locked` followed by `cargo check --offline --locked`. CARGO_HOME, HOME, temp, and target state are isolated and removed, so no executable, cache lock, or dependency state is published. |
+| Swift | three `compile` stages with `swiftc` | Runs the exact Swift driver mode with warnings-as-errors for type-check, a stable named-module object compile, and native link with the ELF build ID disabled. Object/home/cache/temp state is removed and the byte-stable executable is published without execution. |
+| Dart | `restore`, `compile`, then two `validate` stages with `dart` | Accepts only the exact dependency-free pubspec/lock, hashes only those restore inputs, performs an offline enforced-lock dry run, compiles the selected native executable, verifies formatting, and performs fatal analysis. HOME/PUB_CACHE/temp, candidate `.dart_tool`, and the absolute-source-URI-bearing native output are removed; an unreachable package host protects the offline boundary. |
+| Zig | `compile`, then `validate`, with `zig` | Accepts only the exact standard-library-only `build.zig`, builds Debug through the generated project with candidate local/global caches and prefix, then runs `zig fmt --check`. Caches/home/temp and the root-dependent Debug output prefix are removed, so no executable is published. ReleaseSafe/ReleaseFast and `zig build test` remain explicit acceptance/CI profiles. |
+
+All plans use immutable exact argv, absolute configured executable identities, `C.UTF-8` locale, UTC, no shell, declared artifact inputs, and explicit source/build/environment/transient path ownership. A failed discovery, preparation, restore, validation, compile, link, or cleanup is fatal. Native stdout/stderr remain attached to the structured stage diagnostic, the failed candidate is removed, and the previous active generation remains authoritative. A trailing validator does not discard a preceding compiler's declared output. A content-identical watch reconciliation admits no build cycle and therefore performs no restore. Fresh C# candidates restore generation-specific SDK assets locally; Dart performs only an enforced-lock offline dry run whose identity excludes ordinary `.dart` edits. Candidate source/build transient paths are removed only after every child closes.
+
+The version-1 project manifest still admits complete-program text generation only for PHP, Ruby, JavaScript, TypeScript, and Java. Tasks 041–042 add the other ten target plans for validated single-module artifact sets without broadening that semantic project-generation boundary. Those plans use the same public `createTargetCheckPlan` and `TargetCheckRunner`; adding those languages to complete-program manifests is separate semantic-language work.
 
 ## Task 026 iOS application generation
 
@@ -291,7 +317,7 @@ Operands evaluate left to right, and Boolean and/or short-circuit. Conditions re
 
 Integer literals are restricted to JavaScript's safe integer range, `Number.MIN_SAFE_INTEGER` through `Number.MAX_SAFE_INTEGER`, and semantic integers have one unsigned mathematical zero. JavaScript and TypeScript can form IEEE-754 `-0` through negation or multiplication, so generated modules containing either operation stringify their scalar print argument to render both zero signs as `0`; the parser recognizes and removes only this exact entry-point scaffold during reparse. Supported operations cannot otherwise observe a zero sign, and the semantic expression tree is neither rewritten nor folded. Java generation additionally requires primitive-`int` literals and rejects compile-time-known add/subtract/multiply/negate results outside `-2147483648` through `2147483647`. Kotlin emits uppercase-`L` literals, rejects statically known results outside the semantic safe range, and checks dynamic integer arithmetic through `Math.*Exact` plus the safe bound. C# source requires canonical decimal `long` literals with `L`; generation rejects known integer operation trees outside signed 64-bit and emits checked arithmetic. Go source uses canonical decimal `int64`-representable literals; generation rejects compile-time-known operation trees outside signed 64-bit. These checks use exact arithmetic without replacing the semantic expression tree. Runtime arithmetic outside the portable range fails in Kotlin/C# and retains native wrap behavior only in Go.
 
-String literals normalize to their parser-decoded Unicode scalar value. Original quotes and escapes are not retained. PHP and Ruby interpolation, JavaScript/TypeScript template substitution, Java text blocks, PHP heredoc/nowdoc, invalid source encodings, and lone surrogate values are rejected. Backends use target-specific escaping for quotes, backslashes, controls, Unicode, and interpolation introducers. Generated source reparses to the same value.
+String literals normalize to their parser-decoded Unicode scalar value. Original quotes and escapes are not retained. Task 048 lowers PHP double-quoted interpolation, Ruby `#{}` interpolation, and JavaScript/TypeScript template substitution to checked string concatenation of pre-rendered `string`-typed parts in the cohort; PHP short ternaries, heredoc/nowdoc, Java text blocks, invalid source encodings, and lone surrogate values remain rejected. Backends use target-specific escaping for quotes, backslashes, controls, Unicode, and interpolation introducers. Generated source reparses to the same value.
 
 Ruby accepts zero or more required positional parameters. Optional, rest, post, keyword, keyword-rest, and block parameters remain unsupported. Its parameter annotations followed by one return annotation must form the contiguous block immediately before their function. PHP rejects every `declare` form other than one optional exact `declare(strict_types=1)`. Python rejects default, positional-only, keyword-only, variadic, keyword, and starred parameters/calls, quoted or compound annotations, bytes/f-strings/raw/triple/implicitly concatenated strings, decorators, imports, classes, comprehensions, lambdas, attributes, subscripts, and every other dynamic form. Java calls remain unqualified and `main` may not contain ignored statements. C# rejects ref/out/in/scoped/params/default parameters, named/ref arguments, generics, overloads, instance/qualified calls, lambdas/delegates, async/iterators, unsafe code, casts, interpolation/raw/verbatim strings, boxing, `dynamic`, LINQ, and every form outside the exact direct two-argument call and recognized print scaffold. Go rejects variadics, named/multiple/missing results, generic parameters, methods/receivers, qualified or non-two-argument calls, closures, raw/rune/imaginary/float literals, arrays/slices/maps/structs/interfaces/channels/pointers, `defer`, `go`, `select`, conversions, assertions, selectors, indexing, reflection, cgo, and `unsafe`.
 
@@ -303,6 +329,14 @@ Wasm consumes the same validated Tasks 001–004 modules but is not an implement
 
 Binary/application generation returns `program.wasm`, `program.wasm.map`, `semantifold-loader.mjs`, and sole entry `index.html`. The versioned `semantifold.browser.v1` ABI imports only three scalar print functions and exports exactly `memory` and zero-parameter `run`. The loader has no DOM import, allocator import, WASI, memory growth, or semantic JavaScript fallback. See the [complete Browser WebAssembly target contract](webassembly.md).
 
+## Task 048 conditional expressions and string interpolation
+
+PHP, Ruby, JavaScript with JSDoc, TypeScript, and Java expose `conditionalExpressions: true`; PHP, Ruby, JavaScript, and TypeScript additionally expose `stringInterpolation: true`. The canonical `ConditionalExpression {kind, condition, consequent, alternate, type, location}` evaluates its strict-Boolean condition exactly once and evaluates exactly one arm. Semantic validation requires an exact semantic Boolean condition (`NON_BOOLEAN_CONDITION` otherwise), infers each arm independently under the same presence-narrowing applied to `IfStatement` branches, and requires both arms to resolve to one joined type (`TYPE_MISMATCH` at the alternate arm otherwise); the joined type is recorded on the node. Presence narrowing from the condition applies to both arms.
+
+The parser-backed source profile accepts only ordinary ternary forms: `$a ? $b : $c` in PHP, `a ? b : c` in Ruby, JavaScript/TypeScript, and Java. PHP short ternaries (`$a ?: $b`), Ruby statement-position ternaries and modifier forms, nullish `??`, optional/safe navigation (`?.`, `&.`, `?->`), range literals, and general casts/assertions remain located `UNSUPPORTED_SYNTAX` rejections in every language. The five cohort backends emit the matching native parenthesized `(condition ? consequent : alternate)` directly from validated semantic nodes with anchor/operator/colon rich mappings; every other registered target rejects a `ConditionalExpression` with located `UNSUPPORTED_CAPABILITY` before returning source, bytes, or partial artifact sets.
+
+Task 048 adds no new IR node for interpolation. PHP double-quoted interpolation, Ruby `#{}` interpolation, and JavaScript/TypeScript template substitution with substitutions lower in the frontend to a left-associated `StringConcat` binary spine over pre-rendered parts: literal segments become `StringLiteral` nodes and every interpolated segment must already be a `string`-typed expression (`INVALID_OPERAND_TYPE` at the segment otherwise; no implicit coercion). Empty literal segments collapse, a single-part template lowers to its plain expression, and no-substitution templates remain `StringLiteral` nodes. Heredoc/nowdoc, tagged templates, and Java text blocks remain rejected. Backends emit the lowered tree through the existing concatenation spellings unchanged. See the [expression breadth ADR](adr-expression-breadth.md) for the per-construct accept/reject matrix.
+
 ## Diagnostics and limitations
 
 ### Bounded standard-library portability
@@ -319,7 +353,7 @@ All fifteen frontends preserve exact input content and parser-backed semantic to
 
 `UNSUPPORTED_LANGUAGE` is exclusive to unknown or misspelled IDs. `UNSUPPORTED_ROLE` reports a known ID without the requested frontend, text/binary/application backend, artifact, or interoperability role, including C#, Go, C, Rust, Dart, and Zig through a legacy single-artifact API. `UNSUPPORTED_CAPABILITY` reports a role that exists but cannot represent the requested semantic module or target feature. `UNSUPPORTED_SYNTAX` reports parsed constructs outside the subset with the best parser-provided source location. Missing public annotations use `MISSING_TYPE`; a present unsupported type is `UNSUPPORTED_SYNTAX` at that annotation. Parser failures use `PARSE_ERROR`. Semantic resolution/type failures use `DUPLICATE_BINDING`, `UNRESOLVED_BINDING`, `USE_BEFORE_DECLARATION`, `IMMUTABLE_ASSIGNMENT`, and `TYPE_MISMATCH`; Task 005 additionally uses `VOID_AS_VALUE`, `VOID_RETURN_VALUE`, and `MISSING_RETURN_VALUE`. Task 033 adds `DUPLICATE_CLASS`, `DUPLICATE_PRIVATE_FIELD`, `DUPLICATE_CONSTRUCTOR`, `DUPLICATE_METHOD`, `INCOMPLETE_INITIALIZATION`, `ILLEGAL_PRIVATE_ACCESS`, `UNKNOWN_CLASS`, `INVALID_METHOD_RECEIVER`, `UNKNOWN_METHOD`, `CONSTRUCTOR_ARITY_MISMATCH`, and `METHOD_ARITY_MISMATCH`. Task 034 adds `MISSING_CAPABILITY_AUTHORITY`, `INVALID_CAPABILITY_AUTHORITY`, `UNDECLARED_EFFECT`, `UNDECLARED_FAILURE`, `INVALID_EFFECT_ORDER`, `RESOURCE_TYPE_MISMATCH`, `RESOURCE_MOVE_REQUIRED`, `INVALID_RESOURCE_TRANSFER`, `RESOURCE_ALIAS`, `INVALID_RESOURCE_BORROW`, `BORROW_ESCAPE`, `USE_AFTER_MOVE`, `USE_AFTER_CLOSE`, `RESOURCE_STATE_MISMATCH`, `LEAKED_RESOURCE`, and `FAILURE_ABSENCE_CONFLATION`; a repeated close in the bounded probe uses its declared terminal failure rather than `DOUBLE_CLOSE`. Task 035 adds `STDLIB_CONTRACT_INVALID`, `STDLIB_MODULE_UNKNOWN`, `STDLIB_OPERATION_UNDECLARED`, `STDLIB_VERSION_INCOMPATIBLE`, `STDLIB_VERSION_MALFORMED`, `STDLIB_PROVIDER_INVALID`, `STDLIB_PROVIDER_MISSING`, `STDLIB_PROVIDER_AMBIGUOUS`, `STDLIB_PROVIDER_DEPENDENCY_MISSING`, `STDLIB_PROVIDER_CYCLE`, `STDLIB_LINK_FAILURE`, and `STDLIB_NAME_COLLISION`. Task 036 adds `STDLIB_FACADE_INVALID`, `STDLIB_FACADE_IDENTITY_UNPROVED`, `STDLIB_FACADE_MEMBER_UNSUPPORTED`, `STDLIB_FACADE_VERSION_MALFORMED`, `STDLIB_FACADE_VERSION_INCOMPATIBLE`, `STDLIB_FACADE_DYNAMIC_REFERENCE`, `STDLIB_FACADE_REFLECTION_UNSUPPORTED`, `STDLIB_FACADE_NATIVE_EXTENSION_UNSUPPORTED`, `STDLIB_FACADE_SHADOWED`, `STDLIB_FACADE_REOPENED`, `STDLIB_FACADE_AUTHORITY_FORGED`, `STDLIB_FACADE_NAME_COLLISION`, `STDLIB_FACADE_DECLARATION_MISMATCH`, and `STDLIB_FACADE_DESCRIPTOR_INVALID`; Task 037 additionally uses `STDLIB_PROTECTED_BINDING_ACCESS` for portable attempts to reach canonical operations directly. Resolution failures retain parser locations, while descriptor/link failures are transactional. Flow failures use `NON_BOOLEAN_CONDITION`, `MISSING_RETURN`, `UNREACHABLE_STATEMENT`, `ILLEGAL_RETURN_CONTEXT`, `ILLEGAL_BREAK_CONTEXT`, `ILLEGAL_CONTINUE_CONTEXT`, `INVALID_LOOP_TARGET`, `CROSS_FUNCTION_LOOP_TARGET`, and `UNSUPPORTED_STATEMENT`. Backends validate complete recursive block shape, flow, scalar payloads, binding/type agreement, call resolutions, mutability, loop context, identifiers, target bounds, and fixed artifact contracts before emission. Missing or structurally invalid caller IR reports located `UNSUPPORTED_CAPABILITY` rather than leaking a native error or producing partial source. A non-`Main.java` Java basename, non-`Program.cs` C# filename, non-`main.go` Go filename, non-`program.c` C filename, non-`src/main.rs` Rust filename, non-`bin/program.dart` Dart filename, or non-`src/main.zig` Zig filename uses that same contract. Artifact-set generation requires a non-empty string language/target ID and accepts only the explicit `text`, `binary`, and `application` backend-role strings; malformed IDs or roles report `INVALID_ARTIFACT_SET` without coercing caller input, while an unknown string ID reports `UNSUPPORTED_LANGUAGE` and a valid role absent from a known registry record reports `UNSUPPORTED_ROLE`. Optional registry roles and backend metadata may be omitted with `undefined`; present malformed values, including `null`, report `INVALID_REGISTRY`. Invalid registry, artifact-set, byte-map, discovery, and runner inputs have their own normalized diagnostics rather than leaking native type or subprocess errors.
 
-Boxed or coercive types, inferred public types, TypeScript literal/enum/`any`/`unknown`/arbitrary-union types, PHP aliases or implicit nullable declarations, Ruby `boolish`, Java `Boolean`/`char`, universal null values, floating point, decimal, bigint, symbols, regex values, byte strings, and interpolation are unsupported. Division, remainder, exponentiation, bitwise/shift/update/compound operations, Ruby/PHP `and`/`or`, loose equality, ternary/nullish forms, optional/safe navigation, ranges, general casts/assertions, collection/object equality, operator overloading, implicit coercion, and constant folding are also excluded; the sole assertion exception is Task 006's exact TypeScript `Map#get(...)!` wrapper, whose lookup must be independently total. Task 007 supplies only the exact explicit optional model, Task 008 only exact ordered list loops, Task 010 only explicit supplied source projects, Task 011 only the exact nominal unchecked-error model above, Task 012 only the exact unbounded invariant generic profile above, Task 014 only the exact ordered-map pair loop above, Task 032 only the exact strict-Boolean precondition loop above, Task 033 only the exact closed reference-class profile above, and Task 034 only the explicit single-module probe effect/resource profile above. There is no truthiness, implicit-return or general statement-value model, async/generator model, open/inherited/virtual class model, implicit import discovery, post-condition/basic/range loops, arbitrary or ordinary-map iteration, switches, exception behavior beyond Task 011 and declared Task 034 failures, overloads, advanced generic/effect type systems, implicit resource cleanup, unsafe native handles, package-manager resolution, or source-format preservation. The sole value-free expression statements are resolved void function and method calls in the original-five cohort. Ruby type comments remain a bounded RBS-style convention rather than a full signature parser, and single-module Java generation retains the fixed `Main.java` contract.
+Boxed or coercive types, inferred public types, TypeScript literal/enum/`any`/`unknown`/arbitrary-union types, PHP aliases or implicit nullable declarations, Ruby `boolish`, Java `Boolean`/`char`, universal null values, floating point, decimal, bigint, symbols, regex values, and byte strings are unsupported. Task 048 admits exactly two expression families: strict-Boolean conditional (ternary) expressions in the original-five cohort, and parser-proved string interpolation in PHP, Ruby, JavaScript, and TypeScript lowered to checked `StringConcat` concatenation of pre-rendered parts with `string`-typed segments only. Division, remainder, exponentiation, bitwise/shift/update/compound operations, Ruby/PHP `and`/`or`, loose equality, nullish forms, optional/safe navigation, ranges, general casts/assertions, collection/object equality, operator overloading, implicit coercion, and constant folding are also excluded; the sole assertion exception is Task 006's exact TypeScript `Map#get(...)!` wrapper, whose lookup must be independently total. Task 007 supplies only the exact explicit optional model, Task 008 only exact ordered list loops, Task 010 only explicit supplied source projects, Task 011 only the exact nominal unchecked-error model above, Task 012 only the exact unbounded invariant generic profile above, Task 014 only the exact ordered-map pair loop above, Task 032 only the exact strict-Boolean precondition loop above, Task 033 only the exact closed reference-class profile above, Task 034 only the explicit single-module probe effect/resource profile above, and Task 048 only the exact cohort ternary and interpolation lowering above. There is no truthiness, implicit-return or general statement-value model, async/generator model, open/inherited/virtual class model, implicit import discovery, post-condition/basic/range loops, arbitrary or ordinary-map iteration, switches, exception behavior beyond Task 011 and declared Task 034 failures, overloads, advanced generic/effect type systems, implicit resource cleanup, unsafe native handles, package-manager resolution, or source-format preservation. The sole value-free expression statements are resolved void function and method calls in the original-five cohort. Ruby type comments remain a bounded RBS-style convention rather than a full signature parser, and single-module Java generation retains the fixed `Main.java` contract.
 
 CPP uses its own [C++20 scalar and scaffold profile](cpp.md), official CPP grammar, one `program.cpp`, by-value owned strings and checked arithmetic. The shared native occurrence planner is backend-only; CPP owns its exact marker and CST recognizer. Native O0/O2 and ASan/UBSan/leak execution are mandatory.
 

package/docs/parser-qualification.md

@@ -356,7 +356,7 @@ The community grammar required an install-safe modern Node package boundary, so
 | ABI and Node24 API | Grammar ABI 14 and optional peer `tree-sitter@^0.25.1` match exact root binding 0.25.1. ESM import, `Parser#setLanguage`, the real native binding, typed `nodeTypeInfo`, deterministic parse, and exhaustive `child(index)` traversal pass on Node 24.18.1. |
 | Coordinates and recovery | The binding reports UTF-16 code-unit indexes for JavaScript strings. Astral/CRLF probes distinguish them from UTF-8 bytes; the adapter verifies every boundary through the shared converter. Malformed operands and strings expose propagated error/missing nodes. Package headers and file annotations remain visible. Lone surrogates reject before adaptation. |
 | Tasks001-004 CST corpus | Five fixtures cover top-level functions/main, parameters and explicit scalar types, `val`/`var`, assignment, calls/arguments/printing, returns, all scalar literals/operators, nested/one-armed/fallthrough conditionals, comments, and named/anonymous leaves. Every modeled shape and every excluded child is consumed or rejected; no source scan supplies missing structure. |
-| Compiler differential | Exact development identity `info: kotlinc-jvm 2.4.20 (JRE 25.0.4+7-1-26.04-Ubuntu)` compiled original and regenerated fixtures with `-language-version 2.4 -api-version 2.4 -jvm-target 25 -Werror -include-runtime`, and OpenJDK 25.0.4+7 executed every JAR with exact output. The bootstrap admits only the qualified Ubuntu 24.04 or 26.04 compiler-reported suffix because it reflects the active image release, while TensorBuzz retains its exact Noble JDK package pin and exact `openjdk version "25.0.4" 2026-07-21` runtime assertion. Valid Kotlin outside the profile is deliberately rejected by the adapter. |
+| Compiler differential | Exact development identity `info: kotlinc-jvm 2.4.20 (JRE 25.0.4+7-1-26.04-Ubuntu)` compiled original and regenerated fixtures with `-language-version 2.4 -api-version 2.4 -jvm-target 25 -Werror -include-runtime`, and OpenJDK 25.0.4+7 executed every JAR with exact output. The bootstrap admits only the qualified Ubuntu 24.04 or 26.04 compiler-reported suffix because it reflects the active image release, while TensorBuzz pins its exact Noble JDK package and exact `openjdk version "25.0.4.1" 2026-08-18` runtime assertion. Valid Kotlin outside the profile is deliberately rejected by the adapter. |
 | Packed consumer | The root tarball leaves the grammar unbundled and root `acceptDependencies` restricted to the exact private runtime. A fresh credential-free consumer resolves the full-SHA archive with lock integrity and passes install, full listing, clean `npm ci`, strict API typing, grammar loading, Kotlin round trip, and real JAR execution with no Git or SSH lock entry. |
 
 The accepted base/scalars/locals/operators/statements hashes are `b843c4672a3175fe75297f3692003cec0131eaee39e65ba1867f61e6184b0f05`, `42fd2c427a31d3d0b9427faf7781a7e7604399c370701203d06d2d54ceaea7f5`, `52b74e0e8dcca0f2baff9cddf1b035b0e31afa85edd5b7bf1e2dfb220967d615`, `90def0da9e20025e079d72b50722533d1f7223b1ba3cdbffa630b41c5fc9bc72`, and `bf4b05a00eafb1dbeaaabf7c2e7fea0cd8e034f4d3ff3b6e9fea177c31162aeb`. Run `npx velocious-test spec/kotlin-parser-qualification.spec.js`, `npx velocious-test spec/kotlin-native-execution.spec.js`, and the packed-consumer spec for the retained proof.

package/docs/project-build-cli.md

@@ -0,0 +1,147 @@
+# Project manifest and one-shot build CLI
+
+Task 039 adds a strict filesystem boundary above the existing `parseProgram`, `generateProgramArtifactSet`, and `GeneratedArtifactPublisher` APIs. Tasks 040–042 compose the registered developer-check boundary without moving target behavior into the CLI. A build reads one explicit source graph, parses and links it once, generates every ordered target from that semantic program, and makes the complete immutable generation active with one pointer replacement. Ordinary `build` remains generation-only; `build --check` invokes only target-owned non-executing plans. Neither mode executes generated code.
+
+## `semantifold.json` version 1
+
+The manifest is closed JSON: every object rejects unknown fields. The project file's containing directory is the project root.
+
+```json
+{
+  "schema": "SemantifoldProject",
+  "version": 1,
+  "id": "jsdoc-java-example",
+  "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/build"
+    }
+  ]
+}
+```
+
+Root fields are:
+
+- `schema`: exactly `SemantifoldProject`.
+- `version`: exactly `1`.
+- `id`: a stable lowercase project ID matching `[a-z][a-z0-9-]*`.
+- `publicationRoot`: one canonical project-relative portable path owned by the publisher.
+- `sources`: a non-empty ordered array of explicit modules.
+- `targets`: a non-empty ordered array of explicit generated targets.
+
+Each source has exactly `id`, `path`, `language`, and Boolean `entry`. Module IDs are stable logical Task-010 identities. Paths are project-relative source paths; languages are explicit registered frontends that participate in the complete-program profile. All modules use one source-language compatibility profile, paths and IDs are unique, and exactly one module has `entry: true`. Extensions never select a language.
+
+Each target has exactly `id`, `language`, `role`, `sourceProjection`, and optional `buildProjection`. The role is `text`, `binary`, or `application` and must match both the language registry and an implemented complete-program backend. The existing original-five text program backends are supported. A registered single-module target is not automatically a project target; complete-program binary generation is not implemented. Android and Flutter application backends may participate through their default, asset-free requests. iOS requires caller-supplied application identity and deployment configuration that version 1 cannot express, so an iOS application target fails at manifest loading with `UNSUPPORTED_PROJECT_TARGET`; direct public iOS generation with explicit configuration remains supported. This does not define Task 046 watch/check policy.
+
+`sourceProjection` is required. `buildProjection` owns checker/compiler output and defaults to `targets/<target-id>/build`. Both are logical paths inside one immutable generation, never separately promoted output roots. A generation-only build leaves the build projection empty. PHP, Ruby, JavaScript, TypeScript, Rust, Dart, and Zig developer checks leave it empty; Dart 3.13.3 embeds the candidate's absolute source URI, while Zig Debug output retains its absolute project root, so those real native check outputs are removed. Java and Kotlin record class files, Python records its explicit checked-hash `.pyc`, C# records only final `bin/`, and Go/C/C++/Swift record their linked or compiled developer executable after transient restore/intermediate/cache/home/object/target state is removed.
+
+Version 1 has no globs, extension inference, package resolution, environment expansion, configuration callbacks, plugins, shell hooks, commands, target-specific compiler settings, or independent output roots.
+
+## Paths and ownership
+
+Manifest paths use `/`, contain no empty, dot, or dot-dot segment, and are neither absolute nor drive-qualified. Source paths may use valid Unicode scalar filenames, including spaces; their duplicate, prefix, and Unicode case-fold comparisons remain in that source-path domain. Publication and projection paths separately retain the portable ASCII artifact alphabet. Portable source aliases, duplicate module/target IDs, hard-linked source aliases, and colliding or nested projections are rejected.
+
+The manifest, every source, and every existing publication-root component must be real nonsymlink paths under the canonical project root. The publication root cannot contain a source or be a source. Source files may live directly in the project root because the publisher protects their exact paths rather than treating the entire parent directory as source-owned. `GeneratedArtifactPublisher` rechecks source/publication separation and symlink ownership before publication.
+
+The publisher owns only:
+
+```text
+<publicationRoot>/
+  active-generation.json
+  generations/<generation-id>/
+    manifest.json
+    <target source projection>/...
+    <target build projection>/...
+```
+
+Readers resolve `active-generation.json` once and retain the returned immutable generation paths for the whole read. They must not combine paths resolved from separate pointer reads.
+
+## Snapshot and build semantics
+
+`ProjectSnapshotBuilder` reads the exact manifest and all declared source files in manifest order. Descriptor identity, size, modification state, real paths, and exact bytes are checked, and the complete graph is read twice. One inconsistent graph receives one bounded retry. Continued mutation fails with a project-relative `UNSTABLE_PROJECT_SNAPSHOT`; a changed manifest is never combined with the already-validated project value.
+
+The SHA-256 snapshot hash is length-framed over the exact manifest bytes and ordered source IDs, paths, languages, and UTF-8 content. Absolute host paths and wall-clock values are absent. The generation-only ID is `g-<snapshot-hash>`. Each checked invocation uses `g-<snapshot-hash>-checked-<uuid>` for its fresh candidate, so generation-only and compiler-bearing manifests never alias and compiler output produced by one validation run is never mistaken for a later run.
+
+`ProjectBuilder` parses and links the frozen sources once. It generates targets in manifest order through the existing program backend dispatch. With `check: true`, each target must advertise an immutable developer-check capability. The builder discovers exactly that capability's toolchains and attaches a publisher validator; the validator constructs the target-owned plan only after generated artifacts exist in the candidate source subtree. The generic `TargetCheckRunner` validates the complete plan before spawning, owns timeout/cancellation and bounded output, and settles on child `close`. The builder propagates the same cancellation authority through publication, where it is rechecked immediately before the atomic pointer replacement. Only after every target succeeds and cancellation remains inactive does the publisher replace `active-generation.json` once. A configuration, read, parse, link, semantic, generation, discovery, plan, check, cancellation, or pre-pointer publication failure leaves the prior active generation authoritative.
+
+Java's target-owned plan declares only stage `compile` and toolchain `javac`, even though full acceptance metadata also declares later `java` execution. It passes `-d <candidate-build-root>` followed by every staged `.java` artifact. Task 041 adds target-owned PHP `-n -l`, Ruby `--disable=gems -c`, Node `--check`, TypeScript no-emit, Kotlin/JVM class compilation, isolated checked-hash Python bytecode, and offline-isolated C# restore/build plans. Task 042 adds target-owned Go build/vet, strict C/C++ compile/link, Cargo locked/offline build/check, Swift type-check/compile, Dart offline lock verification/compile/format/analyze, and Zig build/format plans. The generic plan declares every staged input, every argv/environment path owner, optional restore-input SHA-256, nullable output ownership, and candidate source/build transient directories that the runner removes only after children close. It publishes the last declared compiler/linker output even when a later non-producing validator succeeds. No generic builder, runner, reporter, CLI, or watcher branch switches on a language ID.
+
+The version-1 project manifest continues to support complete-program text generation only for PHP, Ruby, JavaScript, TypeScript, and Java. Consequently `build --check` can select all five original-language targets immediately; the Task 041–042 Kotlin/Python/C#/Go/C/C++/Rust/Swift/Dart/Zig plans are public and use the same runner for existing generated single-module artifact sets, but do not expand semantic program generation. C# accepts only the exact producer-owned `Semantifold.csproj`, disables ancestor directory-build imports through global properties at restore and compile, and supplies the complete sorted `.cs` set through the manifest's closed compile-item property. Its restore declares a length-framed hash of ordered project/lock content, uses only the staged source root as its package source, and writes packages, HTTP cache, CLI home, user home, temp, and MSBuild intermediates under the candidate build root. Those transient paths are deleted after compile or failure. Dart similarly accepts only its exact dependency-free package/lock, length-frames that restore identity, and removes `.dart_tool`, isolated pub state, and its native check output before publication. Zig removes its root-dependent Debug prefix with the same post-close transient cleanup. An unchanged watch reconciliation admits no cycle, so it cannot perform a restore.
+
+Rebuilding identical generation-only inputs uses the same exact candidate comparison as retained-generation reactivation. If the same deterministic generation is retained but another generation is active, the publisher requires its canonical manifest bytes to equal the validator-free candidate exactly and revalidates the complete inventory, hashes, provenance, symlink boundaries, and hard-link identities before one atomic pointer replacement reactivates it. Task 038 intentionally forbids reactivation requests that carry validators, so a retained same-ID candidate with validators fails with `PUBLICATION_UNOWNED_CONFLICT` instead of trusting previously produced compiler output. Checked builds therefore submit a fresh immutable identity on every invocation and actually rerun every target check, including unchanged and reverted snapshots. A mismatched or malformed retained generation is neither overwritten nor removed, and the previous pointer remains authoritative.
+
+## Command and output
+
+The public package installs one executable:
+
+```sh
+semantifold build
+semantifold build --check
+semantifold build --project path/to/semantifold.json
+semantifold build --project path/to/semantifold.json --check --ndjson
+```
+
+The default is `./semantifold.json`. `build`, `--project <path>`, `--check`, and `--ndjson` are the complete grammar. Options may appear once. Unknown commands/options, missing option values, duplicate options, and positional extras fail with `INVALID_CLI_ARGUMENTS`. The executable passes argument arrays directly to the importable CLI; it does not spawn a shell.
+
+Human mode prints one concise success line only after the active pointer names the committed generation. Failures retain the outer build/publication diagnostic and render each nested Semantifold cause. A check-process failure then prints labeled project/target, tool, stage, exit/signal, duration, and bounded stdout/stderr evidence without repeating its cause line; tool discovery failures instead retain actionable missing, ambiguous, executable, and version details from their nested diagnostics. SIGINT or SIGTERM after a checker closes but before pointer replacement produces one failure terminal record, never a success record. Exit status is `0` only for a committed generation and `1` for the first failure.
+
+`--ndjson` writes one `SemantifoldBuildEvent` version-1 JSON object per line. Every record has `cycle: 1`, `project`, and `state`. Successful builds emit these deterministic states in order:
+
+```json
+{"cycle":1,"project":"jsdoc-java-example","schema":"SemantifoldBuildEvent","version":1,"state":"project-loaded"}
+{"cycle":1,"project":"jsdoc-java-example","schema":"SemantifoldBuildEvent","version":1,"snapshotHash":"<sha256>","state":"snapshot-loaded"}
+{"cycle":1,"project":"jsdoc-java-example","schema":"SemantifoldBuildEvent","version":1,"artifactCount":1,"language":"java","role":"text","state":"target-generated","target":"java-main"}
+{"cycle":1,"project":"jsdoc-java-example","schema":"SemantifoldBuildEvent","version":1,"exitCode":0,"generationId":"g-<sha256>","snapshotHash":"<sha256>","state":"succeeded","targets":[{"artifactCount":1,"id":"java-main","language":"java","role":"text"}],"terminal":true}
+```
+
+There is exactly one record with `terminal: true`. Failure records use `state: "failed"`, `exitCode: 1`, and a stable structured diagnostic. Generation-only records remain deterministic; checked-stage records add the observed lifecycle duration required for process reporting.
+
+Checked builds insert one `target-checked` record per successful stage after `target-generated`. It contains the exact `argv`, target and language, stage, canonical tool ID/command/executable/source/version, exit code or signal, bounded stdout/stderr, and duration. The terminal record includes `checked: true`. Check failures retain the outer publication context and a nested compiler diagnostic rather than flattening away stage/tool/process evidence.
+
+## JavaScript/JSDoc to Java example
+
+Create `src/main.js`:
+
+```js
+/**
+ * @param {number} left
+ * @param {number} right
+ * @returns {number}
+ */
+function add(left, right) {
+  return left + right
+}
+
+console.log(add(2, 3))
+```
+
+Copy the manifest above to `semantifold.json`, then run:
+
+```sh
+npx semantifold build
+npx semantifold build --check
+```
+
+Resolve `.semantifold/active-generation.json` once; the checked generation from this manifest contains Java at `targets/java/source/semantifold/generated/main/Main.java` and compiler output at `targets/java/build/semantifold/generated/main/Main.class`. The two paths belong to the same immutable generation and are never promoted separately. Omitting `buildProjection` instead selects `targets/<target-id>/build`.
+
+`build --check` checks or compiles but never runs generated application behavior. Acceptance code may explicitly invoke committed output afterward. Tasks 043–044 compose the same builder through the packed `semantifold watch --check` JavaScript/JSDoc-to-Java workflow; see [deterministic project watch](project-watch.md) and the shipped [`examples/jsdoc-java-watch`](../examples/jsdoc-java-watch/) project. The terminal all-text acceptance matrix remains Task 045. No build or watch mode garbage-collects committed generations or implements hot reload.
+
+## Importable API and diagnostics
+
+`ProjectManifestLoader`, `SemantifoldProject`, `ProjectSnapshotBuilder`, `ProjectSnapshot`, `ProjectBuilder`, `ProjectBuildReporter`, `ProjectWatchCoordinator`, `ProjectWatchReporter`, `SemantifoldCli`, `parseSemantifoldCliArguments`, `createTargetCheckPlan`, and `TargetCheckRunner` are public ESM exports. `languageCapabilities[].check` truthfully exposes immutable `supported`, `stages`, and `toolchains` fields without claiming execution. The executable is only a thin wrapper around `SemantifoldCli`.
+
+Plan and lifecycle failures use `UNSUPPORTED_TARGET_CHECK`, `INVALID_TARGET_CHECK_PLAN`, `TARGET_CHECK_PREPARATION_FAILURE`, `TARGET_CHECK_LAUNCH_FAILURE`, `TARGET_CHECK_OUTPUT_LIMIT`, `TARGET_CHECK_TIMEOUT`, `TARGET_CHECK_CANCELLED`, `TARGET_CHECK_SIGNAL`, `TARGET_CHECK_NONZERO_EXIT`, `TARGET_CHECK_CLEANUP_FAILURE`, and `TARGET_CHECK_OUTPUT_INVALID`. Restore failures retain stage `restore`; compiler failures retain stage `compile`. Discovery retains `TOOL_NOT_FOUND`, `TOOL_AMBIGUOUS`, and version diagnostics. Publisher validation remains the transaction boundary and preserves the check diagnostic as its structured cause.
+
+Manifest/snapshot diagnostics include `INVALID_PROJECT_MANIFEST`, `INVALID_PROJECT_PATH`, `PROJECT_SOURCE_ALIAS`, `PROJECT_SOURCE_PUBLICATION_OVERLAP`, `PROJECT_PROJECTION_COLLISION`, `PROJECT_SYMLINK_TRAVERSAL`, `PROJECT_MANIFEST_READ_FAILED`, `PROJECT_SOURCE_READ_FAILED`, `INVALID_PROJECT_SOURCE_ENCODING`, `UNSUPPORTED_PROJECT_SOURCE`, `UNSUPPORTED_PROJECT_TARGET`, and `UNSTABLE_PROJECT_SNAPSHOT`. Registry, parser, semantic, backend, artifact, and publication diagnostics retain their existing codes and causes. User output uses project-relative locations and does not print unrelated absolute host paths.

package/docs/project-watch.md

@@ -0,0 +1,60 @@
+# Deterministic project watch
+
+Task 043 adds one language-neutral, long-lived coordinator above the existing project snapshot, build/check, and transactional publication contracts. Task 044 proves its first packed checked vertical slice from JavaScript/JSDoc through generated Java and real `javac`. The coordinator accepts filesystem events only as hints, re-reads the complete explicit manifest/source graph, serializes complete cycles, and never executes generated programs.
+
+## Commands
+
+```sh
+semantifold watch
+semantifold watch --project config/semantifold.json
+semantifold watch --check
+semantifold watch --check --ndjson
+```
+
+`watch` accepts the same single `--project`, `--check`, and `--ndjson` options as `build`. Generation-only watch works for every target accepted by the version-1 project manifest. `--check` additionally requires every configured target to advertise a target-owned non-executing developer-check plan. PHP, Ruby, JavaScript, TypeScript, and Java are check-capable among the manifest's existing complete-program text targets; the registry also exposes Kotlin/JVM, Python, and C# plans for their existing generated single-module artifact sets. Neither command runs generated application code.
+
+The coordinator installs `SIGINT` and `SIGTERM` handlers before loading the initial graph and immediately performs cycle 1. Invalid startup configuration or a failed initial build terminates watch with status 1. Once the initial cycle succeeds, an ordinary source, semantic, generation, discovery, check, or pre-commit publication failure emits a failed cycle and keeps watch alive. The next successful candidate is reported as recovered. Clean signal shutdown returns status 0.
+
+## Events, reconciliation, and cycle ownership
+
+The native backend subscribes to every declared source file, the manifest, and their distinct parent directories. Exact parent-event filenames are mapped to declared graph paths, unknown non-publication events conservatively request a complete reconciliation, and writes identified beneath the publisher-owned root are ignored. Parent subscriptions make deletion, recreation, rename, and editor-style atomic replacement observable without relying on recursive Linux watching.
+
+If initial subscription, live watching, or topology resubscription fails, the coordinator closes the complete native subscription set, reports the transition, and switches once to bounded polling. A 1,000 ms reconciliation interval also backs native subscriptions so event loss can be detected. It compares mutation-sensitive state only to decide when to re-read the complete graph and never treats timestamps as build identity; after an invalid graph, the first successful recovery probe preserves one existing quiet timer instead of postponing it on every shorter polling interval. A changed hint starts a 50 ms quiet window. The public `ProjectWatchCoordinator` constructor permits bounded `quietPeriodMs` values from 1 through 10,000 and `pollIntervalMs` values from 1 through 60,000 for embedding and focused tests. The CLI uses the defaults.
+
+After the quiet window, `ProjectManifestLoader` and `ProjectSnapshotBuilder` re-read the complete graph in stable manifest order. The versioned complete content/configuration hash is authoritative. A touch or event burst whose final hash is unchanged does not admit a cycle. Create, change, delete, rename, and replacement hints never select a partial event filename as the compilation input.
+
+Only one cycle and one checker child can be owned at a time. A hint during a cycle sets one dirty marker; it does not terminate a healthy compiler. After every target checker has closed, the builder invokes a complete-snapshot currentness guard at the publisher's pre-pointer boundary. Changed content supersedes and cleans the staged candidate without replacing `active-generation.json`; one immediate follow-up then owns the latest complete state. A hint in the narrow interval after that guard cancels publication before pointer replacement. After a pointer commit, mutation-sensitive state is compared with the pre-cycle polling baseline: a newer state marks the active cycle dirty and is never absorbed as a clean baseline merely because its native event was lost. A committed pointer still selects exactly one immutable generation, and readers continue to resolve it once.
+
+In NDJSON mode, the first hint admitted while a cycle remains active emits nonterminal `state: "cycle-dirty"`. This acknowledges that the coordinator owns one latest-state follow-up; it does not claim that an event filename is a complete input or that its bytes have already been snapshotted. Further hints in the same active cycle collapse into that one dirty generation.
+
+## Failure, reporting, and shutdown
+
+Human output identifies succeeded, failed, recovered, superseded, and cancelled cycles. NDJSON uses `SemantifoldWatchEvent` version 1. State records carry the project, cycle, complete snapshot hash when available, stable changed paths, ordered target/check evidence, and durations. Every admitted cycle emits exactly one record with `terminal: true` and `terminalScope: "cycle"`; shutdown emits exactly one separate watcher terminal with `terminalScope: "watch"`.
+
+Parse or generation failure never starts a checker. Tool/check failure and stale-candidate refusal never switch the active pointer. Failed candidates are removed through the existing publication ownership journal, while all committed generations remain immutable and retention remains an external policy.
+
+On `SIGINT`, `SIGTERM`, or `ProjectWatchCoordinator.stop(reason)`, the coordinator stops admitting cycles, closes every subscription and timer, awaits any in-progress startup read before terminal settlement, aborts the exact active build/check authority, waits for the owned child process group to reach `close`, waits for publisher staging cleanup, emits the watcher terminal once, and resolves. Startup rechecks stop ownership after each asynchronous boundary, so it cannot subscribe, schedule, or report after terminal shutdown. Generated programs are not started, hot-reloaded, or stopped because watch never executes them.
+
+## Importable API and boundaries
+
+`ProjectWatchCoordinator` and `ProjectWatchReporter` are public ESM exports. The coordinator composes `ProjectManifestLoader`, `ProjectSnapshotBuilder`, `ProjectBuilder`, target-owned check plans, and `GeneratedArtifactPublisher`; it contains no language IDs, parser logic, compiler argument construction, or artifact writes.
+
+The coordinator and generic check runner contain no target-language switch. Target-owned modules construct exact PHP, Ruby, Node, TypeScript, Java, Kotlin/JVM, Python, and C# requests; the runner owns their processes and transient candidate state. Native/project text-target plans remain Task 042, their terminal matrix remains Task 045, and binary/application watch policy remains Task 046. Watch adds no globs, ignore language, daemon mode, editor protocol, runtime execution, hot reload, arbitrary hooks, network access, or package installation.
+
+## Copy-ready JavaScript/JSDoc-to-Java watch
+
+The npm package includes [`examples/jsdoc-java-watch`](../examples/jsdoc-java-watch/). Copy that directory outside `node_modules`, enter it, and run:
+
+```sh
+npx semantifold watch --check
+```
+
+The example manifest explicitly selects `src/main.js`, JavaScript, one Java text target, `targets/java/source`, and `targets/java/classes`. Its JSDoc-typed functions cover numeric and Boolean/string control behavior, and `expected-output.txt` records the output used by acceptance. Cycle 1 prints a line of this form only after real `javac` has closed successfully and the pointer has switched:
+
+```text
+Watch cycle 1 succeeded: project 'jsdoc-java-watch' published generation 'g-<snapshot-sha256>-checked-<uuid>'.
+```
+
+An unambiguous supported `javac` must be available on `PATH`, or `SEMANTIFOLD_JAVAC` must name its absolute configured executable. Missing `javac` fails the declared check; watch never silently changes to generation-only operation. Real `java` is not required by watch because watch does not execute generated code. The Task 044 acceptance harness separately discovers real `java`, resolves `active-generation.json` once, verifies the selected manifest/source/class hashes, and executes only that committed class snapshot.
+
+Saving a valid edit produces a later successful generation. Touching the source without changing content reports no cycle. A located JavaScript/JSDoc parse or semantic error never invokes `javac`; a real compiler error at the generic staged check boundary never switches the pointer. Both failures keep a previously successful watcher alive, and the next valid edit reports recovery. Edits admitted during an active check emit `cycle-dirty` in NDJSON, allow the owned child to close, refuse its stale candidate, and run one latest-state follow-up without overlapping compiler processes. `SIGINT` or `SIGTERM` during idle or checking closes subscriptions and the exact checker process before the sole watcher terminal.

package/docs/rust.md

@@ -86,3 +86,7 @@ Tests also execute each built binary directly, distinguish build diagnostics fro
 Focused product specs cover Tasks001–004 round trips, all 18 operations, strings and ownership, branch/order/divergence behavior, both build modes and every overflow, real rustc E0382/E0505 source rejection, native execution at the generated nesting boundary, malformed IR/helper adversaries, deterministic artifacts and rich/V3 forward/reverse mappings around Unicode. Rust fixtures execute in all original-five native targets, and one original-five source per profile executes in Rust in both modes. Task025 owns the expanded-cohort matrix.
 
 The root packed-consumer proof repeats ordinary npm install and clean npm ci with separate fresh caches, empty configuration files, default install-links=false, isolated modern/legacy runtimes, strict TypeScript and native offline Rust in both modes. The local lane still has the complete home mounted: this proves cleaned-environment behavior, not the external source/home/auth-free boundary. Disposable acceptance inputs and exact local evidence are prepared for the coordinator to run across that boundary before delivery. Local testing uses individual focused files sequentially; TensorBuzz owns full/native aggregate acceptance.
+
+## Non-executing developer check
+
+The registered Task 042 plan accepts only the exact producer-owned dependency-free `Cargo.toml`, `Cargo.lock`, and Rust sources. It qualifies both canonical Rustc and Cargo 1.98.1, binds `RUSTC` to the exact discovered compiler even when the tools occupy different directories, and runs `cargo build --offline --locked --target-dir <candidate>` followed by `cargo check --offline --locked --target-dir <candidate>`. CARGO_HOME, HOME, TMPDIR, incremental state, and the target tree are isolated below the candidate build root and removed after both children close, so no dependency, cache lock, or executable is published or run. Debug/release execution remains explicit acceptance coverage.

package/docs/swift.md

@@ -42,3 +42,5 @@ Discovery uses canonical command `/usr/bin/swiftc` after image construction or a
 The Dockerfile selects official image `swift:6.3.3-noble@sha256:56ef1be2c1ca36f4c52440357dc1fcdfdb5e113587134fcadeef57c225c71b54`; its Linux/amd64 child manifest is `sha256:4e0fc24f0f93a5cf9a91bfcf182534bbc0571d70d757389c04ff1f616c1c460f`. A source stage probes the identity and copies only Swift executable/resource paths into the unchanged final `ubuntu:26.04@sha256:3131b4cc82a783df6c9df078f86e01819a13594b865c2cad47bd1bca2b7063bb` stage. It does not copy project source or replace the final `/usr` tree wholesale.
 
 Real acceptance independently materializes each original parser fixture and regenerated `program.swift` in a fresh directory, runs `swiftc -warnings-as-errors -typecheck`, compiles once without optimization and once with `-O`, executes both binaries, checks exact UTF-8 stdout/stderr/status, verifies source bytes are unchanged, and removes the directory. Its deterministic PATH places the resolved compiler directory first, the canonical host-tool directory `/usr/bin` second, and the isolated caller PATH last with first-occurrence deduplication, so archive Swift selects its own compiler companions while Clang can launch the host linker. The rebuilt canonical image passed this exact Swift 6.3.3 x86_64 contract; `spec/swift-native-execution.spec.js` is 6/6.
+
+The registered Task 042 developer plan uses the same explicit driver mode and warnings-as-errors profile for `-typecheck`, then compiles the stable `SemantifoldGenerated` module to a relative object inside a generation-owned transient directory and links generation-owned `semantifold-swift` with the nondeterministic ELF build ID disabled. This avoids the driver's randomized temporary object path entering Swift's module hash, so repeated candidates produce identical executable bytes. The object directory, HOME, XDG cache, and TMPDIR are removed after close. The developer plan never runs the executable; debug and `-O` execution remain explicit acceptance profiles.

package/docs/testing.md

@@ -1,5 +1,39 @@
 # Testing
 
+## Task 044 packed JavaScript/JSDoc-to-Java watch slice
+
+`jsdoc-java-watch-packed-consumer.spec.js` performs the complete Task 044 proof from a real root tarball after ordinary credential-free install and clean `npm ci`, each with default `install-links=false`, an empty user/global npm configuration, a fresh cache, the public registry, full dependency listing, and strict public API typing. One long-lived packed `watch --check --ndjson` process uses an exact-argv test-owned configured compiler boundary that delegates to canonical real `javac`. Event and process markers—not timing sleeps—drive valid edits, no-op touch suppression, a located frontend failure, one controlled invalid staged-Java compiler failure, recovery, dirty-during-check burst supersession, and idle/active signal shutdown. Every successful cycle resolves the active pointer once, verifies manifest and artifact hashes/provenance, and invokes canonical real `java` only from the acceptance harness. Missing `javac`, overlap, leakage, a changed last-good byte, or a missing tool is a failure, never a skip.
+
+Run it as one focused file:
+
+```sh
+npx velocious-test spec/jsdoc-java-watch-packed-consumer.spec.js
+```
+
+## Task 040 target check plans and Java compiler publication
+
+Task 040 uses focused plan, process-lifecycle, real project transaction, CLI, registry/public-API, and packed-consumer specs. `target-check-plan.spec.js` owns immutable capability/plan schema, exact Java argv, target-declared stage/tool validation, generation-only rejection, path ownership, dense immutable arguments/environment, and the developer execution prohibition. `target-check-runner.spec.js` owns launch, non-zero, output-limit, timeout, cancellation, child-signal, late-output, and close-only settlement behavior without timing sleeps. `project-java-check.spec.js` compiles a real two-unit JavaScript/JSDoc → semantic IR → Java project into the generation-scoped build subtree, executes committed classes only in acceptance code, and proves repeated and A→B→A checked builds rerun real `javac`, exact reverted source/class bytes, missing/ambiguous `javac`, invalid Java, pre-pointer failure, exact last-good bytes, cleanup, and recovery. CLI coverage owns strict `--check`, stage/tool/process reporting, nested compiler and tool-discovery diagnostics, the no-execution boundary, and deterministic cancellation after checker close but before pointer replacement with exact last-good source/class preservation. The packed-consumer proof repeats ordinary install and clean `npm ci` with scrubbed credentials/configuration, public declaration use, real package bin/`javac`, committed class resolution, and explicit post-build `java` execution.
+
+Real Java proofs require canonical `javac` and `java`; absence is a failure, never a skip. Run these focused files individually with `npx velocious-test <file>`. Broad discovery and the complete toolchain matrix remain TensorBuzz-owned.
+
+## Task 039 project manifest and one-shot build CLI
+
+Task 039 uses four focused real-filesystem specs plus the public API and nearby publication regression. Manifest coverage owns the closed schema, registered complete-program roles, identities, entry selection, portable paths, source/publication separation, projection collisions, hard-link aliases, and symlink roots. Snapshot coverage owns deterministic ordered hashing and bounded real-file mutation. Build coverage owns one-file JavaScript/JSDoc-to-Java, Task-010 multi-file/multi-target publication, one parse and pointer commit, project-root source ownership, and late-target atomic failure. CLI coverage owns the original generation-only strict arguments, human/NDJSON terminal truth, and exit status. Task 040 extends rather than replaces these proofs.
+
+Run the focused files individually and sequentially:
+
+```sh
+npx velocious-test spec/project-manifest.spec.js
+npx velocious-test spec/project-snapshot.spec.js
+npx velocious-test spec/project-build.spec.js
+npx velocious-test spec/project-cli.spec.js
+npx velocious-test spec/project-cli-packed-consumer.spec.js
+npx velocious-test spec/generated-artifact-publication.spec.js
+npx velocious-test spec/public-api.spec.js
+```
+
+These tests generate and publish source artifacts only. They do not run `javac`, execute generated output, discover packages, or watch files.
+
 ## Task 005 general function signatures and calls
 
 Task 005 stays bounded to PHP, Ruby, JavaScript with JSDoc, TypeScript, and Java. `general-function-signatures-and-calls.spec.js` proves equivalent zero-, one-, and three-parameter signatures, complete signature collection, nested calls, terminating recursion, scalar/void returns, and the stable semantic failures. `general-function-frontend-validation.spec.js` owns the excluded parameter, call, method, receiver, dispatch, annotation, overload, generic, and higher-order source forms. `general-function-backend-validation.spec.js` proves generation/reparse, exact external-IR signature revalidation, target conflicts, the public feature flag, and transactional rejection from every deferred Task 025/Wasm target. `general-function-provenance-and-mapping.spec.js` proves deterministic declaration/resolution identities and exact signature/call mappings. `general-function-runtime-execution.spec.js` invokes real PHP, Ruby, Node, local `tsc` followed by Node, `javac`, and `java`, requiring exact `ready\n6\n` output; a missing command fails.
@@ -346,7 +380,40 @@ Task 017 adds the distinct ordered `restore` stage and configured .NET SDK 10 di
 
 Task 024 adds configured Go 1.26.x discovery restricted to Linux/amd64; the patch release is read from the discovered toolchain rather than fixed by runtime tests. Acceptance obtains `GOROOT` from that exact `go`, requires the companion `gofmt` beside the configured or discovered executable to resolve to the same `GOROOT/bin/gofmt`, and checks `gofmt -d` before native execution. Each dependency-free generated module is run with `GOTOOLCHAIN=local`, `GOPROXY=off`, `GOSUMDB=off`, `GOVCS=off`, `CGO_ENABLED=0`, `GOENV=off`, `GOWORK=off`, `GOOS=linux`, `GOARCH=amd64`, and isolated HOME/GOPATH/build/module caches. The short-lived discovery fixture also writes exact `off` mode into its isolated Go telemetry directory before invoking the tool, then asserts that the mode file is the only telemetry state: Go 1.26 otherwise starts an unawaited uploader sidecar even in default `local` mode, which can recreate `upload/` while the fixture root is being removed. Cleanup errors remain fatal. Stages run offline `go build`, mandatory `go vet`, and `go run`, while compiler-only differential cases use the matching `go tool compile`. Tests require exact status/stdout, unchanged `go.mod`/`main.go`, no `go.sum`/`go.work`/vendor tree, and byte-identical binaries and output in two fresh directories. Missing, wrong-minor, wrong-architecture, mismatched-gofmt, download, cgo, workspace, vet, formatting, nondeterminism, telemetry leakage, or cleanup evidence fails without a skip.
 
-Task 023 adds exact Kotlin/JVM 2.4.20 discovery on the pinned OpenJDK 25.0.4+7 Ubuntu runtime. Ubuntu26.04 development and Ubuntu24.04 TensorBuzz use their exact `25.0.4+7-1~26.04` and `25.0.4+7-1~24.04` package builds. Bootstrap and discovery accept only their two qualified compiler-reported distribution suffixes, never arbitrary output. Original and generated `Program.kt` files compile with `-language-version 2.4 -api-version 2.4 -jvm-target 25 -Werror -include-runtime` into runnable `Program.jar` files, then execute through the exact `java25` discovery contract. Every process uses a fresh directory and exact status/stderr/UTF-8 stdout assertions; no test downloads a compiler or dependency.
+Task 023 adds exact Kotlin/JVM 2.4.20 discovery on pinned OpenJDK 25 Ubuntu runtimes. Ubuntu26.04 development uses exact `25.0.4.1+1-1~26.04.4`; Ubuntu24.04 TensorBuzz uses exact `25.0.4.1+1-1~24.04.4`. Bootstrap and discovery accept only those two qualified compiler-reported package identities, never arbitrary output. Original and generated `Program.kt` files compile with `-language-version 2.4 -api-version 2.4 -jvm-target 25 -Werror -include-runtime` into runnable `Program.jar` files, then execute through the exact `java25` discovery contract. Every process uses a fresh directory and exact status/stderr/UTF-8 stdout assertions; no test downloads a compiler or dependency.
+
+Task 041's product checks are separate from runtime acceptance. Run the two focused files sequentially:
+
+```sh
+npx velocious-test spec/managed-target-check-plans.spec.js
+npx velocious-test spec/managed-target-check-real-tools.spec.js
+```
+
+The plan spec proves exact frozen registry descriptors/argv, declared input and path ownership, no execute stage, stable C# project/lock hashing, and source-only changes that do not alter that restore identity. The real-tool spec fails rather than skips when any configured PHP, Ruby, Node, TypeScript, Kotlin, Python, or .NET tool is unavailable. It checks a generated supported fixture twice per target, injects invalid native source at every plan boundary, and requires preserved native output, nonzero structured stage diagnostics, the unchanged last-good pointer/bytes, and no failed candidate/staging residue. A separate malformed C# lockfile produces a real `restore` failure distinct from `compile` failure. The same file exercises all Task 041 targets already admitted by the version-1 complete-program boundary through the unchanged generic CLI.
+
+`spec/csharp-target-check-safety.spec.js` is the focused correction gate. With real .NET it proves that altered project bytes are rejected before a safe project-defined write target can run, ancestor `Directory.Build.targets` is not imported, staged source bytes remain unchanged, and an additional invalid `.cs` artifact reaches the compiler through the exact deterministic compile-item list instead of being merely declared as evidence.
+
+Product checks never execute the generated marker program. PHP uses configuration-free lint, Ruby disables gems for syntax checking, Node uses parse-only `--check`, and TypeScript uses no emit/incremental state plus candidate-only type roots. Kotlin publishes only `classes/`; Python uses isolated `py_compile` with checked-hash invalidation and publishes one build-root `.pyc`; C# accepts only its canonical generated manifest, disables ancestor customization, compiles every staged source, and lets restore consult only the staged local source. All NuGet/CLI/home/temp/intermediate paths are generation-owned and removed after the compiler closes, leaving only `bin/`. Repeated output inventories must match, source trees remain byte-owned by the publisher, and missing tools are failures.
+
+Task 042's native/project checks are covered by two additional focused files, run sequentially:
+
+```sh
+npx velocious-test spec/native-project-target-check-plans.spec.js
+npx velocious-test spec/native-project-target-check-real-tools.spec.js
+```
+
+The plan spec asserts exact frozen registry descriptors, argv arrays, declared inputs, path ownership, non-execution, and isolation for Go, C, C++, Rust, Swift, Dart, and Zig. It proves that Dart's length-framed restore identity contains only the exact producer-owned `pubspec.yaml`/`pubspec.lock` and is stable across source-only changes. The real-tool spec fails rather than skips when any qualified tool is unavailable. For every target it publishes two fresh valid candidates, checks stable source/build inventories and successful native stages, injects invalid staged source, retains native diagnostics and exact target identity, preserves the prior pointer/bytes, and proves the failed candidate plus transient state are gone.
+
+The developer profiles are intentionally bounded and non-executing:
+
+- Go uses exact local Go 1.26, `CGO_ENABLED=0`, `GOTOOLCHAIN=local`, read-only modules, network/VCS/workspace disablement, trimmed/build-ID-free output, and mandatory vet. Its HOME, GOPATH, GOCACHE, GOMODCACHE, and GOTMPDIR are candidate-owned; the qualified version-specific telemetry child guard prevents an unowned uploader descendant.
+- C uses strict Clang C17 at `-O0`, compiling every `.c` unit while declaring every `.h`, then linking the complete object set. C++ uses Clang C++20/libstdc++, no exceptions/RTTI, and the matching strict warnings/encoding/overflow profile. Their objects and temp state are removed, leaving only the linked developer executable. Existing O0/O2 ordinary plus ASan/UBSan/leak runs remain mandatory explicit acceptance/CI profiles; they are not hidden watcher branches.
+- Rust requires the exact dependency-free edition-2021 manifest and format-4 lock, qualifies both exact Rustc and Cargo identities, binds Cargo to the discovered compiler through an exact `RUSTC` tool environment path, then runs `cargo build --offline --locked` and `cargo check --offline --locked` with isolated CARGO_HOME/HOME/temp/target state and no incremental compilation. All Cargo target/cache/lock/executable state is transient.
+- Swift 6.3.3 explicitly uses `--driver-mode=swiftc`, warnings as errors, `-typecheck`, then a stable named-module object compile and native link with the ELF build ID disabled. The owned relative object path avoids randomized driver-temporary paths in `.swift_modhash`; object/HOME/XDG cache/temp state is removed, and the byte-stable compiled output is published but never run.
+- Dart 3.13.3 performs `pub get --offline --dry-run --enforce-lockfile --no-precompile` against the fixed dependency-free package, compiles the selected native executable, verifies formatting with no writes, and runs fatal analysis. PUB_CACHE/HOME/temp, the candidate package's `.dart_tool`, and the path-dependent native check output are declared transient and removed after close; `PUB_HOSTED_URL` is unreachable.
+- Zig 0.15.2 accepts only `build.zig` plus generated Zig sources, runs the Debug project build with generation-owned local/global caches and prefix, then runs `zig fmt --check`. The root-dependent Debug prefix is transient, so no native executable leaks or is published. Canonical format, `zig build test`, and builds/runs in Debug, ReleaseSafe, and ReleaseFast remain mandatory explicit acceptance/CI coverage and are not repeated on every edit.
+
+No Task 042 plan runs a generated executable, fetches a package, consults a user-global dependency home, cross-compiles, or adds a terminal matrix. Native nonzero exit, discovery, invalid plan, restore, compile, link, validation, timeout/cancellation, cleanup, and publication failures retain their distinct existing diagnostics.
 
 | Tool ID | Canonical command | Absolute-path override | Accepted canonical version |
 | --- | --- | --- | --- |
@@ -357,8 +424,8 @@ Task 023 adds exact Kotlin/JVM 2.4.20 discovery on the pinned OpenJDK 25.0.4+7 U
 | `tsc` | `tsc` | `SEMANTIFOLD_TSC` | TypeScript 7.x |
 | `javac` | `javac` | `SEMANTIFOLD_JAVAC` | JDK 17–29 |
 | `java` | `java` | `SEMANTIFOLD_JAVA` | JRE 17–29 |
-| `java25` | `java` | `SEMANTIFOLD_JAVA` | exact OpenJDK 25.0.4+7 Ubuntu runtime for JVM25 artifacts |
-| `kotlinc` | `kotlinc` | `SEMANTIFOLD_KOTLINC` | exact Kotlin/JVM 2.4.20 on JRE 25.0.4+7 Ubuntu |
+| `java25` | `java` | `SEMANTIFOLD_JAVA` | exact OpenJDK 25.0.4.1+1 development or TensorBuzz runtime for JVM25 artifacts |
+| `kotlinc` | `kotlinc` | `SEMANTIFOLD_KOTLINC` | exact Kotlin/JVM 2.4.20 on the matching qualified OpenJDK 25 Ubuntu package |
 | `python` | `python3` | `SEMANTIFOLD_PYTHON` | Python 3.x |
 | `dotnet` | `dotnet` | `SEMANTIFOLD_DOTNET` | .NET SDK 10.x |
 | `go` | `go` | `SEMANTIFOLD_GO` | Go 1.26.x, Linux/amd64 |