A methods repository: demonstrating how to specify, test, and stress-test a tiny “overlap” library across wildly different systems — without implying that any one ecosystem should replace its standard library.
This repository is a stress-test and methods lab for aLib.
It exists to demonstrate:
-
How to identify a minimal overlap (“common”) between systems with very different constraints.
-
How to express that overlap as:
-
a stable spec surface,
-
semantics notes,
-
and a conformance test suite.
-
-
How “reversibility” and “safe iteration” can be enforced through disciplined boundaries and test vectors.
This repo is intentionally allowed to be “weird” and “extreme” because its job is to break ideas early.
[!NOTE] The “overlap” demonstrated here is intentionally chosen for stress-testing across very different designs. It is an illustrative demo of method under extreme diversity — not a claim that any ecosystem should adopt this overlap as its standard library.
To avoid confusion:
-
Not a replacement for any ecosystem’s standard library.
-
Not a proposal that “all languages should share one stdlib.”
-
Not a claim that the overlap shown here is the “correct” overlap for all projects.
-
Not a dependency that downstream implementations must import.
This repo demonstrates a method. Implementations may borrow the method, not the code.
In the aLib universe there are two different “common” ideas:
Overlap Common (this repo)
A demonstration overlap chosen to be stress-tested against extreme diversity.
Ecosystem Common (implementation repos)
A practical shared layer for a specific ecosystem (example: AffineScript + Melange + optional runtime validation).
This repo covers only the first meaning.
The overlap is defined by the spec files under specs/: one file per
operation, 29 operations in 6 categories. just list prints them and
just test fails if a category gains or loses a file without the
Justfile being updated.
| Category | Count | Operations |
|---|---|---|
arithmetic |
9 |
add, subtract, multiply, divide, modulo, negate, absolute, max, min |
comparison |
6 |
equal, not_equal, less_than, less_equal, greater_than, greater_equal |
logical |
3 |
and, or, not |
string |
4 |
concat, length, substring, reverse |
collection |
6 |
map, filter, fold, contains, length, empty |
conditional |
1 |
if_then_else |
total |
29 |
Older figures you may meet elsewhere:
-
22 is the v0.1.0 core (2025-11-22): every operation above except negate, absolute, max, min, string
reverse, collectionlengthandempty.data/aggregate.jsonis a dated snapshot of that core, and affinescript’s runnablestdlib/alib.affineimplements those 22. -
20 was a mis-sum of the same 22-operation list (5 + 6 + 3 + 3 + 4 + 1). It has been corrected wherever it appeared.
Each spec ends with executable test cases in YAML (156 vectors across the
29 operations). For conformers that should not parse AsciiDoc, the same
vectors are exported to vectors/<category>.json (I-JSON, JCS form).
vectors/GRAMMAR.adoc gives the JSON layout and the grammar of the
lambda and condition strings that some vectors use.
-
just vectorsregeneratesvectors/*.jsonfrom the specs. -
just vectors-checkfails if the committed JSON differs from what the specs generate;just validateruns it. Both needjq(1.7 or later) andyq.
Some projects may serve as reference points for semantics, verification approaches, or ecosystem-specific implementations.
These relationships are optional and non-binding:
-
proven— a reference implementation that can inform semantics intent and verification style (not required). -
alib-for-affinescript— an ecosystem implementation proving ground (AffineScript/Melange) that applies the aLib method (not required). -
Implementation support repos (optional): conformance runners, codemods, interop pattern cookbooks.
This repo should not become a “dependency magnet”; implementation repos should be able to adopt the method without importing code from here.
aLib also serves as the extension layer over the AffineScript face
family. AffineScript is one canonical cube presented through six faces
(RattleScript, JaffaScript, PseudoScript, LucidScript, CafeScripto, and
the canonical face); implementing an aLib operation once in canonical
AffineScript conforms it for all six faces at the library level, because
the faces are surface sugar that lower to that one definition. This
pairs the library same-cube guarantee (aLib conformance vectors) with
the syntax same-cube guarantee (the invariant-path faces
profile) — the same canonical artefact, grounded on two axes.
-
Conformer:
src/affinescript/ALib.affine— all 29 operations, with an affine-typed collection group that makes AffineScript a stronger conformer than a GC’d reference. -
The argument + a faces gallery (one operation across all six faces):
docs/EXTENSION-LAYER.adoc.
-
Minimal surfaces, explicit semantics.
-
Conformance tests as the safety net.
-
Reversibility: changes must be easy to evaluate and to undo.
-
Ecosystem neutrality: no “blessed” implementation.
This repository demonstrates the extraction of universal patterns from the intersection of multiple language stlibs (Phronesis, Rust, Haskell), choosing the best implementation for each pattern.
See COMPOSITION-GUIDE for the complete methodology:
aggregate-library = (common elements of phronesis stdlib ∩ Rust stdlib ∩ Haskell stdlib)
∪ (compiler utilities)
This creates a leaner library with no duplication - a single source of truth for universal patterns.
An automated tool for extracting common patterns from multiple stlibs is
available in tools/stdlib-merger/.
cd tools/stdlib-merger
julia cli.jl merge \
--stdlib phronesis:/path/to/phronesis/stdlib \
--stdlib rust:/path/to/rust/std \
--stdlib haskell:/path/to/haskell/base \
--output ../../lib/aggregate_librarySee stdlib-merger README and ARCHITECTURE for details.
Current implementation demonstrates:
-
lib/aggregate_library/— Universal stdlib patterns (Result, Collections, FileIO, Stream, Time) -
lib/a_lib/— Compiler utilities (Token, Position, Error, AST.Traversal, StringUtils, ColorOutput) -
specs/— Specifications (arithmetic, comparison, logical, collection, string, conditional operations) -
vectors/— The spec test vectors exported as JSON, plus their grammar -
scripts/— Validation tools (Deno) -
COMPOSITION-GUIDE.md— Detailed methodology and integration examples
-
Read the spec and the design notes.
-
Use conformance vectors to validate an implementation in your ecosystem.
-
Borrow the method for building your own proving-ground library.
Contributions should optimize for:
-
clarity of the overlap definition,
-
stronger tests,
-
stronger reversibility discipline,
-
and reduced ambiguity.
If you are proposing new surface area, you must also propose:
-
semantics notes, and
-
tests that make regressions obvious.