semantifold 0.1.1 → 0.3.0

package/docs/parser-qualification.md

@@ -0,0 +1,219 @@
+# 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 | passed for exact `tree-sitter-c-sharp@0.23.5`; see the checked-in record below |
+| 018 | C | official [`tree-sitter/tree-sitter-c`](https://github.com/tree-sitter/tree-sitter-c) grammar package | legacy pair qualified inside the bundled root distribution below; source/target work remains blocked until that packaging correction is reviewed, green, merged, and verified |
+| 019 | C++ | official [`tree-sitter/tree-sitter-cpp`](https://github.com/tree-sitter/tree-sitter-cpp) grammar package | exact 0.23.4 qualified with the existing isolated 0.21.1 runtime; see Task 019 record below |
+| 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 | passed for exact `tree-sitter-go@0.25.0`; see the checked-in record below |
+| 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.
+
+## Task 017 C# qualification
+
+Qualification passed in a credential-free empty `/tmp` package on canonical Node `v24.18.1`, npm `11.16.0`, Linux x64, and .NET SDK `10.0.111` (runtime/`Microsoft.NETCore.App` `10.0.11`, RID `ubuntu.26.04-x64`, `Microsoft.NETCore.App.Ref`/`Microsoft.AspNetCore.App.Ref` targeting packs `10.0.11`). Task 017 therefore uses the existing exact `tree-sitter@0.25.1` binding with official registry grammar `tree-sitter-c-sharp@0.23.5`; neither dependency is a Git/archive path or vendored artifact.
+
+| Evidence | Qualified result |
+| --- | --- |
+| npm distribution | `tree-sitter-c-sharp@0.23.5`, resolved from `https://registry.npmjs.org/tree-sitter-c-sharp/-/tree-sitter-c-sharp-0.23.5.tgz` with integrity `sha512-xJGOeXPMmld0nES5+080N/06yY6LQi+KWGWV4LfZaZe6srJPtUtfhIbRSN7EZN6IaauzW28v6W4QHFwmeUW6HQ==`; exact peer `tree-sitter@^0.25.0` is satisfied by `0.25.1`. |
+| upstream identity | Official [`tree-sitter/tree-sitter-c-sharp`](https://github.com/tree-sitter/tree-sitter-c-sharp) annotated tag `v0.23.5` (tag object `173c15453b733ccde654032fec7103705b5ad04f`), peeled commit and npm `gitHead` `cac6d5fb595f5811a076336682d5d595ac1c9e85`. |
+| legal and registry provenance | The grammar declares MIT. In the clean exact installation, `npm audit signatures` verified all four installed-package registry signatures and two attestations. The grammar's registry signature, tag/commit identity, package contents, and lockfile integrity were checked; no credential was exposed or requested. |
+| clean Node 24 install/load | With npm auth/token environment variables removed, exact installation and `npm ls --all` passed with zero vulnerabilities. The package has no Node engine declaration, so compatibility was proven empirically: its explicit Node binding import loaded, `Parser#setLanguage` succeeded, and all fixtures parsed through the native binding. |
+| ABI, typing, lifecycle, and package inputs | The grammar declares ABI `15`; `tree-sitter@0.25.1` supports ABI `13`–`15`. The grammar ships typed `bindings/node/index.d.ts`, Linux x64/arm64 prebuilds, grammar C source fallback, and only `install: node-gyp-build`; no runtime downloader is declared. Dry-run packs showed normal registry package contents. No tarball, parser source copy, prebuild, `node_modules`, NuGet cache, `bin`, or `obj` entered the repository. |
+| coordinates and recovery | `child(index)` traversal covered every named, anonymous, comment, nullable directive, error, and missing node. The Node binding exposes UTF-16 code-unit indexes for JavaScript strings despite Tree-sitter's byte-oriented native contract; astral text before an identifier and CRLF probes separated UTF-16 and UTF-8 offsets. The adapter rejects lone surrogates and verifies every boundary through the shared UTF-8-byte-to-UTF-16 converter. Malformed braces, operands, and missing semicolons produced explicit or propagated `hasError`/`isError`/`isMissing`; propagated ancestor error state is rejected even where no distinct `ERROR` child exists. |
+| Tasks 001–004 grammar shapes | The five fixtures proved exact shapes for `preproc_nullable`, file-scoped namespace, class/modifiers, methods/parameters/types, blocks, declarations, carrier comments, assignments, calls/arguments, print member access, checked expressions, all scalar literals/operators, returns, and `if`/`else if`/`else`. Adapter specs retain field and token ranges and reject every unmodeled present child. |
+| official compiler comparison | All five fixture projects restored without external packages, built under .NET 10/C# 14 with warnings as errors and no warning output, and executed with exact expected stdout. Restore, build, and execution were separate; the isolated `NUGET_PACKAGES` path was resolved to an absolute path because the SDK rejects a relative global packages folder. The official grammar needs no community-grammar differential exception. |
+
+Reproduce the registry qualification 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-c-sharp@0.23.5
+npm audit signatures
+npm ls --all
+npm pack tree-sitter@0.25.1 --dry-run --json
+npm pack tree-sitter-c-sharp@0.23.5 --dry-run --json
+```
+
+The accepted C# corpus is `spec/fixtures/{Program.cs,scalars/Program.cs,locals/Program.cs,operators/Program.cs,statements/Program.cs}` with SHA-256 values, in that order: `5ca661d09dff2d775094df99b40e5c5604796c9bff4c32c1da11fa1b4c564a00`, `9cefd6d01c5855480629829489945f2f43338b84879c7a26043963151a8439da`, `ee775fea59ee812212ce325152e4e4cb79c20e699aba081bf39cc698b324444d`, `7137f4acc88dbdc1d0bafd6bb8eb57bed9386daf3e6b11c6fbae3831abceae18`, and `ba63cb72490605437e1efaa7d69ce0abdbfbb07c076aec787bc025e7a277468f`.
+
+## Task 018 legacy C parser boundary qualification
+
+The C grammar's compatible published runtime line cannot share Semantifold's root Tree-sitter instance. The one root `semantifold@0.2.0` distribution therefore explicitly bundles root `tree-sitter@0.25.1` for its modern grammars and a private internal package with an isolated exact `tree-sitter@0.21.1` plus `tree-sitter-c@0.23.2` subtree, whose peer range and grammar ABI agree. The renamed private workspace owns source checking and declaration generation but has no export, publication metadata, or release gate. A separately tested `tree-sitter@0.22.4` plus `tree-sitter-c@0.24.1` install was rejected because `Parser#setLanguage` failed with an undefined `nodeTypeNamesById`; an installable graph alone is not qualification.
+
+| Evidence | Qualified boundary result |
+| --- | --- |
+| npm distribution | `tree-sitter@0.21.1`, integrity `sha512-7dxoA6kYvtgWw80265MyqJlkRl4yawIjO7S5MigytjELkX43fV2WsAXzsNfO7sBpPPCF5Gp0+XzHk0DwLCq3xQ==`; `tree-sitter-c@0.23.2`, integrity `sha512-9kADOx31AF94DHcrsMGW0zM/2LS6v7wFkPHPVm7RQU+vYVVZMKZ2FJ9e99pm5feqsAcjUzB9CarqDLgRT1Fe/w==`. npm's supported `file:` dependency plus repository-local `install-links=true` materializes the private internal package, and root `bundleDependencies` includes both that package and modern `tree-sitter`. Root `acceptDependencies` accepts only the exact private `0.1.0` payload already in the bundle, so consumers use ordinary `install-links=false`. No alias, override, forced peer, archive dependency, copied binding, or custom materialization stage is used. |
+| upstream identity | Official [`tree-sitter/node-tree-sitter`](https://github.com/tree-sitter/node-tree-sitter) tag/commit `v0.21.1` / `bbdba663dc0b8487f1212524a83a7c39e8a5c3ca`; official [`tree-sitter/tree-sitter-c`](https://github.com/tree-sitter/tree-sitter-c) tag/commit and npm `gitHead` `v0.23.2` / `6a4ae2e08916fd08e5739250bb64a14392b01c99`. |
+| legal and registry provenance | Both upstream packages declare MIT and publish registry signatures. Their exact registry URLs and integrities are recorded in `package-lock.json`; the repository gate verifies installed-package signatures and audits the ordinary dependency graph. The private internal package uses ISC and has no public registry identity. All three dependency licenses remain in the root tarball. |
+| ABI and API | `tree-sitter-c@0.23.2` declares language ABI 14; `tree-sitter@0.21.1` accepts ABI 13–14 and the grammar's peer is `^0.21.1`. The legacy binding provides `child(index)` and `fieldNameForChild(index)` but not the newer `fieldNameForNamedChild` convenience API. The adapter therefore traverses every ordered named and anonymous child and copies field names without exposing binding types. |
+| runtime isolation | A real root tarball installed into a credential-free consumer with a fresh npm cache resolves modern `tree-sitter@0.25.1` at the root and legacy `tree-sitter@0.21.1` plus `tree-sitter-c@0.23.2` below the private internal package at distinct paths. No workspace is present in the consumer and no registry publication of the internal name is required. One Node `v24.18.1` Linux x64 process parses modern Go and legacy C without a native-module collision. Ordinary npm install and peer resolution are mandatory. |
+| private boundary | The internal `parseCst(source)` returns only a recursively frozen `semantifold.parser-cst` version 1 envelope and is absent from Semantifold's public exports. Nodes contain plain scalar state, UTF-16 indices/row-column positions, and ordered frozen `{field, node}` edges. Parser, tree, syntax-node, language, method, function, parent, circular, and source-text values do not cross the boundary. The caller retains source ownership and can slice it by the normalized offsets. |
+| recovery and coordinates | Astral text before a later definition plus CRLF separates UTF-8 bytes from UTF-16 code units; the snapshot retains exact UTF-16 indices and row/column positions. Comments remain visible as extra nodes. A missing closing brace propagates `hasError` and preserves the missing node rather than recovering through source text. |
+| lifecycle and package inputs | The native dependencies use only `install: node-gyp-build` and have no runtime downloader. The root tarball retains licenses, `binding.gyp`, and native source fallback for both Tree-sitter bindings plus the C grammar's `binding.gyp` and generated parser source. Modern `tree-sitter@0.25.1` includes Darwin, Linux, and Windows x64/arm64 prebuilds; legacy `tree-sitter@0.21.1` includes Darwin arm64/x64, Linux x64, and Windows x64 prebuilds; `tree-sitter-c@0.23.2` includes Darwin, Linux, and Windows x64/arm64 prebuilds. Only Linux x64 native loading and execution were tested. Other listed platforms rely on upstream prebuild selection or source compilation and are packaging-presence claims, not execution claims. Source fallback additionally requires a compatible compiler toolchain and consumer npm policy permitting the upstream `node-gyp-build` install scripts; fallback compilation was not executed here. Accidental `build/Debug` or `build/Release` output is rejected from the pack proof. |
+| task boundary | This record qualifies only the runtime/package boundary. It does not implement or claim the Task 018 C frontend, semantic normalization, backend, registry, toolchain, compiler comparison, or Tasks 001–004 C corpus. That prerequisite was completed through https://github.com/kaspernj/semantifold/pull/19 at `9184660a21820b429138f0632c89df956a2e350f`; Task 018 implementation and native acceptance are recorded separately below. No package publication is part of that prerequisite. |
+
+Reproduce the repository-owned proof on Node 24 with:
+
+```sh
+npm ci
+npx velocious-test spec/tree-sitter-legacy-adapter.spec.js
+npx velocious-test spec/tree-sitter-legacy-packed-consumer.spec.js
+npm ls --all
+npm pack --dry-run --json
+```
+
+The packed-consumer spec creates the root tarball, fresh cache, and consumer only under unique temporary directories. It removes all inherited npm configuration and token variables case-insensitively, uses empty user/global npm config files and explicit `https://registry.npmjs.org/`, and asserts default `install-links=false` even when supplied synthetic alternate configuration. Before packing, the source/installed consistency gate rejects stale local-package copies; normal root `npm ci` is the recovery after shipped source edits. The spec compares bundled internal files with source and runs default `npm install` followed by default `npm ci`. After each it checks the complete installed lock/tree and real runtime paths, compiles a root API type consumer, and executes both parsers in one process. Cache inspection rejects internal or retired registry lookups; `finally` removes the fixture. Publication is intentionally excluded from this qualification.
+
+The dependency declaration follows npm's implemented [acceptDependencies contract](https://github.com/npm/rfcs/blob/main/implemented/0023-acceptDependencies.md): an already-present exact package can satisfy the edge, but new resolution uses only `dependencies`, here the local `file:` source. It does not relax either native runtime or grammar version and is not an override. With npm 11.16.0, a direct private-workspace fixture packed the legacy bindings under `packages/internal/node_modules` while placing the workspace payload under `node_modules`, leaving the installed boundary unresolved. The materialized local dependency instead packs the complete subtree under its real module directory; the source-byte gate and default-consumer proof protect both halves of that contract.
+
+## Task 024 Go qualification
+
+Qualification passed in a credential-free empty `/tmp` package on canonical Node `v24.18.1`, npm `11.16.0`, Linux x64, and Go `go1.26.0 linux/amd64` with GOROOT `/usr/lib/go-1.26`. Task 024 therefore uses the existing exact `tree-sitter@0.25.1` binding with official registry grammar `tree-sitter-go@0.25.0`; neither dependency is a Git/archive path or vendored artifact.
+
+| Evidence | Qualified result |
+| --- | --- |
+| npm distribution | `tree-sitter-go@0.25.0`, resolved from `https://registry.npmjs.org/tree-sitter-go/-/tree-sitter-go-0.25.0.tgz` with integrity `sha512-APBc/Dq3xz/e35Xpkhb1blu5UgW+2E3RyGWawZSCNcbGwa7jhSQPS8KsUupuzBla8PCo8+lz9W/JDJjmfRa2tw==`; peer `tree-sitter@^0.25.0` is satisfied by exact `tree-sitter@0.25.1` with integrity `sha512-mrcEdkYtHfrK1A6fs3O6FxkBo0Qig5XUXqHhxUOQu0bmPo00QF4XaSx4edpazdHwxnSCjlGKGgIqWdaN4dvTLA==`. |
+| upstream identity | Official [`tree-sitter/tree-sitter-go`](https://github.com/tree-sitter/tree-sitter-go) annotated tag `v0.25.0` (tag object `6048bfc6e5238eaf062c2221bd934489c39fbb61`), peeled commit and npm `gitHead` `1547678a9da59885853f5f5cc8a99cc203fa2e2c`. The binding is official tag `v0.25.1`, npm `gitHead` `75a0eccfedc491e26843bd744bb6806f8a8bfff4`. |
+| legal and registry provenance | Both packages declare MIT. `npm audit signatures` verified all four installed-package registry signatures and two attestations with no invalid or missing signature. The binding publishes npm SLSA provenance; the grammar has a verified registry signature but did not advertise an npm attestation, so tag/commit identity and registry integrity were checked independently. |
+| clean install/load | With npm auth/token environment variables removed, `npm install --save-exact tree-sitter@0.25.1 tree-sitter-go@0.25.0` succeeded from the registry in a fresh package with zero vulnerabilities. `npm ls --all` resolved only `node-addon-api@8.9.2`, `node-gyp-build@4.8.4`, the exact binding, and the exact grammar. The explicit ESM import loaded on Node 24, `Parser#setLanguage` succeeded, and typed `nodeTypeInfo` exposed 188 grammar entries. |
+| ABI, typing, lifecycle, and package inputs | The shipped grammar declares ABI `15`; `tree-sitter@0.25.1` accepts ABI `13` through `15`. The grammar declaration exposes its language handle and `NodeInfo[]` metadata. Both packages use only `install: node-gyp-build`, with no downloader URL or extra lifecycle dependency. Dry-run packs contained 80 binding files (1,594,590-byte archive) and 25 grammar files (558,540-byte archive), including declarations, licenses, platform prebuilds, and source fallback. No archive, prebuild, generated parser, native binary, `node_modules`, or qualification output entered Semantifold. |
+| coordinates, comments, and recovery | The Node binding exposed UTF-16 code-unit indexes: after astral text and CRLF, one literal occupied indexes 61–65 while raw UTF-8 byte boundaries were 63–69; both round-tripped through `utf8ByteOffsetToUtf16Offset()`. Lone surrogates were rejected before parsing. Ordinary and `//go:`, `// +build`, and `//line` directive comments remained visible nodes. Malformed package clauses, parameter lists, missing operands, braces, semicolons, and incomplete strings all exposed `hasError`, `isError`, or `isMissing`. |
+| Tasks 001–004 tree corpus | Exhaustive `child(index)` traversal covered every named and anonymous child, token, comment, and `fieldNameForChild` edge in all five fixtures. Observed shapes include the exact package/import/function/parameter/type/result/block scaffold; variable declarations/specs; assignment/expression lists; returns, calls, arguments, and selectors; parentheses; every accepted scalar/operator node; and nested `if`/`else if`/`else`. No source scan supplied missing structure. |
+| official-tool differential | Matching `/usr/lib/go-1.26/bin/gofmt -d` produced no diff for all five fixtures. In separate dependency-free modules with fixed `go.mod`, every fixture passed offline/local, cgo-disabled `go build`, mandatory `go vet`, and `go run` with exact output. A no-import sample passed `go tool compile`. All six malformed samples were rejected by both `gofmt` and `go tool compile`. A slice/range/short-declaration sample parsed, formatted, built, vetted, and ran under official Go, establishing the intentional valid-but-`UNSUPPORTED_SYNTAX` differential boundary. No `go.sum`, `go.work`, vendor tree, or source mutation appeared. |
+| toolchain isolation | Every Go process used `GOTOOLCHAIN=local`, `GOPROXY=off`, `GOSUMDB=off`, `GOVCS=off`, `CGO_ENABLED=0`, `GOENV=off`, `GOWORK=off`, `GOOS=linux`, `GOARCH=amd64`, and separate absolute cache/module/GOPATH/temp/home paths. `/usr/bin/gofmt` resolved to `/usr/lib/go-1.26/bin/gofmt`, the same verified GOROOT as `go`. |
+
+Reproduce the registry qualification in a fresh 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-go@0.25.0
+npm audit signatures
+npm ls --all
+npm pack tree-sitter@0.25.1 --dry-run --json
+npm pack tree-sitter-go@0.25.0 --dry-run --json
+```
+
+The accepted Go corpus is `spec/fixtures/{program.go,scalars/program.go,locals/program.go,operators/program.go,statements/program.go}` with SHA-256 values, in that order: `5f4ad40a233d8728c90ca885d4bfe6f018f1d7a5e6f2e2cfb97b4b9db4887f1c`, `6d4251def8b1bccdff177df901bf9fe109a8a01ae1514cb8d5aaf364298669b9`, `a7b6eb2f5eae0a20d7cd4982e4d26cc6653760ad03e8b21ff5c360239861dd6f`, `4a263413830a41a59b6d8326a78067826853e3491e65d52559e5acea0d9cf56c`, and `d64f083d70697d25d2ea7f5c7a44cada0ab13a878640fd10bc547df185fa7bba`.
+
+## Task 018 C integration
+
+The C frontend consumes the unchanged frozen parser-neutral legacy boundary qualified above. It adds no native dependency, archive, copied parser, workspace identity, consumer flag or override. Complete C child/field/token traversal, recovery rejection, exact generated-region reconstruction and full canonical-CST comparison are covered by `spec/c-frontend-validation.spec.js` and `spec/c-ordered-expressions.spec.js`. The five checked-in `program.c` fixture profiles pass generated-source round trips and original-five bidirectional execution. Unicode/NUL, every operation/consumer, eager/short-circuit effects and arena/fatal paths run through real separate Clang compile/link/native execution at O0/O2, ordinary and sanitized. The ordinary packed-root consumer now additionally exercises public C parse/generate/reparse and C API typing after both default install and clean npm ci; it preserves the existing credential-free configuration and cache proof. This is implementation regression coverage, not another packaging review. See [C semantics and scaffolds](c.md), [toolchain qualification](testing.md) and [the delivery record](../todo/018-c-source-and-target.md).
+
+## Task 019 C++ grammar qualification — 2026-09-08
+
+This record precedes the dependency manifest change. The official C++ grammar is selected explicitly inside the existing private runtime; the C grammar is not a C++ parser. The root distribution and both existing Tree-sitter versions remain unchanged.
+
+| Evidence | Qualified result |
+| --- | --- |
+| Official npm release | `tree-sitter-cpp@0.23.4`, registry URL `https://registry.npmjs.org/tree-sitter-cpp/-/tree-sitter-cpp-0.23.4.tgz`, integrity `sha512-qR5qUDyhZ5jJ6V8/umiBxokRbe89bCGmcq/dk94wI4kN86qfdV8k0GHIUEKaqWgcu42wKal5E97LKpLeVW8sKw==`. Latest registry tag at qualification was 0.23.4. |
+| Upstream identity and license | Official [tree-sitter/tree-sitter-cpp](https://github.com/tree-sitter/tree-sitter-cpp/tree/v0.23.4), tag `v0.23.4` and npm gitHead both `f41e1a044c8a84ea9fa8577fdd2eab92ec96de02`; MIT license present in the registry package. `git ls-remote` verified the tag. |
+| Ordinary peer graph | Optional peer `tree-sitter@^0.21.1`, grammar ABI 14; exact existing binding 0.21.1 accepts ABI 13–14. Grammar dependency `tree-sitter-c@^0.23.1` dedupes to the existing exact 0.23.2. Clean install and `npm ls --all` resolved these three packages plus node-addon-api 8.9.2 and node-gyp-build 4.8.4, without overrides, force, peer bypass, aliases or a third runtime. |
+| Node and supply chain | Node v24.18.1, npm 11.16.0, Linux x64 as UID1000. Fresh run-local package/cache, empty user/global npm configuration, explicit public registry, inherited npm configuration/token variables removed. Ordinary exact installation succeeded with zero vulnerabilities. `npm audit signatures` verified five registry signatures and one attestation. |
+| Native and typed API | Actual ESM import, `new Parser()`, `setLanguage(CPP)`, parse and exhaustive `child(index)` / `fieldNameForChild(index)` traversal passed beside C in the same process. The declaration's `setLanguage` returns void and fields are nullable; a strict NodeNext typed consumer passed without casts or skipLibCheck, using the repository's Node types. The grammar includes typed `nodeTypeInfo`. |
+| Corpus and coordinates | Five source probes traversed 390 named/anonymous/comment nodes, including qualified scalar types, initialized const/mutable locals, assignment, returns, calls, literals, typed operators, nested/fallthrough branches and main. CPP uses `condition_clause`, independently of C's shape. Astral comment plus CRLF put the next definition at UTF-16 index 10 / UTF-8 byte 12, row 1 column 0. Comments remain explicit extras. |
+| Malformed input and limits | Missing brace and operand produce missing nodes; malformed parameters/string produce ERROR nodes; all four propagate hasError. CPP rejects the same source through the C grammar while CPP accepts it. The binding accepts 32767 UTF-16 units and throws at 32768; adapters must preflight this limit. |
+| Lifecycle and packaged inputs | Only install lifecycle is `node-gyp-build`; no runtime network downloader. Dry-run registry pack reports 27 files, 3,208,986 compressed / 42,392,814 unpacked bytes, including MIT license, declarations, grammar source, native source fallback, Darwin/Linux/Windows x64/arm64 prebuilds and upstream WASM. Only Linux x64 native loading was executed. No archive, vendored grammar/binary or additional publication identity is added to this repository. |
+
+Reproduce in an empty temporary package using Node24 and credential-free public npm configuration:
+
+```sh
+npm init -y
+npm install --save-exact tree-sitter@0.21.1 tree-sitter-c@0.23.2 tree-sitter-cpp@0.23.4
+npm ls --all
+npm audit signatures
+npm pack tree-sitter-cpp@0.23.4 --dry-run --json
+node --input-type=module - <<'JS'
+import Parser from 'tree-sitter'
+import CPP from 'tree-sitter-cpp'
+const parser = new Parser()
+parser.setLanguage(CPP)
+const source = '/* 😀 */\r\nstd::string copy(std::string a, std::string b) { return a; }\n'
+const root = parser.parse(source).rootNode
+function visit(node) {
+  if (node.hasError || node.isError || node.isMissing) throw new Error(node.type)
+  for (let i = 0; i < node.childCount; i++) {
+    console.log(node.fieldNameForChild(i), node.child(i).type)
+    visit(node.child(i))
+  }
+}
+visit(root)
+console.log(root.namedChildren[1].startIndex, root.namedChildren[1].startPosition)
+JS
+```
+
+The complete initial corpus, source SHA-256 values, typed consumer, tree/ABI/package inventory and command logs are retained in the Task019 implementation run's `qualification/` and `evidence/` directories. The repository's private-boundary and CPP behavior specs retain executable regression coverage. Grammar qualification does not claim frontend/backend acceptance, packed-consumer success or CI completion.
+
+The initial qualification corpus is now retained verbatim in the repository (these hashes were recorded before dependency edits):
+
+| Corpus path | SHA-256 |
+| --- | --- |
+| `spec/fixtures/cpp-qualification/corpus-1.cpp` | `6e5763ff158809f0c750011765421c688978e755598cf1c738bd6e9863ccb6e5` |
+| `spec/fixtures/cpp-qualification/corpus-2.cpp` | `0a57ddb7fa84e7f1522452f520898d8e3d99ced6857e85b00d4e6dd327c15835` |
+| `spec/fixtures/cpp-qualification/corpus-3.cpp` | `b9be8da90243dbd9bdcebe3ee9569f2933ba24ddae38b342220183f6c72cf3e7` |
+| `spec/fixtures/cpp-qualification/corpus-4.cpp` | `ec88c7a47a7167b0ad4d2d07744e8d71404551b91a9db927c8d476f6de23a110` |
+| `spec/fixtures/cpp-qualification/corpus-5.cpp` | `a7524580af4881083d2fbf95f9a7b9f940320c2d2c35d3b188094598cca27f59` |
+
+Reproduce exhaustive frozen-edge traversal, coordinate and recovery checks with `npx velocious-test spec/cpp-parser-qualification.spec.js`. The generated Tasks001–004 fixtures are independently accepted by `spec/cpp-cross-language-acceptance.spec.js`; the small grammar probes above qualify CST coverage, not semantic acceptance or native compilation of a complete supported program.

package/docs/plans/2026-09-05-standard-library-portability.md

@@ -0,0 +1,46 @@
+# Standard-library portability implementation plan
+
+Date: 2026-09-05
+
+Status: dependency-ordered future plan; no implementation is claimed.
+
+## Goal and architecture reference
+
+Deliver the first bounded proof of the [standard-library portability architecture](../standard-library-portability.md): language compatibility stdlib/facades and target host providers/native bindings meet only through versioned canonical Semantifold stdlib contracts/capabilities. Pair-specific adapters and direct behavior-changing rewrites are excluded.
+
+## Why semantic prerequisites come first
+
+The current `semantifold@0.2.0` IR cannot express imports, general signatures, receiver calls, classes, loops, optional EOF, typed failures, resource identities, ownership, or close effects. Encoding a socket facade before those meanings exist would push language behavior into parser adapters, emitters, or handwritten source-to-target bridges. That would make evaluation order, EOF, failure, and lifetime accidental and prevent other facades/providers from sharing the work.
+
+The sequence therefore establishes general language semantics first, then defines capability/provider infrastructure, and only then adds a facade and concrete network slice. Numerical task order records this dependency flow; it is not a promise that the work is complete or immediately scheduled.
+
+## Dependency-ordered sequence
+
+1. Complete existing prerequisites [Task 004](../../todo/004-statement-sequencing-and-conditionals.md) and [Task 005](../../todo/005-general-function-signatures-and-calls.md), then add [Task 032 — condition-controlled loops and break/continue](../../todo/032-condition-controlled-loops-and-break.md). This supplies a general strict-Boolean loop model without recognizing stdlib-specific read-loop idioms.
+2. Complete [Task 009](../../todo/009-closed-records-and-member-access.md), then add [Task 033 — reference classes, methods, and constructors](../../todo/033-reference-classes-methods-and-constructors.md). Executable facades need bounded nominal reference identity, private state, construction, and receiver calls; immutable records alone are insufficient.
+3. Build on optionals, typed failures, and reference classes with [Task 034 — effectful capabilities and resource lifetime](../../todo/034-effectful-capabilities-and-resource-lifetime.md). It defines explicit host effects, resource ownership, deterministic close, and typed failure boundaries without claiming async, concurrency, `finally`, or RAII.
+4. Build project/module and effect foundations into [Task 035 — versioned standard-library contracts and provider linking](../../todo/035-versioned-standard-library-contracts-and-provider-linking.md). This owns canonical capability modules, provider registry/negotiation, protected native bindings, transactional linking, and tree-shaking.
+5. Add [Task 036 — language compatibility stdlib/facades](../../todo/036-language-compatibility-stdlib-facades.md). It owns proved stdlib identity, executable source-language facades, collision-safe target names, and same-language recursion isolation.
+6. Combine the loop and facade branches in [Task 037 — blocking TCP client stdlib vertical slice](../../todo/037-blocking-tcp-client-stdlib-vertical-slice.md). This is the first concrete proof, not a general networking or all-language milestone.
+
+The direct dependency chain is also recorded in the [roadmap graph and task index](../../todo/README.md). Phase S stays non-blocking until its prerequisite tasks are delivered; it must not distort the existing language/platform lanes.
+
+## First end-to-end proof
+
+Task 037 provides only these initial integrations:
+
+- canonical versioned blocking `SocketClient`, text-stream line-read, output, and resource-close capabilities;
+- Ruby language compatibility stdlib/facades preserving the supported `TCPSocket.new(host, port)`, `gets`, and `close` shape plus bounded one-string `puts(string)`/`Kernel.puts(string)`;
+- a canonical output operation that writes the string once and appends LF only when it does not already end in LF;
+- a PHP target host provider/native binding implemented with genuine `fsockopen`, `fgets`, and `fclose` for socket operations plus native stdout output without a duplicate LF; and
+- generated PHP that can retain `TCPSocket` and the bounded `puts` function in a collision-safe compatibility namespace/import alias while they call canonical provider operations.
+
+Acceptance starts a real local ephemeral TCP server controlled by the test. Generated PHP runs with the real PHP CLI and must prove exact output, retained input newlines, one appended LF for a final unterminated string, no duplicate LF, an absent result only at clean EOF, normalized connection error before a usable resource escapes, deterministic successful close, the specified repeated-close result, and a typed use-after-close failure. The server and client tests use bounded timeouts so blocking behavior cannot hang the lane.
+
+Negative acceptance covers unresolved or shadowed `TCPSocket` or `puts`, monkey-patching/reopening, dynamic require/lookup, unsupported APIs/options, excluded multi-argument/array/coercive/custom-separator `puts` behavior, missing provider capabilities, namespace collisions, version mismatch, and late provider/link failure. Every failure occurs before partial artifact exposure.
+
+## Delivery discipline for future implementation
+
+Each behavior task must add focused specs, exact public contracts, documentation, and a changelog fragment. Runtime-generation coverage must invoke the real required tools and a real local socket; source snapshots are insufficient. Implementations must validate and return deterministic complete artifact sets, retain semantic/synthetic provenance, and fail if a required tool is unavailable.
+
+This planning change itself adds no compiler/runtime behavior, dependency, generated output, spec, or changelog fragment. It does not trigger release, CI topology, external task mutation, or implementation of the listed tasks.

package/docs/source-maps.md

@@ -1,12 +1,14 @@
 # Source provenance and mappings
 
+C `program.c` uses the same rich/v3 contracts. Original operator, callee, literal, binding and final-consumer tokens retain their parser origins, including after exact ordered-region reconstruction. Generated temporary declarations/names, short-circuit control, markers, prototypes, unused-binding uses and cleanup are synthetic with related semantic origins. Shared semantic objects have separate occurrence paths and temporaries. `semantifold_runtime.h` is a synthetic support artifact related to the module root. C accepts no source-map directive or alternate map filename; use `generateArtifactSet()` and its mapped entry provenance. See the [C profile](c.md).
+
 Semantifold keeps one authoritative, language-neutral provenance chain:
 
 ```text
 generated UTF-16 range -> semantic node/symbol -> original UTF-16 range
 ```
 
-This works for PHP, Ruby, JavaScript, TypeScript, and Java inputs and outputs. It is not limited to JavaScript `sourceMappingURL` comments. `SemantifoldMapping` v1 is the authoritative range model; every generated artifact also includes an ECMA-426/Source Map v3 projection for existing tooling.
+This works for PHP, Ruby, JavaScript, TypeScript, Java, Python, C#, and Go inputs and mapped text outputs. It is not limited to JavaScript `sourceMappingURL` comments. `SemantifoldMapping` v1 is the authoritative range model; every generated program artifact also includes an ECMA-426/Source Map v3 projection for existing tooling.
 
 ## Parsing and semantic provenance
 
@@ -66,7 +68,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 for single-text targets 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. C# is available only through `generateArtifactSet()`: `filename` must be omitted or exact `Program.cs`, and `mapDirective`/`sourceMapFilename` must be omitted. It returns mapped `Program.cs` first and a fixed synthetic `Semantifold.csproj` manifest second. Go also requires `generateArtifactSet()`: `filename` must be omitted or exact `main.go`, mapping options must be omitted, and generation returns fixed synthetic `go.mod` first followed by mapped `main.go`. `sources` may supply exact content for legacy or caller-assembled multi-source IR:
 
 ```js
 generateArtifact({
@@ -79,7 +81,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 the six single-text targets and supplies one generated entry artifact, plus the referenced serialized mapping artifact when an external JavaScript-family directive is requested. For C#, it transactionally returns exactly `Program.cs` (role `entry`, `text/x-csharp`, rich/v3 text provenance) and `Semantifold.csproj` (role `manifest`, `application/xml`, synthetic provenance with the module's canonical root origin as a related origin). For Go it transactionally returns `go.mod` (role `manifest`, `text/plain`) before `main.go` (role `entry`, `text/x-go`, rich/v3 text provenance). The manifest is the exact LF-terminated module `example.com/semantifold/generated` with `go 1.26.0`; its source-free configuration provenance relates back to the module root, and the dependency-free module needs and produces no `go.sum`. `createGeneratedArtifactSet()` validates these and 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 +91,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 single-text target artifacts, C#'s `Program.cs`, and Go's `main.go`; it 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 +129,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, Java, and Python still receive sidecar map objects but never receive non-native map comments. C# and Go reject even an explicitly supplied `none`, because multi-backend options must not be silently consumed and their fixed multi-artifact projects have no source-map directive contract. Native Java debugger mapping, C# portable-PDB integration, and Go compiler source-map integration would require compiler-artifact integration and are 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.
 
@@ -132,3 +161,7 @@ Validation constructs source line starts once, verifies ranges in linear passes,
 The feature is source-compatible and additive: `generate()` bytes are characterized for both existing fixture profiles, legacy semantic modules remain valid, and existing `location` fields are unchanged. Parsed modules now serialize an additional enumerable `provenance` property, so consumers that compare or persist entire module JSON should consciously include or omit it.
 
 Semantifold is pre-1.0. The recommended release is a minor bump from `0.1.x` to `0.2.0`, with no npm publication as part of this implementation. A future incompatible provenance or mapping representation must use a new schema version rather than reinterpret version 1.
+
+## CPP text provenance
+
+The `cpp` lane emits one `program.cpp` with deterministic rich and Source Map v3 data. Original CPP operator/callee/type/consumer tokens remain mapped through exact ordered-region reconstruction. Inline runtime support, prototypes, temporary declarations/uses, discards, paired markers and short-circuit control are synthetic ranges related to original semantic occurrences. The six-digit occurrence namespace is shared with C’s planning algorithm; CPP marker language and CST validation are independent. No header or map artifact is added. See [CPP semantics and bounds](cpp.md).

package/docs/standard-library-portability.md

@@ -0,0 +1,190 @@
+# Standard-library portability
+
+Status: planned architecture; not implemented in `semantifold@0.2.0`.
+
+## Purpose and boundary
+
+Semantifold will make a deliberately bounded set of familiar source-language standard-library APIs portable without building a library translator for every source/target pair. The architecture is hub-and-spoke: source-language API shape is normalized into versioned canonical capabilities, and target-language native behavior is reached only through providers for those capabilities.
+
+This is an incremental compatibility profile, not a promise to translate arbitrary applications or complete standard libraries. The current release cannot parse imports, classes or methods, loops, optional values, typed errors, resources, host APIs, or any standard-library use. The dependency plan must deliver those semantic prerequisites before the first portability slice.
+
+## Terminology
+
+These three names are normative:
+
+- A **language compatibility stdlib/facade** is a source-facing, portable implementation of a proved native-library API shape. It is authored in a Semantifold-supported subset and may use only canonical Semantifold capabilities. It contains executable behavior plus public declarations/contracts; it is not a name-only rewrite table.
+- A **canonical Semantifold stdlib contract/capability** is a versioned, language-neutral operation and behavior contract. It precisely specifies types, evaluation order, effects, typed failures, EOF and presence, encoding, newline retention, blocking and timeout behavior, resource ownership/lifetime, close behavior, and target dependencies.
+- A **target host provider/native binding** implements one or more canonical capabilities using the target language's genuine native standard library. Its protected host-native binding is unavailable to ordinary portable application and facade code.
+
+An integration for a language therefore has two independent sides: its compatibility facade lets that language be a source, and its target host provider lets that language be a target. Both meet only at canonical contracts. There are no Ruby-on-PHP, PHP-on-Ruby, or other pair-specific adapters.
+
+## Compile and link flow
+
+```text
+source application ─┐
+                    ├─ frontend → semantic IR → target backend ─┐
+source compatibility│                                          ├─ linked artifact set
+stdlib/facade ───────┘      canonical capability calls ─────────┘
+                                                                  │
+                          target host provider/native binding ─────┤
+                                                                  ▼
+                                                    target native stdlib
+```
+
+The compiler resolves a proved source stdlib reference, selects the corresponding language compatibility stdlib/facade, and compiles both application and used facade modules through ordinary frontend-to-semantic-to-backend processing. Canonical calls remain explicit link requirements. Artifact assembly selects a compatible target host provider/native binding, validates the complete capability set, and returns the application, facade, provider, and support artifacts transactionally.
+
+Generated target code uses target syntax. It may retain the source API's class or function names in a collision-safe compatibility namespace or behind an import alias, so source-shaped calls remain readable without claiming those names belong to the target's native stdlib. Namespace allocation and provider symbols must not collide with application names, other facades, or target scaffolding.
+
+Only transitively used compatibility and provider modules enter the artifact set. Tree-shaking happens at declared module/capability boundaries after resolution; it must not remove observable initialization, effects, failure paths, or close behavior.
+
+## Ruby-to-PHP example
+
+Consider supported Ruby source that requires `socket`, creates `TCPSocket.new(host, port)`, reads lines with `gets`, calls `puts line`, and closes the socket. Once the necessary semantic tasks exist, Ruby stdlib resolution can prove that `TCPSocket` and the unqualified `puts(string)` or equivalent `Kernel.puts(string)` call refer to the supported native symbols and substitute their Ruby language compatibility stdlib/facades.
+
+The portable facades can be expressed schematically as:
+
+```ruby
+# Public compatibility declaration: Ruby-compatible supported profile.
+class TCPSocket
+  def initialize(host, port)
+    @client = Semantifold::SocketClient.v1_connect(host, port)
+  end
+
+  def gets
+    Semantifold::TextStream.v1_read_line(@client)
+  end
+
+  def close
+    Semantifold::Resource.v1_close(@client)
+  end
+end
+
+module Kernel
+  def self.puts(value)
+    Semantifold::Output.v1_write_line(value)
+  end
+end
+```
+
+This is illustrative pseudocode, not syntax accepted by `0.2.0`. The real facades must use explicit types, optional/presence results, typed failures, and ownership rules from the selected contract versions. `TCPSocket#gets` preserves the supported Ruby behavior, including newline retention and an absent value at EOF, by composing canonical capabilities rather than by recognizing a source read loop. The bounded `puts` facade accepts exactly one string and calls `Output.v1_write_line(text)`, which outputs the string once and appends LF only when the string does not already end in LF. Multiple arguments, arrays or recursive output, implicit string conversion, custom output separators, and every other Ruby `puts` behavior are outside this profile.
+
+The PHP target host provider/native binding can be expressed schematically as:
+
+```php
+// Protected provider code; not callable as a portable application API.
+function socket_client_v1_connect(string $host, int $port): SocketResource {
+    $handle = fsockopen($host, $port, $errorCode, $errorMessage);
+    return checked_socket_resource($handle, $errorCode, $errorMessage);
+}
+
+function text_stream_v1_read_line(SocketResource $socket): ?string {
+    return checked_fgets($socket->nativeHandle);
+}
+
+function resource_v1_close(SocketResource $socket): void {
+    checked_fclose_once($socket->nativeHandle);
+}
+
+function output_v1_write_line(string $text): void {
+    $output = str_ends_with($text, "\n") ? $text : $text . "\n";
+    checked_fwrite_all(STDOUT, $output);
+}
+```
+
+The application and Ruby facades compile to PHP. Generated PHP may define a source-compatible `TCPSocket` class and `puts` compatibility function in a generated compatibility namespace and alias them at their call sites. The class methods call the linked canonical `SocketClient`, text-stream, and resource provider operations; the `puts` facade calls the canonical output operation. The PHP target host provider/native binding writes the canonical line output to native `STDOUT` without duplicating an existing LF, while `fsockopen`, `fgets`, and `fclose` remain the genuine native socket operations.
+
+The path is therefore:
+
+```text
+Ruby application + Ruby TCPSocket/puts facades
+  → semantic IR
+  → generated PHP compatibility class/function
+  → canonical SocketClient/TextStream/Output/Resource calls
+  → PHP provider
+  → native stdout + fsockopen/fgets/fclose
+```
+
+There is no handwritten Ruby-on-PHP library, pair-specific bridge, embedded Ruby runtime, or whole-program intelligent refactor. Syntax becomes PHP syntax while the supported Ruby library shape and behavior remain in the compiled facade.
+
+## Resolution and symbol identity
+
+Compatibility substitution is permitted only when the frontend and semantic module resolver can prove both the referenced native library and symbol identity from parser-backed constructs and the configured supported profile. A recognized `require`, `import`, package path, qualified name, or declaration binding must resolve to the exact catalogued stdlib symbol and version range.
+
+The following never qualify by spelling alone:
+
+- a user-defined class, function, constant, module, or package with the same name;
+- a monkey-patched or reopened native type;
+- reflective or dynamic lookup, computed imports/requires, `eval`, dynamic dispatch, or unresolved aliases;
+- behavior supplied by a native extension, package-manager dependency, preload hook, or runtime mutation; or
+- a parser-rejected or ambiguous construct.
+
+Such programs are rejected with a located diagnostic or remain explicitly outside the supported profile. A frontend must never scan source text as a fallback after its parser adapter or resolver rejects a construct.
+
+Facade selection records the proved source symbol identity, facade module/version, and canonical capability requirements in semantic project metadata. That evidence, not a raw source name, authorizes linking.
+
+## Protected native boundary and recursion isolation
+
+Ordinary portable application and facade code can call canonical capabilities but cannot access raw target-native bindings. Provider modules are compiler-owned artifacts with a protected role and symbols that the normal source resolver will not expose. Backend/provider validation is the only route from a canonical call to a native API.
+
+This separation is essential for same-language generation. When Ruby source using the portable `TCPSocket` facade targets Ruby, the Ruby provider's native binding must reach the genuine host `TCPSocket`, not resolve the compatibility name and enter the facade again. Providers use reserved internal symbols or an equivalent compiler-controlled binding captured outside the compatibility namespace. Facade names, native provider names, and application aliases remain distinct even if their user-visible spellings coincide.
+
+## Canonical contract semantics
+
+Every canonical capability version is a closed public contract. At minimum it declares:
+
+- exact input, output, reference/resource, optional/presence, and typed-failure types;
+- left-to-right evaluation order and which operations are effectful;
+- whether an operation blocks, its timeout units and defaults, and the behavior of unsupported timeout modes;
+- text encoding and decoding, invalid-sequence policy, newline recognition and retention, and whether EOF is an absent value or a failure;
+- ownership transfer or borrowing, allowed aliases, resource lifetime, deterministic explicit close, repeated-close behavior, and use-after-close rejection;
+- failure categories and the point at which native errors are normalized, without depending on target-specific messages or codes; and
+- provider dependencies, supported target/runtime versions, and any capability dependencies.
+
+Contracts do not inherit accidental behavior from the first facade or provider. A provider advertises exact versions and constraints. Capability negotiation succeeds only when one provider set satisfies every used canonical requirement without incompatible versions or semantics.
+
+Capabilities evolve incrementally. A new operation or incompatible semantic rule receives an explicit version boundary; availability of `SocketClient` v1, for example, does not imply TCP server, TLS, UDP, async I/O, or arbitrary socket options.
+
+## Facades, providers, and artifacts
+
+Language compatibility stdlib/facades are normal executable portable definitions under stricter authority rules. Their public declarations define the source-visible supported signatures, and their bodies may use semantic language features and canonical calls only. They cannot invoke target syntax, a protected native binding, reflection, or unversioned host behavior.
+
+Target host providers/native bindings are target-owned modules selected from a validated registry. They may use genuine target stdlib APIs and the minimum generated support needed to implement the canonical contract. They cannot weaken types, EOF distinctions, failure categories, ownership, or blocking behavior merely because the host API differs.
+
+Resolution produces a dependency graph from application symbols through facade modules and canonical capabilities to provider modules. Before returning anything, the linker validates graph closure, versions, target availability, namespaces, artifact paths, and every backend capability. It then returns one deterministic artifact set containing only reachable modules, declarations, mappings, and required support. Every generated range retains source/semantic provenance or an explicit synthetic/provider reason.
+
+## Failure and diagnostic policy
+
+Portability is transactional and fail-loud. No source or artifact subset is exposed when validation fails. Diagnostics distinguish at least:
+
+- unresolved or unproved stdlib module/symbol identity;
+- a recognized stdlib symbol outside the facade's supported API profile;
+- dynamic, monkey-patched, reflective, native-extension, or otherwise non-portable source behavior;
+- a missing or version-incompatible canonical capability;
+- a target provider that cannot meet required encoding, EOF, timeout, failure, ownership, or close semantics;
+- same-language native-binding isolation or generated-name collisions; and
+- invalid provider dependency, linking, or artifact graphs.
+
+Source/resolution failures point to the import/require, symbol, call, or unsupported construct. Contract failures identify the capability and required version; target failures identify the target/provider constraint. A semantic mismatch is never hidden with a best-effort rewrite, partial artifact set, runtime warning, or source-text fallback.
+
+## Optimization boundary
+
+The executable facade plus canonical capability plus provider path is the correctness baseline. A backend may later lower a known facade operation directly to idiomatic target code only when the optimizer proves the replacement preserves the selected contract version, evaluation order, effects, failures, EOF/presence, encoding, blocking/timeouts, and resource lifetime. The unoptimized path must remain valid and covered. Direct lowering cannot authorize a pair-specific behavior change or broaden accepted source identity.
+
+## Supported-subset promise
+
+Each facade publishes the exact source APIs and forms it supports. Each canonical module publishes exact capability versions. Each provider publishes its target/runtime constraints. Unsupported operations remain unsupported even when a target happens to expose a similarly named native function.
+
+The first planned proof is intentionally narrow: a blocking TCP client, Ruby `TCPSocket` and bounded one-string `puts` compatibility facades, and a PHP native provider. It does not imply coverage for every language, every networking API, or general Ruby output behavior. The dependency sequence is maintained in the [implementation plan](plans/2026-09-05-standard-library-portability.md) and [roadmap](../todo/README.md).
+
+## Acceptance strategy
+
+Every implementation slice requires deterministic parser, semantic, link, generation, and real-toolchain acceptance. The first vertical slice will:
+
+1. start a real local ephemeral TCP server under test control, with no external network dependency;
+2. parse supported Ruby source and prove its `socket`/`TCPSocket` and `puts`/`Kernel.puts` identities;
+3. compile the application and used Ruby compatibility facades to PHP;
+4. link only the required PHP provider/native-binding modules;
+5. run the generated artifacts with real `php` and assert exact output, retained input newlines, exactly one appended LF for a final unterminated string, no duplicate LF, distinct EOF absence, normalized connection failure, deterministic close, repeated-close policy, and use-after-close rejection; and
+6. cover unresolved, shadowed, monkey-patched, unsupported, provider-missing, collision, and transactional-failure cases.
+
+Same-language acceptance must additionally prove that the protected native binding bypasses the compatibility facade. Generated artifacts are reparsed where the target frontend supports their profile, generated twice for byte-for-byte determinism, inspected for unused module exclusion, and checked for complete provenance. Snapshots or source-only assertions cannot replace actual execution.