Diablo_Rain/synos-public-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: hybrid pivot — vague the issue-bait surfaces, keep specifics on product

Browse Source 
Front-door + product-surface files (README, GRIMOIRE, FEATURES,
FOR_RECRUITERS) keep their concrete v60 content — these are the pages
that need to project ambition and inform potential users / cohorts /
recruiters.

Three files trimmed to vague:

- ARCHITECTURE.md — drop syscall numbers (469-485), specific module
  names, "11-region brain", "83.54% Rust", "8-node Tailscale mesh".
  Keep the synaptic gap framing, four pillars by name, three-image
  table, axioms. Specs invite "well actually" issues; philosophy
  doesn't.
- ROADMAP.md — keep v60 as the current generation marker, drop the
  v44–v60 codesprint table (16 codenamed campaigns is a lot of
  fact-checkable claims), drop the explicit v61–v70 horizon bullets.
  Replace with broad theme prose. "What we're heading into" rather
  than "what we promise by when".
- CONTRIBUTING.md — drop the explicit "what's coming" promises (lab
  marketplace, CVE channel, community calls, public source release
  date). Drop the "open an issue with title X" workflows that invite
  unbidden submissions. Keep the long-game framing and quiet-channels
  posture.

Net: front-door pages still impress with specifics; the surfaces a
random reader might use to file noise issues now offer none of the
hooks for it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
ShellDiablo33 2026-05-09 13:48:52 -04:00
parent e870d388cb
commit 05f9a0683c
No known key found for this signature in database
GPG Key ID: 8019DF7A5C73BB5A
3 changed files with 72 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
ARCHITECTURE.md
View File

@ -1,6 +1,6 @@
# Architecture
### *biological in inspiration. rigorous in implementation. v60.0.0 "Sun & Salt".*
### *biological in inspiration. rigorous in implementation.*
---
@ -11,94 +11,75 @@ The design philosophy starts with a metaphor and refuses to let it become decora
Syn_OS treats the operating system itself as the synaptic cleft.
```
Pre-synaptic neuron = Hardware
Synaptic cleft = Syn_OS (kernel + userspace + ALFRED)
Post-synaptic neuron = Application consciousness (ALFRED decisions, user processes)
Neurotransmitters = System calls (469–485)
Receptors = Syscall handlers
Synaptic plasticity = Adaptive kernel module behavior + ALFRED's learning loops
Hardware → pre-synaptic firing
Syn_OS (the OS itself) → the synapse
Application + intent → post-synaptic decision
```
This is not branding. It's the framing every architectural decision is checked against.
This is not branding. It's the framing every architectural decision is checked against. *Where in the gap does this live? What does it translate from, and what does it translate into?*
---
## the four pillars
The system rests on four load-bearing components, each genuinely irreplaceable in the design.
### the kernel
A custom Linux 6.19 build with `CONFIG_RUST=y` and **17 custom system calls** (469–485). The syscalls expose:
| Range | Purpose |
|---|---|
| **469–479** | Consciousness state, quantum memory entanglement, AI metrics, eBPF monitor control |
| **480–485** | Kernel observability, perf instrumentation, process attestation, snapshot, twin |
The kernel ships **11 loadable Rust kernel modules** covering memory, networking, hardening, interrupts, modloader, procfs, power, consciousness, and module verification. After the v56 Rust Ratchet, the kernel hot path is **83.54% Rust** by line count. KSPP hardening fragment merged. Module signing wired through MOK keys generated at build time.
A custom Linux build with significant Rust integration — not Linux-with-Rust-bolted-on, but Linux taking the rust-in-kernel work seriously. Memory-safe modules where memory safety matters most. A deliberate library of system calls that lets userspace ask the system about itself in ways a vanilla kernel cannot. The kernel is not a black box — it's an active participant in the system's awareness of itself.
### ALFRED
The Adaptive Learning Framework for Responsive Evolution and Defense. ALFRED is the AI daemon — not a chatbot, but the operator's companion at the system level.
- **11-region neuroanatomical brain.** Modeled loosely after biological structure: thalamus (gating), amygdala (threat detection), hippocampus (memory), insula (interoception), cerebellum (coordination), corpus callosum (interhemispheric routing), default mode network (idle synthesis), glial (support), brainstem (orchestration), nucleus, plus the consciousness-types crate that ties them.
- **Cortex stage** fuses traditional AI, neuromorphic spike networks, quantum coherence collapse, and Edelman's Theory of Neuronal Group Selection (TNGS) into a single decision pipeline.
- **Local inference** via Ollama and ONNX. No cloud in the critical path.
- **BrainBridge** consumes `AlfredSignal` events from kernel telemetry into the cortex. The kernel and the daemon talk through the syscall surface.
The operator's companion. A local AI daemon that runs on the box, not in the cloud. Modeled loosely after the structure of a biological brain: many small specialized regions, each with a job, coordinating through a central conductor. ALFRED watches the system, anticipates the operator's loop, surfaces context when context is what's missing. It does not phone home.
### GRIMOIRE
The gamified cybersecurity training platform — 100 labs, 13 categories, faction system, XP economy, boss contracts, branching narrative, cohort competition. Covered in detail in [GRIMOIRE.md](./GRIMOIRE.md).
The gamified cybersecurity training surface — the public face of the platform, covered in detail in [its own document](./GRIMOIRE.md). GRIMOIRE turns cybersecurity practice into a world worth living inside. Factions, labs, boss contracts, economy, narrative. The training arc that takes a novice to an operator and means it.
GRIMOIRE is the public face. It's what the GRIMOIRE Public ISO ships. It's the apprenticeship surface for the entire community we're building.
### the mesh
### the mesh — Arcanum Hive
When the system extends across hardware, it does so as the Arcanum Hive: an 8-node Tailscale mesh coordinated by a Kubernetes operator. Per-tenant HMAC. mTLS by default. Sovereignty as a design property, not a marketing claim.
The Hive Stoneglass GA playbook (v55) is the public-facing self-hosting recipe. The hive is yours to extend.
When the system is ready to extend, it does so as a mesh — encrypted, peer-to-peer, sovereign. Multiple machines, owned by you, talking to each other on terms you set. The mesh is where the platform stops being a single laptop and becomes infrastructure.
---
## the three-image strategy
Syn_OS is built once and ships in three signed ISOs from a single source tree.
Syn_OS is built once and ships in tiers. The split exists because the audiences are genuinely different.
| Image | Audience | License |
| Image | Audience | Posture |
|---|---|---|
| **Operator (Master)** | The team. Internal. | Proprietary, not distributed publicly |
| **GRIMOIRE Public** | Students, cohorts, practitioners | Apache 2.0 + LicenseRef-GRIMOIRE-Public |
| **Goodlife** | AI researchers, post-quantum, civilian work | Apache 2.0 |
| **Operator** | The team that builds Syn_OS. Internal. | The full surface. Not distributed publicly. |
| **GRIMOIRE Public** | Students, cohorts, self-taught practitioners. | The training platform — same world, gated tooling. |
| **Goodlife** | AI researchers, post-quantum experimenters, civilian work. | Research-oriented defaults. AI tooling. Civilian-safe. |
Capability boundaries between images are **mechanically enforced** — by binary symbol scanning, feature flag audits, lab integrity manifests, and supply-chain provenance checks. The mechanism is part of the architecture, not bolted on.
The boundaries are enforced. What ships in each image is what was meant to ship. The mechanism is mechanical, not honor-system.
---
## the substrate
Below the four pillars sits the engineering work that makes the higher-level vision viable:
Below the four pillars, there's a substrate of practical engineering work that makes the higher-level vision viable. None of this is glamorous. All of it is required:
- **160-crate Rust workspace** with zero compile errors. `cargo check --workspace` passes; `cargo deny` clean.
- **Toolchain pinned** at `nightly-2026-02-12` (rustc 1.95.0-nightly).
- **41-stage self-healing build pipeline.** Producing the three images is a multi-hour process that recovers from individual stage failures without losing the whole run. SLSA-3 reproducible build target. Dual-witness signature support across mesh nodes.
- **Test infrastructure.** 1,600+ tests. 100% pass rate. 35% tarpaulin coverage floor. Continuous integration across 17 workflows (5 ubuntu-latest, 12 self-hosted).
- **Post-quantum cryptography.** ML-KEM (key encapsulation), ML-DSA (signatures), SLH-DSA (hash-based signatures) integrated into the trust toolkit.
- **Cosign + Rekor** signing path for ISO releases. Sigstore transparency log entries. Verifiable provenance from build oracle to USB stick.
- **MkDocs Material documentation** site, version-aware, fact-checked against the source tree.
- **Rust everywhere it makes sense.** The bulk of the system is memory-safe code.
- **A self-healing build pipeline.** Producing the images is a multi-stage process that recovers from individual failures without losing the whole run.
- **Post-quantum cryptography in the toolkit.** Built for the cryptographic transition that's already underway.
- **Reproducible builds and signed releases.** Verifiable provenance from build to delivery.
- **Documentation that takes itself seriously.** Living documents, version-aware, checked against the codebase.
---
## design axioms
Three axioms applied recursively:
Three axioms, applied recursively:
1. **The synaptic gap is real.** Hardware is not the OS. The OS is not the application. The OS is the gap, and the quality of the system is the quality of that translation.
2. **Memory safety where it matters.** The Rust ratchet is a one-way commitment. Kernel hot paths and userspace foundations move toward Rust, never away.
3. **Tiers are mechanical.** Capability boundaries between Operator, GRIMOIRE Public, and Goodlife images are enforced by the build, not by goodwill.
2. **Memory safety where it matters.** Where Rust earns its keep, Rust earns its keep.
3. **Tiers are mechanical.** Capability boundaries between images are enforced by the build, not by goodwill.
---
## further reading
The deeper architectural surface — full kernel internals, ALFRED's brain crate topology, mesh authentication and rotation mechanics, the master-only capability set — lives with the source. The public-facing pillars described here are the shape of the system.
The deeper architectural surface — kernel internals, AI daemon mechanics, mesh authentication, build pipeline — lives with the source. The shape described here is the public-facing pillars.
The shape is enough to know whether the rest will interest you.

88
CONTRIBUTING.md
View File

@ -1,89 +1,27 @@
# Contributing
### *the long-arc community we're building, and how to join it.*
---
# A note for those interested in contributing
Syn_OS is built on the premise that **security is a craft**, and crafts are sustained by communities — not consumers. The community we want around this project is the kind that takes the craft seriously, that can hold a long arc, and that contributes from a place of mastery.
This document describes how to participate today, and what we're building toward.
---
## current state of contribution
The Syn_OS source tree is private. The boundaries between the three images (Operator, GRIMOIRE Public, Goodlife) are still being formalized in ways that affect how external contribution surfaces are exposed. We're being deliberate about opening doors.
Right now, the team is small and the substrate is still solidifying. The boundaries between the public-facing images and the internal one are still being formalized in ways that affect how external contribution surfaces are exposed. We're being deliberate about opening doors.
That said, **doors are not closed**. They are narrower than they will be.
---
## what we welcome today
## if you're interested in following along
### feedback on public-facing documentation
The repository you're reading right now is the project's first impression on the world. If something here is unclear, misleading, or wrong, we want to know. **Open an issue on this repository.** Documentation issues are the one category of community contribution that we have an immediate place for.
### conversations with practitioners
If you're a cybersecurity practitioner, security researcher, kernel engineer, AI/ML systems engineer, or game/training designer — and Syn_OS resonates with the kind of work you'd want to do — we want to know who you are.
We are building a platform that lives or dies by the practitioners around it. The earliest conversations shape the work most.
### lab proposals for GRIMOIRE
GRIMOIRE's 100-lab corpus is hand-authored. As the cohort programs scale, we'll be running curated lab-contribution programs. If you have a specific lab — a real-world scenario, a teaching arc, a vulnerability reproduction with educational depth — we'd be glad to evaluate it.
Open an issue with the title `Lab proposal:` and a one-paragraph description. We'll respond.
### cohort partnerships
If you run a class, a security club, a CTF team, or a corporate training program, and you're interested in piloting GRIMOIRE in a cohort context — open an issue with the title `Cohort partnership:` or reach out through the channels that emerge as the program matures.
The most useful thing you can do today is **watch this repository**. When the chapters change, the documents change with them. New capabilities, new directions, new opportunities to participate — they'll show up here first.
---
## what's coming
## conversations we welcome today
### public source release for the GRIMOIRE Public image
There are a few categories of input we genuinely value, even at this stage:
When the GRIMOIRE Public ISO ships, the source tree carrying the **public profile** will be open. The license is mixed Apache 2.0 + LicenseRef-GRIMOIRE-Public. At that point, full PR-and-issues contribution will be possible against the public surface.
- **Stories about the kind of platform you wish existed.** We're building one. Hearing from people who would actually use it, what they'd want from it, and what they'd push back on — that shapes the work.
- **Quiet conversations.** If you're a practitioner who'd want to participate in deeper development or cohort programs as those mature, we want to know who you are. Watch for channels as they open.
### GRIMOIRE lab marketplace
We're building infrastructure for community-contributed labs to be reviewed, signed, and distributed. Authors get attribution. The integrity manifest enforces quality.
### public CVE / advisory channel
When the GRIMOIRE Public + Goodlife ISOs are publicly distributed, we will operate a coordinated disclosure channel. Until then, security issues found in pre-release artifacts can be reported through the channels noted below.
### community calls and roadmap input
As the cadence of public releases stabilizes, we will run regular community calls — roadmap walk-throughs, design discussions, lab clinics. Watch this repository for announcements.
---
## what we're not yet ready for
- **Forks-and-PRs against the source tree at scale.** The repository carrying the source is private, and the boundaries between what's public and what's internal are still being formalized. External contribution to source becomes available with the public ISO releases.
- **A general-purpose issue tracker for the source repo.** The private repo's issues are internal-only. Once the public ISOs ship, public issues attach to the public source.
None of this is permanent. All of it is "not yet."
---
## code of conduct
Crafts thrive in communities of mutual respect. Discussion in this project's spaces — issue trackers, future forums, future community calls — operates under a posture of: **assume good faith, push back hard on the work, never on the person.**
A formal code of conduct document will be published alongside the public source release. The norms above are the ones we're building toward.
---
## reporting security issues
If you've identified a security issue in any artifact released by this project, please **do not file a public issue**. Instead, open a coordinated disclosure: open a private security advisory through the GitHub interface (or through the channels published with each ISO release).
We respond. We coordinate. We credit researchers in our advisory pages.
For now, those conversations happen privately. As the project matures, the channels will become more public. We're not in a hurry to lower that bar before the bar is ready.
---
@ -93,4 +31,10 @@ This project is built on multi-year time horizons. The community we want around
---
For the earliest possible signal as channels open: watch this repository. Star it if you're interested. The cadence of changes here tracks the cadence of the project.
## a brief word on security disclosure
If you're a researcher who's identified a security issue in any artifact released under this project's name, please reach out through coordinated channels rather than filing it publicly. We'll respond. We'll coordinate. We'll credit. The specific channels will be published alongside each public release.
---
If any of this resonates, the best thing to do is stay close. The cadence of changes here tracks the cadence of the project.

105
ROADMAP.md
View File

@ -1,91 +1,42 @@
# Roadmap
# Direction
### *what's shipped, what's imminent, what's the long game.*
### *what's shipped, where we're heading.*
---
## v60.0.0 "Sun & Salt" — current
## what's already in the platform
The first ISO carrying the full v44 → v60 codesprint. Sixteen versions of compounding work fused into one signed release.
The current generation of Syn_OS — **v60 "Sun & Salt"** — is the product of a sustained, multi-year build. The system that exists today carries:
**What v60 brings:**
- SBOM (CycloneDX) drift detector across builds
- IPO readiness self-test — institutional-grade audit pass
- External blocker playbook for cosign + cross-oracle ceremonies
- All v44–v59 features merged into a single coherent release surface
- A custom Linux kernel with deep Rust integration and a deliberate system-call surface for AI/observability.
- A local AI daemon — codename **ALFRED** — modeled after the structure of a biological brain.
- The **GRIMOIRE** gamified training platform with a hand-authored lab corpus, faction system, narrative quests, and a long arc from novice to sovereign operator.
- An integrated game engine surface for the parts of the user experience that benefit from one.
- A distributed mesh capability for those ready to extend the system across multiple machines.
- Post-quantum cryptography woven through the trust toolkit.
- A self-healing build pipeline producing signed releases with verifiable supply-chain provenance.
The work to get here was coordinated across many named campaigns, each adding a load-bearing piece to the platform. The compounding effect is what v60 represents.
---
## the v44 → v60 codesprint, shipped
## what's coming
| Codename | What landed |
|---|---|
| **v44 Crucible** | Fuzz harness, attest LSM, observability kernel, rebuild-verify CI |
| **v45 Glasswalker** | Kernel observability syscalls 480–485 (now 17 total) |
| **v46 Beachhead** | Process attestation HMAC ledger + LSM hooks |
| **v47** | License gate, audit HMAC chain, CSV/EVTX/syslog exports |
| **v48 Forge** | Sigstore Rekor + SLSA-3 reproducible builds |
| **v49 Crystal Net** | Federation server (mTLS + per-tenant HMAC) |
| **v50 Tenfold** | RaaS engine, billing integration, LLM red-team harness |
| **v51 Storm Glass** | TwinPlugin (8th synos-bevy plugin) + kernel-snapshot |
| **v52 Riftrunner** | In-kernel safe-bytecode VM |
| **v53 Quantumweave** | synos-cortex-q tensor-network ML |
| **v54** | Capability tokens (synos-curtain-tokens) |
| **v55 Stoneglass** | Hive Ansible deploy (8-node GA playbook) |
| **v56** | Rust ratchet — kernel hot-path Rust at 83.54% |
| **v57 Phoenix Eye** | LLM red-team |
| **v58 Stagehand** | Classroom + cohort + instructor mode |
| **v59 Doublecross** | FedRAMP Moderate control map + daily ConMon |
| **v60 Sun & Salt** | SBOM drift detector + IPO readiness self-test + external blocker playbook |
Syn_OS is heading into a phase of **public release**. The platform has been validated internally for long enough; the next chapter is opening it to the practitioners we've been building it for.
Some of these features are master-internal — the codesprint shipped capability across all three images, but the surface visible in each varies by license tier. The public ISOs (GRIMOIRE Public + Goodlife) carry their full intended share of the work.
Broad themes, in rough order of when they mature:
- **Public-facing ISO releases** — the GRIMOIRE training image and the AI-research variant, signed and verifiable, distributed through channels suited to a serious cybersecurity audience.
- **Cohort programs** — multi-tenant deployments for classes, clubs, security teams, and training programs that want a real platform under their curriculum.
- **Deeper AI augmentation** — the companion daemon does its job today; we have a long list of ways it could do more.
- **Continual GRIMOIRE content waves** — new labs, new boss contracts, new narrative arcs, new factions over time. The world deepens.
- **Easier mesh adoption** — the distributed parts of the platform have power; we're working on the parts that make them feel inevitable rather than effortful.
We don't ship a public roadmap with dates. Calendars lie, and we'd rather be honest. The directions above are real. The cadence at which they arrive is whatever the work requires.
---
## imminent — public ISO releases
The work toward public distribution is in flight.
- **GRIMOIRE Public ISO** — the gamified training platform, signed with cosign, anchored in Rekor, distributed publicly. First-boot wizard, faction selection, 100-lab corpus, full game engine, integrity-manifest enforcement.
- **Goodlife ISO** — the AI research variant. Jupyter, ALFRED `research-mode`, post-quantum experimentation toolkit, LUKS-encrypted research data.
- **Cohort program v1** — multi-tenant GRIMOIRE deployments for classes, clubs, and security teams.
- **Public Sigstore + Rekor** — verifiable supply chain from build oracle to USB stick.
- **Hive expansion playbook** (Stoneglass GA) — public Ansible recipe for self-hosting the 8-node Arcanum Hive.
These are not "someday" items. They're what the team is heading into next.
---
## near-term themes
**Tightening what exists.** The platform has been evolving fast. The next chapter sands every rough edge — onboarding, documentation, error messaging, first-boot polish, the unglamorous work that makes the user-visible improvement.
**Deeper AI augmentation.** ALFRED does its job today. There's a long list of ways it could do more — context, anticipation, usefulness in the operator's actual loop. v61–v65 carries that work forward.
**Continual GRIMOIRE content waves.** New labs. New boss contracts. New narrative arcs. New factions, possibly. Cohort tooling, definitely. The world deepens with every release.
**Mesh, made easier.** Distributed-by-default sounds simple in a sentence and is harder in practice. We're working on the parts that make a mesh feel inevitable rather than effortful.
---
## medium-term — the v61–v70 horizon
Themes we're paying attention to, in rough priority order:
- **Public release cadence** — predictable, signed, transparent. ISOs every cycle.
- **Cohort programs at scale** — clubs, classes, training programs running on shared GRIMOIRE infrastructure.
- **AI capability ladder** — bigger models, smarter routing, deeper integration with the kernel observability surface.
- **Reproducible builds in production** — every public ISO byte-for-byte reproducible by an independent verifier.
- **Federation between independent operators** — Hive-to-Hive, with cryptographic identity and permissioned visibility.
- **Curriculum partnerships** — formal mappings between GRIMOIRE progression and academic / industry training.
- **Hardware diversity** — supported architectures beyond x86_64.
- **Mobile companion** — read-only operator dashboard for on-the-go awareness.
Specific version numbers attach to specific deliverables as we get closer. Today's roadmap is themes; tomorrow's commit log is the truth.
---
## long-term — the north star
## the long arc
The end-state we're moving toward is a platform where the operator owns their infrastructure, their intelligence, and their future — not in a slogan, but **mechanically, cryptographically, architecturally**. The pieces are there. The work is in fitting them together with the polish, the trust, and the longevity that an operating system deserves.
@ -97,12 +48,12 @@ The roadmap reflects that.
## what isn't on this roadmap
The Operator (Master) image's internal feature trajectory. It exists. It evolves alongside the public roadmap. It is not for public distribution and is not part of this document by design.
The internal Operator image's feature trajectory. It exists. It evolves alongside the public roadmap. It is not for public distribution and is not part of this document by design.
If a master-internal capability ever crosses the boundary into a public image, it shows up here.
Specific dates. Specific version numbers for things that haven't shipped yet. Promises that read better in marketing than they do six months later. The work happens at the pace it happens.
---
## how to follow
The work happens in public, in this repository's metadata and in the cadence of releases. Watch this repo. When the chapters change, the documents change with them.
Watch this repository. When the chapters change, the documents change with them. The work is the work. The story will keep updating as it unfolds.