Skip to content

Commit f084968

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
chore: update Justfile + advance submodule pointers + add opsm.toml + reversibility design doc
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 182de3c commit f084968

4 files changed

Lines changed: 216 additions & 1 deletion

File tree

‎Justfile‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,40 @@ check: lint test
3131
release VERSION:
3232
@echo "Releasing {{VERSION}}..."
3333

34+
# ============================================================
35+
# OPSM — native package management for nextgen-languages
36+
# ============================================================
37+
38+
# Install all workspace dependencies via OPSM
39+
deps:
40+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found — install from https://github.com/hyperpolymath/odds-and-sods-package-manager" && exit 1)
41+
opsm install --workspace
42+
43+
# Install pinned tool versions from [runtime] section in opsm.toml
44+
runtime-install:
45+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found" && exit 1)
46+
opsm runtime install --from opsm.toml
47+
48+
# Publish all workspace members to the Hyperpolymath Forge Registry
49+
publish:
50+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found" && exit 1)
51+
opsm publish --workspace --registry hf
52+
53+
# Search OPSM for a package across all nextgen-languages registries
54+
search QUERY:
55+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found" && exit 1)
56+
opsm search "{{QUERY}}" --registry hf
57+
58+
# List installed OPSM runtime tools
59+
runtime-list:
60+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found" && exit 1)
61+
opsm runtime list
62+
63+
# Audit workspace packages (license + sustainability)
64+
audit:
65+
@command -v opsm >/dev/null 2>&1 || (echo "OPSM not found" && exit 1)
66+
opsm audit --workspace
67+
3468

3569
# Run panic-attacker pre-commit scan
3670
assail:

‎affinescript‎

‎docs/design/jtv-007-reversibility-fork.adoc‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
4+
= JTV v2 / 007 Reversibility: Designed Fork
5+
:toc: macro
6+
7+
[.lead]
8+
A portfolio-level note on the deliberate divergence between JTV v2's canonical
9+
reversibility model and 007's Phase 1 implementation. This is a designed
10+
experiment — two languages in this portfolio exploring adjacent points in the
11+
reversible computation design space, with shared foundations and a clear
12+
convergence point.
13+
14+
toc::[]
15+
16+
== Context
17+
18+
JTV (Julia the Viper) is the heritage language from which 007 descends.
19+
JTV v1 (Alpha stage) established the addition-only Data Language — a single
20+
arithmetic primitive with the thesis that all other arithmetic operations
21+
are derivable. JTV v2 (Gamma stage) extends this to the Control Language:
22+
subtraction is not a primitive, it is the inverse of addition, expressed
23+
as `reverse { x += v }`.
24+
25+
In April 2026, 007's JTV v2 reversibility implementation underwent a
26+
comprehensive design session closing five open questions about `reversible { }`,
27+
`reverse { }`, `irreversible { }`, and the `ReversalToken` mechanism. In
28+
resolving those questions, a deliberate fork from JTV v2's canonical model
29+
was identified and documented. This file records that fork at the portfolio
30+
level.
31+
32+
== The Shared Foundation
33+
34+
Both JTV v2 and 007 (all phases) share the following:
35+
36+
[options="header"]
37+
|===
38+
| Mechanism | Description
39+
| *Linear `ReversalToken`* | Produced by `reversible { }`, consumed by `reverse tok` or `abandon tok`. Pairing is type-enforced, not runtime stack or label lookup.
40+
| *`ReversalToken<S>` type parameter* | `S` encodes what was captured. Typechecker infers `S` from mutations inside the block.
41+
| *`Option<ReversalToken>` at branch joins* | Path-sensitive typing at `branch` join points. Asymmetric branches produce `Option<ReversalToken<S>>` automatically. `match` forces exhaustive handling. No lint needed.
42+
| *`ExternalHandle` static error* | Sending to an external agent inside `reversible { }` without `irreversible { }` wrapping is a compile-time error. Local reversibility only — distributed reversibility is a protocol-level concern.
43+
| *`irreversible { }` escape* | Explicit annotation for operations with no defined inverse.
44+
| *Structural sugar* | `reversible { ... } reverse { ... }` desugars to the token form.
45+
|===
46+
47+
== The Fork
48+
49+
The divergence is in what the token carries and what `reverse tok` does.
50+
51+
=== JTV v2 Canonical Model
52+
53+
Per-operation reversal. The `ReversalToken` carries a reversal *log* —
54+
a sequence of `(op, inv(op))` pairs recorded as operations execute.
55+
`reverse tok` replays the inverse operations in reverse order.
56+
57+
Subtraction is genuinely `reverse { x += v }` at the operation level.
58+
Each step of the forward computation has a corresponding inverse step.
59+
This is the Janus tradition: step-by-step invertibility, theoretical
60+
alignment with Landauer's principle.
61+
62+
=== 007 Phase 1
63+
64+
Whole-block snapshot restore. The `ReversalToken` carries the pre-block
65+
values of `@state` fields declared in `reversible_state { }` (or inferred
66+
by the typechecker from mutations). `reverse tok` restores those field values.
67+
68+
In a purely functional language, local bindings need no snapshotting —
69+
lexical scope provides this for free. Only `@state` fields need capturing.
70+
The snapshot approach delivers correct semantics with minimal machinery
71+
and is statically verified via token linearity. It is not per-operation.
72+
73+
=== 007 Phase 2 (Planned)
74+
75+
Per-operation reversal via `ref T`. Mutable references within `reversible`
76+
blocks, with a per-operation inverse log. Converges toward JTV v2's model.
77+
`ref T` is introduced as a deliberate later addition once Phase 1 has been
78+
proven in use.
79+
80+
== The Experiment Design
81+
82+
[options="header"]
83+
|===
84+
| Question | Evidenced by
85+
| Is per-operation inversion required to honour the "subtraction as inverse" claim? | JTV v2 usage
86+
| Is whole-block snapshot sufficient for agent programming in practice? | 007 Phase 1 usage
87+
| Does `ref T` at Phase 2 feel natural or forced? | 007 Phase 2 implementation
88+
| Is snapshot a useful pedagogical stage or merely a stepping stone? | Comparison of learning curves
89+
| Does the convergence hypothesis hold? | 007 Phase 2 vs JTV v2 canonical — if they agree, yes
90+
|===
91+
92+
== Comparison with the Reversible Computation Literature
93+
94+
The shared foundation (linear token, type-parameter-encoded state,
95+
Option-lifting at branches) represents three mechanisms not present in any
96+
existing reversible programming system:
97+
98+
. *Linear token as unified pairing + snapshot/log carrier* — no existing
99+
reversible language (Janus, R, Theseus, STM, algebraic effects) uses a
100+
linear value as both the pairing mechanism and the typed state carrier.
101+
102+
. *Type-parameter-encoded captured state* — `ReversalToken<S>` encodes
103+
statically what was captured. STM logs are untyped. Janus has no type
104+
system. Koka's effect rows do not encode captured values.
105+
106+
. *Option-lifting at branch joins* — Janus and R require syntactically
107+
symmetric branches. STM retries. Effect handlers require explicit
108+
continuation management. This portfolio's solution falls out of existing
109+
linear typing rules with zero new machinery.
110+
111+
These are believed to constitute a novel contribution to the reversible
112+
computation literature, publishable alongside the 007 or JTV v2 language
113+
papers.
114+
115+
== Cross-References
116+
117+
* `julia-the-viper/docs/language/DESIGN-JTV-V2-REVERSIBILITY.md` — JTV v2
118+
canonical model in full
119+
* `007/docs/session-2026-04-12-jtv-v2-reversibility-design.adoc` — 007's
120+
five closed design decisions and Phase 1/Phase 2 plan
121+
* `typell/docs/decisions/0002-reversibility-as-typing-case-study.md` — the
122+
three type-system collapses as a TypeLL case study

‎opsm.toml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
#
4+
# nextgen-languages workspace manifest.
5+
# OPSM is the native package manager for all nextgen languages.
6+
#
7+
# Usage:
8+
# opsm install # install workspace deps
9+
# opsm publish --registry hf # publish all member packages
10+
# opsm runtime install # install pinned tool versions below
11+
12+
[workspace]
13+
# All language sub-projects in this monorepo
14+
members = [
15+
"affinescript",
16+
"betlang",
17+
"eclexia",
18+
"ephapax",
19+
"error-lang",
20+
"julia-the-viper",
21+
"my-lang",
22+
"oblibeny",
23+
"phronesis",
24+
"tangle",
25+
"wokelang",
26+
]
27+
28+
# Workspace-level default registry — all members publish here unless overridden
29+
default_registry = "hf"
30+
31+
[workspace.opsm]
32+
trust_level = "hyperpolymath"
33+
34+
[workspace.dependencies]
35+
# Shared dependencies available to all members
36+
proven = { git = "https://github.com/hyperpolymath/proven", registry = "hf" }
37+
groove = { git = "https://github.com/hyperpolymath/groove", registry = "hf" }
38+
verisimdb = { registry = "hf", version = "latest" }
39+
40+
[runtime]
41+
# Tool versions for the full nextgen-languages toolchain.
42+
# OPSM runtime extension manages all of these — no asdf needed.
43+
#
44+
# Compilers
45+
ocaml = "5.1.0" # AffineScript compiler
46+
rust = "nightly" # Betlang, KRL, tools
47+
haskell = "9.8.1" # k9-haskell, pandoc-k9
48+
49+
# BEAM
50+
erlang = "26.2.0"
51+
elixir = "1.16.0"
52+
53+
# Core build tools
54+
just = "1.46.0"
55+
zig = "0.14.0" # ABI/FFI layer
56+
deno = "2.6.10" # JS build scripts
57+
58+
# Language-specific toolchains (installed via OPSM runtime)
59+
# julia is managed by the julia-the-viper sub-project directly

0 commit comments

Comments
 (0)