Skip to content

docs: describe current behavior and trim implementation history - #318

Merged
lannbot merged 1 commit into
mainfrom
docs/current-invariants
Sep 8, 2026
Merged

docs: describe current behavior and trim implementation history#318
lannbot merged 1 commit into
mainfrom
docs/current-invariants

Conversation

@lannbot

@lannbot lannbot commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator

Summary

Edit the documentation and comments around current behavior rather than implementation history.

  • Replace stale sync-only, plan-v0, deferred-async, and generated-adapter descriptions in guides and source headers.
  • Distinguish the public runtime facade from raw executor values and bindgen's declarations/digest wrapper.
  • Explain current scheduler/JSPI ownership, result settlement, cancellation, destructor, and unwind invariants without repeated incident narratives.
  • Correct plan examples, cache identity and limitations, corpus accounting, dependency references, and supported-versus-planned features.
  • Keep semantic requirements and named divergences explicit; update resolved upstream findings and label historical consumer/benchmark observations.
  • Tighten security guidance without presenting WASI path checks, process permissions, or cache layout as stronger isolation than they provide.
  • Shorten development/release instructions and recipe comments while retaining commands and policy.

No executable code, public types, compiler directives, test names/expectations, generated fixtures, protocol bytes, lockfiles, schema versions, or package versions change. No deleted history is moved into new repository artifacts. Architectural section headings/anchors remain stable.

Verification

  • Scratch comparison against the base verifies 124 source files: TypeScript AST leaf tokens, comment-free transpiled JavaScript, directive comments, Rust non-comment tokens/string literals, and shell/just recipe lines are unchanged.
  • 177 local Markdown path and anchor checks pass; all architecture headings retained.
  • Independent guide, contract, and runtime-comment accuracy reviews completed with their corrections applied.
  • Full just gates < /dev/null passed: runtime 827/0/3, seeded scheduling, conformance, packaging/npm, shell/browser realms, OPFS, and TLS/C0 consumer smokes. Formatting and diff checks passed. Existing expected failures/skips unchanged, consumer trees unchanged.

145 files edited, approximately 6,000 net lines removed.

Some existing implementation limitations became apparent while checking prose. This PR qualifies claims rather than changing behavior, including directory-cache adapter puts, digest normalization limits, and top-level-only import argument cleanup.

@lannbot
lannbot enabled auto-merge September 8, 2026 04:08
@lannbot
lannbot merged commit 72c5275 into main Sep 8, 2026
4 checks passed
@lannbot
lannbot deleted the docs/current-invariants branch September 8, 2026 04:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants