semantifold 0.3.0 → 0.4.0

package/docs/standard-library-portability.md

@@ -1,12 +1,16 @@
 # Standard-library portability
 
-Status: planned architecture; not implemented in `semantifold@0.2.0`.
+Status: Task 034's single-module effect/lifetime foundation is delivered through PR #44, Task 035's versioned canonical contract/provider-linking hub is delivered through PR #45 and merge `a2aad9d4932bfc6087adc4ff8bca43678c92413c`, and Task 036's bounded executable facade qualification layer is delivered through PR #46 and merge `9aba48f9d48bcef4fd4c9275aec14bfcc4f0904c`. Task 037 implements the first concrete Ruby-to-PHP blocking TCP slice on its topic branch. None is released in `semantifold@0.3.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.
+This is an incremental compatibility profile, not a promise to translate arbitrary applications or complete standard libraries. The published `semantifold@0.3.0` release does not resolve standard-library identities or provide compatibility facades, canonical capability calls, host providers, or provider linking. The current source tree has since added bounded project imports, optionals, typed errors, Task 032 condition-controlled loops, and Task 033 single-module bounded reference classes/methods. Task 034, delivered through PR #44, adds explicit unversioned compiler authority, host effects, owned resources, deterministic close, and typed host-failure normalization. Task 035, delivered through PR #45, adds the versioned canonical contract/provider registries, capability negotiation, protected provider linking with tree-shaken artifacts, and transactional link validation. Task 036, delivered through PR #46, adds the neutral qualification facades documented below. Task 037 uses those foundations only for the bounded concrete Ruby-source-to-PHP-target profile documented here.
+
+Task 034 proves the fixed `semantifold.task034.resource-probe` conformance capability on PHP, Ruby, JavaScript/JSDoc, TypeScript, and Java. Its hard-coded compiler-owned native bindings exercise real local file handles so acquisition, clean EOF, read failure, close failure, terminal reuse, and exactly-once order can be tested. In single-module mode the probe is not a portable file API, a provider object, a provider registry, or a canonical standard-library version. Ordinary same-named source declarations do not gain authority. Task 035 now exposes that capability as the versioned canonical contract `semantifold.task034.resource-probe@1.0.0`: program-mode generation negotiates the adopted target's provider, materializes a tree-shaken provider artifact under a protected native binding, and links canonical calls through the generated artifact set.
+
+Task 006's exact collection construction, read, and size spellings are closed surface forms for core immutable-collection IR, not standard-library integrations. Their target emitters select equivalent representation syntax from validated semantic nodes; they do not retain source-library call identities, translate API names, or bypass the facade/canonical-contract/provider path. Standard-library portability remains owned by Tasks 035–037.
 
 ## Terminology
 
@@ -37,9 +41,21 @@ Generated target code uses target syntax. It may retain the source API's class o
 
 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.
 
+## Task 036 bounded qualification facades
+
+Task 036 proves this flow without taking Task 037's TCP scope. Each original-five source profile registers a public `semantifold.task036.<language>.probe@1.0.0` facade, one internal `probe-runner` dependency, and an unreferenced `unused` facade used only to prove elimination. The public declaration is exactly one direct function from `string` to `string`, with host effect and no escaping failure; PHP and Ruby spell it `compatibility_probe`, while JavaScript/JSDoc, TypeScript, and Java spell it `compatibilityProbe`.
+
+The exact parser-proved native module identities are `Semantifold\Task036\Probe` for PHP, `semantifold/task036/probe` with the `SemantifoldTask036Probe` module for Ruby, `semantifold:task036/probe` for JavaScript/JSDoc and TypeScript, and `semantifold.task036.Probe` for Java. Registry records include the source/runtime profile, version, public declaration, native symbols, compiler-owned source path/module, facade dependencies, and canonical requirements. The public wrapper delegates to the internal runner; only that runner receives compiler-owned authority for `probeEffect` and `probeTrace` from `semantifold.task034.resource-probe` range `1`. Application code and the public wrapper cannot forge or inherit that authority.
+
+`parseProgram` stores `SemantifoldStdlibFacadeResolution` v1 evidence on the resolved import and a dependency-first `SemantifoldStdlibFacades` v1 descriptor on the program. The selected facade source is parsed and semantically validated through its own language frontend, then every selected module follows the ordinary target backend. Generated paths use the reserved `semantifold/facade/<source-language>/...` compatibility namespace; the internal runner's logical alias is `probe_runner`, which remains a valid collision-checked identifier on Java targets. Facade artifacts have the `support` role and mapped source provenance, while providers retain synthetic protected provenance. The artifact-set `SemantifoldStdlibLink` metadata includes the complete facade descriptor, canonical modules, providers, native entries, and provider carrier.
+
+Resolution rejects unproved modules, unsupported members/forms, local shadowing, reopened modules, assignment/monkey-patching, dynamic imports/requires, reflection, native extensions, caller-owned facade ID/path collisions, and forged capability or facade descriptors with stable located diagnostics. Parser failure is terminal and is never recovered by scanning source text. Before provider planning or writer allocation, generation recompiles the registered facade source through the ordinary parser and semantic pipeline and structurally compares the complete compiler-owned semantic modules; retaining valid source bytes, locations, markers, or requirement names cannot conceal mutated facade IR. Generation also validates the descriptor, identity evidence, canonical/provider versions, target names, and complete artifact paths transactionally. Same-language lanes keep compatibility aliases outside the Task 035 protected provider route, including Java's owner-module provider carrier, so the genuine provider operation executes once without facade recursion.
+
+This corpus remains a neutral architecture fixture by itself: it adds no file, console, socket, `TCPSocket`, `fsockopen`, or other concrete public host behavior. Task 037 separately supplies the first TCP vertical slice.
+
 ## 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.
+Supported Ruby source requires exact literal `require "socket"`, creates `TCPSocket.new(host, port)`, reads lines with zero-argument receiver `gets`, calls `puts line` or `Kernel.puts(line)`, and explicitly calls zero-argument receiver `close`. Within that proved profile, Ruby stdlib resolution proves that `TCPSocket` and exactly one-string `puts` refer to the supported native symbols and selects their executable compiler-owned compatibility facades. The same `puts` spellings outside this profile retain legacy program-mode behavior.
 
 The portable facades can be expressed schematically as:
 
@@ -66,7 +82,7 @@ module Kernel
 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 sketch shows the source-visible shape. The compiler-owned facades use explicit types, optional/presence results, exact canonical failure declarations, and the selected contract ownership rules. `TCPSocket#gets` preserves 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:
 
@@ -120,7 +136,7 @@ The following never qualify by spelling alone:
 
 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.
+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. When a program selects more than one facade profile, each compiler-owned module receives authority under its requirement's owning canonical capability name; combining the Task 036 resource probe with the Task 037 socket/output facades neither renames nor propagates either profile's authority to public facade or application modules.
 
 ## Protected native boundary and recursion isolation
 
@@ -140,6 +156,19 @@ Every canonical capability version is a closed public contract. At minimum it de
 - 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.
 
+Task 037's exact v1 contract set is normative:
+
+| Canonical module | Operation | Parameters | Result/resource flow | Dependencies | Declared failures |
+| --- | --- | --- | --- | --- | --- |
+| `semantifold.socket-client@1.0.0` | `v1_connect` | `host: string`, `port: integer` | acquired owned `semantifold.resource.ByteStream` | `semantifold.resource@1` | `InvalidHost`, `InvalidPort`, `ConnectionFailure` |
+| `semantifold.text-stream@1.0.0` | `v1_read_line` | borrowed `semantifold.resource.ByteStream` | `optional:string`; borrow remains with owner | `semantifold.resource@1` | `ReadFailure`, `DecodeFailure`, `semantifold.resource.ResourceClosed` |
+| `semantifold.output@1.0.0` | `v1_write_line` | `text: string` | `void`; no resource flow | none | `WriteFailure` |
+| `semantifold.resource@1.0.0` | `v1_close` | owned `ByteStream` | `void`; terminal consume | none | `CloseFailure`, `ResourceClosed` |
+
+All four operations are synchronous, host-effectful, and evaluate receiver, arguments, and effects left to right exactly once. `v1_connect` accepts a non-empty Unicode host without stream-wrapper scheme syntax and an integer port from 1 through 65535; the provider rejects wrapper-style hosts before native connection so the contract can select only TCP transport. It exposes no resource unless native connection succeeds and offers no timeout parameter. `v1_read_line` incrementally validates UTF-8, retains LF and a preceding CR, returns a final unterminated line once, uses absence only for clean EOF before bytes, and distinguishes non-EOF read failure. `v1_write_line` writes all canonical UTF-8 bytes and appends one LF only when the input does not already end in LF. Either success or failure of the first `v1_close` attempt is terminal; later reads or closes fail as `ResourceClosed` before another native operation.
+
+The only Task 037 provider profile is PHP 8.2 or newer with core streams, recorded as `php82-core-streams-v1`. Its separately tree-shaken protected artifacts are `providers/php/semantifold/socket-client.php`, `providers/php/semantifold/text-stream.php`, `providers/php/semantifold/output.php`, and `providers/php/semantifold/resource.php`. The PHP provider owns the native handle and captures warnings only within each native call before normalizing them to the typed categories above; native messages and errno values are not portable. The only compatibility artifacts are `semantifold/facade/ruby/socket.php` and `semantifold/facade/ruby/output.php`.
+
 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.
@@ -174,11 +203,11 @@ The executable facade plus canonical capability plus provider path is the correc
 
 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).
+Task 036's delivered qualification proof remains intentionally neutral and original-five-only. Task 037 adds only the concrete blocking TCP client proof with Ruby `TCPSocket` and bounded one-string `puts` compatibility facades targeting the PHP native provider. Neither implies coverage for complete standard libraries, 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:
+Every implementation slice requires deterministic parser, semantic, link, generation, and real-toolchain acceptance. Task 037's vertical slice does all of the following:
 
 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;
@@ -187,4 +216,6 @@ Every implementation slice requires deterministic parser, semantic, link, genera
 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.
+The acceptance uses separate fresh loopback server instances for the source Ruby reference and generated PHP, explicit event/deadline coordination, and cleanup of tracked sockets, listeners, and child processes. Protected generator-only PHP seams deterministically exercise split multibyte reads, false/non-EOF reads, close warning/failure, and short/zero/false stdout writes with real PHP; a real refused connection and genuine successful `fclose` remain required. Generated portable PHP is reparsed where supported, protected provider PHP is checked with real `php -l` and execution, repeated generation is byte-for-byte deterministic across every artifact/mapping/provenance/metadata field, and snapshots or source-only assertions never replace execution.
+
+TCP servers/listeners, TLS, UDP, Unix sockets, nonblocking I/O, async/event loops, configurable timeouts, cancellation, concurrency, custom DNS policy, proxies, arbitrary socket options, binary framing, output beyond one-string `puts`, arbitrary encodings, other Ruby `Socket`/`IO` APIs, other source facades, other target providers, and direct idiomatic lowering remain explicit non-goals.

package/docs/swift.md

@@ -0,0 +1,44 @@
+# Swift source and target
+
+Task022 adds `swift` as a frontend and deterministic single-file text backend for the Tasks001–004 semantic subset. This is general Swift language support only. Apple frameworks, Objective-C interoperability, Xcode projects, signing, simulators, devices, and iOS application artifacts remain separate later tasks.
+
+## Parser route
+
+The frontend uses root `tree-sitter@0.25.1` with the MIT-licensed `tree-sitter-swift@0.7.1` grammar from the Semantifold packaging fork. The dependency is the immutable HTTPS archive for merge commit `2a4515bb1d2d075c4c72a3466fbccb75f5269caf`; human tag `v0.7.1-semantifold.1` identifies that commit. The root lock records integrity `sha512-MoaFzZrwF8mYIiKbTcU4lUpIOXLz9NAuKZKUcM4xOYOgGIbQuP+jdeX5428pz0l7p8ggfiDeoY+yAv2krt4MRg==`.
+
+The fork supplies the install-safe Node binding/package boundary needed by the otherwise unchanged 0.7.1 grammar. It ships a typed binding, generated parser and scanner, source fallback, and a native Node module; installation uses only `node-gyp-build` and has no downloader. Grammar ABI 14 is accepted by the exact binding. The adapter exhaustively visits every named, anonymous, extra, directive, error, and missing node, verifies parser indexes through the shared UTF-8-byte to UTF-16 converter, and rejects recovery rather than scanning source text.
+
+The parser packaging, Node24 loading, CST corpus, recovery, coordinates, and five profile hashes are qualified in `spec/swift-parser-qualification.spec.js`. The rebuilt canonical image passed compiler differential typechecks for the original and generated five-profile corpus and native debug/optimized execution with the selected compiler. The independent review completed with one bounded local correction; exact-head TensorBuzz CI, merge, and post-merge verification remain delivery gates.
+
+## Source profile
+
+Functions are synchronous top-level `func` declarations with exactly two unlabeled parameters, explicit `Int64`, `Bool`, or `String` parameter and return types, a braced body, and explicit scalar returns on every reachable path. Semantic functions precede executable top-level entry statements. Calls are direct, unlabeled, and have exactly two arguments.
+
+Locals use an explicit scalar annotation and initializer. `let` is immutable; `var` is accepted only when semantic assignment rules permit writes. Assignment targets are plain local identifiers. Conditions are strict `Bool`; nested and one-armed `if`, `else if`, `else`, and fallthrough normalize to semantic blocks. Entry printing is exactly one-argument `print(...)`.
+
+The profile accepts safe canonical decimal integers, `true`/`false`, ordinary noninterpolated Unicode-scalar strings, direct identifiers and calls, integer add/subtract/multiply/negate and ordering, Boolean not/short-circuit and/or, integer/Boolean equality/inequality, and string concatenation. The adapter recognizes the qualified grammar's trailing-call additive CST shape directly, so `piece(…) + piece(…)` normalizes without source-text recovery and retains left-before-right operands. Ordinary Swift String `==`/`!=` are rejected because their canonical-equivalence semantics differ from semantic scalar-sequence equality. Source integer spelling never uses target-width `Int`, overflow operators, separators, alternate radices, floating point, or implicit conversion.
+
+Type inference, optionals, tuples, collections, nominal declarations, extensions, generics, closures, property wrappers, result builders, macros, throwing/async/actor behavior, imports, Objective-C exposure, reflection, unsafe pointers, Foundation, UIKit, SwiftUI, loops, switches, error handling, interpolation, qualified calls, arbitrary standard-library dispatch, and custom operators are outside this profile. Parser recovery uses `PARSE_ERROR`; missing required types use `MISSING_TYPE`; other valid Swift outside the profile uses located `UNSUPPORTED_SYNTAX`.
+
+## Generated program
+
+The backend emits exactly one LF-normalized UTF-8 `program.swift`. Functions retain explicit scalar types and unlabeled parameters; locals retain `let`/`var`; entry statements remain in Swift's canonical top-level executable shell. Each generated mutable local receives an exact synthetic no-op `inout` marker to remain warning-clean without changing semantic mutability; the frontend collapses only its canonical adjacent shape. Rich mappings and Source Map v3 cover semantic names, types, literals, callees, and operators. Helper definitions, braces, separators, entry layout, and print plumbing are synthetic with related semantic origins. Before an artifact is returned, its final emitted source passes the registered Swift frontend, including its CST traversal limit. Only an omitted filename or exact `program.swift` is accepted, and Swift rejects source-map directive and alternate-map options with `UNSUPPORTED_CAPABILITY`.
+
+Swift `String.==` applies canonical Unicode equivalence, while semantic string equality compares the exact scalar sequence. Ordinary source `==`/`!=` on Strings therefore reject after parser-backed type resolution. Generated equality and inequality use two fixed private `semantifold_` helpers backed by `unicodeScalars.elementsEqual`; only their complete canonical definitions and calls have authority. A helper-looking name or partial/modified definition has no authority.
+
+Swift value types preserve Boolean, integer, and string copies without ownership scaffolding. Native function/operator evaluation supplies the required left-to-right and short-circuit behavior. Ordinary Swift `Int64` arithmetic remains overflow-checked in the required debug and `-O` modes; overflow operators are never emitted. Compile-time-known values outside signed 64-bit reject before emission. Generation also rejects malformed/cyclic or excessively expanded graphs, invalid scalar payloads, non-NFC or unsupported target identifiers, Swift keywords, scalar/entry names, and the private `semantifold_` namespace before a public artifact is returned.
+
+## Compiler contract
+
+The sole accepted compiler identity is:
+
+```text
+Swift version 6.3.3 (swift-6.3.3-RELEASE)
+Target: x86_64-unknown-linux-gnu
+```
+
+Discovery uses canonical command `/usr/bin/swiftc` after image construction or absolute override `SEMANTIFOLD_SWIFTC`. Because discovery retains the executable's exact resolved identity, version and compilation invocations explicitly pass `--driver-mode=swiftc`; this preserves compiler mode when an installed `swiftc` is a symlink to the multi-call `swift-driver`. Missing, ambiguous, non-executable, wrong-release, development-snapshot, or foreign-target tools fail loudly. No generation or test downloads a compiler.
+
+The Dockerfile selects official image `swift:6.3.3-noble@sha256:56ef1be2c1ca36f4c52440357dc1fcdfdb5e113587134fcadeef57c225c71b54`; its Linux/amd64 child manifest is `sha256:4e0fc24f0f93a5cf9a91bfcf182534bbc0571d70d757389c04ff1f616c1c460f`. A source stage probes the identity and copies only Swift executable/resource paths into the unchanged final `ubuntu:26.04@sha256:3131b4cc82a783df6c9df078f86e01819a13594b865c2cad47bd1bca2b7063bb` stage. It does not copy project source or replace the final `/usr` tree wholesale.
+
+Real acceptance independently materializes each original parser fixture and regenerated `program.swift` in a fresh directory, runs `swiftc -warnings-as-errors -typecheck`, compiles once without optimization and once with `-O`, executes both binaries, checks exact UTF-8 stdout/stderr/status, verifies source bytes are unchanged, and removes the directory. Its deterministic PATH places the resolved compiler directory first, the canonical host-tool directory `/usr/bin` second, and the isolated caller PATH last with first-occurrence deduplication, so archive Swift selects its own compiler companions while Clang can launch the host linker. The rebuilt canonical image passed this exact Swift 6.3.3 x86_64 contract; `spec/swift-native-execution.spec.js` is 6/6.