Synapse

Synapse is AIEN's high-throughput, agent-native changeset and integration service with deterministic Git object materialization and Radicle canonicality verification (aien-spark/aien-sovereign-core#515).

Direction (2026-10-14): Synapse is becoming the new Git for AI: source control for AI agents only, built from the best ideas of every system, with Git kept as a small machine bridge for import, export, and existing tooling (ADR 0002, tracked in aien-spark/synapse#8).

Architecture Overview

Synapse accelerates the high-frequency multi-agent inner loop (changeset creation, virtual tree/diff inspection without working-tree checkout, test evidence attachment, conflict detection, and integration queueing) while enforcing three non-negotiable boundaries:

1. Git Compatibility: Accepted changesets deterministically materialize into standard Git blob, tree, and commit objects compatible with git fsck, git clone, and git fetch.
2. GitHub Human Projection: Human review projections (GitHubPullRequestProjection) publish compact summaries and evidence digests without uploading bulky machine logs or silently force-moving human branches.
3. Radicle Canonical Authority: Fast WAL ingest order (WalSeq) and GitHub PR state never confer authority to advance canonical branches. Canonical promotion (RadicleCanonicalHead) requires cryptographic verification of refs/rad/id and refs/namespaces/<nid>/refs/rad/sigrefs against the repository's delegate quorum threshold.

Workspace Crates

Crate	Gate	Responsibility
synapse-core	Gate 0	Distinct identity types (ChangesetId, BlobDigest, GitOid, RadicleCanonicalHead, GitHubPullRequestProjection, IdempotencyKey, WalSeq), ChangesetEnvelope v1, did:key Ed25519 verification, and RefusalCode taxonomy
synapse-store	Gate 1	Single-writer append-only WAL (SWAL v1) with CRC32C and SHA-256 hash chain, configurable fsync policy, content-addressed blob store, checkpoint compaction, GC, and crash fault injection
synapse-auth	Gate 2	Ed25519 capability grants (Read, Propose, Evaluate, Review, Publish), expiry/replay guards, rate/size quotas, and hash-chained security audit log
synapse-api	Gate 2	Bounded paginated API (submit, get, diff, tree, history, provenance, conflicts, status, watch), checkout-free virtual tree overlay, and exact path-index invalidation
synapse-git	Gate 3	Deterministic Git loose object writer/reader, bidirectional ChangesetId <-> GitOid map, ref namespace separation, and GitHub PR projection builder
synapse-radicle	Gate 3	Radicle refs/rad/id and refs/rad/sigrefs Ed25519 delegate threshold verifier and split-brain refusal engine
synapse-bench	Gate 4	Comparative qualification harness (Synapse ingest and checkout-free queries versus Git worktree and Git plumbing workflows) plus WAL, Git materialization, and Radicle canonicality conformance suites

Documentation and Evidence

• Domain Glossary (CONTEXT.md)
• ADR 0001: Synapse Architecture, Owning Boundary, and Compatibility Invariants
• ADR 0002: Synapse-First Source Control for AI Agents, with Git as a Bridge
• Gate 0 Reality Check Audit and Reproducible Baseline
• Threat Model and Capability Permission Matrix
• Changeset Schema, WAL Format, Consistency, and GC Specification
• Gate 0 Empirical Baseline Receipt (evidence/gate0-baseline/)
• Gate 4 Comparative Qualification Report
• Gate 4 Qualification Evidence (evidence/gate4-qualification/), reproduced with scripts/run_gate4_qualification.sh
• Spark verification gates (docs/PIPELINE.md): the interop and Gate 4 scripts honour CARGO_TARGET_DIR, so SYNAPSE-CONFORMANCE runs the same on the Spark as in a plain checkout

License

Licensed under the Apache License, Version 2.0 (Apache-2.0).