// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2024-2026 hyperpolymath (Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>)
= AffineScript ↔ aLib Integration

This directory contains documentation and tools for integrating
AffineScript with the *aggregate-library (aLib)* methodology.

== Quick Links

* *Strategy Document*: link:../ALIB-INTEGRATION.adoc[ALIB-INTEGRATION.md]
- Complete integration strategy
* *Conformance Generator*: ../../tools/alib_conformance_gen.jl -
Auto-generate tests from aLib specs
* *aLib Repository*: https://github.com/hyperpolymath/aggregate-library

== What is aLib?

aggregate-library (aLib) is a *methods repository* that demonstrates how
to: - Specify minimal overlap between diverse programming ecosystems -
Express that overlap as stable specs {plus} semantics {plus} conformance
tests - Enable cross-language compatibility without imposing a standard
library

aLib is NOT a library to import - it’s a methodology to apply.

== Why AffineScript {plus} aLib?

AffineScript brings *unique value* to aLib:

[arabic]
. *Stress Testing* - Affine types are "`extreme constraints`" that push
specs to their limits
. *Novel Semantics* - Shows how common operations work under move
semantics
. *Safety Model* - Demonstrates memory-safe, use-after-free-free
implementations
. *Ecosystem Diversity* - Adds functional {plus} affine-typed language
to aLib portfolio

== Current Status

=== ✅ Completed

* [x] Strategic analysis of aLib integration opportunities
* [x] Documentation of integration approach
* [x] Conformance test generator tool (Julia)

=== 🚧 In Progress

* [ ] Run conformance tests against current stdlib
* [ ] Document affine semantics for each aLib spec
* [ ] Create `alib-for-affinescript` ecosystem repo

=== 📋 Planned

* [ ] Contribute affine semantics notes to aLib upstream
* [ ] Cross-language benchmarking
* [ ] Interop examples with other aLib-conformant systems

== Quick Start

=== Generate Conformance Tests

[source,bash]
----
# Assuming aggregate-library is cloned alongside affinescript
cd affinescript
julia tools/alib_conformance_gen.jl \
    ../aggregate-library/specs \
    tests/conformance
----

=== Run Conformance Tests

[source,bash]
----
affinescript test tests/conformance/
----

=== View Conformance Report

[source,bash]
----
affinescript test --alib-conformance-report
----

== aLib Spec Categories

AffineScript stdlib aligns with these aLib categories:

[width="100%",cols="35%,47%,18%",options="header",]
|===
|aLib Category |AffineScript Module |Status
|`arithmetic` |`stdlib/math.affine` |✓ Good

|`collection` |`stdlib/collections.affine` {plus} `prelude.affine` |⚠
Needs affine semantics docs

|`comparison` |`stdlib/prelude.affine` |✓ Good

|`conditional` |Built-in (if/match) |✓ Good

|`logical` |Built-in (&&, {vbar}{vbar}, !) |✓ Good

|`string` |`stdlib/string.affine` |⚠ Partial
|===

== Affine Semantics Examples

=== map (Collection → Collection)

*aLib Spec*:
`map: Collection++[++A++]++, Function++[++A -++>++ B++]++ -++>++ Collection++[++B++]++`

*AffineScript Implementation*:

[source,affinescript]
----
/// Conforms to aLib collection/map
/// Affine: source moved, elements consumed exactly once
fn map<T, U>(arr: [T], f: T -> U) -> [U] {
  let result = [];
  for x in arr {  // arr moved
    result = result ++ [f(x)];  // x consumed by f
  }
  result
}
// arr is no longer accessible here (moved)
----

*Key Difference*: aLib spec doesn’t specify ownership. AffineScript
adds: - Source collection *moved* (not copied) - Each element consumed
*exactly once* - Result collection *owned* by caller

=== filter (Collection {plus} Predicate → Collection)

*aLib Spec*:
`filter: Collection++[++A++]++, Function++[++A -++>++ Bool++]++ -++>++ Collection++[++A++]++`

*AffineScript Implementation*:

[source,affinescript]
----
/// Conforms to aLib collection/filter
/// Affine: predicate borrows, source moved, filtered elements dropped
fn filter<T: affine>(arr: [T], pred: &T -> Bool) -> [T] {
  let result = [];
  for x in arr {
    if pred(&x) {  // predicate borrows (doesn't consume)
      result = result ++ [x];  // x moved into result
    }
    // else: x dropped here (affine allows drop without use)
  }
  result
}
----

*Key Difference*: Predicate *borrows* instead of consuming (allows
checking without ownership transfer).

== Contributing

=== To AffineScript

[arabic]
. Implement aLib-conformant operations in stdlib
. Add conformance test attributes
. Document affine-specific semantics

=== To aLib (upstream)

[arabic]
. Contribute affine semantics notes
. Add affine-specific test vectors
. Document edge cases under move semantics

== Resources

* *aLib Specs*:
https://github.com/hyperpolymath/aggregate-library/tree/main/specs
* *Integration Strategy*:
link:../ALIB-INTEGRATION.adoc[ALIB-INTEGRATION.md]
* *AffineScript Types*: ../specs/affinescript-spec.md

== License

PMPL-1.0 (following AffineScript project license)
