Skip to content

Latest commit

 

History

74 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.

Status

Experimental / research / demonstration.

What this repo is

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.

What this repo is NOT

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.

Two meanings of “Common”

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 operations

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, collection length and empty. data/aggregate.json is a dated snapshot of that core, and affinescript’s runnable stdlib/alib.affine implements 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.

Test vectors

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 vectors regenerates vectors/*.json from the specs.

  • just vectors-check fails if the committed JSON differs from what the specs generate; just validate runs it. Both need jq (1.7 or later) and yq.

Reference implementations and optional consumers

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.

AffineScript faces — the extension layer

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.

Design principles

  • 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.

Composition Guide

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.

stdlib-merger Tool

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_library

See stdlib-merger README and ARCHITECTURE for details.

Contents

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

How to use this repo

  • 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.

Contributing

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.

License

PLMP-1.0.0-or-later

Releases

Sponsor this project

Packages

Used by

Contributors

Languages