From 62cb8393ee424f60770d6d52460b3edf8656c6ad Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 26 May 2026 21:00:45 +0100 Subject: [PATCH] docs: ephapax-vs-AffineScript disambiguation hooks (README + CLAUDE.md + a2ml) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds three thin pointers to the canonical disambiguation doc at nextgen-languages/docs/disambiguation/ephapax-vs-affinescript.md (commit 2fcb55a on hyperpolymath/nextgen-languages main): 1. README.adoc β€” top-of-file [IMPORTANT] admonition immediately after the title, explaining (a) this is Ephapax not AffineScript, (b) the two share only the typed-wasm target, (c) the internal naming trap where the `ephapax-affine` sublanguage is NOT AffineScript. 2. CLAUDE.md (new) β€” agent guidance with a 🚨 Disambiguation block as first content, plus side-by-side path/extension/build/checker table. Documents the dyadic-internal-naming trap explicitly. Cross-refers the canonical memory entry feedback_affinescript_ephapax_siblings_not_impl_proof.md. 3. .machine_readable/6a2/AGENTIC.a2ml β€” new [agentic-config.disambiguation] block with fields: this, canonical-name, distinct-from, shared-with-distinct, internal-sublanguages, ephapax-affine-is-not-affinescript, canonical-doc, canonical-memory-entry, do-not-apply-cross-repo-lessons-without-explicit-check. Why: AI agents have repeatedly conflated Ephapax with AffineScript across sessions ("we have gone through this a dozen times before", 2026-05-26). The shared `affine` syllable is logic-family terminology (both type systems exhibit affine-flavored substructural properties, like nearly every modern resource-safe language) β€” not a project relationship. Companion hooks land in hyperpolymath/affinescript and hyperpolymath/typed-wasm via separate PRs. Co-Authored-By: Claude Opus 4.7 (1M context) --- .machine_readable/6a2/AGENTIC.a2ml | 25 ++++++++++++-- CLAUDE.md | 52 ++++++++++++++++++++++++++++++ README.adoc | 24 ++++++++++++++ 3 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 CLAUDE.md diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/6a2/AGENTIC.a2ml index 345a08c6..04d5f699 100644 --- a/.machine_readable/6a2/AGENTIC.a2ml +++ b/.machine_readable/6a2/AGENTIC.a2ml @@ -32,5 +32,26 @@ banned = ["typescript", "go", "python", "makefile"] # NEVER modify formal proofs (Coq/Idris2) without verifying them. # Always run `just golden` before committing to ensure proof closure. # Respect the dyadic boundary: affine vs linear must be explicitly handled. -last-modified-at = "2026-04-23T13:00:00Z" -modification-summary = "Initial creation from 1.0.0 template" +last-modified-at = "2026-05-26T20:00:00Z" +modification-summary = "Added @disambiguation block β€” Ephapax vs AffineScript canonical pointer" + +# ── Disambiguation ──────────────────────────────────────────────────────── +# AI agents have repeatedly conflated this repo (Ephapax) with the unrelated +# language AffineScript (hyperpolymath/affinescript). The two share exactly +# one thing β€” both target hyperpolymath/typed-wasm β€” and otherwise have +# different ASTs, type checkers, compilers, and proof stories. The shared +# `affine` syllable names a substructural-logic property in BOTH cases (it's +# a logic-family name), not a project relationship. +[agentic-config.disambiguation] +this = "hyperpolymath/ephapax" +canonical-name = "Ephapax" +distinct-from = ["hyperpolymath/affinescript"] +shared-with-distinct = ["hyperpolymath/typed-wasm"] +internal-sublanguages = ["ephapax-linear", "ephapax-affine"] +# `ephapax-affine` is an internal sublanguage of THIS repo (dyadic with +# ephapax-linear, one AST, one Rust crate). It is NOT the AffineScript +# language at hyperpolymath/affinescript. +ephapax-affine-is-not-affinescript = true +canonical-doc = "https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md" +canonical-memory-entry = "feedback_affinescript_ephapax_siblings_not_impl_proof.md" +do-not-apply-cross-repo-lessons-without-explicit-check = true diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..78a35997 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,52 @@ + + + +# CLAUDE.md β€” Ephapax repo agent guidance + +## 🚨 Disambiguation (read first) + +**This repo is `hyperpolymath/ephapax`.** It is **NOT** `hyperpolymath/affinescript`. + +| | This repo | NOT this repo | +|---|---|---| +| Name | **Ephapax** | AffineScript | +| Path | `hyperpolymath/ephapax` | `hyperpolymath/affinescript` | +| File extension | `.eph` | `.affine` (plus face dialects) | +| Build | `Cargo.toml` at root | `dune-project` at root | +| Type checker | `ephapax-linear/src/{linear,affine}.rs` (Rust) | `lib/borrow.ml` (OCaml) | +| Proofs | `formal/Semantics.v` (Coq), `src/abi/Ephapax/…` (Idris2) | None mechanized; `lib/borrow.ml` only | + +**Internal naming trap.** Ephapax itself is dyadic. Inside this repo: +- **ephapax-linear** = strict, formally-verified core. +- **ephapax-affine** = versatile prototyping companion to ephapax-linear. + +Both are *internal sublanguages*. They share one AST, one Rust crate (`ephapax-linear/`), one grammar directory. **The `ephapax-affine` sublanguage is NOT AffineScript.** The word `affine` is shared because both happen to be substructural-logic-family type systems β€” that's a logic-family fact, not a project relationship. + +**Rule for agents:** before applying any prior-session lesson, memory entry, or snippet, check whether it was about *ephapax* or about *AffineScript*. They share zero AST / typing / borrow-checker / codegen. The only shared surface is the compile target (`hyperpolymath/typed-wasm`). + +When in doubt: state the context shift explicitly ("switching from AffineScript context to ephapax context") so the user sees the boundary respected. + +**Canonical disambiguation doc** (single source of truth): +https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md + +**Companion memory entry** (in user auto-memory): +`feedback_affinescript_ephapax_siblings_not_impl_proof.md` + +--- + +## Machine-readable artefacts + +Structured project metadata lives in `.machine_readable/6a2/`: + +- `STATE.a2ml` β€” current project state and progress. +- `META.a2ml` β€” architecture decisions and development practices. +- `ECOSYSTEM.a2ml` β€” position in the ecosystem and related projects. +- `AGENTIC.a2ml` β€” AI agent interaction patterns (also carries an `@disambiguation` block). +- `NEUROSYM.a2ml` β€” neurosymbolic integration config. +- `PLAYBOOK.a2ml` β€” operational runbook. + +## Standing reminders + +- Formal-proof work touches `formal/Semantics.v` (Coq) and `src/abi/Ephapax/…/*.idr` (Idris2). Both build oracles are authoritative; `coqc` and `idris2 --check` are the only "is this proved?" answers. +- Preservation closure plan: see `ROADMAP.adoc` Β§ "Preservation closure plan" and `formal/PRESERVATION-HANDOFF.md`. +- All commits GPG-signed (key `4A03639C1EB1F86C7F0C97A91835A14A2867091E`), email `6759885+hyperpolymath@users.noreply.github.com`. Auto-merge ON for every PR. diff --git a/README.adoc b/README.adoc index 7be460ca..2b49c9bd 100644 --- a/README.adoc +++ b/README.adoc @@ -16,6 +16,30 @@ image:https://api.thegreenwebfoundation.org/greencheckimage/ephapax.org[Green Ho _ἐφάπαξ β€” once for all._ +[IMPORTANT] +.Not to be confused with AffineScript +==== +This is **Ephapax**, a research language for WebAssembly memory safety. +It is *not* https://github.com/hyperpolymath/affinescript[AffineScript], a +separate language at `hyperpolymath/affinescript` that succeeds JS / TS / +ReScript. + +The two share **exactly one thing**: both target +https://github.com/hyperpolymath/typed-wasm[typed-wasm]. They have separate +ASTs, separate type checkers, separate compilers, separate proof stories. +The word `affine` overlaps in both names because it names a substructural- +logic property β€” that's a logic-family fact, not a project relationship. + +Internal note: Ephapax is itself dyadic β€” `ephapax-linear` (strict core) +and `ephapax-affine` (versatile prototyping companion) are *both inside this +repo*, one Rust crate, one AST, two structural disciplines. **`ephapax-affine` +is not AffineScript.** When ambiguous, write "ephapax-affine sublanguage" +vs "AffineScript language". + +Canonical disambiguation: +link:https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md[nextgen-languages/docs/disambiguation/ephapax-vs-affinescript.md]. +==== + A dyadic linear+affine type system for compile-time WebAssembly memory safety. Resources are tracked through the type system so the compiler can guarantee β€” without a garbage collector β€” that no value