HEAV3NS-Publishing

The Sovereign Creator Monetization Engine & Autonomous Persona Platform
High-Assurance Rust (Axum 0.7 + PostgreSQL & SQLite WAL) · Next.js 16 (React 19 + Turbopack) · Joyzoning 100% Sovereign Architecture

The Mission & Gravity · The What, How & Why · Onboarding Strategy · 60s Quickstart · System Architecture · Creator Economics · AI & MCP · Verification · Docs Hub

🎯 The Mission & System Gravity

Digital publishing and creative community platforms sit at the fragile nexus of artistic expression, private community trust, and high-assurance financial custody. Over the past two decades, the creator economy has grown into a $250B+ global industry, yet it remains anchored to an exploitative, centralized architecture.

Corporate platforms (OnlyFans, Patreon, Substack, YouTube, Twitch) have breached their social contract with creators through systematic rent-seeking, opaque censorship, and structural security negligence:

The Legacy Crisis: The Broken Social Contract

Dimension	Legacy Web2 Creator Platforms (The Exploitative Contract)	HEAV3NS-Publishing (The Sovereign Contract)
Platform Take Rate	Confiscatory 20% to 50% fees; arbitrary ad-revenue share shifts, opaque platform deductions, and hidden payment processing surcharges.	Immutable 85% Creator / 15% Platform split; calculated and settled atomically inside database transactions.
Payout Liquidity	14 to 30-day payout freezes; creator revenues held as interest-free corporate float, subject to arbitrary account freezes without legal recourse.	Instant wallet liquidity upon purchase; immediate withdrawal balance escrow with automated refund safeguards on payout rejection.
Paywall & Content Security	Porous client-side paywalls; raw JSON payloads transmit cleartext captions, comments, and media URLs hidden behind superficial CSS blur filters.	Zero-leak serialization boundary; text, comments, polls, media file paths, and HLS streams are cryptographically redacted before wire transmission.
Audience Ownership	Algorithmic hostage-taking; feeds artificially throttle creator reach to coerce creators into paying for sponsored reach or paid boosts.	Unmediated audience custody; open vs. paid profiles, custom fan lists, scheduled releases, and direct broadcast messaging without algorithmic suppression.
Infrastructure Overhead	Cloud microservice bloat; 10+ fragile Docker containers, Kafka, Redis clusters, and multi-thousand dollar monthly cloud hosting bills.	Radical mechanical sympathy; compiled into a single high-performance Rust binary with embedded SQLite WAL + pooled 16-shard PostgreSQL.
Autonomous AI Agency	Hostile scraping & bans; AI agents treated as adversarial scrapers, or superficial chatbots tacked on without financial guardrails.	First-class sovereign AI agency; Model Context Protocol (MCP 2024-11-05), No-Inference Autonomous Persona Studio, and hardware spend caps.

The Systemic Gravity: Why Sovereignty Is Non-Negotiable

Economic Sovereignty: When platforms extract 20% to 50% of gross creator revenue and hold balances hostage for weeks, creators are not platform partners—they are digital sharecroppers. HEAV3NS-Publishing guarantees that 85 cents of every gross dollar settles instantly in the creator's wallet.
Cryptographic Privacy & Intellectual Property: In modern creator spaces, a paywall leak is not merely a loss of revenue—it is an existential violation of creator dignity, fan privacy, and sensitive personal information. Security cannot be delegated to client-side presentation code. Unprivileged bytes must never cross the network serialization boundary.
Operational Resilience & Local-First Sympathy: A system that cannot be verified locally in seconds cannot be audited, secured, or trusted. By pairing an embedded SQLite WAL engine (running 14 complete integration test suites in < 0.5s) with a production 16-shard PostgreSQL cluster, HEAV3NS-Publishing proves that enterprise-grade capability does not require cloud-microservice fragility.
The Convergence of Human Creators & Autonomous Agents: As generative AI evolves, creators must not be replaced by closed-source foundation models. Instead, creators must possess sovereign tools to deploy, train, supervise, and economically meter their own autonomous AI personas on the same auditable ledger.

🧭 The What, How, and Why

To comprehend the full scope of HEAV3NS-Publishing, evaluate the platform through three rigorous lenses: what it delivers, how its mechanics operate, and why its invariants are inviolable.

1. WHAT: The Sovereign Publishing & Monetization Suite

HEAV3NS-Publishing delivers an end-to-end, full-stack creator platform combining sovereign creator tools with native autonomous agent infrastructure:

6 Unified Monetization Primitives:
- Tiered Subscriptions: Creator-configured 1m, 3m, 6m, and 12m bundles with automated promotional discount campaigns (creator_offers).
- Pay-Per-View (PPV) Posts: Locked feed posts with server-side media and comment redaction.
- Pay-Per-View (PPV) Video Reels: Short-form vertical video feed (/reels) with paywalled playback.
- Pay-Per-View (PPV) Direct Messages: Locked media attachments in 1-on-1 and broadcast chats.
- VIP Live Stream Access: Ticketed and subscriber-only HLS/RTMP live video broadcasts (/my/streams).
- Direct Creator Tips: In-chat, on-post, on-stream, and profile tipping with instant settlement.
5 Comprehensive Media Publishing Formats:
- Rich feed posts with interactive multi-choice polls and Media Vault attachments.
- Short-form vertical video Reels with full-screen playback.
- 24-hour ephemeral Stories with permanent profile Story Highlights.
- Low-latency RTMP ingest and HLS live video broadcasting with subscriber chat.
- 1-on-1 Direct Messaging and mass subscriber Broadcast DMs.
Autonomous AI Agency via Model Context Protocol (MCP 2024-11-05):
- 32 standardized MCP tools for programmatic publishing, tipping, unlock purchasing, and persona evolution.
- 6 dynamic resources exposing profile telemetry, wallet ledgers, and 16-shard metrics to LLM tools.
- 3 structured prompts guiding autonomous agent workflows (publishing, community engagement, ledger auditing).
No-Inference Autonomous Persona Studio (/my/agents):
- Run multi-persona agent swarms without incurring server-side GPU inference costs.
- Deterministic execution brief compilation, numbered practice revisions, and multi-agent swarm batch coordinator (POST /api/agent/swarm/batch).
Creator Workstation Ergonomics:
- Universal ⌘K / Ctrl+K Command Palette navigating all 26 App Router views.
- Centralized Media Vault (/my/vault) allowing creators to upload once and attach everywhere.
- Member referral engine ($5.00 referrer / $2.50 registrant welcome reward).
- Printable, tax-compliant PDF/HTML invoices (/invoices/[id]).

2. HOW: Architectural Mechanics & Mechanical Sympathy

HEAV3NS-Publishing is engineered from first principles under strict architectural sovereignty:

Joyzoning 5-Zone Sovereign Decomposition (ADR-009):
- Source code is strictly partitioned into DOMAIN (0% I/O entropy), CORE (orchestration), INFRASTRUCTURE (concrete adapters), PLUMBING (stateless leaf helpers), and UI (presentation).
- Contractual Sovereignty: Pure trait contracts in domain/interfaces/* (IAuthProvider, ILedgerProcessor, IMediaVault, IMessagingDispatcher, IQuotaPolicy, IShardedRepository, ISwarmCoordinator) eliminate Martin's Zone of Pain.
Domain-Driven Design (DDD) Bounded Contexts (ADR-008):
- 75+ REST and MCP route handlers organized across 9 isolated domain contexts under backend/src/core/handlers/ (identity, content, discovery, social, messaging, monetization, media, governance, platform).
Dual-Engine Persistence Strategy:
- Embedded SQLite WAL: Zero-config local development and blazing-fast in-memory test execution (14 suites verify the entire system in < 0.5s).
- 16-Shard PostgreSQL Cluster: Deterministic FNV-1a 64-bit sharding across 16 virtual shards and 3 isolated relay pool tiers (central, premium, studio).
Serialization-Boundary Enforcement (ADR-004):
- Access control is computed server-side before wire serialization. Locked assets have text stripped, polls nullified, comments emptied, and media URLs replaced with placeholder SVG vectors.
ACID Transaction State Machine (ADR-005):
- Monetary mutations execute inside conn.transaction_with_behavior(TransactionBehavior::Immediate), preventing race conditions and double spends. Authoritative prices are queried from the database, ignoring client-submitted amounts.
GCRA Soft Token-Bucket Quotas (ADR-007):
- Smooth Generic Cell Rate Algorithm pacing (smooth $\to$ soft_paced $\to$ cooldown_advisory) allows high-frequency AI agents to operate without abrupt HTTP 429 disconnects or retry storms.

3. WHY: The Non-Negotiable Sovereign Maxims

Every commit, architecture decision, and code review is governed by five foundational maxims from PAPER-001: Philosophy Paper:

"Never trust the client with money or entitlements."
Pricing, balances, fee splits, and unlock status are evaluated exclusively on the server. The client UI is an untrusted presentation projection.
"If it is locked, it does not cross the wire."
The network perimeter is an adversarial boundary. A user without entitlement receives zero cleartext bytes, zero media URLs, and zero private comments.
"Architectural sovereignty is non-negotiable."
Every file belongs to exactly one Joyzoning zone. Domain rules remain pure with zero I/O. Architectural purity is continuously verified by npm run joy-check (100% Stability Index).
"Zero-config startup, sub-second verification."
High assurance does not require distributed chaos. Any contributor can clone the repository, run ./start-dev.sh, and run all 14 integration test suites in under half a second.
"Human creators and autonomous agents share the same sovereign ledger."
AI agents are first-class economic actors bound by the same cryptographic authentication, rate-limiting, and financial spend caps as human participants.

🎯 The Onboarding Strategy: What This Is Accomplishing

The primary point of failure in open-source systems is cognitive onboarding collapse: creators are overwhelmed by low-level code, security researchers cannot find formal invariants, enterprise stakeholders cannot verify compliance, and autonomous AI agents hallucinate across unstructured directories.

HEAV3NS-Publishing solves this through an engineered Cognitive Role-Based Onboarding Strategy with Progressive Disclosure of Complexity.

flowchart TD
    RepoRoot["Repository Clone\n(git clone HEAV3NS-PUBLISHING)"] --> Ignition["Stage 1: Zero-Config Ignition\n(./start-dev.sh in < 60s)"]
    
    Ignition --> RoleSelection{"Stage 2: Select Your Perspective"}
    
    RoleSelection -->|"Build Audience & Monetize"| CreatorFunnel["🎨 Creators & Operators\nGoal: Launch creative studio & configure rates\nUnlocks: Sovereign publishing & instant 85% payouts"]
    RoleSelection -->|"Verify Paywalls & Invariants"| AuditorFunnel["🔬 Researchers & Auditors\nGoal: Audit threat model & run security suites\nUnlocks: Mathematical proof of 7 core invariants"]
    RoleSelection -->|"Evaluate Economics & TCO"| ExecFunnel["📊 Stakeholders & Executives\nGoal: Review 85/15 model, escrow & compliance\nUnlocks: De-risked governance & financial clarity"]
    RoleSelection -->|"Write Code & Extend Platform"| AgentFunnel["🤖 AI Agents & Contributors\nGoal: Master Joyzoning layers & DDD handlers\nUnlocks: Zero-hallucination, zero-regression edits"]

    CreatorFunnel --> Stage3["Stage 3: Verifiable Proof & Local Exploration"]
    AuditorFunnel --> Stage3
    ExecFunnel --> Stage3
    AgentFunnel --> Stage3

    Stage3 --> Stage4["Stage 4: Sovereign Autonomous Deployment\n(PostgreSQL Sharding, MCP Studio, Production Live)"]

1. What Onboarding Accomplishes by Role

🎨 For Creators & Platform Operators

The Accomplishment: Eliminates platform dependency. Transforms the creator from an exploited user of a centralized service into the sovereign operator of their own creative business in under five minutes.
What It Unlocks:
- Instant full-stack studio launch with pre-seeded demo accounts (@ariavance, @marcusfit, @elenamusic).
- Configuration of 1/3/6/12-month subscription tiers and time-boxed promotional discount campaigns.
- Creation of PPV posts, PPV vertical video reels, and VIP ticketed live streams.
- Immediate withdrawal escrow testing ($20.00 minimum) with automatic rejection refunds.
- Delegation of publishing and audience engagement tasks to autonomous AI personas (/my/agents) under strict hardware spend guardrails.
Dedicated Guide: Creators & Platform Operators Guide

🔬 For Security Researchers & Systems Auditors

The Accomplishment: Replaces "faith-based security" with executable mathematical and runtime proofs. Empowers auditors to verify the platform's threat model and seven core invariants in under 1 second.
What It Unlocks:
- Direct mapping to the 7 Core Security Invariants (INV-1..7): server-side media redaction, reel/stream protection, PII masking, authoritative pricing, BEGIN IMMEDIATE ledger locks, bidirectional blocking, and Joyzoning purity.
- Sub-second adversarial test execution (cargo test --test api_security_tests) validating that client tampering, price spoofing, and double purchases fail deterministically.
- Access to four exhaustive historical vulnerability post-mortems (PM-001..PM-004) documenting exact root causes and permanent regression safeguards.
Dedicated Guide: Security Researchers & Systems Auditors Guide

📊 For Stakeholders, Product Leaders & Executives

The Accomplishment: De-risks product adoption and regulatory compliance. Proves the viability of the 85/15 unit economics model, platform solvency safeguards, and operational runbooks.
What It Unlocks:
- Verification of unit economics: 85% creator compensation, 15% platform margin, settled on every transaction.
- Payout solvency guarantee: instant wallet deduction on withdrawal request prevents double-spending during review; automated refund restores funds on rejection.
- Complete compliance workflow review: built-in Creator KYC identity verification (user_verifies), abuse reporting (user_reports), printable tax invoices (/invoices/[id]), and DMCA takedown playbooks.
- Total Cost of Ownership (TCO) evaluation: eliminating microservice bloat lowers monthly cloud operating costs by over 75%.
Dedicated Guide: Stakeholders & Product Executives Guide

🤖 For AI Coding Agents & Open-Source Contributors

The Accomplishment: Eliminates AI hallucination, context pollution, and architectural degradation. Establishes a deterministic, token-efficient feedback loop that allows coding agents to make zero-regression modifications.
What It Unlocks:
- Deterministic 11-step context acquisition order and 7 critical engineering rules.
- Clear architectural boundaries across 5 Joyzoning layers and 9 DDD bounded-context handler directories.
- Token-efficient verification loop: npm run joy-check (architectural purity) + cargo test (14 suites in < 0.5s) + npm run build (Next.js 16 App Router).
Dedicated Guide: AI Coding Agents & Open-Source Contributors Guide

2. Role-Based Navigation & Invariant Matrix

Perspective	Core Objective	Key Verifiable Invariant	Primary Exploration Tool	Onboarding Guide	Deep-Dive Reference
🎨 Creators & Operators	Monetize content, build audience, run AI agents	85/15 split & instant withdrawal escrow	Next.js Web UI (`http://localhost:3000`)	Creators Guide	Startup Playbook (`PB-001`) · Payout Playbook (`PB-003`)
🔬 Researchers & Auditors	Verify paywall security & cryptographic boundaries	Zero cleartext bytes cross the network wire (`INV-1..7`)	`cargo test --test api_security_tests`	Auditors Guide	Technical Whitepaper (`PAPER-003`) · Paywall ADR (`ADR-004`)
📊 Stakeholders & Execs	Validate unit economics, solvency & compliance	15% platform take rate & atomic ledger integrity	Admin Dashboard (`/admin`) & Dossier	Executives Guide	Stakeholder Dossier (`PAPER-002`) · Philosophy (`PAPER-001`)
🤖 AI Agents & Engineers	Implement features with zero architectural entropy	100% Joyzoning layer purity & 0 clippy warnings	`npm run joy-check` & `cargo test`	Contributors Guide	Joyzoning ADR (`ADR-009`) · DDD Handlers (`ADR-008`)

⚡ 60-Second Onboarding

Launch, explore, and transact on a fully seeded, production-grade instance in under 60 seconds with zero external Docker or database dependencies.

1. Prerequisites

Rust 1.75+ (cargo)
Node.js v20+ (npm)
PostgreSQL (initdb / pg_ctl, automatically initialized locally into .data/postgres/central on port 54329 by the startup script)

2. Launch Full Stack

./start-dev.sh

This single startup script deterministically executes three operations:

Bootstraps Local PostgreSQL Cluster (postgres://postgres@127.0.0.1:54329/heav3ns_publishing) and applies the 28-table migration schema (backend/migrations/001_heav3ns_publishing_postgres.sql).
Starts Rust Axum Core API (http://127.0.0.1:8080) — Loads 75+ REST endpoints across 9 DDD bounded contexts, embedded SQLite WAL persistence, the 16-Shard Soft Quota Engine, and the MCP 2024-11-05 Server.
Compiles Next.js 16 Turbopack UI (http://127.0.0.1:3000) — Serves 26 App Router views with React 19 and dynamic route proxies to the backend.

3. Sign In with Seeded Demo Personas

Open http://localhost:3000 in your browser. All seeded accounts use the password: password123:

Seeded Persona	Handle & Email	Profile Type	Initial Wallet	Primary Exploration Flow
Admin & Verified Creator	`@ariavance` `aria@justfans.local`	`$14.99/mo` (Active Promo)	`$1,450.50`	Access `/admin` governance panel, approve payouts, configure promotional discounts, and operate `/my/agents` Persona Studio.
Verified Creator	`@marcusfit` `marcus@justfans.local`	`$9.99/mo` (Paid Feed)	`$820.00`	Publish PPV feed posts, upload vertical PPV reels (`/reels/create`), and test RTMP/HLS live streaming (`/my/streams`).
Open / Free Creator	`@elenamusic` `elena@justfans.local`	Free (`$0.00`) (PPV Unlocks)	`$540.75`	Test top-of-funnel follower acquisition with individual paywalled flagship posts, polls, and locked attachments.
Fan / Subscriber	`@alexrivera` `alex@justfans.local`	Active Member (Subscriber)	`$250.00`	Subscribe to creators, unlock PPV posts/reels/DMs, send creator tips, vote in polls, and inspect printable tax invoices (`/invoices/[id]`).

4. Workstation Shortcuts & Core Navigation

Universal Command Palette (⌘K / Ctrl+K): Press anywhere to search creators, trigger publishing actions (New Post, New Reel, New Story, Go Live), or toggle light/dark theme.
Autonomous Agent Studio (/my/agents): Mint scoped hp_mcp_* tokens, configure per-tx and daily hardware spend caps, compile zero-inference markdown briefs, and inspect 16-shard telemetry.
Creator Media Vault (/my/vault): Upload high-resolution media once; attach seamlessly across posts, reels, and direct messages without redundant file transfers.

🏗️ System Architecture & Joyzoning Topology

HEAV3NS-Publishing implements the Joyzoning sovereign architecture protocol (HEAV3NS-JOY 1.0.0, ADR-009). Pure business rules and trait contracts remain strictly sovereign with zero I/O entropy:

flowchart TB
    subgraph UI_LAYER["1. UI Zone (Next.js 16.4.3 + React 19 + Turbopack :3000) [UI ZONE]"]
        AppShell["AppShell + ⌘K Command Palette\n(frontend/src/components/AppShell.tsx)"]
        DecomposedUI["Modular Components (agents, profile, settings)\n(frontend/src/components/*)"]
        Pages["26 App Router Views\n(frontend/src/app/**)"]
        Proxy["Next.js Proxy Rewrite (/api/* & /uploads/*)\n(frontend/next.config.mjs)"]
    end

    subgraph AGENTS_ZONE["Autonomous Agent Clients (Model Context Protocol)"]
        MCPClient["Claude Code / Cursor / Windsurf / Swarms\n(X-Agent-Token: hp_mcp_* + X-Idempotency-Key)"]
    end

    subgraph CORE_LAYER["2. Core Orchestration Zone (Rust Axum 0.7 :8080) [CORE ZONE]"]
        AuthExtractor["AuthUser / OptionalAuthUser / Scope Guards\n(infrastructure/auth.rs)"]
        ShardingEngine["16-Shard Router · 3 Relay Pools · GCRA Soft Quotas\n(core/sharding/{router,quota,pool}.rs)"]
        MCPServer["MCP 2024-11-05 Server (/api/mcp)\n32 Tools · 6 Resources · 3 Prompts (core/mcp/)"]
        DDDEngine["9 DDD Bounded Context Handlers + Swarm Coordinator\ncore/handlers/{identity,content,discovery,social,\nmessaging,monetization,media,governance,platform}"]
    end

    subgraph DOMAIN_LAYER["3. Domain Contract Zone (Pure Rust 2021 — 0% I/O) [DOMAIN ZONE]"]
        DomainInterfaces["Pure Trait Contracts (domain/interfaces/*)\nIAuthProvider · ILedgerProcessor · IMediaVault\nIMessagingDispatcher · IQuotaPolicy · IShardedRepository · ISwarmCoordinator"]
        DomainEntities["Bounded-Context Types & Value Objects\n(domain/types/*)"]
    end

    subgraph INFRA_LAYER["4. Infrastructure Persistence Zone [INFRASTRUCTURE ZONE]"]
        AuthAdapter["JWT Authentication Adapter (infrastructure/auth.rs)"]
        PostgresPool[("PostgreSQL Cluster (:54329)\n28 Sharded Tables (migrations/001_*)")]
        SQLiteEngine[("Embedded SQLite 3 WAL\nBEGIN IMMEDIATE Transactions (db/*)")]
        MediaStore[("Media Vault File Storage\nbackend/uploads/")]
    end

    subgraph PLUMBING_LAYER["5. Plumbing Leaf Primitives Zone (Stateless) [PLUMBING ZONE]"]
        Leafs["Stateless Leaf Helpers (datetime, math::round_money, sharding::fnv1a, validation)\n(backend/src/plumbing/*)"]
    end

    Pages & DecomposedUI & AppShell --> Proxy
    Proxy --> AuthExtractor
    MCPClient --> AuthExtractor
    AuthExtractor --> ShardingEngine --> DDDEngine
    MCPClient --> MCPServer --> DDDEngine
    DDDEngine --> DomainInterfaces
    DomainInterfaces -.-> DomainEntities
    DomainInterfaces --> AuthAdapter
    DomainInterfaces --> PostgresPool
    DomainInterfaces --> SQLiteEngine
    DDDEngine --> MediaStore
    CORE_LAYER -.-> Leafs
    INFRA_LAYER -.-> Leafs

Joyzoning 5-Zone Architectural Matrix

Zone	Folder Location	Responsibility & Invariant Scope	Permitted Imports	I/O Entropy
`DOMAIN`	`backend/src/domain/`	Pure business domain rules, entities (`domain/types/`), and trait contracts (`domain/interfaces/`). Eliminates Martin's Zone of Pain.	Rust `core` & `std` only; never imports infrastructure or UI.	`0.0` (Zero I/O)
`CORE`	`backend/src/core/`	Use-case orchestration: 75+ endpoints across 9 DDD bounded contexts (`core/handlers/`), 16-shard router, Persona Studio, and MCP Server (`core/mcp/`).	Domain interfaces and types; never imports UI.	`0.0` (Pure orchestration)
`INFRASTRUCTURE`	`backend/src/infrastructure/`	Concrete I/O adapters: PostgreSQL connection pool (`postgres.rs`), SQLite WAL with panic-safe mutex locking (`state.rs`, `helpers.rs`), and JWT provider (`auth.rs`).	Implements domain interfaces; never imported by domain or plumbing.	`1.0` (Concrete I/O)
`PLUMBING`	`backend/src/plumbing/`	Pure stateless leaf helpers: FNV-1a 64-bit sharding hash, canonical JSON hashing, money rounding (`round_money`), datetime normalization (`normalize_db_datetime`).	Zero upward imports; zero mutable top-level state. Pure leaf.	`0.0` (Stateless leaf)
`UI`	`frontend/`, `docs/`	Next.js 16 App Router views, modular React 19 subcomponents (`components/{agents,profile,settings}/*`), styling, and documentation.	Consumes core REST and MCP APIs; never reaches infrastructure directly.	`1.0` (Presentation)

💰 Creator Economics & Financial Governance

HEAV3NS-Publishing operates on an immutable, mathematically deterministic financial ledger designed to eliminate double charges, price spoofing, and platform withholding:

1. Six Unified Revenue Streams

Monetization Primitive	API Endpoint	Settlement Timing	Creator Net	Platform Fee
1. Multi-Month Subscriptions	`POST /api/payments/initiate` (`subscription`)	Instant on purchase	85%	15%
2. Pay-Per-View (PPV) Posts	`POST /api/payments/initiate` (`post-unlock`)	Instant on purchase	85%	15%
3. Pay-Per-View (PPV) Video Reels	`POST /api/payments/initiate` (`reel-unlock`)	Instant on purchase	85%	15%
4. Pay-Per-View (PPV) Direct Messages	`POST /api/payments/initiate` (`message-unlock`)	Instant on purchase	85%	15%
5. VIP Live Stream Access	`POST /api/payments/initiate` (`stream-unlock`)	Instant on purchase	85%	15%
6. Direct Creator Tips	`POST /api/payments/initiate` (`tip`, `*-tip`)	Instant on purchase	85%	15%

2. Deterministic Settlement Formula

Every financial mutation executes inside an atomic BEGIN IMMEDIATE database transaction using two-decimal rounding from backend/src/plumbing/math.rs:

$$\text{Creator Credit} = \text{round}\left(\text{Gross Amount} \times 0.85, 2\right)$$

$$\text{Platform Fee} = \text{Gross Amount} - \text{Creator Credit}$$

Client-supplied amounts for subscriptions and PPV unlocks are strictly ignored by the server; the backend queries authoritative prices directly from the database to prevent price-spoofing attacks (ADR-005, PM-001).

3. Immediate Payout Escrow & Automatic Refund Safeguards

To guarantee platform solvency and eliminate double withdrawals, payouts enforce a bulletproof two-phase escrow lifecycle:

sequenceDiagram
    autonumber
    actor Creator as Creator (@ariavance)
    participant API as Rust Ledger Engine
    participant DB as SQLite WAL (BEGIN IMMEDIATE)
    actor Admin as Platform Admin

    Creator->>API: POST /api/withdrawals/request ($100.00, min $20.00)
    API->>DB: Verify wallets.total >= $100.00<br/>Deduct $100.00 from wallets.total (Immediate Escrow)<br/>Insert withdrawals (status = 'requested')<br/>COMMIT
    API-->>Creator: 200 OK (Balance Escrowed, Pending Review)

    alt Admin Approves Payout
        Admin->>API: POST /api/admin/withdrawals/:id { action: "approve" }
        API->>DB: Update withdrawals SET status = 'approved'<br/>Record settlement in transactions ledger
    else Admin Rejects Payout
        Admin->>API: POST /api/admin/withdrawals/:id { action: "reject" }
        API->>DB: BEGIN IMMEDIATE<br/>Update withdrawals SET status = 'rejected'<br/>Refund +$100.00 back to wallets.total<br/>COMMIT
    end

🤖 Autonomous AI Personas, MCP & 16-Shard Soft Quotas

Unlike platforms that treat AI as a bolt-on chatbot or an unauthorized scraping target, HEAV3NS-Publishing provides native first-class infrastructure for autonomous agents:

1. Model Context Protocol (MCP 2024-11-05) Server

Standardized Discovery: GET /api/mcp/manifest exposes full capabilities to LLM tools.
Unified JSON-RPC 2.0: POST /api/mcp and REST tool bridge (POST /api/mcp/tools/:tool_name).
32 Built-In Tools: Post publishing, PPV unlocks, tipping, subscriptions, media vault management, reel publishing, live stream configuration, user blocking, and persona evolution.
6 Dynamic Resources: Profile telemetry, creator feeds, 16-shard statistics, wallet statements, and audit logs.
3 Workflow Prompts: Standardized system prompts for autonomous publishing, subscriber engagement, and payout auditing.

2. No-Inference Autonomous Persona Studio (`/my/agents`)

Zero Server-Side LLM Overhead: The platform manages state, versioning, memory rosters, and execution coordination without incurring costly GPU server inference fees.
Optimistic Concurrency: Revisions enforce expected_revision locking to eliminate state conflicts when multiple agent processes operate concurrently.
Deterministic Brief Compilation: Generates standardized Markdown execution briefs with creator context, recent activity, and performance metrics.
Multi-Persona Swarm Coordinator: Batch-dispatch complex workflows across multiple agent personas via POST /api/agent/swarm/batch.

3. 16-Shard Routing & Soft Token-Bucket Quotas

Deterministic FNV-1a Hashing: Consistent 64-bit hashing routes all user actions across 16 virtual shards (0..15) and 3 isolated relay pools:
- central: Standard public feed and consumer browsing.
- premium: Paid subscriber traffic and financial transactions.
- studio: Autonomous agent personas and high-throughput batch swarms.
GCRA Soft Pacing: Employs Generic Cell Rate Algorithm pacing (smooth $\to$ soft_paced $\to$ cooldown_advisory) to gently throttle high-frequency agents without abrupt HTTP 429 disconnects or retry storms.
Idempotency Deduplication: Clients submit X-Idempotency-Key headers to ensure network retries never trigger duplicate financial deductions or duplicated post submissions.

🧪 Verification & Quality Gates

Every layer of HEAV3NS-Publishing is protected by automated quality gates running in GitHub Actions CI (.github/workflows/ci.yml) and locally:

# 1. Joyzoning Architectural Sovereign Audit (100% layer purity, 0 blocking violations)
npm run joy-check

# 2. Run all 14 Rust integration, security, sharding, MCP & swarm test suites (< 0.5s)
cd backend && cargo test

# 3. Strict Rust Clippy static analysis (0 warnings tolerated)
cd backend && cargo clippy --all-targets -- -D warnings

# 4. Next.js 16.4.3 TypeScript compilation & production build (26 App Router routes)
cd frontend && npm run build

# 5. Trinity durable primitives & environment doctor diagnosis
npm run trinity:selftest
npm run doctor

# 6. Execute entire verification pipeline in one command
npm run verify

Trinity Durable Primitives & Specialist Swarm

Persistent Job Queues: npx joy trinity queue add|list|drain survives turn or process restarts.
Buffered Storage Tables: npx joy trinity db push|select provides lightweight local persistence.
Specialist Swarm: Coordinated multi-agent execution via swarm plan, swarm next, swarm report, and swarm finish.

🏛️ Joyzoning Sovereignty & Coding Guidelines

The codebase strictly adheres to Joyzoning (HEAV3NS-JOY 1.0.0). When modifying any source file:

Tag Every File: The first line of every file must contain its zone header tag (e.g. , /* [LAYER: DOMAIN] */, # [LAYER: CORE]).
Respect Zone Boundaries:
- DOMAIN: 0% I/O; never import infrastructure or UI. Pure business interfaces only.
- CORE: Orchestrates use-cases; depends on domain interfaces in domain/interfaces/*; never imports UI.
- INFRASTRUCTURE: Implements domain traits; never imported by domain or plumbing.
- PLUMBING: Pure stateless leaf helpers; zero upward imports; no mutable state.
- UI: Next.js 16 frontend; communicates with backend only via core REST/MCP endpoints.
Keep Files Focused: Files must stay under ~800 lines. Decompose UI views into subcomponents under frontend/src/components/{agents,profile,settings}/*.
Token-Efficient Check Loop:
- Pre-edit check: npx joy check . --phase pre-edit --scope <file> --neighborhood 1 --format compact
- Post-edit check: npx joy check . --phase post-edit --scope <file> --format compact

For coding agent operational protocols, consult AGENTS.md and SOUL.md.

📚 Complete Documentation Index

Explore the comprehensive documentation hub in docs/README.md:

📜 Foundational Papers

PAPER-001: Philosophy Paper — Creator sovereignty, serialization-boundary invariants, and zero-bloat systems design.
PAPER-002: Stakeholder Handoff Dossier — 85/15 unit economics, operational readiness, escrow safeguards, and compliance governance.
PAPER-003: Technical Whitepaper — Mathematical specifications, Joyzoning layers, DDD bounded contexts, and ACID state machine.

🧭 Role-Based Onboarding Guides

Creators & Platform Operators Guide — Two-minute launch, subscription tiers, PPV reels/streams, immediate payout escrow, and AI persona studio.
Security Researchers & Systems Auditors Guide — Threat models, 7 core system invariants (INV-1..7), and sub-second adversarial security suites.
Stakeholders & Product Executives Guide — Unit economics, 85/15 split, solvency mitigations, KYC/abuse triage, and TCO reduction.
AI Coding Agents & Open-Source Contributors Guide — Deterministic read order, 7 critical rules, Joyzoning boundaries, and pre/post-edit check loops.

🏗️ Specifications & Reference

Domain Knowledge Base & Glossary — Domain terms, invariants, codebase directory map, and seeded personas.
System Architecture & Data Flow — Topology diagrams, request lifecycles, and paywall enforcement.
Database Schema Reference (28 Tables) — PostgreSQL & SQLite 28-table schema, indexing, and cascade rules.
REST & MCP API Reference (75+ Routes) — 75+ endpoints across 9 DDD bounded contexts with JSON schemas and status codes.

🏛️ Architecture Decision Records (ADRs)

🛠️ Operational Playbooks

🔍 Engineering Post-Mortems

🤝 Open-Source Community & Governance

Contributing Guidelines (CONTRIBUTING.md) · Security Policy (SECURITY.md) · Code of Conduct (CODE_OF_CONDUCT.md) · Changelog (CHANGELOG.md) · Support (SUPPORT.md) · MIT License (LICENSE)

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude		.claude
.clinerules		.clinerules
.cursor		.cursor
.gemini		.gemini
.github		.github
.joy		.joy
.vscode		.vscode
.windsurf/rules		.windsurf/rules
backend		backend
docs		docs
frontend		frontend
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.joyignore		.joyignore
.mcp.json		.mcp.json
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SOUL.md		SOUL.md
SUPPORT.md		SUPPORT.md
llms.txt		llms.txt
package.json		package.json
stability.config.json		stability.config.json
start-dev.sh		start-dev.sh
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation