peffect 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. peffect-0.1.2/.agents/README.md +24 -0
  2. peffect-0.1.2/.agents/setup +69 -0
  3. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_loop_top.cfg +4 -0
  4. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_mask_check.cfg +4 -0
  5. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_notify.cfg +4 -0
  6. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_park_done.cfg +4 -0
  7. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_token_claim.cfg +4 -0
  8. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_no_wait.cfg +4 -0
  9. peffect-0.1.2/.claude/skills/verify-formal-kernel/Break_old_done.cfg +4 -0
  10. peffect-0.1.2/.claude/skills/verify-formal-kernel/FiberKernel.cfg +4 -0
  11. peffect-0.1.2/.claude/skills/verify-formal-kernel/FiberKernel.tla +294 -0
  12. peffect-0.1.2/.claude/skills/verify-formal-kernel/SKILL.md +221 -0
  13. peffect-0.1.2/.claude/skills/verify-formal-kernel/run.sh +12 -0
  14. peffect-0.1.2/.claude/skills/verify-formal-kernel/tlc_chart.py +939 -0
  15. peffect-0.1.2/.claude/skills/verify-peffect/SKILL.md +60 -0
  16. peffect-0.1.2/.claude/skills/verify-peffect/features/README.md +24 -0
  17. peffect-0.1.2/.claude/skills/verify-peffect/features/boundary-lint.md +40 -0
  18. peffect-0.1.2/.claude/skills/verify-peffect/features/clock.md +50 -0
  19. peffect-0.1.2/.claude/skills/verify-peffect/features/context.md +46 -0
  20. peffect-0.1.2/.claude/skills/verify-peffect/features/parity.md +27 -0
  21. peffect-0.1.2/.claude/skills/verify-peffect/features/quickstart.md +44 -0
  22. peffect-0.1.2/.claude/skills/verify-peffect/features/scope.md +42 -0
  23. peffect-0.1.2/.claude/skills/verify-peffect/run.sh +58 -0
  24. peffect-0.1.2/.github/workflows/release.yml +67 -0
  25. peffect-0.1.2/.gitignore +5 -0
  26. peffect-0.1.2/.gitmodules +3 -0
  27. peffect-0.1.2/AGENTS.md +133 -0
  28. peffect-0.1.2/CHANGELOG.md +31 -0
  29. peffect-0.1.2/PKG-INFO +6 -0
  30. peffect-0.1.2/docs/APPLICATION_PATTERN_AUDIT.md +69 -0
  31. peffect-0.1.2/docs/DESIGN.md +133 -0
  32. peffect-0.1.2/docs/FIRST_USABLE_SLICE.md +81 -0
  33. peffect-0.1.2/docs/INVARIANTS.md +581 -0
  34. peffect-0.1.2/docs/QUEUE_SOURCE_MAP.md +171 -0
  35. peffect-0.1.2/docs/RELEASING.md +53 -0
  36. peffect-0.1.2/docs/ROADMAP.md +241 -0
  37. peffect-0.1.2/docs/UPSTREAM_TESTS.md +510 -0
  38. peffect-0.1.2/docs/lessons/01-kernel.html +60 -0
  39. peffect-0.1.2/docs/lessons/02-verification.html +55 -0
  40. peffect-0.1.2/docs/lessons/03-boundaries.html +51 -0
  41. peffect-0.1.2/docs/lessons/04-context.html +38 -0
  42. peffect-0.1.2/docs/lessons/05-clock.html +37 -0
  43. peffect-0.1.2/docs/lessons/06-testclock.html +35 -0
  44. peffect-0.1.2/docs/lessons/07-ref.html +16 -0
  45. peffect-0.1.2/docs/lessons/08-queue.html +38 -0
  46. peffect-0.1.2/docs/research/2026-11-15-roi/README.md +28 -0
  47. peffect-0.1.2/docs/research/2026-11-15-roi/REPORT.md +252 -0
  48. peffect-0.1.2/docs/research/2026-11-15-roi/optional-packages.html +1 -0
  49. peffect-0.1.2/docs/research/2026-11-15-roi/optional-packages.md +62 -0
  50. peffect-0.1.2/docs/research/2026-11-15-roi/scout-1.md +27 -0
  51. peffect-0.1.2/docs/research/2026-11-15-roi/scout-2.md +19 -0
  52. peffect-0.1.2/docs/research/2026-11-15-roi/scout-3.md +27 -0
  53. peffect-0.1.2/docs/research/2026-11-15-roi/scout-4.md +32 -0
  54. peffect-0.1.2/docs/research/2026-11-15-roi/scout-5.md +22 -0
  55. peffect-0.1.2/docs/research/2026-11-15-roi/scout-6.md +25 -0
  56. peffect-0.1.2/docs/research/2026-11-15-roi/scout-7.md +15 -0
  57. peffect-0.1.2/docs/research/2026-11-15-roi/scout-8.md +26 -0
  58. peffect-0.1.2/docs/research/2026-11-15-roi/waves.html +70 -0
  59. peffect-0.1.2/docs/scouts/cause-exit.md +70 -0
  60. peffect-0.1.2/docs/scouts/config-data.md +53 -0
  61. peffect-0.1.2/docs/scouts/context.md +63 -0
  62. peffect-0.1.2/docs/scouts/fibers.md +90 -0
  63. peffect-0.1.2/docs/scouts/kernel.md +97 -0
  64. peffect-0.1.2/docs/scouts/layer-scope.md +71 -0
  65. peffect-0.1.2/docs/scouts/observability.md +40 -0
  66. peffect-0.1.2/docs/scouts/schedule-clock.md +44 -0
  67. peffect-0.1.2/docs/scouts/schema.md +64 -0
  68. peffect-0.1.2/docs/scouts/stream.md +37 -0
  69. peffect-0.1.2/examples/clock.py +107 -0
  70. peffect-0.1.2/examples/context.py +80 -0
  71. peffect-0.1.2/examples/parity/.gitignore +1 -0
  72. peffect-0.1.2/examples/parity/README.md +211 -0
  73. peffect-0.1.2/examples/parity/app.ts +158 -0
  74. peffect-0.1.2/examples/parity/batch.ts +94 -0
  75. peffect-0.1.2/examples/parity/batch_scenarios.ts +42 -0
  76. peffect-0.1.2/examples/parity/bun.lock +15 -0
  77. peffect-0.1.2/examples/parity/compare.py +146 -0
  78. peffect-0.1.2/examples/parity/composed.ts +87 -0
  79. peffect-0.1.2/examples/parity/composed_scenarios.ts +61 -0
  80. peffect-0.1.2/examples/parity/fixtures/check.output.json +60 -0
  81. peffect-0.1.2/examples/parity/fixtures/check.ts +51 -0
  82. peffect-0.1.2/examples/parity/fixtures/negative.ts +40 -0
  83. peffect-0.1.2/examples/parity/fixtures/positive.ts +23 -0
  84. peffect-0.1.2/examples/parity/outcomes.ts +31 -0
  85. peffect-0.1.2/examples/parity/package.json +13 -0
  86. peffect-0.1.2/examples/parity/python_app.py +204 -0
  87. peffect-0.1.2/examples/parity/python_batch.py +172 -0
  88. peffect-0.1.2/examples/parity/python_batch_scenarios.py +58 -0
  89. peffect-0.1.2/examples/parity/python_composed.py +177 -0
  90. peffect-0.1.2/examples/parity/python_reference.py +160 -0
  91. peffect-0.1.2/examples/parity/python_scenarios.py +103 -0
  92. peffect-0.1.2/examples/parity/reference.output.json +664 -0
  93. peffect-0.1.2/examples/parity/reference.ts +88 -0
  94. peffect-0.1.2/examples/parity/tsconfig.json +20 -0
  95. peffect-0.1.2/examples/queue_worker.py +219 -0
  96. peffect-0.1.2/examples/quickstart.py +84 -0
  97. peffect-0.1.2/examples/scope.py +91 -0
  98. peffect-0.1.2/prototypes/pfx/docs/overview.html +60 -0
  99. peffect-0.1.2/prototypes/pfx/examples/__init__.py +0 -0
  100. peffect-0.1.2/prototypes/pfx/examples/app.py +162 -0
  101. peffect-0.1.2/prototypes/pfx/pyproject.toml +46 -0
  102. peffect-0.1.2/prototypes/pfx/src/pfx/__init__.py +40 -0
  103. peffect-0.1.2/prototypes/pfx/src/pfx/core.py +307 -0
  104. peffect-0.1.2/prototypes/pfx/src/pfx/layer.py +189 -0
  105. peffect-0.1.2/prototypes/pfx/src/pfx/py.typed +0 -0
  106. peffect-0.1.2/prototypes/pfx/src/pfx/schema.py +72 -0
  107. peffect-0.1.2/prototypes/pfx/tests/test_runtime.py +126 -0
  108. peffect-0.1.2/prototypes/pfx/tests/test_types.py +31 -0
  109. peffect-0.1.2/prototypes/pfx/typetests/declared.py +39 -0
  110. peffect-0.1.2/prototypes/pfx/typetests/should_fail.py +48 -0
  111. peffect-0.1.2/prototypes/pfx/typetests/should_pass.py +39 -0
  112. peffect-0.1.2/prototypes/pfx/typetests/syntax/alternatives.py +68 -0
  113. peffect-0.1.2/prototypes/pfx/uv.lock +571 -0
  114. peffect-0.1.2/pyproject.toml +52 -0
  115. peffect-0.1.2/scripts/check_boundaries.py +350 -0
  116. peffect-0.1.2/src/peffect/__init__.py +223 -0
  117. peffect-0.1.2/src/peffect/cause.py +177 -0
  118. peffect-0.1.2/src/peffect/clock.py +130 -0
  119. peffect-0.1.2/src/peffect/console.py +99 -0
  120. peffect-0.1.2/src/peffect/context.py +258 -0
  121. peffect-0.1.2/src/peffect/core.py +1273 -0
  122. peffect-0.1.2/src/peffect/deferred.py +99 -0
  123. peffect-0.1.2/src/peffect/duration.py +497 -0
  124. peffect-0.1.2/src/peffect/fiber.py +1082 -0
  125. peffect-0.1.2/src/peffect/latch.py +120 -0
  126. peffect-0.1.2/src/peffect/layer.py +789 -0
  127. peffect-0.1.2/src/peffect/logger.py +166 -0
  128. peffect-0.1.2/src/peffect/managed_runtime.py +325 -0
  129. peffect-0.1.2/src/peffect/option.py +50 -0
  130. peffect-0.1.2/src/peffect/pull.py +116 -0
  131. peffect-0.1.2/src/peffect/py.typed +0 -0
  132. peffect-0.1.2/src/peffect/queue.py +670 -0
  133. peffect-0.1.2/src/peffect/ref.py +133 -0
  134. peffect-0.1.2/src/peffect/resources.py +113 -0
  135. peffect-0.1.2/src/peffect/scheduler.py +55 -0
  136. peffect-0.1.2/src/peffect/scope.py +394 -0
  137. peffect-0.1.2/src/peffect/semaphore.py +255 -0
  138. peffect-0.1.2/src/peffect/synchronized_ref.py +183 -0
  139. peffect-0.1.2/src/peffect/testing/__init__.py +7 -0
  140. peffect-0.1.2/src/peffect/testing/_clock.py +453 -0
  141. peffect-0.1.2/src/peffect/testing/_console.py +105 -0
  142. peffect-0.1.2/src/peffect/timeout.py +67 -0
  143. peffect-0.1.2/tests/conftest.py +9 -0
  144. peffect-0.1.2/tests/test_application_parity.py +234 -0
  145. peffect-0.1.2/tests/test_boundaries.py +260 -0
  146. peffect-0.1.2/tests/test_clock.py +48 -0
  147. peffect-0.1.2/tests/test_clock_duration_upstream.py +217 -0
  148. peffect-0.1.2/tests/test_clock_sleep.py +176 -0
  149. peffect-0.1.2/tests/test_composition_upstream.py +370 -0
  150. peffect-0.1.2/tests/test_console_logger.py +413 -0
  151. peffect-0.1.2/tests/test_context.py +330 -0
  152. peffect-0.1.2/tests/test_context_identity_upstream.py +243 -0
  153. peffect-0.1.2/tests/test_context_upstream.py +242 -0
  154. peffect-0.1.2/tests/test_deferred_upstream.py +240 -0
  155. peffect-0.1.2/tests/test_duration_format_upstream.py +119 -0
  156. peffect-0.1.2/tests/test_duration_upstream.py +416 -0
  157. peffect-0.1.2/tests/test_fiber_bulk_upstream.py +254 -0
  158. peffect-0.1.2/tests/test_fiber_lifecycle_upstream.py +438 -0
  159. peffect-0.1.2/tests/test_fiber_resume_upstream.py +247 -0
  160. peffect-0.1.2/tests/test_fiber_start_upstream.py +270 -0
  161. peffect-0.1.2/tests/test_finalization_upstream.py +139 -0
  162. peffect-0.1.2/tests/test_fork_scoped_upstream.py +85 -0
  163. peffect-0.1.2/tests/test_gen_cleanup.py +197 -0
  164. peffect-0.1.2/tests/test_kernel.py +322 -0
  165. peffect-0.1.2/tests/test_kernel_props.py +361 -0
  166. peffect-0.1.2/tests/test_latch_upstream.py +460 -0
  167. peffect-0.1.2/tests/test_layer_upstream.py +528 -0
  168. peffect-0.1.2/tests/test_managed_runtime_interleavings.py +363 -0
  169. peffect-0.1.2/tests/test_managed_runtime_upstream.py +842 -0
  170. peffect-0.1.2/tests/test_option.py +100 -0
  171. peffect-0.1.2/tests/test_pull_upstream.py +254 -0
  172. peffect-0.1.2/tests/test_queue_interleavings.py +290 -0
  173. peffect-0.1.2/tests/test_queue_props.py +446 -0
  174. peffect-0.1.2/tests/test_queue_upstream.py +722 -0
  175. peffect-0.1.2/tests/test_queue_worker.py +17 -0
  176. peffect-0.1.2/tests/test_race_review_regressions.py +52 -0
  177. peffect-0.1.2/tests/test_race_timeout_upstream.py +1141 -0
  178. peffect-0.1.2/tests/test_ref_props.py +456 -0
  179. peffect-0.1.2/tests/test_ref_upstream.py +345 -0
  180. peffect-0.1.2/tests/test_resources_upstream.py +367 -0
  181. peffect-0.1.2/tests/test_root_context.py +28 -0
  182. peffect-0.1.2/tests/test_scheduler_upstream.py +311 -0
  183. peffect-0.1.2/tests/test_scope.py +521 -0
  184. peffect-0.1.2/tests/test_scope_add_finalizer_unsafe.py +42 -0
  185. peffect-0.1.2/tests/test_scope_parallel.py +233 -0
  186. peffect-0.1.2/tests/test_semaphore_upstream.py +1037 -0
  187. peffect-0.1.2/tests/test_suspend_exit.py +281 -0
  188. peffect-0.1.2/tests/test_synchronized_ref_upstream.py +611 -0
  189. peffect-0.1.2/tests/test_testclock.py +894 -0
  190. peffect-0.1.2/tests/test_traversal_upstream.py +541 -0
  191. peffect-0.1.2/tests/test_types.py +58 -0
  192. peffect-0.1.2/typetests/declared.py +39 -0
  193. peffect-0.1.2/typetests/should_fail.py +731 -0
  194. peffect-0.1.2/typetests/should_pass.py +858 -0
  195. peffect-0.1.2/untangle-log.md +79 -0
  196. peffect-0.1.2/uv.lock +651 -0
@@ -0,0 +1,24 @@
1
+ # Development setup
2
+
3
+ Run `./.agents/setup` from any directory. Re-run after a Scotty session resumes:
4
+ dependencies and installed tools are not preserved by its workspace snapshot.
5
+
6
+ The script targets Scotty's Debian image (passwordless sudo or root) and existing
7
+ macOS development hosts. It installs missing Debian prerequisites, uv 0.11.10,
8
+ Bun 1.3.13, managed Python 3.13, and dependencies from `uv.lock` and the parity
9
+ `bun.lock`. Python patch releases and Debian packages follow their repositories;
10
+ this is a repeatable setup, not a hermetic image. macOS requires git, curl, unzip,
11
+ Node and Java already installed. Formal verification requires Java 11 or newer;
12
+ Debian setup installs Java 17 when missing.
13
+
14
+ Only an absent vendor submodule is initialized. An existing checkout at a different
15
+ revision fails without resetting it. No source files or lockfiles are rewritten.
16
+ Linux links uv and Bun into `/usr/local/bin` for subsequent agent turns. On macOS,
17
+ newly installed tools live in `~/.local/share/peffect-tools`; add its `bin` and
18
+ `bun/bin` directories to PATH if they were not already available.
19
+
20
+ peffect is a library: setup starts no server and requires no hatch URL.
21
+ Run `.claude/skills/verify-peffect/run.sh` for application parity, tests, lint and
22
+ types; `.claude/skills/verify-formal-kernel/run.sh` for bounded kernel verification;
23
+ and `uv build` for wheel and source distributions. Setup itself only checks tools
24
+ and the editable package import; it does not claim those verification suites pass.
@@ -0,0 +1,69 @@
1
+ #!/usr/bin/env bash
2
+ # Idempotent development setup for Scotty's Debian/Node image and existing macOS hosts.
3
+ set -euo pipefail
4
+ root="$(cd "$(dirname "$0")/.." && pwd)"
5
+ cd "$root"
6
+ uv_version=0.11.10
7
+ bun_version=1.3.13
8
+ python_version=3.13
9
+ tools_dir="${HOME}/.local/share/peffect-tools"
10
+ export PATH="$tools_dir/bin:$tools_dir/bun/bin:$PATH"
11
+
12
+ as_root() {
13
+ if [ "$(id -u)" -eq 0 ]; then "$@"; else sudo -n "$@"; fi
14
+ }
15
+
16
+ if [ "$(uname -s)" = Linux ] && command -v apt-get >/dev/null; then
17
+ missing=()
18
+ for pair in curl:curl unzip:unzip git:git node:nodejs java:openjdk-17-jre-headless; do
19
+ command -v "${pair%%:*}" >/dev/null || missing+=("${pair#*:}")
20
+ done
21
+ if [ "${#missing[@]}" -gt 0 ]; then
22
+ as_root apt-get update
23
+ as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ca-certificates "${missing[@]}"
24
+ fi
25
+ fi
26
+ for tool in curl unzip git node java; do
27
+ command -v "$tool" >/dev/null || { echo "Missing $tool; install it and rerun .agents/setup" >&2; exit 1; }
28
+ done
29
+ # java may exist as a macOS launcher without an installed JRE.
30
+ java -version
31
+ mkdir -p "$tools_dir/bin"
32
+ setup_tmp="$(mktemp -d)"
33
+ trap 'rm -rf "$setup_tmp"' EXIT
34
+ if ! uv --version 2>/dev/null | grep -q "^uv $uv_version\( \|$\)"; then
35
+ curl -fsSL "https://astral.sh/uv/$uv_version/install.sh" -o "$setup_tmp/uv.sh"
36
+ UV_UNMANAGED_INSTALL="$tools_dir/bin" sh "$setup_tmp/uv.sh"
37
+ fi
38
+ if [ "$(bun --version 2>/dev/null || true)" != "$bun_version" ]; then
39
+ curl -fsSL https://bun.com/install -o "$setup_tmp/bun.sh"
40
+ BUN_INSTALL="$tools_dir/bun" bash "$setup_tmp/bun.sh" "bun-v$bun_version"
41
+ fi
42
+ # Make tools visible to later Scotty turns, not just this script's child processes.
43
+ if [ "$(uname -s)" = Linux ]; then
44
+ for tool in uv bun; do
45
+ tool_path="$(command -v "$tool")"
46
+ if [ "$tool_path" != "/usr/local/bin/$tool" ]; then
47
+ as_root ln -sfn "$tool_path" "/usr/local/bin/$tool"
48
+ fi
49
+ done
50
+ fi
51
+
52
+ # Initialize only a missing vendor checkout. Never reset an existing vendor tree.
53
+ if [ ! -f vendor/effect-v4/packages/effect/package.json ]; then
54
+ git submodule update --init vendor/effect-v4
55
+ fi
56
+ expected_vendor="$(git ls-tree HEAD vendor/effect-v4 | awk '{print $3}')"
57
+ actual_vendor="$(git -C vendor/effect-v4 rev-parse HEAD)"
58
+ [ "$actual_vendor" = "$expected_vendor" ] || { echo "Vendor differs from gitlink; refusing to reset it" >&2; exit 1; }
59
+ uv python install "$python_version"
60
+ uv sync --locked --python "$python_version"
61
+ (cd examples/parity && bun install --frozen-lockfile)
62
+ uv run --no-sync python -c 'import pathlib, peffect, sys; assert sys.version_info[:2] == (3, 13); assert pathlib.Path(peffect.__file__).resolve() == pathlib.Path("src/peffect/__init__.py").resolve(); print("Python", sys.version.split()[0], "| peffect import OK")'
63
+ uv --version
64
+ bun --version
65
+ node --version
66
+ echo 'Ready: peffect library environment (no server or public URL required).'
67
+ echo 'Verify: .claude/skills/verify-peffect/run.sh'
68
+ echo 'Formal: .claude/skills/verify-formal-kernel/run.sh'
69
+ echo 'Build: uv build'
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_loop_top"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_mask_check"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_notify"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_park_done"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_token_claim"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "no_wait"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "old_done"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,4 @@
1
+ SPECIFICATION Spec
2
+ CONSTANT Break = "none"
3
+ INVARIANT K1_ExitOnce K2_ResumeOnce K3_OneRunner K6_MasksHold K7_InterruptsLand K8_NoOrphans
4
+ PROPERTY AllPublish
@@ -0,0 +1,294 @@
1
+ ---------------------------- MODULE FiberKernel ----------------------------
2
+ (* The fiber kernel's park / resume / interrupt / yield / children protocol.
3
+
4
+ Code: src/peffect/fiber.py (Fiber.evaluate, yield_now, interrupt_unsafe, _done, _await_all,
5
+ _start), src/peffect/core.py (Async, Failure, SetInterruptible). Effect v4 runs a fiber
6
+ synchronously inside whoever wakes it: a resume, an interrupt of a fiber that is not running,
7
+ an immediate fork and a root start all call `evaluate` before returning. So drives nest:
8
+ `cur` is the innermost running drive and `stk` the drives suspended under it, outermost
9
+ first. Every action is atomic: one asyncio loop, and `evaluate` never awaits.
10
+
11
+ Wakers may act at any point, nested in whatever drive is running (user code can call a
12
+ resume, `interrupt_unsafe` or a dispatcher `flush` from any node) or from the loop:
13
+ ExtResume, Interrupt and Drive (a dispatcher task) carry no `cur = "none"` guard.
14
+
15
+ Two fibers. P (the root, started at once) forks C with default or inherited mask, yields,
16
+ explicitly enables interruption, parks, and ends while C may still run. C yields, parks,
17
+ explicitly enables interruption, masks, parks inside the mask, and unmasks. Both regain
18
+ interruption before finishing: K7 does not cover permanently masked completion. An
19
+ interrupter interrupts P once. Async completions arrive at any point, late ones included. *)
20
+ EXTENDS Naturals, Sequences, FiniteSets
21
+
22
+ CONSTANT Break \* "none" = the code as it is; the other values mirror scratch breaks (SKILL.md)
23
+
24
+ Fibers == {"P", "C"}
25
+ Prog == [f \in Fibers |->
26
+ IF f = "P" THEN <<"fork", "yield", "enable", "park">>
27
+ ELSE <<"yield", "park", "enable", "mask", "park", "unmask">>]
28
+ End(f) == Len(Prog[f]) + 1
29
+ WAIT == 99 \* pc and park id while P is parked on _await_all in Fiber._done
30
+
31
+ VARIABLES
32
+ cur, \* the fiber whose evaluate is innermost, or "none" (no drive is running)
33
+ stk, \* drives suspended under cur's (nested evaluate), outermost first
34
+ fb, \* per-fiber state, fields below
35
+ started, \* C has been forked (fiber._start)
36
+ obs, \* P's _await_all observer is registered on C (Fiber.add_observer)
37
+ sent, \* the interrupter has called P.interrupt_unsafe
38
+ selfUsed \* a register has interrupted its own fiber (bounded to once)
39
+ vars == <<cur, stk, fb, started, obs, sent, selfUsed>>
40
+
41
+ (* fb[f] fields and the Fiber field each models:
42
+ pc next instruction (straight-line Prog), WAIT while waiting on children
43
+ node the node the running drive evaluates next: "start" | "ok" | "int" | "await" | "none"
44
+ intr Fiber.interruptible irq Fiber.interrupted is not None
45
+ dfr Fiber._deferred parked Fiber._parked is not None
46
+ pid id of the current Park (an Async, or a queued yield step) pdone Park.done
47
+ wakes claims of the current Park: resume, queued step or interrupt (K2)
48
+ ext ids of Async Parks whose completion is still pending (resume callbacks)
49
+ drv dispatcher tasks queued for this fiber: <<"start", 0>> (scheduled fork, a no-op
50
+ once exited) or <<"y", id>> (yield_now's step, a no-op once its Park is done)
51
+ st the fiber's first evaluate has run (an unstarted one has an empty stack)
52
+ ending Fiber._ending exit Fiber._exit ("none" | "ok" | "int")
53
+ pubs times _publish ran (K1) req an interrupt was requested before the exit *)
54
+
55
+ Init ==
56
+ \E parentIntr \in BOOLEAN :
57
+ /\ cur = "P" /\ stk = <<>> \* run_exit -> _start(None, ...): the root's evaluate runs at once
58
+ /\ fb = [f \in Fibers |->
59
+ [pc |-> 1, node |-> IF f = "P" THEN "start" ELSE "none",
60
+ intr |-> IF f = "P" THEN parentIntr ELSE TRUE, irq |-> FALSE, dfr |-> FALSE,
61
+ parked |-> FALSE, pid |-> 0, pdone |-> TRUE, wakes |-> 0, ext |-> {}, drv |-> <<>>,
62
+ st |-> f = "P",
63
+ ending |-> "none", exit |-> "none", pubs |-> 0, req |-> FALSE]]
64
+ /\ started = FALSE /\ obs = FALSE /\ sent = FALSE /\ selfUsed = FALSE
65
+
66
+ InStk(f) == \E i \in 1..Len(stk) : stk[i] = f
67
+ Running(f) == cur = f \/ InStk(f) \* Fiber.running
68
+
69
+ \* f's evaluate starts now, nested in the running drive (or from the loop)
70
+ Push(f) == cur' = f /\ stk' = IF cur = "none" THEN stk ELSE Append(stk, cur)
71
+ \* the running drive returns to the drive it was nested in, or to the loop
72
+ EndDrive == IF stk = <<>> THEN cur' = "none" /\ stk' = stk
73
+ ELSE cur' = stk[Len(stk)] /\ stk' = SubSeq(stk, 1, Len(stk) - 1)
74
+ \* cur's drive ends and f's starts in its place (the caller has nothing left to run)
75
+ Replace(f) == cur' = f /\ UNCHANGED stk
76
+
77
+ \* the claim a resume, queued step or interrupt makes on the current Park, then evaluate
78
+ Claim(r, node) == [r EXCEPT !.pdone = TRUE, !.parked = FALSE, !.node = node,
79
+ !.wakes = IF r.parked THEN @ + 1 ELSE @]
80
+
81
+ Masked(f) == ~fb[f].intr \/ (f = "C" /\ fb[f].pc \in {5, 6})
82
+ \* Keep the explicit-mask interval independent of intr; also check inherited startup masks.
83
+
84
+ \* Fiber.interrupt_unsafe: deferred while running or masked, otherwise _interrupt_now at once
85
+ \* (take_interrupt, mark the parked Park done, evaluate the Failure). `now`: that drive starts.
86
+ \* A fiber whose queued start has not run has an empty stack and no children or observers
87
+ \* (only C is ever unstarted, and only P waits on it, after this call): its Failure goes
88
+ \* straight to _done and _publish, running no user code, so it publishes atomically here.
89
+ IntUnsafe(r, running) ==
90
+ IF r.exit # "none" THEN [rec |-> r, now |-> FALSE]
91
+ ELSE IF running \/ (~r.intr /\ Break # "no_mask_check")
92
+ THEN [rec |-> [r EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = TRUE], now |-> FALSE]
93
+ ELSE IF ~r.st
94
+ THEN [rec |-> [r EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = FALSE, !.exit = "int",
95
+ !.pubs = @ + 1], now |-> FALSE]
96
+ ELSE [rec |-> [Claim(r, "int") EXCEPT !.irq = TRUE, !.req = TRUE, !.dfr = FALSE],
97
+ now |-> TRUE]
98
+
99
+ \* end of evaluate: parked while an interrupt waited (it came in during register) -> a fresh
100
+ \* evaluate of the interrupt at the same nesting level; otherwise the drive returns
101
+ DriveTail(f, r) ==
102
+ IF r.dfr /\ r.intr /\ r.parked
103
+ THEN /\ fb' = [fb EXCEPT ![f] = [Claim(r, "int") EXCEPT !.dfr = FALSE]]
104
+ /\ UNCHANGED <<cur, stk>>
105
+ ELSE /\ fb' = [fb EXCEPT ![f] = r]
106
+ /\ EndDrive
107
+
108
+ \* Fiber.evaluate loop top: `if self._deferred and self.interruptible` -> Failure(take_interrupt())
109
+ LoopTop(f) ==
110
+ LET r == fb[f] IN
111
+ /\ cur = f /\ r.dfr /\ r.intr /\ Break # "no_loop_top"
112
+ /\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.node = "int", !.dfr = FALSE]]
113
+ /\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
114
+
115
+ Ready(f) == cur = f /\ (~(fb[f].dfr /\ fb[f].intr) \/ Break = "no_loop_top")
116
+
117
+ \* Fiber._done, then _publish (single call site). o = obs after any cancel ran.
118
+ Done(f, e, o) ==
119
+ LET r == fb[f]
120
+ e2 == IF r.ending = "none" THEN e ELSE IF e = "int" THEN "int" ELSE r.ending
121
+ liveC == f = "P" /\ started /\ fb["C"].exit = "none" /\ Break # "no_wait"
122
+ p == fb["P"]
123
+ ic == IntUnsafe(fb["C"], Running("C"))
124
+ pub == [r EXCEPT !.exit = e2, !.pubs = @ + 1, !.node = "none"]
125
+ \* C's _publish calls P's _await_all observer: one_done -> resume(UNIT) -> P.evaluate.
126
+ \* C's drive has nothing left once it publishes, so P's drive replaces it; Python still
127
+ \* has C.running set here (upstream has already cleared it), but every entry to C now
128
+ \* returns at the `_exit` check, so reentry is harmless. White-box observers can see
129
+ \* the running flag difference; that observation is outside this protocol model.
130
+ notify == f = "C" /\ o /\ p.pid = WAIT /\ Break # "no_notify" /\ (~p.pdone \/ Break = "no_park_done")
131
+ \* the pre-fix _done published P from C's observer, outside P's run loop
132
+ oldPub == f = "C" /\ Break = "old_done" /\ p.pc = WAIT /\ p.exit = "none"
133
+ IN
134
+ IF ~liveC THEN
135
+ /\ IF f = "P" THEN \* no_wait: interrupt C, don't wait
136
+ IF Break = "no_wait" /\ started
137
+ THEN /\ fb' = [fb EXCEPT !["P"] = pub, !["C"] = ic.rec]
138
+ /\ IF ic.now THEN Replace("C") ELSE EndDrive
139
+ ELSE /\ fb' = [fb EXCEPT !["P"] = pub]
140
+ /\ EndDrive
141
+ ELSE IF notify THEN
142
+ /\ fb' = [fb EXCEPT !["C"] = pub, !["P"] = Claim(p, "ok")]
143
+ /\ Replace("P")
144
+ ELSE
145
+ /\ fb' = [fb EXCEPT !["C"] = pub,
146
+ !["P"] = IF oldPub THEN [p EXCEPT !.exit = p.ending, !.pubs = @ + 1]
147
+ ELSE p]
148
+ /\ EndDrive
149
+ /\ obs' = IF f = "C" THEN FALSE ELSE o
150
+ /\ UNCHANGED <<started, sent, selfUsed>>
151
+ ELSE IF Break = "old_done" THEN
152
+ /\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.ending = e2, !.pc = WAIT, !.node = "none"],
153
+ !["C"] = ic.rec]
154
+ /\ obs' = TRUE
155
+ /\ IF ic.now THEN Replace("C") ELSE EndDrive
156
+ /\ UNCHANGED <<started, sent, selfUsed>>
157
+ ELSE \* remember the exit, interrupt C (it may run now, nested), then evaluate _await_all
158
+ /\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.ending = e2, !.pc = WAIT, !.node = "await"],
159
+ !["C"] = ic.rec]
160
+ /\ obs' = o
161
+ /\ IF ic.now THEN Push("C") ELSE UNCHANGED <<cur, stk>>
162
+ /\ UNCHANGED <<started, sent, selfUsed>>
163
+
164
+ \* core.py Async._eval: register (which may interrupt its own fiber), _park, end of drive
165
+ Park(f) ==
166
+ \E self \in (IF selfUsed THEN {FALSE} ELSE BOOLEAN) :
167
+ LET r == fb[f]
168
+ r1 == IF self THEN IntUnsafe(r, TRUE).rec ELSE r
169
+ r2 == [r1 EXCEPT !.ext = @ \cup {r.pc}, !.parked = TRUE, !.pid = r.pc, !.pdone = FALSE,
170
+ !.wakes = 0, !.pc = @ + 1, !.node = "none"]
171
+ IN /\ DriveTail(f, r2)
172
+ /\ selfUsed' = (selfUsed \/ self)
173
+ /\ UNCHANGED <<started, obs, sent>>
174
+
175
+ \* Fiber.yield_now: queue the step on the dispatcher, park on it, end of drive
176
+ Yield(f) ==
177
+ LET r == fb[f]
178
+ r2 == [r EXCEPT !.drv = Append(@, <<"y", r.pc>>), !.parked = TRUE, !.pid = r.pc,
179
+ !.pdone = FALSE, !.wakes = 0, !.pc = @ + 1, !.node = "none"]
180
+ IN /\ DriveTail(f, r2)
181
+ /\ UNCHANGED <<started, obs, sent, selfUsed>>
182
+
183
+ \* fiber._await_all: add observers on C, park (interruptible), end of drive. If C already
184
+ \* published (it ran to its end inside the interrupt above), add_observer calls back during
185
+ \* register: the resume is synchronous and nothing parks.
186
+ AwaitPark ==
187
+ LET r == fb["P"]
188
+ r2 == [r EXCEPT !.parked = TRUE, !.pid = WAIT, !.pdone = FALSE, !.wakes = 0, !.node = "none"]
189
+ IN IF fb["C"].exit # "none"
190
+ THEN /\ fb' = [fb EXCEPT !["P"] = [r EXCEPT !.node = "ok"]]
191
+ /\ UNCHANGED <<cur, stk, obs, started, sent, selfUsed>>
192
+ ELSE /\ DriveTail("P", r2)
193
+ /\ obs' = TRUE
194
+ /\ UNCHANGED <<started, sent, selfUsed>>
195
+
196
+ \* one node of Fiber.evaluate's loop (`cur = cur._eval(self)`)
197
+ Eval(f) ==
198
+ LET r == fb[f]
199
+ ins == Prog[f][r.pc]
200
+ IN
201
+ /\ Ready(f)
202
+ /\ r.node # "none"
203
+ /\ IF r.node = "int" THEN
204
+ \* the interrupt unwinds to the top; under _await_all, its _AsyncCancel removes the observer
205
+ Done(f, "int", IF f = "P" /\ r.pc = WAIT THEN FALSE ELSE obs)
206
+ ELSE IF r.node = "await" THEN AwaitPark
207
+ ELSE IF r.pc = WAIT \/ r.pc = End(f) THEN Done(f, "ok", obs)
208
+ ELSE IF ins = "park" THEN Park(f)
209
+ ELSE IF ins = "yield" THEN Yield(f)
210
+ ELSE IF ins = "fork" THEN
211
+ \E imm \in BOOLEAN, inherit \in BOOLEAN :
212
+ /\ started' = TRUE
213
+ /\ IF imm THEN \* _start(immediate=True): C's evaluate runs now, nested in P's
214
+ /\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok"],
215
+ !["C"] = [@ EXCEPT !.node = "start", !.parked = FALSE, !.st = TRUE,
216
+ !.intr = IF inherit THEN r.intr ELSE TRUE]]
217
+ /\ Push("C")
218
+ /\ UNCHANGED <<obs, sent, selfUsed>>
219
+ ELSE \* _start: C's start is queued on P's dispatcher
220
+ /\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok"],
221
+ !["C"] = [@ EXCEPT !.drv = Append(@, <<"start", 0>>),
222
+ !.intr = IF inherit THEN r.intr ELSE TRUE]]
223
+ /\ UNCHANGED <<cur, stk, obs, sent, selfUsed>>
224
+ ELSE IF ins = "mask" THEN
225
+ /\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.node = "ok", !.intr = FALSE]]
226
+ /\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
227
+ ELSE \* "enable" / "unmask": interruptible / SetInterruptible.on_any deliver via take_interrupt
228
+ /\ fb' = [fb EXCEPT ![f] = [r EXCEPT !.pc = @ + 1, !.intr = TRUE,
229
+ !.node = IF r.irq THEN "int" ELSE "ok",
230
+ !.dfr = IF r.irq THEN FALSE ELSE r.dfr]]
231
+ /\ UNCHANGED <<cur, stk, started, obs, sent, selfUsed>>
232
+
233
+ \* a dispatcher task runs (its batch from the loop, or a flush nested in any drive)
234
+ Drive(f) ==
235
+ LET r == fb[f]
236
+ t == Head(r.drv)
237
+ r1 == [r EXCEPT !.drv = Tail(@)]
238
+ live == IF t[1] = "start" THEN r.exit = "none"
239
+ ELSE (t[2] = r.pid /\ ~r.pdone) \/ (Break = "no_token_claim" /\ r.exit = "none")
240
+ IN /\ r.drv # <<>>
241
+ /\ IF ~live THEN fb' = [fb EXCEPT ![f] = r1] /\ UNCHANGED <<cur, stk>>
242
+ ELSE IF t[1] = "start" THEN
243
+ fb' = [fb EXCEPT ![f] = [r1 EXCEPT !.node = "start", !.parked = FALSE, !.st = TRUE]]
244
+ /\ Push(f)
245
+ ELSE fb' = [fb EXCEPT ![f] = Claim(r1, "ok")] /\ Push(f)
246
+ /\ UNCHANGED <<started, obs, sent, selfUsed>>
247
+
248
+ \* an async completion fires: Async resume checks `not park.done`, then evaluates at once
249
+ ExtResume(f) ==
250
+ \E id \in fb[f].ext :
251
+ LET r == fb[f]
252
+ r1 == [r EXCEPT !.ext = @ \ {id}]
253
+ hit == (id = r.pid /\ ~r.pdone) \/ (Break = "no_park_done" /\ r.exit = "none")
254
+ IN /\ IF hit THEN fb' = [fb EXCEPT ![f] = Claim(r1, "ok")] /\ Push(f)
255
+ ELSE fb' = [fb EXCEPT ![f] = r1] /\ UNCHANGED <<cur, stk>>
256
+ /\ UNCHANGED <<started, obs, sent, selfUsed>>
257
+
258
+ \* someone calls P.interrupt_unsafe, from the loop or from inside any drive
259
+ Interrupt ==
260
+ LET x == IntUnsafe(fb["P"], Running("P")) IN
261
+ /\ ~sent /\ fb["P"].exit = "none"
262
+ /\ sent' = TRUE
263
+ /\ fb' = [fb EXCEPT !["P"] = x.rec]
264
+ /\ IF x.now THEN Push("P") ELSE UNCHANGED <<cur, stk>>
265
+ /\ UNCHANGED <<started, obs, selfUsed>>
266
+
267
+ Settled(f) == fb[f].drv = <<>> /\ fb[f].ext = {} /\ (fb[f].exit # "none" \/ (f = "C" /\ ~started))
268
+ Finished == cur = "none" /\ \A f \in Fibers : Settled(f)
269
+ Done_ == Finished /\ UNCHANGED vars
270
+
271
+ Next ==
272
+ \/ \E f \in Fibers : Drive(f) \/ LoopTop(f) \/ Eval(f) \/ ExtResume(f)
273
+ \/ Interrupt
274
+ \/ Done_
275
+
276
+ Spec == Init /\ [][Next]_vars /\ WF_vars(Next)
277
+
278
+ \* ---- invariants (docs/INVARIANTS.md) ----
279
+ LiveTasks(f) == {i \in 1..Len(fb[f].drv) :
280
+ IF fb[f].drv[i][1] = "start" THEN fb[f].exit = "none"
281
+ ELSE fb[f].drv[i][2] = fb[f].pid /\ ~fb[f].pdone}
282
+ Drives(f) == Cardinality({i \in 1..Len(stk) : stk[i] = f}) + (IF cur = f THEN 1 ELSE 0)
283
+
284
+ K1_ExitOnce == \A f \in Fibers : fb[f].pubs <= 1
285
+ K2_ResumeOnce == \A f \in Fibers : fb[f].wakes <= 1
286
+ \* one evaluate per fiber at a time, nested or not, and none queued while it runs or waits
287
+ K3_OneRunner == \A f \in Fibers : Drives(f) + Cardinality(LiveTasks(f)) <= 1
288
+ K6_MasksHold == \A f \in Fibers : (cur = f /\ fb[f].node = "int") => ~Masked(f)
289
+ K7_InterruptsLand == \A f \in Fibers : (fb[f].exit # "none" /\ fb[f].req) => fb[f].exit = "int"
290
+ K8_NoOrphans == (fb["P"].exit # "none" /\ started) => fb["C"].exit # "none"
291
+
292
+ \* progress: every fiber that started publishes
293
+ AllPublish == <>Finished
294
+ =============================================================================