Merge branch 'main' into claude/lucid-pascal-0xL5X - resolve conflicts

Conflicts resolved by accepting PR branch versions (WASI S6b feature additions):
- .machine_readable/6a2/META.a2ml: Updated with S6b completion
- docs/ECOSYSTEM.adoc: Added S6b (sockets on-ramp) documentation
- docs/TECH-DEBT.adoc: Updated with latest progress
- docs/specs/SETTLED-DECISIONS.adoc: Updated decisions
- lib/codegen.ml: Updated WASI codegen
- lib/typecheck.ml: Updated type checking

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

Author: hyperpolymath

.build/dune-project

@@ -39,6 +39,7 @@
   (odoc (and (>= 2.4) :with-doc))
   (js_of_ocaml (>= 5.0))
   (js_of_ocaml-ppx (>= 5.0))
-  (ocamlformat (and (>= 0.26) :with-test)))
+  (ocamlformat (and (>= 0.26) :with-test))
+  (bisect_ppx (and (>= 2.8) :with-test)))
  (tags
   (programming-language compiler webassembly affine-types dependent-types row-polymorphism effects ocaml)))

.claude/CLAUDE.md

@@ -140,3 +140,117 @@ Rule: An issue is closed only by explicit merge of a PR with "Closes #N" OR by e
 Action (Hypatia): When asked to close an issue, confirm via a reply on the issue thread before doing so.
 Action (gitbot): Never use GitHub's "close issue" API directly; only close via PR merge with "Closes #N" keywords.
 
+## Agent operations notes
+
+Practical guidance for agents (Claude / other) operating in this repo,
+captured from parallel-bot session experience. Read once; saves turns.
+
+### CI signal reliability
+
+**"PR merged" does NOT mean "build green".** Auto-merge on this repo
+currently fires even when `build` or `lint` is failing — multiple
+recently-merged PRs (#334, #335, #336, #344) landed with `build` red,
+and the red persisted until PR #346's `FnExtern` interp fix. If you
+inherit a session reasoning about a recently-merged PR, do not assume
+its CI was green; check `mcp__github__pull_request_read` with method
+`get_check_runs` for the actual statuses, and check whether `main`
+itself is currently red before treating a build failure on your own
+PR as something *you* introduced.
+
+### Reading CI logs
+
+`WebFetch` against the GitHub Actions UI returns the React skeleton,
+not the log content. The fast paths for an agent are:
+
+* `mcp__github__pull_request_read` with method `get_check_runs` —
+  per-job status (queued / in_progress / success / failure) with
+  `details_url`. Sufficient for "did the build pass".
+* `mcp__github__pull_request_read` with method `get_status` —
+  combined commit status.
+* For actual log lines on a failed run, hand back to the user with
+  `gh run view --log-failed <run-id>`; do not loop trying to scrape
+  the UI.
+
+### Known-failing baseline checks
+
+These checks currently fail on *every* PR for repo-wide reasons, not
+because of any individual PR's changes. Do not waste turns
+investigating them on a per-PR basis:
+
+* `vscode-smoke` — npm 404 on `@hyperpolymath/affine-vscode` (the
+  in-editor harness depends on a not-yet-published npm package).
+* `migration-assistant` — was fixed by #342, but any branch created
+  from a base older than #342 will still see it red until rebased.
+* `governance / Language / package anti-pattern policy` — flags the
+  approved TypeScript exemptions (`affinescript-deno-test/*.ts`,
+  `editors/vscode/test/*.js`, etc., all documented in this file's
+  exemptions tables); the check has no allowlist for them.
+* The Hypatia security-scan bot comment — 143 findings; the bulk are
+  the same TypeScript exemption hits + pre-existing root files. A
+  real new finding will show as a *delta* in the count; otherwise
+  ignore.
+
+If a check from this list *changes status* on a PR (e.g.
+`vscode-smoke` suddenly passes, or Hypatia surfaces a new class of
+finding), that's signal worth investigating.
+
+### Branching discipline with concurrent merges
+
+When multiple agents are spawned in parallel, branch-creation time
+can lag `main` by hours and a stale base will silently revert other
+agents' work at merge time. **Before pushing any branch, run:**
+
+```
+git fetch origin main
+git rebase origin/main
+```
+
+Not just at branch-creation; immediately before push, after any
+in-session work. This guards against parallel-merge drift. Claude 1's
+STDLIB-04c branch (#337) accidentally reverted #334 and #335 because
+its base was stale; force-rebased to fix. Cheap to prevent, expensive
+to clean up.
+
+### Post-squash-merge branch divergence
+
+When a PR is squash-merged, the squashed commit on `main` gets a
+*new* SHA, distinct from any of the source-branch commits. If you
+then reset your local branch to `main` (or simply re-resolve it),
+`git status` reports N "ahead of origin/branch" — but those N
+commits are just the main-side commits the obsolete remote
+branch-tip never saw, not unpushed work.
+
+Recognising the situation:
+
+* The branch was already merged (PR closed, `merged: true`).
+* The local working tree matches `main`.
+* The remote branch still points at the *pre-merge* tip
+  (`origin/<branch>` is an old SHA, not the squashed one).
+* `git log origin/<branch>..HEAD` lists commits that look like
+  other people's work.
+
+Safe fix — pick the one matching intent:
+
+```
+git push origin --delete <branch>            # done with the branch
+git push --force-with-lease origin <branch>  # align the remote to main
+```
+
+`--force-with-lease` is safe here because nothing on the remote
+branch is unmerged work; force-push without `--lease` only matters
+if someone else pushed concurrently, which is irrelevant for an
+already-merged branch you're cleaning up.
+
+### Test-fixture hygiene for latent bug surfaces
+
+When you add a stdlib `extern fn` (or any other new declaration
+shape), add a test that feeds it to *every* downstream consumer
+(parse, resolve, typecheck, interp, every codegen target that
+shouldn't reject it). The PR #346 `FnExtern` interp bug had survived
+since the interpreter was written because no test had ever fed an
+inline `extern fn` to `Interp.eval_program` — STDLIB-04a's tests
+were the first, and only then did the missing match arm fire.
+
+Treat "first user of an existing-but-untested declaration shape" as a
+class-level surface, not a single test case.
+

.github/workflows/ci.yml

@@ -98,6 +98,110 @@ jobs:
         run: opam exec -- dune build @doc
         continue-on-error: true
 
+  bench-visibility:
+    # Visibility-only microbenchmarks per docs/standards/TESTING.adoc
+    # §"Bench standards". Does NOT block merge. Promotion to a
+    # ratcheted gate requires a calibrated baseline first.
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up OCaml
+        uses: ocaml/setup-ocaml@e32b06a3e831ff2fbc6f08cf35be2085e3918014 # v3
+        with:
+          ocaml-compiler: "5.1"
+
+      - name: Install dependencies
+        run: opam install . --deps-only --with-test --with-doc
+
+      - name: Build bench targets
+        run: opam exec -- dune build @bench --force
+        continue-on-error: true
+
+      - name: Run benches
+        id: bench
+        continue-on-error: true
+        run: |
+          set -o pipefail
+          opam exec -- dune runtest @bench --force 2>&1 | tee bench-output.log
+
+      - name: Render bench summary
+        if: always()
+        run: |
+          {
+            echo "# AffineScript microbench output (visibility-only)"
+            echo ""
+            echo "Policy: see [docs/standards/TESTING.adoc](docs/standards/TESTING.adoc)."
+            echo ""
+            if [ -f bench-output.log ]; then
+              echo '```'
+              cat bench-output.log
+              echo '```'
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload bench log
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: bench-output
+          path: bench-output.log
+          retention-days: 30
+
+  coverage-visibility:
+    # Visibility-only coverage report per
+    # docs/standards/TESTING.adoc §"Coverage (visibility-only)".
+    # No merge-blocking floor today.
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up OCaml
+        uses: ocaml/setup-ocaml@e32b06a3e831ff2fbc6f08cf35be2085e3918014 # v3
+        with:
+          ocaml-compiler: "5.1"
+
+      - name: Install dependencies
+        run: opam install . --deps-only --with-test --with-doc
+
+      - name: Run tests with bisect_ppx instrumentation
+        continue-on-error: true
+        run: |
+          opam exec -- dune runtest --force --instrument-with bisect_ppx
+
+      - name: Generate HTML coverage report
+        continue-on-error: true
+        run: |
+          opam exec -- bisect-ppx-report html -o _coverage --title="AffineScript coverage"
+          opam exec -- bisect-ppx-report summary | tee coverage-summary.txt
+
+      - name: Render coverage summary
+        if: always()
+        run: |
+          {
+            echo "# AffineScript coverage (visibility-only)"
+            echo ""
+            echo "Policy: see [docs/standards/TESTING.adoc](docs/standards/TESTING.adoc)."
+            echo ""
+            if [ -f coverage-summary.txt ]; then
+              echo '```'
+              cat coverage-summary.txt
+              echo '```'
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload coverage HTML
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: coverage-html
+          path: _coverage
+          retention-days: 30
+
   vscode-smoke:
     # In-editor end-to-end smoke test for the .affine VS Code extension
     # (issue #139). Loads the compiled out/extension.cjs in a real VS Code
@@ -183,16 +287,22 @@ jobs:
         # ReScript source. Picks the existing res-to-affine test fixture
         # so any drift in the pinned commit's syntactic surface area
         # surfaces here rather than at walker-rule writing time.
+        #
+        # NOTE: tree-sitter-cli >= 0.25 repurposed `--paths` to mean "a
+        # file listing input source paths", not "a directory containing
+        # a grammar". Grammar lookup is now driven by the current
+        # working directory (the CLI walks up looking for grammar.js /
+        # src/parser.c), so we cd into the vendored grammar tree and
+        # pass an absolute path to the fixture. Without this, the step
+        # fails with `Failed to read paths file ... Is a directory`.
         run: |
           shopt -s nullglob
           fixtures=(tools/res-to-affine/test/fixtures/*.res)
           if [ ${#fixtures[@]} -eq 0 ]; then
             echo "no .res fixtures to smoke-parse; skipping"
             exit 0
           fi
-          tree-sitter parse \
-            --quiet \
-            "${fixtures[0]}" \
-            --paths tools/vendor/tree-sitter-rescript \
-            > /dev/null
+          fixture_abs="$(realpath "${fixtures[0]}")"
+          ( cd tools/vendor/tree-sitter-rescript \
+              && tree-sitter parse --quiet "${fixture_abs}" > /dev/null )
           echo "smoke-parsed: ${fixtures[0]}"

.github/workflows/panic-attack.yml

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MPL-2.0
+# panic-attack.yml — estate compliance scanner, weekly schedule.
+#
+# Per docs/standards/PANIC-ATTACK.adoc:
+#   - This runs on a weekly cron; per-PR invocation is intentionally
+#     out of scope (CodeQL/Semgrep/secret-scanner cover per-PR).
+#   - Findings are surfaced as a workflow summary. Critical/high
+#     findings that are not in the false-positive registry will
+#     open a tracking issue.
+#   - Release cuts call `just panic` manually per RELEASE.md.
+#
+# Tool: `panic-attacker` Rust crate from
+#       road-skate/features/panic-attacker. Installed via cargo.
+
+name: Panic-Attack (compliance scan)
+
+on:
+  schedule:
+    # Sundays 03:00 UTC — quiet window for the estate's CI fleet.
+    - cron: '0 3 * * 0'
+  workflow_dispatch:
+
+# Read-only audit workflow — safe to cancel superseded runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  issues: write  # opens a tracking issue on unresolved critical/high
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install Rust toolchain (stable)
+        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 # stable
+        with:
+          toolchain: stable
+
+      - name: Install panic-attacker
+        # Source-install from the estate crate. Once published to
+        # crates.io this can switch to `cargo install panic-attacker`.
+        run: |
+          if [ -d road-skate/features/panic-attacker ]; then
+            cargo install --path road-skate/features/panic-attacker --locked || \
+              cargo install --path road-skate/features/panic-attacker
+          else
+            echo "::warning::road-skate/features/panic-attacker not found; trying crates.io"
+            cargo install panic-attacker || {
+              echo "::error::panic-attacker unavailable from both estate path and crates.io"
+              exit 1
+            }
+          fi
+
+      - name: Run panic-attack
+        id: scan
+        continue-on-error: true
+        run: |
+          set -o pipefail
+          panic-attack assail 2>&1 | tee panic-attack.log
+
+      - name: Render summary
+        if: always()
+        run: |
+          {
+            echo "# panic-attack weekly scan"
+            echo ""
+            echo "Repository: \`${{ github.repository }}\`"
+            echo "Ref: \`${{ github.sha }}\`"
+            echo ""
+            if [ -f panic-attack.log ]; then
+              echo "## Output"
+              echo '```'
+              tail -200 panic-attack.log
+              echo '```'
+            else
+              echo "(no output captured)"
+            fi
+            echo ""
+            echo "Policy: see [docs/standards/PANIC-ATTACK.adoc](docs/standards/PANIC-ATTACK.adoc)."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload log artifact
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: panic-attack-log
+          path: panic-attack.log
+          retention-days: 30

.gitignore

@@ -80,6 +80,11 @@ secrets/
 # Test/Coverage
 /coverage/
 htmlcov/
+/_coverage/
+bisect*.coverage
+
+# Benchmark archives (visibility-only output, see docs/standards/TESTING.adoc)
+/bench-runs/
 
 # Logs
 *.log