semantifold 0.1.1 → 0.2.0

package/docs/parser-qualification.md

@@ -0,0 +1,70 @@
+# Parser dependency qualification
+
+Task 015 adds no parser dependency. It freezes the gate that every owning language task must complete before changing `package.json` or `package-lock.json`. Qualification is evidence for one exact candidate release; a package name or upstream reputation alone is not approval.
+
+## Required record
+
+The owning task must add a checked-in table row containing all of the following before its manifest edit:
+
+| Evidence field | Required value |
+| --- | --- |
+| npm distribution | Exact registry package name and version; no range |
+| upstream identity | Repository URL, release tag, and full commit SHA |
+| legal/supply chain | SPDX license, npm integrity from the lockfile, and registry provenance checked |
+| runtime compatibility | Exact `tree-sitter` Node binding version, grammar ABI/language version, and clean Node 24 install/import result on canonical Linux |
+| API/coordinates | Typed Node API availability; parser UTF-8 byte/point behavior; tested conversion to one-based UTF-16 Semantifold locations |
+| parser behavior | Comment visibility plus explicit missing/error/recovery-node and malformed-input results |
+| Task 001–004 corpus | Every required declaration, block, statement, expression, type, identifier, literal, and call node; complete named/unnamed child traversal |
+| differential result | Official compiler command/version and acceptance comparison for community grammars; discrepancies enumerated |
+| repository audit | Proof that no generated archive, Git URL/tarball dependency, postinstall download, runtime fetch, or vendored parser binary entered the repository |
+
+The record includes the exact corpus commands and hashes/paths, the installed dependency tree, and the tool output needed to reproduce the result. Any failure blocks that language task. It does not permit a source-text fallback, ignored recovery node, unrecorded parser substitution, runtime download, or softened test.
+
+## Owning-task routes
+
+All Tree-sitter languages use the official `tree-sitter` Node binding. The language task, not Task 015, selects and pins the exact npm versions and records the lockfile integrity after the gate passes.
+
+| Owning task | Language | Required upstream route | Qualification state before owner starts |
+| --- | --- | --- | --- |
+| 016 | Python | official [`tree-sitter/tree-sitter-python`](https://github.com/tree-sitter/tree-sitter-python) grammar package | blocked until the exact release record above passes |
+| 017 | C# | official [`tree-sitter/tree-sitter-c-sharp`](https://github.com/tree-sitter/tree-sitter-c-sharp) grammar package | blocked until the exact release record above passes |
+| 018 | C | official [`tree-sitter/tree-sitter-c`](https://github.com/tree-sitter/tree-sitter-c) grammar package | blocked until the exact release record above passes |
+| 019 | C++ | official [`tree-sitter/tree-sitter-cpp`](https://github.com/tree-sitter/tree-sitter-cpp) grammar package | blocked until the exact release record above passes |
+| 020 | Rust | official [`tree-sitter/tree-sitter-rust`](https://github.com/tree-sitter/tree-sitter-rust) grammar package | blocked until the exact release record above passes |
+| 022 | Swift | community [`alex-pinkus/tree-sitter-swift`](https://github.com/alex-pinkus/tree-sitter-swift) candidate plus differential `swiftc` checks | candidate only; blocked until exact release and differential record pass |
+| 023 | Kotlin/JVM | community [`fwcd/tree-sitter-kotlin`](https://github.com/fwcd/tree-sitter-kotlin) candidate plus differential `kotlinc` checks | candidate only; blocked until exact release and differential record pass |
+| 024 | Go | official [`tree-sitter/tree-sitter-go`](https://github.com/tree-sitter/tree-sitter-go) grammar package | blocked until the exact release record above passes |
+| 029 | Dart | candidate selected and qualified by Task 029 | intentionally deferred |
+| 031 | Zig | candidate selected and qualified by Task 031 | intentionally deferred |
+
+Swift or Kotlin qualification failure leaves Task 022 or 023 blocked until its roadmap/source decision is explicitly revised. Parser archives produced by CI or release pages are not an alternative dependency route.
+
+## Task 016 Python qualification
+
+Qualification passed on the canonical Node `v24.18.1`, npm `11.16.0`, Linux lane with Python `3.14.4`. Task 016 therefore uses exact registry dependencies `tree-sitter@0.25.1` and the official `tree-sitter-python@0.25.0`; neither dependency is a Git URL, tarball path, copied archive, or vendored repository artifact.
+
+| Evidence | Qualified result |
+| --- | --- |
+| npm distribution | `tree-sitter@0.25.1`, integrity `sha512-mrcEdkYtHfrK1A6fs3O6FxkBo0Qig5XUXqHhxUOQu0bmPo00QF4XaSx4edpazdHwxnSCjlGKGgIqWdaN4dvTLA==`; `tree-sitter-python@0.25.0`, integrity `sha512-eCmJx6zQa35GxaCtQD+wXHOhYqBxEL+bp71W/s3fcDMu06MrtzkVXR437dRrCrbrDbyLuUDJpAgycs7ncngLXw==` |
+| upstream identity | Official [`tree-sitter/node-tree-sitter`](https://github.com/tree-sitter/node-tree-sitter) tag `v0.25.1`, commit `75a0eccfedc491e26843bd744bb6806f8a8bfff4`; official [`tree-sitter/tree-sitter-python`](https://github.com/tree-sitter/tree-sitter-python) annotated tag `v0.25.0` (`d326e4cad262cf681656e130960e49dfc04c03ea`), peeled commit/npm `gitHead` `293fdc02038ee2bf0e2e206711b69c90ac0d413f` |
+| legal and registry provenance | Both packages declare MIT. `npm audit signatures` verified all four installed-package registry signatures and two attestations. The binding publishes npm SLSA provenance; the grammar release has a verified registry signature but did not advertise an npm attestation. The exact official tag/commit and registry integrity were therefore checked independently. |
+| clean install/load | Credential-free `npm install --save-exact tree-sitter@0.25.1 tree-sitter-python@0.25.0` succeeded in an empty temporary package. ESM default imports loaded both CommonJS packages, `new Parser().setLanguage(Python)` succeeded, and `npm ls --all` resolved only `node-addon-api@8.9.2`, `node-gyp-build@4.8.4`, the exact binding, and the exact grammar. |
+| ABI and typed API | The shipped grammar parser declares ABI `15`; the binding headers accept language ABI `13` through `15`. The binding ships `tree-sitter.d.ts`; the grammar ships `bindings/node/index.d.ts` with its language handle and node-type metadata. |
+| lifecycle and packaged inputs | Each package has only `install: node-gyp-build`; there is no network-download lifecycle. Registry contents include Linux/macOS/Windows prebuilds plus binding/grammar C sources, grammar/node-type JSON, declarations, and licenses. No package archive, prebuild, generated parser, native binary, or `node_modules` content is checked into Semantifold. Cold installs may select the registry prebuild or compile the shipped sources, so the canonical image retains its native build prerequisites. |
+| coordinates and recovery | The native grammar contract is byte-based, but `node-tree-sitter@0.25.1` feeds JavaScript strings to Tree-sitter as UTF-16LE and exposes normalized UTF-16 code-unit indexes (`src/parser.cc`; an astral prefix shifted bytes and code units differently). The adapter rejects lone surrogates and routes every binding boundary through the shared UTF-8-byte-to-UTF-16 converter for exact verification. Comments are visible named nodes. Malformed parameters, conditions, and incomplete expressions set `hasError` and expose `ERROR`; the adapter also checks `isMissing` exhaustively even though the malformed probes recovered with `ERROR`. |
+| Tasks 001-004 tree corpus | Exhaustive `child(index)` traversal observed named and anonymous nodes/tokens for modules, definitions, exact annotations, parameters, blocks, initialized assignments, plain assignment, returns, calls/arguments, scalar literals, unary/binary/Boolean/comparison operators, comments, `if`/`elif`/`else`, and entry expression statements. Adapter specs cover rejected dynamic/recovery nodes and exact token spans. |
+| official-runtime comparison | `python3 -m py_compile` accepted all five Python fixtures under deterministic UTF-8. Python is the official implementation and the grammar is official, so no community-grammar differential exception applies. |
+
+Reproduce the install/supply-chain gate in an empty temporary directory with:
+
+```sh
+npm init -y
+env -u NODE_AUTH_TOKEN -u NPM_TOKEN -u npm_config__auth -u npm_config_token \
+  npm install --save-exact tree-sitter@0.25.1 tree-sitter-python@0.25.0
+npm audit signatures
+npm ls --all
+npm pack tree-sitter@0.25.1 --dry-run --json
+npm pack tree-sitter-python@0.25.0 --dry-run --json
+```
+
+The accepted Python corpus is `spec/fixtures/{program.py,scalars/program.py,locals/program.py,operators/program.py,statements/program.py}` with SHA-256 values, in that order: `045ac897756dde15066878b56e40c84ee1aabdbd6fd32bddb9d0058ad512972a`, `b4acdda8c4c096ef7d76f83aec7dc148e049a0cd33583c55a79fd18ab1d6f6a6`, `123bb06c0833786168722ad7dfdcb47b95d37b502f6240fde4c12cd60f8e6715`, `35dce1aef96e5dc381baa1b2c39b58232d76b9e14350f0e81c4dd296da77df1e`, and `4907b25568006f65ce749f4c57b4b1eb9c7e6f655ad6be6e014d94c84885ada4`. Run `PYTHONPYCACHEPREFIX="$(mktemp -d)" python3 -m py_compile` over those paths so bytecode remains outside the checkout.

package/docs/source-maps.md

@@ -66,7 +66,7 @@ artifact.sourceMap     // encoded Source Map v3 object
 artifact.sourceMapFilename
 ```
 
-Default filenames are `program.php`, `program.rb`, `program.js`, `program.ts`, and `Main.java`. Java artifacts may include directories but must retain the basename `Main.java`, matching the generated public class and making the returned filename directly compilable; any other basename is a located `UNSUPPORTED_CAPABILITY` diagnostic for the Java backend. `sources` may supply exact content for legacy or caller-assembled multi-source IR:
+Default filenames are `program.php`, `program.rb`, `program.js`, `program.ts`, `Main.java`, and `program.py`. Defaults apply only when `filename` or `sourceMapFilename` is omitted (`undefined`); an explicitly supplied `null` remains invalid. Java artifacts may include directories but must retain the basename `Main.java`, matching the generated public class and making the returned filename directly compilable; any other basename is a located `UNSUPPORTED_CAPABILITY` diagnostic for the Java backend. Python artifacts likewise may include directories but retain the deterministic basename `program.py`; Python adds no package, environment, requirements, or dependency metadata. `sources` may supply exact content for legacy or caller-assembled multi-source IR:
 
 ```js
 generateArtifact({
@@ -79,7 +79,7 @@ generateArtifact({
 })
 ```
 
-This single-artifact envelope is intentionally reusable as an element in task 010's future ordered artifact set. Generation never writes files.
+`generateArtifactSet()` wraps this exact result for original-five single-text targets and supplies one generated entry artifact, plus the referenced serialized mapping artifact when an external JavaScript-family directive is requested. `createGeneratedArtifactSet()` validates other single-module target shapes without introducing Task 010's source-project semantics. Its dense artifact array preserves caller/backend order and requires unique safe relative POSIX paths without file/directory prefix collisions, non-empty text or bytes, media types, one of `entry`/`source`/`manifest`/`support`/`mapping`/`resource`/`loader`, generated ownership, provenance, and exactly one entry. Binary storage remains private and every `content` read returns a detached `Uint8Array`, so mutations cannot alter the validated artifact or drift from byte provenance. Backends return no iterable or partial files: the complete set is validated before it becomes observable. Generation and set construction never write files.
 
 All outputs have deterministic LF newlines. Returned rich mappings are detached from caller-owned semantic locations and provenance before they are deeply frozen and internally indexed after trust-boundary validation. Freezing an artifact mapping therefore never freezes the mutable semantic module used to generate it. The rich map's `generated.content` is the exact returned code and its ordered, non-empty spans cover every UTF-16 code unit without gaps or overlaps:
 
@@ -89,9 +89,36 @@ All outputs have deterministic LF newlines. Returned rich mappings are detached
 
 Every span may carry a canonical `nodeId`, `symbolId`, semantic `role`, and Source Map `name`. Sources retain filenames, exact `sourcesContent` when available, and independent registry identity. Rich mappings are the serialization and interchange contract because v3 represents points rather than ranges and cannot retain semantic roles or the closed derived/synthetic model.
 
+## Binary and resource byte mappings
+
+`SemantifoldByteMapping` v1 is separate from the text mapping schema:
+
+```js
+const mapping = createByteMapping({
+  path: "program.wasm",
+  byteLength: bytes.byteLength,
+  ranges: [
+    {
+      generated: {start: 0, end: 8},
+      origin: {kind: "synthetic", reason: "WebAssembly header", relatedOrigins: []}
+    },
+    {
+      generated: {start: 8, end: bytes.byteLength},
+      nodeId: "node:4",
+      role: "encoded function body",
+      origin
+    }
+  ]
+})
+```
+
+The discriminator is `SemantifoldByteMapping`, version is `1`, and `coordinateSystem` is exactly `bytes`. The range array and every nested provenance-origin array are dense; ranges contain non-negative safe-integer half-open offsets, are non-empty, ordered, non-overlapping, and bounded by `generated.byteLength`. Source/derived origins retain ordinary UTF-16 original `SourceLocation` values; only the generated side is in bytes. Every source location has nondecreasing offsets and lexicographically ordered `(line, column)` endpoints; equal endpoints remain valid for zero-width origins. Synthetic regions require a non-empty reason. Optional `nodeId`, `symbolId`, and `role` fields are omitted only by `undefined`; any present value must be a non-empty string. These identities associate encoded regions without fabricating source positions. `parseByteMapping()` validates serialized input and `stringifyByteMapping()` emits canonical key-sorted JSON with one LF.
+
+Text artifact provenance embeds the validated rich mapping and Source Map v3 projection. Its optional `sourceMapFilename` may be omitted, but when present must be a non-empty single-line string; optional Source Map arrays must likewise be omitted rather than set to `null`. Malformed values are rejected as `INVALID_ARTIFACT_SET`. Binary artifact provenance must embed a matching byte map whose path and byte length equal its artifact. Manifest, support, loader, and other source-free text/resources may instead carry an explicit artifact-level synthetic reason and related source origins. Optional related-origin identities follow the same `undefined`-only omission rule. Artifact-set construction detaches and deeply freezes every such related origin, including its location and start/end points.
+
 ## Source Map v3 and directives
 
-`artifact.sourceMap` exists for all five targets and is generated with `@jridgewell/gen-mapping`; lookup and import use `@jridgewell/trace-mapping`. Semantifold does not hand-code VLQ or tracing. The v3 map contains deterministic `file`, `sources`, `sourcesContent`, `names`, and `mappings` fields.
+`artifact.sourceMap` exists for all six text targets and is generated with `@jridgewell/gen-mapping`; lookup, import, and artifact-set validation use `@jridgewell/trace-mapping`. Semantifold does not hand-code VLQ or tracing. Artifact-set validation requires dense `sources`, `names`, and optional `sourcesContent` arrays, decodes and canonically re-encodes the mapping payload, requires standard one-, four-, or five-field segments, rejects source or name indices outside their declared arrays, and requires the complete v3 value to equal the existing `toSourceMapV3()` projection of the accepted rich mapping. That projection comparison covers generated and original positions, source and name indexes, content, and the documented trailing unmapped directive span without a second encoder. The v3 map contains deterministic `file`, `sources`, `sourcesContent`, `names`, and `mappings` fields.
 
 Directives are opt-in and only valid for JavaScript and TypeScript:
 
@@ -100,7 +127,7 @@ generateArtifact({language: "javascript", module, mapDirective: "external"})
 generateArtifact({language: "typescript", module, mapDirective: "inline"})
 ```
 
-`external` appends `//# sourceMappingURL=<relative-map-url>`. `artifact.sourceMapFilename` remains the map artifact's literal logical filename, while the directive is relative to `artifact.filename`'s directory and URL-encodes each filesystem path segment without encoding structural slashes. Both logical paths resolve against one synthetic artifact root before relativization, so mixed leading-parent depths do not become false common segments; for example, generated `../../dist/out.js` and map `../maps/out.js.map` emit `../maps/out.js.map`. `dist/program.js` still advertises `dist/program.js.map` and emits `sourceMappingURL=program.js.map`; a literal `#` or `?` in the sidecar filename is emitted as `%23` or `%3F`. Names containing any ECMAScript line terminator—LF, CR, U+2028, or U+2029—are rejected before emission. `inline` appends a UTF-8 base64 data URL. The default is `none`. PHP, Ruby, and Java still receive sidecar map objects but never receive non-native map comments. Native Java debugger mapping such as JSR-45 would require class-file/toolchain integration and is not part of v1.
+`external` appends `//# sourceMappingURL=<relative-map-url>`. `artifact.sourceMapFilename` remains the map artifact's literal logical filename, while the directive is relative to `artifact.filename`'s directory and URL-encodes each filesystem path segment without encoding structural slashes. Both logical paths resolve against one synthetic artifact root before relativization, so mixed leading-parent depths do not become false common segments; for example, generated `../../dist/out.js` and map `../maps/out.js.map` emit `../maps/out.js.map`. `dist/program.js` still advertises `dist/program.js.map` and emits `sourceMappingURL=program.js.map`; a literal `#` or `?` in the sidecar filename is emitted as `%23` or `%3F`. Names containing any ECMAScript line terminator—LF, CR, U+2028, or U+2029—are rejected before emission. `generateArtifactSet()` makes that reference materializable by adding the LF-terminated deterministic JSON serialization of `artifact.sourceMap` at the advertised safe path with role `mapping`; `generateArtifact()` retains its existing sidecar-object contract. `inline` appends a UTF-8 base64 data URL. The default is `none`. PHP, Ruby, and Java still receive sidecar map objects but never receive non-native map comments. Native Java debugger mapping such as JSR-45 would require class-file/toolchain integration and is not part of v1.
 
 The directive itself is an unmapped synthetic rich-map span. `artifact.sourceMap` is computed for the program before that self-referential comment is appended; this is required for a stable inline data URL and is the conventional v3 behavior. Use the rich mapping when the directive span itself matters. Rich registries may distinguish same-named sources by `sourceId`; Source Map v3 identifies sources by filename, so callers should use unique filenames when exporting such an assembled registry to v3.
 

package/docs/testing.md

@@ -1,6 +1,22 @@
 # Testing
 
-Specs use the released `@velocious/testing@0.0.0` framework and standalone `velocious-test` runner with one top-level `describe` per file. Direct value checks use the framework's `expect` API where it improves clarity; predicate-rich diagnostic assertions retain `node:assert/strict`. Frontend tests load real fixtures through Babel, php-parser, Prism, and Lezer and compare modeled meaning after removing source locations and the separately tested provenance index. They separately assert normalized JSDoc and TypeScript types and verify locations exist.
+Specs use the released `@velocious/testing@0.0.0` framework and standalone `velocious-test` runner with one top-level `describe` per file. Direct value checks use the framework's `expect` API where it improves clarity; predicate-rich diagnostic assertions retain `node:assert/strict`. Frontend tests load real fixtures through Babel, php-parser, Prism, Lezer, and the qualified official Tree-sitter Python route and compare modeled meaning after removing source locations and the separately tested provenance index. They separately assert normalized annotations, complete named/anonymous child traversal, parser recovery rejection, and exact UTF-16 locations.
+
+Task 015 has separate focused specs for immutable registry-derived discovery, role-specific diagnostics, safe transactional artifact sets, byte-coordinate provenance, exact tool discovery, and staged acceptance. Every caller-supplied ordered array in these contracts must be dense before element validation or iteration; each field independently retains its documented empty/non-empty rule. Error-path discovery uses controlled local fake executables. Positive runner coverage discovers and invokes real `php`, `ruby`, `node`, the lockfile-installed `tsc`, `javac`, and `java`; a missing or unsupported tool is a failure, never a skip. Runner assertions cover isolated directory cleanup, fixed `C.UTF-8` locale and UTC timezone, absence of undeclared ambient variables, exact argument arrays, and distinct invalid-input, missing, ambiguous, version, setup/materialization, launch, output-limit, nonzero-stage, signal, and timeout diagnostics. `ACCEPTANCE_LAUNCH_FAILURE` is restricted to explicit operating-system spawn errors. `ACCEPTANCE_OUTPUT_LIMIT` identifies a child that launched but exceeded the fixed 16 MiB capture limit; its diagnostic retains stage/tool/version and the deterministic limit evidence while omitting the oversized streams and child error object.
+
+Task 016 extends the same fail-loud discovery and staged runner to configured Python 3. Native Python acceptance first invokes `python3 -m py_compile program.py`, then executes `python3 program.py` with deterministic `C.UTF-8`, `PYTHONUTF8=1`, and `PYTHONIOENCODING=utf-8`. Cross-language coverage generates and reparses Python from every original-five Tasks 001–004 fixture, then generates every original target from Python-derived IR, compiling where applicable and comparing exact runtime output. Missing Python is a test failure.
+
+| Tool ID | Canonical command | Absolute-path override | Accepted canonical version |
+| --- | --- | --- | --- |
+| `php` | `php` | `SEMANTIFOLD_PHP` | PHP 8.x |
+| `ruby` | `ruby` | `SEMANTIFOLD_RUBY` | Ruby 3.x |
+| `node` | `node` | `SEMANTIFOLD_NODE` | Node 24.x |
+| `tsc` | `tsc` | `SEMANTIFOLD_TSC` | TypeScript 7.x |
+| `javac` | `javac` | `SEMANTIFOLD_JAVAC` | JDK 17–29 |
+| `java` | `java` | `SEMANTIFOLD_JAVA` | JRE 17–29 |
+| `python` | `python3` | `SEMANTIFOLD_PYTHON` | Python 3.x |
+
+Canonical toolchain IDs must be non-empty primitive strings and are validated before property lookup or diagnostic formatting; malformed values normalize to `INVALID_TOOLCHAIN`, while an unknown valid string retains that string as its diagnostic identity. Discovery records the complete version output and first version line. Optional discovery and runner configuration defaults only when a field is `undefined`; explicit `null`, including in an environment entry, is invalid before lookup, setup, or launch. Explicit timeouts must be positive integers no greater than Node's exact timer ceiling of 2,147,483,647 milliseconds; larger values are rejected before lookup, setup, or launch rather than being clamped to one millisecond. Explicit environments must be ordinary or null-prototype records containing only enumerable own data properties with string or `undefined` values; inherited fields, accessors, symbol keys, collection/class instances, and other object shapes are rejected. Accepted environment values are synchronously detached before override lookup, setup, or launch. An override must be an executable absolute path resolving to a regular file; directories and other invalid file types report `TOOL_NOT_FOUND`. Canonical lookup examines the explicit PATH, accepts only executable regular files, resolves symlinks to exact paths, deduplicates aliases of the same executable, and rejects zero or multiple distinct matches. Version arguments and the accepted non-global/non-sticky version-policy expression are validated and detached before asynchronous executable lookup; the immutable discovery result retains the exact argument array that was executed, and caller mutation cannot change the pending version decision. TensorBuzz installs its pinned Node archive at `/usr/local/bin/node` and binds that exact executable through `SEMANTIFOLD_NODE`; a distinct host `/usr/bin/node` therefore cannot make the real-runtime lane ambiguous. This does not weaken canonical ambiguity detection when no override is configured. The runner inherits no ambient variables other than PATH unless the caller explicitly supplies them; locale and timezone are always normalized. Stage executable and version fields are copied and frozen before setup yields, embedded NUL is rejected before temporary-directory setup, and each completed stage returns a frozen copy of its executed argument array, so caller mutation cannot change execution or its audit record. On POSIX, version probes and acceptance stages spawn into one distinct owned process group: the configured deadline signals that exact group with `SIGTERM`, a fixed 250ms grace escalates the still-open group to `SIGKILL`, and a second fixed 250ms grace closes only the owned capture-pipe readers if an escaped descendant still retains their writers. The API then settles on the direct child's `close` event without claiming that an escaped process was terminated; captured output and timer-owned timeout classification remain unchanged. Platforms without this process-group contract fail with normalized unsupported launch/version diagnostics before spawning rather than claiming descendant cleanup. Timeout diagnostics derive from timer ownership rather than a subprocess signal, so spontaneous signals remain `TOOL_VERSION_FAILURE` or `ACCEPTANCE_SIGNAL` with their exact evidence. If a stage and isolated-directory cleanup both fail, the stage diagnostic remains primary with its exact stage, exit, signal, and bounded output fields; a bounded `ACCEPTANCE_CLEANUP_FAILURE` diagnostic is retained in its cause chain. Cleanup failure after successful stages remains `ACCEPTANCE_CLEANUP_FAILURE`.
 
 Backend tests start from one parsed semantic module, generate every target, parse each generated program back to equivalent modeled meaning, and work in isolated `mkdtemp` directories. They invoke real commands and assert exact `5\n` output:
 
@@ -9,10 +25,13 @@ Backend tests start from one parsed semantic module, generate every target, pars
 - `node program.js`
 - local lockfile-installed `tsc program.ts`, then `node program.js`
 - `javac Main.java`, then `java -cp … Main`
+- `python3 -m py_compile program.py`, then `python3 program.py` with `PYTHONUTF8=1` and `PYTHONIOENCODING=utf-8`
 
 Cleanup runs in `finally`. A missing tool raises the process error and fails the spec; there are no skip branches or mocked compilers. Diagnostic specs cover unsupported syntax, missing JSDoc types, and backend capability rejection.
 
-Mapping specs assert all 25 frontend/backend combinations, exact/anchor/synthetic coverage without gaps, semantic-token roles, deterministic source/node/symbol IDs, exact `sourcesContent`, independently decoded v3 maps, rich/v3 composition, malformed caller metadata repair, legacy modules, caller-assembled multi-source IR, and deterministic JSON round trips. Transformation regressions cover same-kind function reorder, insertion, deletion, cloning, ID regeneration, source ownership, shared parameter, expression, and statement occurrences, and their distinct JSON-pointer node identities. UTF-16 cases cover BMP/astral text plus LF, canonical CRLF, and lone CR; escaped Babel identifiers cover declarations, references, and calls. Imported maps are checked against TraceMap on unmapped prefixes and lines; content-backed EOF anchors, including empty sources, round-trip as exact points, while mapped imports without source content are rejected before offset construction. Composition coverage includes derived intermediate provenance that resolves only to unmapped synthetic content, untraced intermediate EOF points whose registry source must remain available, and ordering where a later range remains traceable. Identity-index coverage checks direct, derived, and synthetic-related node/symbol associations for ordered deduplication. External directive coverage includes mixed parent-relative depths and resolution to the advertised map path. A bounded 50-to-200-function scaling test guards linear validation and indexed lookups; deterministic operation-count coverage guards Babel token indexing without wall-clock thresholds. A real `tsc` map is composed through generated TypeScript to original Ruby source. A separate mapped-artifact acceptance executes PHP, Ruby, Node, TypeScript through real `tsc`/Node, and Java through real `javac`/`java`; unavailable commands fail. SHA-256 characterization checks preserve every existing base/local generated byte across all source languages and targets.
+Mapping specs assert all 36 frontend/backend combinations, exact/anchor/synthetic coverage without gaps, semantic-token roles, deterministic source/node/symbol IDs, exact `sourcesContent`, independently decoded v3 maps, rich/v3 composition, malformed caller metadata repair, legacy modules, caller-assembled multi-source IR, and deterministic JSON round trips. Transformation regressions cover same-kind function reorder, insertion, deletion, cloning, ID regeneration, source ownership, shared parameter, expression, and statement occurrences, and their distinct JSON-pointer node identities. UTF-16 cases cover BMP/astral text plus LF, canonical CRLF, and lone CR; escaped Babel identifiers cover declarations, references, and calls. Imported maps are checked against TraceMap on unmapped prefixes and lines; content-backed EOF anchors, including empty sources, round-trip as exact points, while mapped imports without source content are rejected before offset construction. Composition coverage includes derived intermediate provenance that resolves only to unmapped synthetic content, untraced intermediate EOF points whose registry source must remain available, and ordering where a later range remains traceable. Identity-index coverage checks direct, derived, and synthetic-related node/symbol associations for ordered deduplication. External directive coverage includes mixed parent-relative depths and resolution to the advertised map path. A bounded 50-to-200-function scaling test guards linear validation and indexed lookups; deterministic operation-count coverage guards Babel token indexing without wall-clock thresholds. A real `tsc` map is composed through generated TypeScript to original Ruby source. Mapped-artifact acceptance executes PHP, Ruby, Node, TypeScript through real `tsc`/Node, Java through real `javac`/`java`, and Python through its configured interpreter after `py_compile`; unavailable commands fail. SHA-256 characterization checks preserve every existing base/local generated byte across all original source languages and targets.
+
+Task 016 adds mapped Python execution through the configured interpreter after `py_compile`; the original-five SHA-256 characterizations remain unchanged.
 
 Local-binding fixtures cover initialized mutable and immutable declarations, plain assignment, function/branch/entry sequencing, exact Ruby/PHP profile metadata, and source locations in all five frontends. Focused negatives cover every declaration/assignment exclusion, declaration-before-use, unresolved and duplicate bindings, callable-name and lexical no-shadowing, immutable parameters/locals, exact type preservation, and RHS-before-target validation. Ruby coverage rejects profile-like tag misspellings, places multibyte text before later function and local carrier comments, asserts their UTF-16 locations, and reparses generated Ruby with the same offset shift. Backend shape coverage applies missing, null, primitive, array, sparse, and unsupported-object values to recursive blocks, statement elements, declaration/assignment fields, and recursively nested call expressions, proving caller-supplied malformed IR receives the nearest located capability diagnostic before emitter dispatch. Backend runtime coverage regenerates and reparses the same binding/mutability semantics, then executes the result through all five real toolchains with exact `yes\n` output. Target-focused coverage rejects JavaScript/TypeScript `console` and Java `args`/`System` entry captures, JavaScript/TypeScript `console` and Java `System` function parameter/local print-receiver captures, and JavaScript/TypeScript `console` and Ruby `puts` function captures before emission. Real `tsc`, PHP, and Ruby coverage demonstrates their strict or reserved binding failures and requires located target-backend rejection for each proven declaration/assignment role. The PHP probe matrix separately covers automatic-global parameters, the narrower `GLOBALS`/`this` assignment restriction, legal function names, assignable non-`GLOBALS` superglobals, ordinary predefined variables, and exact-case near-collisions; other runtime coverage executes safe JavaScript behavior, Ruby `_10`, and TypeScript near-collisions.
 

package/index.js

@@ -2,8 +2,18 @@
 
 import {parseSource} from "./src/frontends/index.js"
 import {generateArtifactSource, generateSource} from "./src/backends/index.js"
+import {createGeneratedArtifactSet as constructArtifactSet} from "./src/artifacts.js"
+import {SemantifoldDiagnostic} from "./src/diagnostic.js"
+import {languageRegistry} from "./src/language-registry.js"
 
-export {SemantifoldDiagnostic} from "./src/diagnostic.js"
+const artifactBackendRoles = new Set(["text", "binary", "application"])
+
+export {SemantifoldDiagnostic}
+export {languageCapabilities, supportedLanguages} from "./src/language-registry.js"
+export {createGeneratedArtifactSet} from "./src/artifacts.js"
+export {createByteMapping, parseByteMapping, stringifyByteMapping} from "./src/binary-mapping.js"
+export {canonicalToolchains, discoverCanonicalToolchain, discoverToolchain} from "./src/toolchains.js"
+export {runAcceptanceStages} from "./src/acceptance.js"
 export {getNodeProvenance, getSymbolProvenance} from "./src/semantic/provenance.js"
 export {primaryLocation} from "./src/semantic/provenance.js"
 export {
@@ -21,9 +31,6 @@ export {
   toSourceMapV3
 } from "./src/mapping.js"
 
-/** @type {readonly import("./src/semantic/types.js").SemanticLanguage[]} */
-export const supportedLanguages = Object.freeze(["php", "ruby", "javascript", "typescript", "java"])
-
 /**
  * Parses source into Semantifold's shared semantic representation.
  * @param {object} input - Parse request.
@@ -61,3 +68,101 @@ export function generate(input) {
 export function generateArtifact(input) {
   return generateArtifactSource(input)
 }
+
+/**
+ * Generates a deterministic artifact set for one semantic module.
+ * @param {object} input - Artifact-set generation request.
+ * @param {string} input.language - Registered target language or platform ID.
+ * @param {import("./src/semantic/types.js").SemanticModule} input.module - Semantic module.
+ * @param {"text" | "binary" | "application"} [input.role] - Requested backend artifact role.
+ * @param {string} [input.filename] - Safe output path for a text target.
+ * @param {"none" | "external" | "inline"} [input.mapDirective] - JavaScript-family map directive.
+ * @param {string} [input.sourceMapFilename] - External map filename.
+ * @param {{filename: string, content: string, language?: import("./src/semantic/types.js").SemanticLanguage}[]} [input.sources] - Original sources.
+ * @returns {import("./src/semantic/types.js").GeneratedArtifactSet} Complete generated set.
+ */
+export function generateArtifactSet(input) {
+  if (!input || typeof input != "object" || Array.isArray(input) || Object.getPrototypeOf(input) != Object.prototype) {
+    throw new SemantifoldDiagnostic({
+      code: "INVALID_ARTIFACT_SET",
+      language: "artifact",
+      message: "Artifact-set generation requires a request object."
+    })
+  }
+  const {filename, language, mapDirective, module, role = "text", sourceMapFilename, sources} = input
+
+  if (typeof language != "string" || language.length == 0) {
+    throw new SemantifoldDiagnostic({
+      code: "INVALID_ARTIFACT_SET",
+      language: "artifact",
+      message: "Artifact-set generation requires a non-empty string language or target ID."
+    })
+  }
+  if (typeof role != "string" || !artifactBackendRoles.has(role)) {
+    throw new SemantifoldDiagnostic({
+      code: "INVALID_ARTIFACT_SET",
+      language,
+      message: "Artifact backend role must be 'text', 'binary', or 'application'."
+    })
+  }
+
+  if (role == "text") {
+    const record = languageRegistry.record(language)
+
+    if (record.artifactMultiplicity == "multiple") {
+      const backend = languageRegistry.resolve(language, "textBackend", module?.location)
+
+      return constructArtifactSet(backend({filename, language, module, sources}))
+    }
+    const artifact = generateArtifactSource({
+      filename,
+      language: /** @type {import("./src/semantic/types.js").SemanticLanguage} */ (language),
+      mapDirective,
+      module,
+      sourceMapFilename,
+      sources
+    })
+
+    /** @type {import("./src/semantic/types.js").GeneratedSetArtifact[]} */
+    const artifacts = [{
+      content: artifact.code,
+      contentKind: "text",
+      mediaType: /** @type {string} */ (record.mediaType),
+      ownership: "generated",
+      path: artifact.filename,
+      provenance: {
+        kind: "text",
+        mapping: artifact.mapping,
+        sourceMap: artifact.sourceMap,
+        sourceMapFilename: artifact.sourceMapFilename
+      },
+      role: "entry"
+    }]
+
+    if (mapDirective == "external") {
+      artifacts.push({
+        content: `${JSON.stringify(artifact.sourceMap)}\n`,
+        contentKind: "text",
+        mediaType: "application/json",
+        ownership: "generated",
+        path: artifact.sourceMapFilename,
+        provenance: {
+          kind: "synthetic",
+          reason: "Serialized Source Map v3 projection for the generated entry artifact.",
+          relatedOrigins: []
+        },
+        role: "mapping"
+      })
+    }
+
+    return constructArtifactSet({
+      artifacts,
+      target: language
+    })
+  }
+
+  const registryRole = role == "binary" ? "binaryBackend" : "applicationBackend"
+  const backend = languageRegistry.resolve(language, registryRole, module?.location)
+
+  return constructArtifactSet(backend({filename, language, module, sources}))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantifold",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Language-neutral semantic code analysis, transformation, generation, and execution toolkit",
   "type": "module",
   "main": "build/index.js",
@@ -51,7 +51,9 @@
     "@lezer/java": "^1.1.3",
     "@ruby/prism": "^1.9.0",
     "comment-parser": "^1.4.1",
-    "php-parser": "^3.7.0"
+    "php-parser": "^3.7.0",
+    "tree-sitter": "0.25.1",
+    "tree-sitter-python": "0.25.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",