semantifold 0.3.0 → 0.5.0

package/docs/dart.md

@@ -0,0 +1,60 @@
+# Dart source and target
+
+Task 029 adds `dart` as Semantifold's fourteenth parser-native source/text language. It round-trips the Tasks 001–005 semantic profile through a deterministic dependency-free Dart VM/native package. The implementation and exact Dart 3.13.3 local acceptance are complete; independent review, exact-head TensorBuzz CI, merge, and post-merge verification remain pending.
+
+## Source profile
+
+The frontend accepts one directive-free compilation unit containing synchronous top-level functions followed by exactly one `void main()`. Functions use explicit `int`, `bool`, `String`, or `void` returns and zero or more explicitly typed required positional parameters. Statements are initialized `final Type name = value;` or mutable `Type name = value;` locals, simple identifier assignment, strict-Boolean `if`/`else if`/`else`, explicit value or bare returns, resolved void-call expression statements, and exact `print(value);`. Expressions are scalar literals, identifiers, parentheses, direct resolved calls, and the Tasks 001–005 unary/binary operations. Strings are ordinary noninterpolated quoted strings with the implemented escapes and valid Unicode scalar values.
+
+Every named, anonymous, extra, field, error, and missing CST edge is traversed. Parser recovery is `PARSE_ERROR`; missing explicit types use `MISSING_TYPE`; valid Dart outside the profile uses located `UNSUPPORTED_SYNTAX`. Ordinary comments may be ignored only after complete traversal. Parser trees stay inside `src/frontends/dart.js`.
+
+Inference, `var`, inferred `final`, `const`, `late`, `dynamic`, `Object`, `num`, `double`, user `BigInt`, nullability, named/optional/default parameters or arguments, generics, methods/classes/mixins/extensions/enums/records, closures/tear-offs, casts/type tests, interpolation, raw/multiline strings, collections, loops/switch/assert, exceptions, async/futures/streams/isolates, directives/imports, annotations, external/operator/getter/setter declarations, cascades, and null-aware syntax are rejected. Exact `_` is a Dart 3 wildcard rather than a binding and is rejected for semantic function, parameter, and local names; ordinary identifiers such as `_value` remain available. Exact lowercase `// dart format off` and `// dart format on` comments are rejected as formatter directives, while case or spacing near-misses remain ordinary comments. Flutter and browser/JavaScript Dart are separate work.
+
+## Qualified parser
+
+The exact dependency is public registry `tree-sitter-dart-orchard@0.7.0`, tarball `https://registry.npmjs.org/tree-sitter-dart-orchard/-/tree-sitter-dart-orchard-0.7.0.tgz`, integrity `sha512-dO4hyC6eCz7tnXNWk7ZZ/CVzorvWQKRhxRYUT/uwAnA50m+4Jbogd1Oh33lPcj1/bP9wG1pS3TWQEfs1W3LFbg==`, and MIT license. Immutable annotated tag `v0.7.0` peels to commit/npm `gitHead` `9322cd5e1266c60983ae0ff921fbb4e77e903781`. Its ABI 14 language object, typed 359-entry node metadata, local native source, lifecycle, signatures, complete corpus traversal, recovery, coordinates, clean ordinary install/`npm ci`, and credential-free packed-consumer behavior pass with Node 24 and exact root `tree-sitter@0.25.1`.
+
+Unscoped `tree-sitter-dart@1.0.0` is rejected because its language object is incompatible with the root binding. `@driftlog/tree-sitter-dart@1.0.4` is rejected because a clean install leaves undeclared extraneous `@driftlog/node-addon-api` residue. No cleanup hook, Git/archive dependency, copied or vendored parser, source-text fallback, compiler-output AST, or private package replaces either failure. See [parser qualification](parser-qualification.md#task-029-dart-grammar-qualification--2026-09-15).
+
+## Generated package and public API
+
+Use `generateArtifactSet({language: "dart", module})`. The ordered result is exactly:
+
+1. `pubspec.yaml` — `manifest`, `application/yaml`, synthetic configuration provenance;
+2. `pubspec.lock` — `manifest`, `application/yaml`, deterministic synthetic provenance;
+3. `bin/program.dart` — sole `entry`, `text/x-dart`, rich mapping and Source Map v3 provenance.
+
+The fixed package is named `semantifold_generated`, has `publish_to: none`, declares exact SDK `3.13.3`, has no dependencies, and emits the deterministic empty-package lockfile. `.dart_tool/`, SDK files, caches, and compiled executables are never artifacts. Omitted `filename` selects `bin/program.dart`; any other filename or any map-directive/source-map filename option fails transactionally with `UNSUPPORTED_CAPABILITY`. Because Dart is multi-artifact, `generate()` and `generateArtifact()` reject it with `UNSUPPORTED_ROLE`.
+
+Generation validates the whole module before writer allocation, including types, required arity, complete call resolutions, identifiers, compiler-owned name collisions, safe known arithmetic, graph bounds, and Task 006+ exclusions. Over-width signatures use Dart 3.13.3's canonical one-parameter-per-line form with a trailing comma while preserving parameter type/name mappings. Repeated generation is byte-identical across paths, contents, mappings, Source Map v3, and metadata.
+
+## Safe integers and generated support
+
+Semantic integers remain within `[-9007199254740991, 9007199254740991]`. Literals and statically known arithmetic outside that range fail before artifact allocation. Dynamic integer add, subtract, multiply, and negate use exact private compiler-owned helpers that calculate in `BigInt`, range-check, and convert to `int`. A private Boolean identity helper prevents Dart analyzer constant folding from reporting valid short-circuit branches as dead code; it does not change left-to-right or short-circuit evaluation. When an accepted initialized local has no semantic read, generation preserves its declaration and initializer effects, then emits one synthetic private no-op read so fatal Dart analysis remains clean.
+
+The frontend recognizes these calls only after recursively matching the complete canonical runtime CST—node type, named/extra state, child count, field names, and leaf text. Partial, reordered, renamed, duplicated, or token-modified support fails. The exact no-op local read is removed only when it immediately follows its matching declaration behind that authenticated prefix, so generated reparse reconstructs the original semantic block. User source cannot name the helpers, `BigInt`, `RangeError`, or runtime constants. Formatter-required trailing commas in generated formal parameter and call lists are accepted only behind this authenticated generated-runtime route.
+
+## Mappings
+
+`bin/program.dart` maps function names, parameter/local types and names, assignments, operators, calls and arguments, literals, print, returns, and entry statements to semantic/source origins. Formatting, the runtime prefix, manifest content, lockfile content, and fixed main shell are explicitly synthetic with related origins. Its embedded Source Map v3 names `bin/program.dart`; Dart emits no source-map directive or `.map` artifact. See [source provenance and mappings](source-maps.md).
+
+## Exact toolchain and offline acceptance
+
+The canonical Docker and TensorBuzz lanes install the official stable Linux x64 Dart SDK 3.13.3 ZIP under `/opt/dart-sdk-3.13.3`, verify SHA-256 `549c182cffbdc6864df7509c16fec646c73fe6cb8a18c2cb572db1292f300cd7`, and require:
+
+```text
+Dart SDK version: 3.13.3 (stable) (Tue Sep 1 01:07:17 2026 -0700) on "linux_x64"
+```
+
+`SEMANTIFOLD_DART` may select only an executable matching that identity. Each acceptance run owns fresh absolute HOME, PUB_CACHE, project, native-output, and TMPDIR paths; sets `CI=true`, `DART_SUPPRESS_ANALYTICS=true`, `LANG=C.UTF-8`, `LC_ALL=C.UTF-8`, and `TZ=UTC`; and points `PUB_HOSTED_URL` at an unreachable loopback endpoint. It runs without credentials or ambient Dart/pub configuration:
+
+```sh
+dart pub get --offline --no-precompile
+dart format --output=none --set-exit-if-changed bin/program.dart
+dart analyze --fatal-infos --fatal-warnings
+dart run bin/program.dart
+dart compile exe bin/program.dart -o semantifold-dart
+./semantifold-dart
+```
+
+All three generated artifact hashes remain unchanged after every command; only disposable `.dart_tool/` state and the native executable appear. The six Tasks 001–005 Dart fixtures translate to every compatible target and execute identically on Dart VM/native. Representative PHP, Ruby, JavaScript, TypeScript, and Java fixtures translate into Dart. Additional acceptance proves Unicode, eager argument ordering, direct recursion, void calls, Boolean short-circuiting, and the safe-integer boundary with exact empty stderr and identical VM/native stdout.

package/docs/goals.md

@@ -2,8 +2,8 @@
 
 Semantifold's long-term goal is a language-neutral toolkit for understanding, transforming, generating, and eventually executing programs through a shared high-level semantic representation. The representation should make types, control flow, calls, declarations, diagnostics, and source provenance understandable without exposing a language parser's private tree.
 
-The current source tree proves one minimal Tasks 001–004 vertical slice across nine registered languages: PHP, Ruby, JavaScript, TypeScript, Java, strictly annotated Python, canonical C#, bounded Go, and C17. It includes versioned source provenance, deterministic semantic node/symbol identity, range-based generated mappings, Source Map v3 interop, composition, and diagnostic remapping across that slice. The published `semantifold@0.2.0` release predates the C#, Go, and C additions. Neither the source tree nor that release provides a general analyzer, transformation API, interpreter, optimizer, project graph, debugger integration, coverage remapping, or lossless formatter.
+The current source tree proves one minimal Tasks 001–004 vertical slice across fourteen registered source languages: PHP, Ruby, JavaScript, TypeScript, Java, Kotlin/JVM, strictly annotated Python, canonical C#, bounded Go, C17, C++20, Rust edition 2021, Swift, and Dart. Dart additionally implements the bounded Task 005 required-function/call profile; the original five retain the delivered Task 013 acceptance gate for the combined Tasks 001–008 profile, Task 009 nominal closed records, Task 010 explicit acyclic multi-source semantic programs, Task 011 exact nominal typed unchecked errors, and Task 012 invariant unbounded function/record type parameters with closed applications and argument-only first-order call inference. Task 014 is delivered through PR #41, Task 032 through PR #42, Task 033 through PR #43, and Task 034 through PR #44. Task 035 is delivered through PR #45 and merge commit `a2aad9d4932bfc6087adc4ff8bca43678c92413c`, with versioned canonical standard-library contracts, target host providers and protected native bindings, capability negotiation, and program-mode provider linking. Task 036 is delivered through PR #46 and merge `9aba48f9d48bcef4fd4c9275aec14bfcc4f0904c`; it adds bounded versioned executable qualification facades and exact parser-backed native identity resolution for the original five. Task 037 adds only the first concrete Ruby-source-to-PHP-target blocking TCP/line-output slice on those foundations. The source tree includes versioned source provenance, deterministic semantic node/symbol identity, range-based generated mappings, Source Map v3 interop, composition, and diagnostic remapping across those bounded profiles. The published `semantifold@0.3.0` release predates these additions. Neither the source tree nor that release provides a general analyzer, transformation API, interpreter, optimizer, implicit project/package discovery, debugger integration, coverage remapping, or lossless formatter.
 
-The long-term product direction includes bounded standard-library portability through [language compatibility stdlib/facades, canonical Semantifold stdlib contracts/capabilities, and target host providers/native bindings](standard-library-portability.md). That direction is incremental and versioned; it does not promise arbitrary standard-library coverage or arbitrary-application translation. The `0.2.0` release has no imports, classes or methods, loops, optional values, typed errors, resources, host APIs, or stdlib portability.
+The long-term product direction includes bounded standard-library portability through [language compatibility stdlib/facades, canonical Semantifold stdlib contracts/capabilities, and target host providers/native bindings](standard-library-portability.md). That direction is incremental and versioned; it does not promise arbitrary standard-library coverage or arbitrary-application translation. The `0.3.0` release has no imports, classes or methods, loops, optional values, typed errors, resources, host APIs, or stdlib portability.
 
-Other roadmap candidates include a versioned fuller semantic schema, more scalar and compound types, expressions and statements, user-authored transformations, richer backend capability negotiation, multi-file modules, cross-language stack/coverage presentation, and a semantic interpreter. LLVM, Wasm, JVM bytecode, package publication automation, and production TensorBuzz changes remain outside the current release.
+Other roadmap candidates include a versioned fuller semantic schema, more scalar and compound types, expressions and statements, user-authored transformations, richer backend capability negotiation, cross-language stack/coverage presentation, and a semantic interpreter. Task 014 owns the only observable ordered-map iteration profile; Task 032 owns exact condition-controlled loops; Task 033 owns only the closed single-module reference-class profile; and Task 034 owns the bounded effect/ownership/close foundation. Task 035 supplies the delivered canonical/provider hub, and Task 036 supplies the delivered neutral qualification facades with exact identity evidence, ordinary compilation, collision-safe aliases, and protected same-language isolation. Task 037's concrete profile is only literal Ruby `require "socket"`, genuine `TCPSocket.new`/`gets`/`close`, and one-string `puts` compiled to protected PHP 8.2 core-stream providers; other sources, targets, networking APIs, output forms, timeouts, async behavior, and pair-specific rewrites remain outside it. LLVM, general Wasm source support, JVM bytecode, package-manager resolution, package publication automation, and production TensorBuzz changes remain outside the current release.

package/docs/ios.md

@@ -0,0 +1,121 @@
+# iOS application target
+
+Task 026 has an implemented Linux-qualified deterministic generation/provenance slice, with materialization and Apple-platform acceptance explicitly deferred. The registered `ios` identity is a target-only application backend: it has no frontend, text backend, binary-backend route, interoperability bridge, provider role, source-discovery behavior, filesystem writer, or entry in `supportedLanguages`. Real Xcode, Apple SDK, XCTest, XCUIAutomation, and iOS Simulator proof has not been run, so the task is not delivered and the generated Xcode model is not yet platform-qualified.
+
+## Public route
+
+Callers parse source normally, build an explicit Task 010 program, and request the application role. Omitting `role` retains ordinary text generation. Generation is pure and performs no filesystem access.
+
+```js
+import {generateProgramArtifactSet, parseProgram} from "semantifold"
+
+const program = parseProgram({
+  entryModule: "main",
+  sources: [{
+    filename: "main.rb",
+    id: "main",
+    language: "ruby",
+    source: "module Main\n  puts 7\nend\n"
+  }]
+})
+
+const artifactSet = generateProgramArtifactSet({
+  configuration: {
+    bundleIdentifier: "com.example.semantifold",
+    deploymentTarget: "18.0",
+    displayName: "Semantifold",
+    moduleName: "SemantifoldApp",
+    organizationPrefix: "com.example",
+    productName: "SemantifoldApp"
+  },
+  language: "ios",
+  program,
+  role: "application"
+})
+```
+
+`generateArtifactSet` accepts the same application fields for one semantic module and normalizes it to one project module. Both routes validate the entire semantic graph before rendering. The source registry accepts provenance from every registered frontend language, including compatible Dart modules, while the supported semantics remain exactly the Tasks 001–004 Swift subset from Task 022: typed scalar values, typed locals/assignment, the closed scalar operators, nested statement blocks/conditionals, exact two-argument scalar-return functions, resolved calls, and deterministic text output. Task 010 owns project modules, source ownership, imports, exports, and dependency order. iOS adds no parser rule or semantic node for SwiftUI, application lifecycle, capture, configuration, resources, signing, or Apple APIs.
+
+Program-shaped application dispatch is limited to program-capable application targets, currently `ios` and `android`. The separate Wasm application backend remains available through the single-module `generateArtifactSet` route and is rejected with `UNSUPPORTED_ROLE` when requested through `generateProgramArtifactSet`; a program object is never passed to that module backend.
+
+Unsupported source or caller-supplied IR produces a located `SemantifoldDiagnostic` with `UNSUPPORTED_CAPABILITY` and target `ios`. The backend never embeds Ruby, invokes a Ruby runtime from the app, translates through JavaScript, emulates dynamic Ruby behavior, or discovers sources/packages.
+
+## Closed configuration and assets
+
+The required configuration fields are `productName`, `moduleName`, `organizationPrefix`, `bundleIdentifier`, `deploymentTarget`, and `displayName`. They are caller-owned; no account, team, certificate, provisioning profile, installed SDK, or host path supplies a default. Product and module names are ASCII upper-camel identifiers. Organization and bundle identities are canonical lowercase reverse DNS, and the bundle must extend the organization prefix. Deployment is a canonical caller-supplied `major.minor` string.
+
+The only defaults are:
+
+| Field | Exact value |
+| --- | --- |
+| `sourceRoot` | `Sources` |
+| `resourceRoot` | `Assets.xcassets` |
+| `lifecycle` | `swiftui` |
+| `infoPlist` | empty object |
+| `permissions` | empty array |
+| `entitlements` | empty array |
+| `privacyDeclarations` | empty array |
+| `capabilities` | empty array |
+
+The schema is closed. Unknown fields, any nonempty plist extension/capability set, alternate lifecycle/root, or invalid identity fails before emission. The baseline creates no entitlements file and does not synthesize an icon.
+
+Every asset is explicit `{path, content, mediaType, sha256}` input. Its path must use only ASCII letters, digits, `.`, `_`, and `-` in nonempty relative POSIX components below `Assets.xcassets`; this closed alphabet has complete ASCII case-fold comparison. Sharp-S, sigma, composed/decomposed non-ASCII names, traversal, duplicates, case-fold collisions, and file/directory-prefix collisions fail at input validation before an artifact set is returned. This path restriction does not alter Unicode semantic source filenames, source text, string values, or generated Swift content. Asset content is a nonempty exact string or `Uint8Array`, and its lowercase SHA-256 must match the exact UTF-8 text or bytes. Assets are defensively copied and sorted.
+
+## Deterministic artifact contract
+
+Generation returns one ordered `GeneratedArtifactSet` with exactly one `entry`, `Sources/Application/App.swift`. The fixed categories are:
+
+1. `<Product>.xcodeproj/project.pbxproj` and its shared scheme;
+2. `Configuration/Base.xcconfig` and `Configuration/Info.plist`;
+3. the shared semantic runtime and one namespace-owned Swift file per project module;
+4. `App.swift`, `SemantifoldBridge.swift`, and `SemantifoldOutputView.swift`;
+5. base `Assets.xcassets/Contents.json` and exact caller assets;
+6. pure-logic XCTest and accessibility-route XCUI test sources;
+7. `semantifold-project.json`.
+
+The semantic renderer uses one shared reference-type `SemantifoldOutputSink`. Nested calls receive that same sink, preserving exact evaluation/output order. The semantic entry returns `[String]`; the bridge invokes it; the SwiftUI view joins with one LF and assigns accessibility identifier `semantifold-output`. Per-module Swift lives in deterministic `SemantifoldModule…` namespaces.
+
+Xcode object IDs are the uppercase first 24 hexadecimal digits of built-in SHA-256 over normalized, collision-checked full identities. Project sections, groups, build phases, build settings, paths, configuration JSON, and assets have canonical ordering; text uses LF and relative paths. Signing is disabled and no entitlement/team/account/certificate/provision data is emitted. Two generations from the same validated input return byte-identical artifacts. The generated Xcode source/project syntax is deterministic but remains platform-unqualified.
+
+## Manifest and provenance
+
+`semantifold-project.json` is `SemantifoldIosProject` version 1. It records generator identity/version, target, the complete normalized configuration, caller source and asset hashes, exact ordered owned paths, explicit excluded path patterns, and Apple tool requirements whose status is `deferred`. Its `SemantifoldIosSemanticProgram` version 1 section preserves caller-order source IDs, filenames, hashes and ownership; dependency-order caller module IDs and import dependencies; source-to-module ownership links; generated namespaces/artifacts; and the selected entry module, generated function, bridge, and application artifact linkage.
+
+Mapped semantic Swift retains rich UTF-16 range provenance and Source Map v3 projection through every originating module, including Ruby and Dart. Synthetic runtime, SwiftUI, project, configuration, asset-catalog base metadata, and test scaffolding carry explicit synthetic provenance. Each owning renderer records causal configuration spans while emitting a specific field-derived token; the manifest groups only those ranges with their JSON pointers and never reconstructs ownership through substring scans. Equal module/product values, an organization prefix embedded in a bundle ID, and synthetic text matching the display name therefore cannot create false citations. Exact assets record path, media type, representation, and SHA-256; binary artifact provenance spans every byte.
+
+Build products, `DerivedData`, Xcode user data, code signatures, and caller files outside the owned path list are excluded. The manifest is an ownership description, not a filesystem mutation or permission to overwrite or adopt a project.
+
+## Deferred filesystem publication
+
+Materialization is deferred and this release exposes no public project writer. Node's public filesystem API does not provide the combination required by the accepted contract: genuine atomic no-replace publication of a complete directory plus descriptor-relative no-follow anchoring for staging, publication, and cleanup. A path preflight followed by ordinary rename can replace a raced empty directory or follow an exchanged ancestor, so it is not retained as best effort.
+
+A future materializer requires a separately authorized, reviewed, and platform-qualified native boundary. Until then, generation returns only an immutable in-memory artifact set; no transactional filesystem, regeneration, adoption, merge, or overwrite claim is made.
+
+## Acceptance status
+
+| Criterion | Status | Evidence or remaining boundary |
+| --- | --- | --- |
+| AC01 | implemented | Complete Task 010 graph preflight and Tasks 001–004 lowering are focused-spec covered. |
+| AC02 | partial | SwiftUI shell/bridge/view and capture are generated; real Apple compilation is deferred. |
+| AC03 | implemented | Closed caller configuration and identity validation are covered. |
+| AC04 | implemented | Empty capabilities, exact hashed assets, and the complete portable ASCII path boundary are covered. |
+| AC05 | partial | Canonical project, IDs, paths, LF, and double generation are covered; `xcodebuild` validation is deferred. |
+| AC06 | partial | Unit/UI sources and Linux semantic execution exist; real XCTest/XCUI execution is deferred. |
+| AC07 | deferred | No public materializer ships; atomic no-replace plus descriptor-relative no-follow publication requires a separately authorized native boundary. |
+| AC08 | implemented | Ruby/Dart/Swift mapping, renderer-owned configuration spans, stable semantic program identities/linkage, ownership, and asset provenance are covered. |
+| AC09 | partial | Located capability and stable application diagnostics are covered; filesystem safety diagnostics remain deferred with materialization. |
+| AC10 | implemented | Real Ruby output equals generated Swift output in debug and optimized Linux execution. |
+| AC11 | implemented | No VM, runtime emulation, credentials, entitlements, dependencies, signing, or host leakage is emitted. |
+| AC12 | deferred | No qualified macOS/Xcode/Apple SDK/Swift compiler lane has listed or built the project. |
+| AC13 | deferred | No named iOS Simulator has been booted, installed to, or launched. |
+| AC14 | deferred | No XCTest/XCUIAutomation run has observed exact `semantifold-output` text. |
+| AC15 | implemented locally for generator scope | Focused generation and packed-generator proofs are required; materializer/Apple proof and coordinator CI remain deferred or external. |
+| AC16 | implemented for this reduced scope | Public generator contract, provenance, path boundary, deferrals, testing, changelog, task, and roadmap are documented without claiming delivery. |
+
+Linux acceptance runs real Ruby and exact Swift 6.3.3 on x86_64 Linux. Generated semantic Swift is typechecked, compiled, and run in debug and optimized modes with exact Unicode/output assertions. The packed proof uses a fresh cache, empty npm configurations, explicit public registry, default `install-links=false`, ordinary install and clean `npm ci`, full dependency listings, repeated deterministic generation/manifest checks, strict type consumption, and proof that no materializer implementation/declaration is shipped. Missing Ruby or Swift commands fail.
+
+Kasper separately selected “Defer the materializer and ship the generator/provenance scope,” so AC07 remains deferred without weakening its transaction guarantee. Per Kasper's 2026-09-14 direction to skip OSX work for now, no `xcodebuild`, Apple SDK, signing, runtime download, simulator, XCTest, or XCUIAutomation command was run, and TensorBuzz configuration was not changed to manufacture a lane. AC12–AC14 also remain deferred. Task 026 and its roadmap row therefore remain in progress rather than delivered.
+
+## Non-goals
+
+The profile does not support arbitrary Ruby or Swift, UIKit parity, storyboards, platform APIs, storage, networking, concurrency, background modes, package dependencies, CocoaPods/SwiftPM resolution, non-iOS Apple targets, Objective-C/Objective-C++/Metal bridges, signing, physical devices, archives/export, TestFlight, App Store submission, deployment, release, or publication.

package/docs/kotlin.md

@@ -0,0 +1,42 @@
+# Kotlin/JVM source and target
+
+Task023 adds `kotlin` as a frontend and deterministic single-file Kotlin/JVM text backend for exactly the Tasks001–004 semantic subset. It does not claim Android, Gradle, Kotlin/Native, Kotlin/JS, Wasm, multiplatform projects, compiler plugins, package resolution, or Java interoperability beyond executing the generated JVM bytecode. Android application packaging and lifecycle remain Task028.
+
+## Parser route
+
+The frontend uses root `tree-sitter@0.25.1` with the MIT-licensed `tree-sitter-kotlin@0.4.0` grammar from the Semantifold packaging fork. The exact dependency is the full-SHA source archive `https://github.com/kaspernj/tree-sitter-kotlin/archive/57c35ad1a80ccd2a0ebd8fffe852f0d13a20acd0.tar.gz`, and the lock records that HTTPS URL with SHA-512 integrity. The commit is also tagged `v0.4.0-semantifold.1`. The fork keeps grammar ABI 14, declares optional peer `tree-sitter@^0.25.1`, ships typed `nodeTypeInfo`, generated parser/scanner sources and the `node-gyp-build` binding, and has no install-time downloader.
+
+The root tarball does not bundle the grammar. A credential-free consumer resolves the immutable archive over HTTPS and verifies its lock integrity, while root `acceptDependencies` remains restricted to the exact private legacy-runtime payload. The packed-consumer proof uses empty user/global npm configuration, a fresh cache, the public registry, default `install-links=false`, full dependency listing, ordinary install, clean `npm ci`, strict public API typing, parser loading, and real Kotlin/JVM execution without SSH or credentials.
+
+The adapter exhaustively visits every named, anonymous, extra, error, and missing child, verifies parser indexes through the shared UTF-8-byte-to-UTF-16 converter, rejects lone surrogates and recovery, and never scans source text to recover rejected syntax. The parser route, five fixture hashes, CST corpus, coordinates, lifecycle, package boundary, and exact `kotlinc` differential are recorded in [parser qualification](parser-qualification.md).
+
+## Source profile
+
+Source consists of one or more top-level semantic `fun` declarations followed by exactly one `fun main()`. A semantic function has exactly two ordinary parameters and explicit `Long`, `Boolean`, or `String` parameter and return types. Calls are direct, positional, and have exactly two arguments. `main` has no parameters or return annotation and contains the sequenced entry statements; printing is direct one-argument `println(...)`.
+
+Locals require `val|var name: Long|Boolean|String = expression`. `val` is immutable and `var` is mutable under the shared assignment rules; targets are plain local identifiers. Conditions require semantic `Boolean`. Braced nested and one-armed `if`, `else`, and fallthrough normalize to semantic blocks. Returns are explicit on every reachable function path.
+
+The profile accepts safe canonical decimal integers with an optional uppercase `L`, ordinary noninterpolated strings, Boolean literals, identifiers, calls, integer add/subtract/multiply/negate and ordering, Boolean not/short-circuit and/or, same-type scalar equality/inequality, and string concatenation. Ordinary unescaped identifiers follow the qualified grammar's letters/decimal-digits/underscore profile and NFC requirement; unsupported Unicode identifier forms reject before emission rather than failing generated reparse. Types remain exact: there is no numeric widening, conversion, inference, nullable/platform type, unsigned/arbitrary-width number, boxing, or `null` mapping.
+
+Packages, imports, annotations, classes/interfaces/data/value classes, objects/companions, extensions, overloads, generics, lambdas, local functions, delegation, casts, smart casts, referential equality, arrays/collections, indexing, ranges, loops, `when`, exceptions, reflection, coroutines/`suspend`, interpolation, raw strings, qualified calls, arbitrary APIs, and locale-dependent formatting are outside the profile. Parser recovery uses `PARSE_ERROR`; omitted required types use `MISSING_TYPE`; other parsed Kotlin outside the profile uses located `UNSUPPORTED_SYNTAX`.
+
+## Generated program
+
+The backend emits exactly one LF-normalized `Program.kt`. It preserves explicit scalar types and `val`/`var`, emits uppercase-`L` integer literals, and uses ordinary Kotlin/JVM scalar equality. Native eager operands and call arguments retain left-to-right order, while `&&` and `||` retain native short-circuiting. Private target-only helpers wrap `Math.addExact`, `subtractExact`, `multiplyExact`, and `negateExact`, then check the result against `-9007199254740991L...9007199254740991L`; dynamic overflow therefore cannot silently wrap outside the semantic safe-integer range. Only the complete byte-for-byte helper CST prefix authorizes helper-call collapse during generated reparse. Caller identifiers cannot enter the helper namespace or capture Kotlin/JVM scaffolding.
+
+Rich mappings and Source Map v3 cover semantic names, types, literals, callees, and operators. Runtime helpers, separators, braces, `main`, and `println` plumbing are synthetic and related to semantic origins. Generation validates malformed/cyclic/excessively expanded graphs, types, names, literals, known arithmetic bounds, mutability, and the fixed filename transactionally, then reparses the final source through the registered Kotlin frontend before returning it. Only omitted filenames or exact `Program.kt` are accepted; map directives and alternate map names reject with `UNSUPPORTED_CAPABILITY`.
+
+`generateArtifactSet()` returns one `text/x-kotlin` entry plus detached immutable metadata. Its declared build and run recipe is:
+
+```sh
+kotlinc -language-version 2.4 -api-version 2.4 -jvm-target 25 -Werror -include-runtime Program.kt -d Program.jar
+java -jar Program.jar
+```
+
+No Gradle files or downloaded project dependencies are generated.
+
+## Compiler contract
+
+`kotlinc` discovery accepts only Kotlin/JVM 2.4.20 on the exact OpenJDK 25.0.4+7 Ubuntu builds: `info: kotlinc-jvm 2.4.20 (JRE 25.0.4+7-1-26.04-Ubuntu)` in the Ubuntu26.04 development image or the corresponding `...-1-24.04-Ubuntu` identity in Ubuntu24.04 TensorBuzz. The canonical command is `kotlinc`; `SEMANTIFOLD_KOTLINC` may provide an absolute executable override. Kotlin execution uses the separate `java25` contract, which invokes `java` through `SEMANTIFOLD_JAVA` and accepts only the complete matching OpenJDK25.0.4 runtime and 64-bit Server VM output for one of those two Ubuntu revisions; the broader Java-language `java` contract remains JRE17-29. Missing, ambiguous, non-executable, wrong-compiler, wrong-Kotlin, or wrong-JRE identities fail loudly.
+
+The Dockerfile and TensorBuzz download only the official Kotlin `2.4.20` compiler ZIP from JetBrains and verify SHA-256 `59e9ca74c7904ef2c122b12114937673ccce68de820a663f0ed66ccf8799e0b7` before installation at `/opt/kotlinc`. The development image pins `openjdk-25-jdk-headless=25.0.4+7-1~26.04`; Noble TensorBuzz pins the repository-compatible `25.0.4+7-1~24.04` build. Their bootstrap probes require the complete Kotlin/JVM 2.4.20 and JRE 25.0.4+7 identity while admitting only the known Ubuntu 24.04 or 26.04 packaging suffix. They expose `/opt/kotlinc/bin/kotlinc` through `SEMANTIFOLD_KOTLINC` without shadowing `PATH`. Runtime tests materialize fresh directories, compile original and generated five-profile sources with the exact metadata arguments, execute runnable JARs through the discovered Java25 contract, assert status/stderr/exact UTF-8 stdout bytes, and remove all temporary artifacts.