references.md

polyengine — references

Use the checked-in dependency pins when investigating behavior. Links to upstream main show current upstream work, not necessarily this checkout's semantics. The authority policy is in architecture §1.

Component Model spec (submodule: third_party/component-model)

The submodule pins the spec, executable reference, and WAST corpus used by this checkout. Its principal sources are:

Source	Purpose
Explainer	Text format, types, validation, canonical interface names
Canonical ABI	Lift/lower, canonical options, built-ins, state rules
definitions.py	Executable semantic reference; use function names rather than line numbers
run_tests.py	Reference tests; diff.py compares reference and prose
Binary format	Component binary encoding
Concurrency	Tasks, streams, futures, and concurrency model
WIT	Interface language
Linking	Shared-nothing linking
WAST suite	Official test corpus

Current upstream sources are at WebAssembly/component-model. The spec pin is merged PR #719, a53b241d4d50487d256900fcad77cd6cda51808f, including idle drop delivery from #720 and partial/zero-length tests from #721. It supersedes the earlier provisional adoption and resolves CM-3; see architecture §1. The Component Model book is introductory documentation, not the semantic tie-breaker. Local discrepancies belong in upstream-component-model-repo-findings.md.

JSPI and engine support

• JSPI overview: promising, Suspending, and the restriction on intervening JS frames.
• V8 JSPI introduction.
• WebAssembly feature matrix: useful context; project coverage is recorded in architecture §3, browser expectations, and shell expectations.
• Shell pins: exact tested shell/runtime builds.
• V8 wasm code caching: published engine policy, not a portable cache guarantee. See architecture §10.
• Stack-switching proposal: related core-wasm work, not polyengine's current scheduling mechanism.

wasmtime internals (pinned: wasmtime-environ 50.0.0-dev+cc546ee, a git rev of main)

The revision is declared in Cargo.toml and resolved in Cargo.lock. Update source links with the pin.

• Environ at the pinned revision: component translation and plan structures under component/; fused adapter generation in fact.rs and fact/.
• Adapter translation: how component linkage is translated into FACT adapters.
• Component-model tests at the same revision: converted and classified separately by just test-wasmtime (see harness/README.md); supplementary reference material, not merged into the official corpus or an independent check of the reused frontend.
• Async test-programs guests at the same revision: async_round_trip_stackless and async_short_reads, built by just wasmtime-guests and driven through the public embedder API by just test-wasmtime-guests.

Toolchain crates (pinned versions in lockfiles)

Cargo.toml and Cargo.lock govern the host toolchain; individual guest crates pin their own dependencies (for example, hello). The wasm-tools release train must agree with the wasmtime frontend.

• wasm-tools: CLI and libraries, including wasmparser, wasm-encoder, wit-parser, wast, and json-from-wast.
• wasmparser: parsing and validation.
• wasm-encoder: core and component binary generation.
• wit-parser: bindgen's WIT input.
• wast: WAST parsing; use the version in the lockfile.
• json-from-wast: testgen's JSON-command and wasm-artifact conversion.
• wit-bindgen and its pinned 0.60.0 generate! documentation: guest bindings, distinct from polyengine's host-facing crates/bindgen.

JS platform specifics

• WebIDL USVString and String.prototype.toWellFormed: lone-surrogate replacement during string lowering.
• TextEncoder.encode: the current non-ASCII UTF-8 lowering path in runtime/src/cabi/strings.ts.
• Encoding labels: TextDecoder("latin1") means Windows-1252, not the CABI's latin1 mapping.
• FinalizationRegistry: nondeterministic resource backstop, not guaranteed cleanup.
• Explicit resource management: using and Symbol.dispose.
• WebAssembly JS API.
• Deno documentation.

For deployment authority and cache trust, see security.md.