Skip to content
CAI
Software that uses CAICheck a score

macula-io/macula

66.2

Weak · 15 November 2026

56.7k

lines of production code

Erlang

with Rust

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Initial SDK release with QUIC transport, CBOR wire protocol, and post-quantum identity

This entry establishes the Macula SDK foundation (v3.0.0+), replacing the previous MessagePack wire format with a native deterministic CBOR codec and switching the QUIC transport from quicer/MsQuic to a Quinn-based Rust NIF. It introduces post-quantum identity support via ML-DSA-87 keys, UCAN/DID authorization, and a new ownership-tier topic system (realm/org/app) with strict validation. The release also includes a comprehensive test suite, documentation restructuring, and a shift to the Apache-2.0 license.

(repo-wide) · high confidence

Introduce Erlang distribution over the Macula mesh

This change adds a new distribution system (\macula\_dist\_system\) that enables Erlang nodes to connect across NATs and firewalls without a VPN. It provides three transport modes: direct QUIC for low-latency LAN clustering, a pool-tunneled path via the existing mesh pub/sub (activated with \macula:join\_mesh/1\), and a dedicated freight relay for raw QUIC stream forwarding (activated with \macula:join\_dist\_relay/1\). The implementation includes a custom OTP distribution driver (\macula\_dist\), a bridge system for the pool-tunneled path, and a client for the dedicated relay, all secured with end-to-end TLS sessions inside the tunnels.

_src/macula\_dist\system · high confidence

Introduce end-to-end sealed pubsub with epoch-based key rotation

Adds the core components for end-to-end sealed pubsub in the \seal\ module, enabling publishers to seal events under rotating group epochs and subscribers to open them with automatic key management. The new \macula\_group\_epoch\ module defines epoch lifecycles with a 15-minute default rotation and an ahead window for seamless key distribution. \macula\_group\_keyring\ manages the local state, pulling current and future epochs from a distributor (\macula\_group\_keys\) and handling membership checks, while \macula\_group\_opener\ processes incoming events, delivering sealed payloads or reporting specific refusal reasons like \unknown\_epoch\ or \not\_a\_member\. The system relies on \macula\_seal\ for the underlying cryptographic primitives (ML-KEM-1024 and AES-256-GCM) and \macula\_kem\_keyring\ for node-level key generation and rotation. Also in this area: 1 commit (1 fix) fixing src/seal; 2 commits (0 fixes) modifying src/seal; Epoch keys are no longer exposed in process state, status, or crash reports.

src/seal · medium confidence · unverified

Native crypto and MRI NIFs for ML-DSA, BLAKE3, and trie-based resource identification

This change introduces high-performance native implementations for core cryptographic and resource-identification operations. The new \macula\_crypto\_nif\ provides ML-DSA (FIPS 204) key generation, signing, and verification for node keys and UCAN tokens, alongside BLAKE3 and SHA-256 hashing functions optimized for content-addressed storage. The \macula\_mri\_nif\ adds native support for parsing Macula Resource Identifiers (MRIs) and includes a persistent trie index for efficient O(d) hierarchy queries (children/descendants) in large-scale deployments. These NIFs replace previous Ed25519-based identity mechanisms and pure-Erlang MRI handling, offering significant speedups for service discovery, authorization, and routing.

_native/macula\_crypto\nif · high confidence

New MRI type system, storage adapters, and z-base-32 encoding

This change introduces the core Macula Resource Identifier (MRI) infrastructure. It adds a new \macula\_z32\ codec for encoding node IDs into DNS-friendly strings, and a comprehensive MRI type registry (\macula\_mri\_registry\) that supports built-in types (including a new \station\ type rooted by node\_id) and custom runtime registration. The system provides pluggable storage and graph behaviors (\macula\_mri\_store\, \macula\_mri\_graph\) with an in-memory ETS adapter (\macula\_mri\_ets\) as the default, alongside a high-performance NIF-accelerated module (\macula\_mri\_nif\) with pure Erlang fallbacks for parsing, validation, and hierarchy queries.

src/mri · high confidence

New brand assets and architecture diagrams added

Added a comprehensive set of visual assets to the \artwork\ directory, including a new SVG logo (with color, dark, and white variants), an animated logo, and multiple architecture diagrams (including a Mermaid source file and SVGs) that illustrate the Macula mesh network, gateway nodes, edge nodes, and P2P communication patterns.

artwork · high confidence

New cryptographic and serialization primitives for records

The record module now includes native NIF-backed implementations for BLAKE3 hashing (macula\_blake3\_nif) and CBOR serialization (macula\_cbor\_nif), replacing or supplementing previous pure-Erlang approaches. The BLAKE3 module provides high-performance content hashing with a deterministic Erlang fallback, while the CBOR module introduces deterministic encoding/decoding compliant with RFC 8949, including strict decoding rules for post-quantum record formats. These primitives support the new signed-object record format (macula\_record) which uses BLAKE3 for content addressing and CBOR for wire serialization, enabling features like monotonic UUIDv7 versioning (macula\_record\_uuid) and strict element budget limits during decoding.

src/record · high confidence

New developer tooling and test vector generation scripts

The repository now includes a suite of new scripts in the \scripts/\ directory to support development, testing, and documentation workflows. These include \are\_markdown\_links\alive.sh\ for validating external documentation links against the Internet Archive, \build-docs-pdf.sh\ for generating professional PDF documentation using Pandoc, and \bump-version.sh\ for synchronizing version numbers across the application source and documentation. Additionally, several scripts (\generate-\-vectors.sh\ and their corresponding Erlang modules) have been added to regenerate deterministic test vectors for UCANs, seal advertisements, station endpoints, and other protocol components, ensuring test consistency across crypto profiles. Supporting scripts for benchmarking post-quantum verification costs, generating QUIC TLS certificates, and running Rust NIF tests are also introduced. Also in this area: 1 commit (0 fixes) modifying scripts; 9 commits (1 fix) modifying scripts; 2 commits (0 fixes) modifying scripts; Updated wire 1.0 vector generation to include schema and lifetime\_class fields.

scripts · medium confidence · unverified

New macula\_bridge module for TCP-to-mesh streaming

Added the \macula\_bridge\ module and its \macula\_bridge\_pump\ helper to bridge unmodified TCP applications across the mesh. The bridge exposes a \serve/5\ API to advertise a local TCP service as a bidi stream procedure and a \listen/4\ API to accept local TCP connections and forward them to that procedure. It handles credit-based flow control, chunked data pumping, and stream lifecycle management, allowing legacy TCP clients and servers to communicate over the Macula mesh without modification. The application version has been bumped to 13.4.0.

src · high confidence

New pool-based client architecture with replication, dedup, and replay

The \src/client\ area now implements a new \macula\_client\ pool that manages peering links to multiple stations, replacing the previous single-link model. This change introduces automatic replication of publish operations across connected links, deduplication of inbound events to prevent duplicates, and subscription replay to restore state after link respawns. It also adds request admission controls to limit resource usage, peer budgeting to cap new connections, and geographic-aware relay discovery for optimized routing.

src/client · high confidence

New pubsub API with callback subscriptions, supervised consumers, and per-publisher ordering

The \src/pubsub\ area introduces a V2 pubsub surface (\macula\_pubsub\) that adds \subscribe\_callback/4\ for stateless event handling via an internal receiver process, and a new \macula\_subscriber\ behavior for building supervised, stateful consumers with \init/1\, \handle\_event/4\, and optional \handle\_unopened/3\ callbacks. To ensure correct delivery, \macula\_pubsub\_order\ provides per-publisher ordering modes (\ordered\, \latest\_only\, \as\_arrives\) that buffer and reorder events based on monotonic sequence numbers, while \macula\_publication\_seq\ manages these counters per signing key. These changes allow users to choose between simple callback-based processing and robust, supervised stateful subscribers, with guaranteed ordering and handling of unopened sealed events.

src/pubsub · high confidence

Post-quantum identity keys and binding infrastructure

The identity subsystem now supports post-quantum cryptography by introducing ML-DSA-87 (FIPS 204) as the primary signature algorithm, implemented via a new Rust NIF (\macula\_crypto\_nif\) for performance-critical hashing and signing. Node keys are stored as 32-byte seeds, and the system enforces strict key hygiene by refusing key files with incorrect permissions and redacting private keys from logs and status reports. New modules manage the lifecycle of these keys: \macula\_node\_keys\ handles generation and persistence, \macula\_key\_bindings\ creates and verifies TLS and CONNECT key bindings to the node identity, and \macula\_statement\_issuer\ periodically issues and rotates these bindings to maintain active status.

src/identity · high confidence

Structured diagnostics and post-quantum peering handshake

This change introduces a structured diagnostics module (macula\_diagnostics) that emits events via OTP logger with a domain filter to prevent silent drops, and implements a post-quantum handshake (version 5) binding proofs to the TLS session's exporter. It also adds a BOLT\#4-style error taxonomy for CALL failures, updates the wire format to deterministic CBOR, and refactors the peering connection state machine to support the new handshake and stream handling.

src/peering · high confidence

Behavioural changes

12 commits (1 fix) modifying src/auth

A change to existing behaviour in src/auth — 12 commits (1 fix), 2 files: “stream authority: hold keyed on the chain root's member, by time only; shared reading bounded”; “stream serving: a gated session ends when the token it was opened with expires”; “fix: a direct dial carries the presented memberships; proofs hashed after the size check; tests leave the rights table to the app (Refs \#128, S1 r1)”; and 9 more (refs \#128, \#127, \#87, \#129).

src/auth · medium confidence · unverified

4 commits (0 fixes) modifying src/audit

A change to existing behaviour in src/audit — 4 commits, 8 files: “audit: the gates a new slice has to pass, and the refusals they exposed (\#175 WP1)”; “audit: the checkpoint's type carries the node its key must match (\#175 WP1)”; “audit: bind the checkpoint to its node, and close the two holes behind it (\#175 WP1)”; and 1 more (refs \#175).

_native/macula\_mri\nif, src/audit · medium confidence · unverified

Build script hard-fails on missing Rust toolchain for critical NIFs

The new priv/build-nifs.sh script ensures that required Rust NIFs (macula\_quic, macula\_crypto\_nif, and macula\_cbor\_nif) are built from source and fail the build immediately if the Rust toolchain is missing, rather than silently skipping and causing runtime errors. It also fixes stale NIF caching by checking source file timestamps against the compiled artifact, ensuring updates are picked up correctly.

priv · high confidence

Introduction of centralized configuration and type definitions

This change introduces new header files to the include directory to standardize application settings and data structures. macula\_config.hrl defines global constants for network timeouts (such as a 30-second QUIC connection timeout), retry limits, DHT parameters, and default ports, while also providing legacy aliases for backward compatibility. macula\_connection.hrl establishes the shared state record for connection management, including fields for peer identification, connection status, and retry delays. Additionally, macula\_quic\_error\_codes.hrl centralizes named QUIC application error codes (e.g., CANCELLED, REFUSED, STREAM\_PROTOCOL\_ERROR) to replace magic numbers in the codebase.

include · high confidence

LAN clustering is now a standalone system with gossip authentication and static node strategies

The \macula\_cluster\_system\ module now provides a dedicated LAN clustering solution that is separate from the mesh distribution system. It introduces two discovery strategies: \macula\_cluster\_gossip\ for zero-config, same-subnet discovery via UDP multicast, which now requires a shared secret of at least 32 bytes to authenticate packets via HMAC-SHA256; and \macula\_cluster\_static\ for connecting to a predefined list of nodes. The system no longer manages Erlang distribution cookies, relying instead on the node's release configuration or environment for authentication. This change allows applications like \bc\_gitops\ to delegate cluster formation to Macula while remaining usable standalone.

_src/macula\_cluster\system · high confidence

Macula overlay replaces Hecate with new HyParView and Plumtree gossip implementations

The overlay layer has been refactored to replace the previous Hecate implementation with a new Macula suite. This introduces \macula\_hyparview\_proto\ and \macula\_hyparview\_view\ for bounded peer-view management, where admission is now gated by verifying realm member endorsements against a trusted realm key ID. The \macula\_plumtree\ module implements push-lazy gossip for realm-scoped publications, while \macula\_realm\_pubsub\ and its registry handle topic subscriptions and event delivery. Additionally, the \macula\_hyparview\_endorsement\ module enforces strict validation rules for join handshakes, including signature verification, realm ID matching, and a 30-day maximum endorsement window.

src/overlay · high confidence

Node-served chunked content sharing and fetching

Content is now served directly by the node that shares it, rather than being stored in the station. This introduces a new chunked content model where large files are split into 256 KiB chunks with a manifest, using SHA-384 for content IDs. Nodes announce their content in the DHT, and fetchers retrieve data directly from the sharer, verifying each chunk against its manifest. Stations act only as relays for these streams.

src/content · high confidence

Post-quantum crypto profiles now define signature policies only, decoupled from key exchange

The \macula\_crypto\_profile\ module now exposes two profiles, \pq\_pure\ (CNSA 2.0 policy) and \pq\_hybrid\ (ML-DSA-87 with RSA-PSS-4096), which strictly declare signature algorithms for TLS and identity proofs. The profile configuration no longer includes or influences the key exchange group; key exchange is handled entirely by the \macula-pqc\ crate (offering SecP384r1MLKEM1024 and SecP256r1MLKEM768), ensuring that the profile name reflects the signature policy rather than the connection's key exchange mechanism. The application requires exactly one profile to be configured to start, refusing to run if none or multiple are specified.

_src/crypto\profile · high confidence

Replaced MsQuic with Quinn Rust NIF for QUIC transport

The native/macula\_quic module has been rewritten to use the Quinn QUIC library instead of the previous MsQuic-based implementation. This change introduces a dedicated Tokio runtime for QUIC operations, implements post-quantum TLS 1.3 handshakes using ML-DSA-87 certificates via macula-pqc, and disables TLS session resumption and early data. It also adds support for certificate reloading on listeners, exposes connection statistics (RTT, congestion window, lost packets), and provides new NIFs for managing dial/stream cancellation and peer leaf verification.

_native/macula\quic · high confidence

Wire protocol switches from MessagePack to deterministic CBOR

The native serialization layer in \native/macula\_cbor\_nif\ has been replaced to use deterministic CBOR (RFC 8949) instead of the previous MessagePack implementation. This change introduces a new Rust-based codec that ensures byte-for-byte deterministic encoding—specifically sorting map keys bytewise and enforcing strict integer/float widths—which is required for signed payloads and compatibility with UCAN/DID standards. The new decoder includes safety limits, capping element counts at 131,072 items and running on a dirty CPU scheduler to prevent blocking, while explicitly handling malformed input as errors rather than crashes. Existing non-deterministic CBOR paths remain available but are distinct from this new deterministic wire format.

_native/macula\_cbor\nif · high confidence

Test coverage

1 commit adding/updating tests in test/fixtures; 3 commits adding/updating tests in test/e2e; Add test configuration for post-quantum crypto profile; Added E2E seal scheme 1 test vector generator; Added consumer contract tests to validate API specs against Dialyzer; Added regression tests for the station link connect watchdog; Added test fixtures for LAMPS composite signature validation; Added test fixtures for cross-SDK frame validation; Added tests for Macula overlay protocol and fleet helpers; Added tests for distribution relay client, bridge, and protocol; Added tests for gossip discovery, static clustering, and cookie isolation; New end-to-end test suite for multi-node mesh scenarios.

Dependencies

New Rust NIF crates for CBOR, cryptography, MRI, and QUIC

The native layer now includes four new Rust crates (macula\_cbor\_nif, macula\_crypto\_nif, macula\_mri\_nif, macula\_quic) that provide Erlang NIF bindings for core mesh capabilities. The CBOR NIF handles wire protocol serialization using ciborium, the crypto NIF implements ML-DSA-87 signatures and hashing via macula-mldsa, the MRI NIF manages resource identifier hierarchies, and the QUIC NIF establishes post-quantum secure connections using macula-pqc and Quinn.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 68 → 66 (-2.1)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 72 → 65 (-6.4)
  • Architecture 96 → 97 (+0.5)
  • Maturity 75 → 78 (+3.5)
  • Readiness 57 → 56 (-1.2)
  • Security 84 → 78 (-5.8)
  • Event Sourcing 100 → 100 (+0.0)
  • Performance 100 → 100 (+0.0)

Resolved (15)

  • Duplicated block (5 lines × 2) (native/macula_quic/src/connection.rs)
  • Duplicated block (6 lines × 2) (native/macula_quic/src/message.rs)
  • Duplicated block (8 lines × 2) (src/client/macula_client.erl)
  • Duplicated block (8 lines × 3) (src/client/macula_client.erl)
  • Duplicated block (9 lines × 3) (src/client/macula_client.erl)
  • FileTooLong: scripts/wire_1_0_vectors.erl (scripts/wire_1_0_vectors.erl)
  • Hotspot: src/client/macula_client.erl (src/client/macula_client.erl)
  • Hotspot: src/macula_dist_system/macula_dist_relay_client.erl (src/macula_dist_system/macula_dist_relay_client.erl)
  • Hotspot: src/macula_stream.erl (src/macula_stream.erl)
  • Hotspot: src/overlay/macula_realm_pubsub_server.erl (src/overlay/macula_realm_pubsub_server.erl)
  • Hotspot: src/peering/macula_handshake.erl (src/peering/macula_handshake.erl)
  • Hotspot: src/peering/macula_peering_conn.erl (src/peering/macula_peering_conn.erl)
  • Hotspot: src/record/macula_record.erl (src/record/macula_record.erl)
  • No ADRs found
  • TooManyFunctions: macula_relay_discovery (src/client/macula_relay_discovery.erl)

New (162)

  • Duplicated block (5 lines × 2) (native/macula_quic/src/connection.rs)
  • Duplicated block (7 lines × 2) (native/macula_quic/src/message.rs)
  • Duplicated block (8 lines × 2) (src/client/macula_client.erl)
  • Duplicated block (8 lines × 3) (src/client/macula_client.erl)
  • Duplicated block (9 lines × 3) (src/client/macula_client.erl)
  • Edited copies of one member (3 members, 11+ corresponding lines) (src/client/macula_station_link.erl)
  • Edited copies of one member (3 members, 16+ corresponding lines) (src/macula_pusher.erl)
  • Edited copies of one member (3 members, 2+ corresponding lines) (src/macula_pusher.erl)
  • Edited copies of one member (3 members, 3+ corresponding lines) (src/auth/macula_realm_rights.erl)
  • Edited copies of one member (3 members, 3+ corresponding lines) (src/macula_publisher.erl)
  • Edited copies of one member (3 members, 3+ corresponding lines) (src/macula_response.erl)
  • Edited copies of one member (3 members, 3+ corresponding lines) (src/peering/macula_handshake.erl)
  • Edited copies of one member (3 members, 4+ corresponding lines) (src/client/macula_client.erl)
  • Edited copies of one member (3 members, 4+ corresponding lines) (src/macula_direct_dial.erl)
  • Edited copies of one member (3 members, 5+ corresponding lines) (src/macula_publisher.erl)
  • Edited copies of one member (3 members, 5+ corresponding lines) (src/peering/macula_frame.erl)
  • Edited copies of one member (3 members, 5+ corresponding lines) (src/peering/macula_frame.erl)
  • Edited copies of one member (3 members, 6+ corresponding lines) (native/macula_quic/src/connection.rs)
  • Edited copies of one member (3 members, 7+ corresponding lines) (native/macula_quic/src/connection.rs)
  • Edited copies of one member (3 members, 7+ corresponding lines) (src/macula_stream_sink.erl)
  • …and 142 more

Changes since last survey

  • 39 commits — 34 feature/other, 5 fixes

By area

  • (root) — 16 commits
  • docs/design — 6 commits
  • src/audit — 4 commits
  • src/client — 3 commits
  • (repo) — 2 commits
  • src/auth — 2 commits
  • test/macula_admission_reply_delivery_tests.erl — 2 commits
  • test/macula_client_tier_pool_tests.erl — 2 commits
  • src/peering — 1 commit
  • test/macula_content_sharer_tests.erl — 1 commit

Notable commits

  • fix: fix(pubsub): a link that lost liveness says so, not drained (Refs macula-io/macula-station#129)
  • fix: fix: a call's UCAN and a membership token show nowhere a status is read (#192) (#194)
  • fix: fix: a counter write survives a missing table, across all three peering counters (#186, folds #187) (#188)
  • fix: fix: a re-join's rotated token is the one later pulls present (#190) (#193)
  • fix: fix: redact a group's admission UCAN by name (#189) (#191)
  • change: CHANGELOG: a signed body names only stations on its signer's tier (macula#201)
  • change: Drive the tier rules through the pool, where they are used (macula#201)
  • change: Link info names its tier: update the three pool stubs that predate it (macula#201)
  • change: Merge origin/main (28f2754, v18.2.0) into ceres/176-k1-sealed-key
  • change: Re-arm a tier's pending retries when it becomes the live one (macula#201)
  • change: Re-arm an unconfigured seed's retry too, not only a configured one (macula#201)
  • change: SECURITY.md: response times, attachment and identity rules, drills (macula-io/macula#174)
  • change: Station tiers: public and fallback lists, measured-RTT ranking, redial backoff (macula#201)
  • change: Tier pool tests: the frame relay ends with its link (macula#201)
  • change: audit: bind the checkpoint to its node, and close the two holes behind it (#175 WP1)
  • change: audit: the chain, its checkpoints, the verifier and the JSON-lines export (#175 WP1)
  • change: audit: the checkpoint's type carries the node its key must match (#175 WP1)
  • change: audit: the gates a new slice has to pass, and the refusals they exposed (#175 WP1)
  • change: chore: Release v18.1.0
  • change: chore: Release v18.1.1
  • …and 19 more

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

macula-io/macula was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 15 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit c297ea08841ea14b0447f671880204aa5399b05a — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-3c33c1882dc1.