Intelligent, Security-Conscious, and Designed for Effortless Productivity

Because With Rullst, We Rule! Rullst is a modular Rust framework suite built on Tokio, Axum, Tower, and SQLx for full-stack applications and the product workflows around them. Version 12 is under active development; use the capability and release documents to distinguish implemented behavior from roadmap work.

Welcome to the Rullst documentation. Build a small application, understand the code behind it, then explore the tools that fit your next idea.

New here? Start with the guided learning path →

Choose a generated application, a hand-written first route or a JSON API. Each path tells you what to run, what to expect and where to go next.

Documentation Hub

• ✨ Why Rullst?
• 📖 Getting Started & Blueprints Showcase
• 🤖 Rullst AI: Developing with Autonomous Agents
• 📊 Rullst Studio: Real-Time Monitoring & Radar
• ⚙️ Rullst Nexus: Explicit Admin CMS
• 💳 Rullst Capital: SaaS Billing & Revenue Dashboard
• 🧠 Integrating AI into Rullst
• 🍳 Rullst Cookbook & Tutorials
• 📜 Framework Spec
• 🗺️ Blueprints Roadmap
• 💻 CLI Reference
• 🛡️ Audit Report
• 📦 View on Crates.io

Learn the foundations, then explore

• 🚀 Measured performance: Criterion suites and CI track regressions; application latency must be measured on the target workload.
• 🧩 Server-rendered UI: html! and HTMX-oriented scaffolds are the audited default. LiveView and Wasm Island primitives exist, while turnkey Leptos/Dioxus adapters remain roadmap work.
• 📖 Interactive Scalar Docs (/docs): Built-in OpenAPI UI via cargo rullst make:scalar.
• ☸️ Kubernetes Native: Cloud-Native manifest scaffolding (cargo rullst make:k8s) with /health & /ready probes.
• 📡 Rullst Radar & Prometheus: Process/Tokio observations and a Prometheus text exporter, with unavailable probes reported explicitly.
• 🛡️ Local AI option: Use an Ollama endpoint when prompts should stay on infrastructure you control; network isolation remains a deployment duty.
• 📦 Batteries Included: ORM (rullst-orm), Auth, Revenue Dashboard, Jobs, Mail, Scheduler, Cache, Security.

Your first idea, running in Rust

You do not need to understand every Rullst crate before writing your first application. Start small, make one thing work, and learn what each layer does as your product needs it.

You are exploring the v12 development preview. It is not yet a supported production release. Use the instructions for this source revision—not the older CLI installed by an unversioned crates.io command. The release program and current audit show the remaining gates.

Pick your starting line

For the simplest first experiment, choose Blank + SQLite, or Blank with --no-database if you do not need persistence yet. The larger LMS and SaaS blueprints have more moving parts and longer first builds. You can explore them after your toolchain and local workflow are working.

A small loop that teaches a lot

1. Run it. Reach the local page or JSON endpoint before adding features.
2. Find the code. Open src/main.rs, then the generated controllers, models and pages that exist in your chosen blueprint.
3. Make one visible change. Edit a heading or response field. With cargo rullst dev, watch the rebuild and process restart; with plain cargo run, stop and restart it yourself.
4. Break something safely. Introduce a small syntax error in your local experiment. Read the compiler diagnostic, correct it and save again. The supervisor keeps the old application running when compilation fails.
5. Verify the result. Reload the page or repeat the request. A successful build is only the first check; the response should do what you intended.

See exact restart and state boundaries. Do not use production databases or credentials for this exercise.

Build your understanding, one layer at a time

You can use an AI assistant while learning. Ask it to explain the generated files, point to the exact APIs and show a failing test before a bug fix. Treat its output as a proposed change, not as proof. Rullst’s architecture specification is the common reference for both of you.

When the first run does not work

If you are still stuck, share the command, operating system, Rust version, framework commit and a minimal reproduction in an issue or on Discord. Remove secrets and personal data first. Send security vulnerabilities privately using the security policy.

Before this becomes a real product

A generated app is a foundation, not a deployment approval. Review authentication, ownership, secrets, database backups and migrations, external provider setup and release status. Start with the security architecture, choose features using the capability status, and measure your own workload.

Ready? Create your first application →

Why Rullst?

Rullst is an opinionated, Axum-based full-stack framework for teams that want the productivity of a coordinated application platform without hiding Rust’s types or the underlying ecosystem.

Its strongest distinction is not that every individual feature is unique. It is the combination of compile-time-oriented APIs, explicit security boundaries, first-party backend capabilities, offline development contracts, and one coordinated CLI and release train.

Version status: Rullst v12 is under active development. This page lists implemented or explicitly bounded capabilities in the current source tree; it is not a production-readiness certificate. The framework specification, capability ledger, and v12 release program are authoritative when a shorter description and the code disagree.

The short answer

Choose Rullst when you want to build a backend-oriented Rust application with:

• an explicit Axum, Tokio, Tower, and SQLx foundation;
• compile-time-generated routes, HTML, and models, with compiler-visible diagnostics instead of runtime reflection;
• a coordinated ORM, authentication, security, jobs, mail, AI, billing, administration, observability, and CLI toolchain;
• secure, fail-closed defaults for privileged and production-facing surfaces;
• deterministic offline paths for supported external-provider integrations;
• server-rendered interfaces that do not require a project-local SPA bundle;
• standard escape hatches when a framework abstraction is not the right fit.

What makes the combination distinctive

1. AI-native means explicit and inspectable

Rullst is designed so that both humans and coding agents can reason about an application from its source. Common routes, models, HTML trees, policies, and scaffolds are represented by typed Rust or macro input rather than runtime class scanning or hidden reflection.

This does not make generated code automatically correct. It makes important structure available to the compiler, review tools, and the CLI. Macro diagnostics, compile-fail tests, generated-project gates, and the AST-based IDOR scanner turn that structure into evidence.

The AI layer follows the same rule. Its bounded RAG pipeline makes tenant context, retrieval, context limits, source metadata, and audit explicit in one typed operation. It rejects differently tagged or unsafe passages and refuses ungrounded generation when retrieval is empty. The included cosine retriever is clearly process-local; production datastore authorization and durability are not hidden behind an “automatic AI” claim.

Conversational memory follows that explicit model too: a static-dispatch tenant-bound contract has a bounded offline store and an opt-in SQL adapter for SQLite, PostgreSQL, MySQL, and MariaDB. Each successful turn commits the user and assistant messages atomically, while revision compare-and-swap rejects stale cross-process writers instead of silently scrambling history or automatically repeating a billable model request.

2. A broad platform that keeps its foundations visible

Rullst coordinates a large backend surface in one versioned workspace, but it does not replace its foundations with proprietary runtime primitives:

• applications can mount ordinary axum::Router values;
• middleware remains compatible with Tower composition;
• Tokio remains the asynchronous runtime;
• SQLx pools and raw parameterized queries remain available beside the ORM.

The Axum and SQLx interoperability guide documents the supported escape hatches. Framework conveniences can still require migration work, so Rullst describes this as reduced lock-in rather than “zero lock-in.”

3. Security boundaries are part of framework design

The framework treats authorization and privileged tooling as architectural inputs rather than deployment footnotes. Current bounded contracts include:

• fail-closed production environment and secret validation;
• CSRF, secure headers, request heuristics, DLP, abuse controls, and security telemetry primitives;
• route-scoped JSON Schema 2020-12 or OpenAPI 3.1-component enforcement with bounded offline compilation, local-only references and linear-time regexes;
• explainable aggregate threat assessment plus an opt-in authenticated, subject-bound, expiring and locally one-shot proof-of-work gate;
• Argon2id password hashing, expiring encrypted sessions, RBAC, model policies, and explicit owner-or-role guards;
• a typed OAuth/OIDC session transaction that keeps PKCE verifiers and OIDC nonces server-side, expires them after ten minutes, and consumes them before callback validation;
• a provider-generic automatic token coordinator that binds refreshes to the original user, redacts credentials, detects a bounded expiry window and prevents overlapping provider calls while waiters reuse a valid transition;
• an authenticated Nexus admin surface and a loopback/debug-constrained Studio;
• one bounded signed-payment-webhook verifier exposed through both Axum and opt-in Actix middleware adapters;
• versioned AES-256-GCM ORM field encryption with authenticated context;
• CI gates against panic!, unwrap(), and expect() in declared production targets.

These are defense-in-depth controls, not a claim that an application is secure without its own authorization model, deployment controls, reviews, and tests. The Sentinel is deliberately deterministic rather than marketed as autonomous AI: the host still owns aggregate collection, identity, accessible fallback, distributed replay state and enforcement. See the security architecture and v12 security claims.

4. Persistence depth without a fictional universal database API

The relational ORM provides generated Active Record and query APIs, transactions, migrations, relations, tenant scopes, policies, soft deletion, auditing, encrypted fields, typed pgvector helpers, structured telemetry, and an opt-in transactional outbox.

The primary relational matrix covers SQLite, PostgreSQL, MySQL, and MariaDB. Turso/libSQL has a separate typed primary profile. MongoDB, DuckDB, SurrealDB, Qdrant, Redis, and external search engines use capability-specific adapters so their different consistency and query models stay visible. MongoDB and SurrealDB share only a narrow identifier-preserving recovery boundary: a bounded encrypted snapshot can be rehearsed across both, while writer quiescence, schema provisioning, key custody and durable backup remain explicit application/operator work.

This is deliberate: Rullst prefers several honest, bounded APIs over one API that pretends documents, OLAP, graphs, vectors, key-value structures, and relational transactions have identical semantics. Read the polyglot persistence, transactional outbox, and Scout search guides.

The same boundary discipline now applies to messaging. rullst-messaging defines one versioned envelope, bounded topic/group metadata, idempotent publication, consumer groups, expiring acknowledgement leases, retry and dead-letter semantics, with a deterministic concurrent in-memory contract. A canonical bounded v1 envelope codec and allowlisted W3C trace-context boundary make byte compatibility and correlation behavior executable. The codec still does not open a remote connection or map broker-specific semantics. SQLite can explicitly protect header values and payloads with row-bound AES-256-GCM and a bounded rotation keyring while keeping visible metadata and operator duties honest. The opt-in relational outbox relay also proves its unavoidable publish-before-ACK crash window as an exact idempotent replay instead of calling two systems one atomic transaction. That makes offline tests and future adapter conformance explicit without pretending the local broker is Kafka, RabbitMQ, NATS, Redis Streams, or a cloud service. Applications still own topic authorization and idempotency of remote side effects. See Bounded Brokered Messaging.

5. External services remain usable during offline development

Supported AI, OAuth, mail, billing, search, and persistence adapters expose deterministic offline behavior when configured with their documented empty or mock_* credentials. This lets generated projects, tests, examples, and local sandboxes run without silently contacting a third party.

The Brazilian fiscal boundary applies the same evidence-first approach: its bounded DPS 1.01 builder, checksum-pinned official XSD catalogue, local PKCS#12 XMLDSig verification, deterministic issuance JSON, strict signed-authorization and structured-rejection codec, and mTLS client preparation are testable without calling SEFIN, while tax authorization remains explicitly disabled until the external trust and homologation gates pass.

Mail scheduling follows the same bounded approach: SQLite and Redis persist a due time and never claim it early, while unsupported real direct transports reject a future message instead of delivering it immediately. Offline fixtures may retain that timestamp for assertions. Polling delay, at-least-once delivery, and provider acceptance remain visible operational boundaries.

The optional native AWS SES v2 path follows the provider’s real authentication model instead of disguising a bearer request as AWS support. It delegates regional SigV4 and credential-provider rotation to the official AWS SDK while retaining the same pre-flight, HTML/text, attachment/CID and RFC 8058 message contract. Its local signed-request fixture proves integration shape, not AWS account readiness, reputation or inbox delivery.

Mocks prove the local application contract, not the live provider contract. Provider-specific production support still requires the applicable live or protocol tests, credentials, policy, and operational evidence.

6. Framework upgrades are a product feature

cargo rullst upgrade --dry-run inventories a project and reports a versioned migration plan. cargo rullst upgrade snapshots controlled files, updates the coordinated Rullst dependency train, applies supported compiler fixes, runs a Cargo check gate, and restores those files when the gate fails.

It intentionally refuses to invent database migrations, business rules, or security policy. The useful distinction is a bounded, recoverable upgrade transaction with human and machine-readable reports. See the assisted upgrade tutorial.

7. Server-first UI with optional escalation

The compile-time html! macro escapes supported dynamic text and attribute values, while RawHtml makes an unescaped boundary explicit. HTMX-oriented server rendering is the default path for applications that do not need a project-local SPA bundle.

LiveView, selected Wasm islands, Tera, and packaging helpers are optional strategies with separate maturity and operational requirements. Rullst does not claim that every frontend mode is interchangeable or bundle-free.

Omni extends that server-first model with a deterministic Tauri shell for desktop, Android, and iOS instead of creating a second business backend. Its portable versioned client envelope carries no local authority, and the opt-in native offline foundation adds bounded idempotent proposals, explicit conflict/resync state, account-bound encrypted snapshots, and a coordinator with request budgets, timeouts, and cursor checks over application transports. Platform secure storage, concrete HTTP/background transport, physical-device behavior, signing, and store acceptance remain separate evidence gates; see the web-first Omni guide and offline synchronization guide.

8. Local control surfaces use real application signals

Studio is a local developer control room with explicit unavailable states when a probe is not connected. Nexus generates an authenticated administration surface from registered model metadata and applies server-side field policy. Tenant-owned models can explicitly bind every built-in CRUD/search/batch path to a trusted Core tenant context, while an opt-in required audit row shares the mutation transaction and rolls it back on audit failure. The host still owns identity/membership and immutable external evidence; Nexus does not disguise a same-database mutable table as an append-only audit service. Studio’s relational browser can also perform deliberately narrow primitive row edits/deletions: the write surface exists only behind the verified local request capability, binds values, identifies one row by its inspected complete primary key and runs against four relational engines. It is not presented as a replacement for application tenant authorization or production administration. Studio flag toggles also invalidate already-warm database flag drivers in the same process without an unbounded key registry; cross-process invalidation remains an explicit application transport.

The queue monitor follows an explicit retention rule as well. SQLite removes successful payloads by default, while applications that need operational history can opt into a validated, atomically pruned limit and purge it from Studio. Rullst does not silently trade privacy for a more impressive dashboard.

The ORM emits secret-free structured spans for generated and raw query entrypoints, streams, transaction outcomes, and Rullst-owned pool acquisition timing. The host owns subscriber initialization, sampling, collector security, and retention. See the telemetry guide.

9. Scaffolding is treated as shipped code

The CLI can generate projects, routes, models, migrations, auth, mail, billing, deployment manifests, LMS foundations, and other bounded application slices. Rullst tests representative generated projects and maintains structural matrices instead of assuming that a template is correct because its source file compiles inside the CLI crate.

The Academy slice is already more than a landing-page mock: its generated SQLite journey exercises server-owned progress, assessment, score, leaderboard, automation, notifications and school boundaries. Its accessible lesson presentation supports bounded video/audio metadata, mandatory WebVTT captions for video and escaped transcripts. Its generic activity boundary also keeps points out of untrusted submissions: static-dispatch evaluators construct server-authored results, with tested single-choice, bounded pair-matching and typed-recall exercises as the first examples. Typed recall retains a policy-bound digest rather than raw learner input, with deliberately narrow normalization semantics. The complete starter then rederives the persisted activity policy and atomically projects that opaque result into a versioned score event, leaderboard and outbox. Its owner-only routes accept only an idempotency key plus a chosen option, pair IDs or bounded typed text, while the same transaction locks the exact evaluator configuration and retains an exact-replay attempt; cross-user, actor/evidence/policy mismatch and conflicting replay are materialized negatives. Opt-in rullst-box-v1 policies also update a durable, bounded learner/activity review schedule in that transaction; a replay cannot move it, and an owner-only due queue rechecks school membership, course scope and enrollment. The algorithm is deliberately inspectable and does not claim FSRS/SM-2 compatibility or learning efficacy. That is a useful foundation for a language-learning product, not a claim that Rullst generates pedagogy, content, speech recognition, native-device behavior or a complete Duolingo equivalent.

For example, make:billing --model Workspace now materializes distinct SQLx and Turso-primary persistence profiles. Both are generated, linted, migrated and exercised through subscription ownership and collision negatives; the test does not turn provider sandbox validation or distributed reconciliation into an automatic claim.

The billing facade follows the same bounded design: an explicit generic subscription handle delegates pause/cancel without erasing the provider type, while its grace-period value validates time bounds but leaves persistence, authorization and entitlement policy visible in application code. Its shared-quota boundary likewise derives one subject from trusted tenant state, reserves idempotently before creation and can commit the counter and a relational domain insert in the same caller-owned transaction. SQLite plus live PostgreSQL/MySQL/MariaDB contention contracts prove that concurrent workspace members stop at the configured limit; membership and tier reconciliation remain visible host responsibilities. Coupon and trial management follows the same evidence boundary: coupon IDs are bounded/redacted, Stripe binds the expanded applied discount, and 1–730-day relative trial updates have stable explicit-clock retries plus bound Stripe and Lemon Squeezy protocol fixtures. Providers without a reviewed live operation fail explicitly instead of presenting a local no-op as remote success.

The same CLI includes inspection, toolchain diagnostics, migration assistance, SBOM generation, and a bounded static route-access scanner. Generated output remains application code: review it, test it, and keep it under version control.

10. Ambition is separated from evidence

Rullst keeps ambitious ideas, but labels them as implemented, partial, experimental, offline mock, roadmap, or not recommended. Benchmarks are reported for their measured workload instead of becoming universal performance slogans. Hardware, provider, regulatory, and certification claims remain incomplete until the corresponding external evidence exists.

This distinction is essential for a broad framework. The capability ledger records the boundary; the technical comparison records both competitive strengths and areas where other frameworks are more mature.

Where Rullst is a particularly good fit

Rullst is worth evaluating for:

• backend-heavy SaaS and multi-tenant applications;
• server-rendered products that still need jobs, realtime, mail, billing, and administration;
• Rust teams that prefer one coordinated release train over assembling every application subsystem independently;
• projects that need relational data plus explicit document, analytics, search, vector, graph, or key-value capabilities;
• organizations that value offline reproducibility, secure scaffolds, and machine-readable engineering evidence;
• teams using coding agents that benefit from explicit APIs, bounded files, strong types, and a normative specification.

When another choice may be better

Rullst may not be the best choice when:

• only a small HTTP router or middleware library is needed;
• a browser-component ecosystem is the primary product architecture;
• long production history, a very large plugin ecosystem, or commercial support matters more than Rust-native integration;
• the application requires a capability that the ledger still marks partial, experimental, or roadmap;
• the team does not want the maintenance surface of a batteries-included framework.

In those cases, using Axum directly, another Rust application framework, a frontend-centered framework, or a mature platform in another ecosystem can be the more responsible decision.

How to evaluate Rullst today

1. Start with the Zero-to-Hero tutorial.
2. Check the exact capability you need in the specification and capability ledger.
3. Enable only the required Cargo features and inspect their dependency graph.
4. Run the documented tests against your database, provider, proxy, and threat model.
5. Pin an immutable release or commit for evaluation; do not deploy from a moving development branch.

This page will be reviewed again against the immutable v12 RC source and CI evidence. Until then, it is a concise map of the strongest implemented ideas, not a substitute for the detailed contracts.

Simple capability status

This is the compact view of Rullst’s canonical M1–M39 programme. It is derived from the root ROADMAP; that roadmap and the capability ledger retain the evidence and limitations. The labels here deliberately do not turn partial foundations into completed features.

v12 RC engineering snapshot — 5 September 2026

This functionality inventory is deliberately separate from release quality. All 15 non-IoT crates currently meet the approved A floor and rullst-iot meets its approved B exception. All 15 active crates have also reached their higher audited local ceiling: 1,509/1,509 local campaign points are backed by repository evidence (100%), with zero planning points remaining. The exact SHA still earns those dimensions only when its conditioning gates pass. The older 91.8% readiness estimate in the v12 release programme is a superseded planning snapshot, not the current percentage. The post-audit release report is authoritative and keeps the RC at NO-GO until its candidate gates and explicit approval are complete.

Coverage is a separate RC gate. Codecov measured candidate 27e81152 at 90.06% across the whole repository and 91.33% for the framework_libraries component, so both candidate views exceed their zero-tolerance 90% targets. This is valid candidate evidence, not evidence for a future commit or tag; the same gates must pass again on the exact frozen RC SHA.

Historical candidate 27e81152 completed all 22/22 applicable automatic push workflows successfully, including the full all-feature workspace suite on Linux, macOS and Windows. It predates the reopened audit and is therefore background evidence only. The post-audit candidate must independently pass its applicable hosted and manually dispatched release matrices.

The later manual campaign on 45fbdbe7 produced passing bounded Miri, Kani and sanitizer evidence, while fuzzing usefully exposed three stale harnesses and a real Unicode-boundary panic in database-URL redaction. Those findings have committed regressions and corrections; the repaired ORM parser plus both affected security targets passed 100,000 local libFuzzer/AddressSanitizer executions. This is remediation evidence, not a substitute for rerunning the complete heavy matrix on the frozen RC SHA.

The two percentages are neither conflicting measurements nor values to average: they answer questions about different path sets. Rullst must keep the whole-repository result primary and must not reuse this candidate’s passing result as proof for a later SHA that Codecov has not measured.

The latest ceiling gain is the umbrella rullst facade’s dedicated shared-local SQLite profile. It composes Auth revocation, Capital quota, encrypted Connect tokens, Mail suppression, encrypted Messaging and Core queueing behind aggregate lifecycle readiness, then proves restart/idempotency, plaintext secret exclusion and isolated fail-closed corruption. It deliberately does not claim a cross-subsystem transaction, whole-file online consistency, key/backup operations or multi-host coordination.

rullst-ai has now earned its audited 95/A local ceiling. In addition to strict opt-in OpenAI-compatible SSE/cancellation, AuditDeliveryClient supplies bounded HMAC-authenticated export and AdaptiveAiEvaluator<P> supplies bounded multi-turn feedback, explicit pass/fail/inconclusive results and a raw-content-free JSON report. Receiver operations, non-compatible provider protocols, exact live-model results and corpus quality remain external or v13 work rather than being mislabeled as v12 guarantees.

rullst facade versus rullst-core

Documentation release gate

Before the v12 RC is tagged, the complete repository documentation remains an explicit review gate: build the mdBook, compile the Rust snippets sourced from all public tutorials, validate local links and anchors, reconcile commands, features and version examples with the frozen manifests, and manually review the upgrade guides and external-provider boundaries. A green documentation build proves structural consistency, not that every external service or store workflow was homologated.

Canonical milestones

Current planning snapshot: 5 implemented, 24 partial, and 9 not started inside the 38-milestone web-framework horizon. M31 is excluded because it is a separately governed safety-critical programme. The weighted planning estimate is 44.7% complete and 55.3% remaining; this is not v12 release readiness and the 33 milestones without strict closure are not 33 blockers for v12.0. The v12 programme owns release gates, while the root roadmap assigns confirmed v12 defects to 12.0.x maintenance and all additive capability work, research or major contracts to v13.

Claims that are impossible as framework guarantees

No useful capability above is dismissed merely because it is difficult. The impossible label is reserved for absolute wording that code in this repository cannot honestly establish:

Use the quality scorecard for per-commit engineering evidence. It is intentionally separate from this functionality view.

Quality scorecard

Audit reopening (2026-09-05): the second-computer CLI handoff and new negative regressions revealed gaps outside the earlier test inventory. Scores and ceiling-completion statements below describe the previous campaign; they are not a current release approval. See the v12 release audit for reviewed scopes, corrections and gates that must pass before reconfirming those conclusions.

Rullst generates an evidence-bound quality scorecard for every push to main and every pull request. The report is attached to the corresponding Rust CI run as quality-scorecard-<commit SHA> and is also written to that run’s job summary.

The permanent source of a run score is therefore the commit plus its workflow run, not a mutable badge. The versioned expert-audit ceilings live in .github/quality-scorecard-policy.json; CI can reduce them when required evidence fails, but a green run cannot inflate them.

What the score measures

Specialist evidence includes database/Redis live matrices, AI evals, the threat minimum, release local-access negatives, provider matrices, the facade’s shared-local recovery composition, and Messaging’s wire/trace, encrypted SQLite and ORM outbox crash-replay cases. Failed, cancelled, or skipped applicable gates suppress the dimensions they prove; the report is still generated so a red push cannot hide its note.

Documentation/DX evidence also includes a Cargo-aware aggregation of the 52 public tutorials. It consumes the Markdown files directly during the normal all-feature doctest run, so a green workspace test proves the standalone Rust examples compile on that SHA; explicitly contextual fragments remain visible as ignored and do not count as compiled examples.

Grades use the following fixed bands: A+ 97–100, A 90–96, B 80–89, C 70–79, D 60–69, and F below 60.

The v12 RC quality objective is A (90) or better for every crate except rullst-iot, whose approved floor is B (80). A+ is an evidence threshold, not a value to assign by intent. This owner-approved gate is deliberately stricter than the earlier all-B floor and reopens bounded implementation work before the feature freeze. It does not pre-approve a commit: the exact SHA still earns each ceiling only when every constraining gate succeeds.

Current audited green-gate scores — 3 September 2026

These are the maximum current scores when every referenced Rust CI gate passes. They are not presumed results for a new commit; the exact per-SHA artifact applies the real gate outcomes and includes the full finding for every row. They are also not the highest scores that future repository-owned work can earn. Here, current audited score means the score supported by code and evidence already present; local campaign ceiling means a planning target that must still be earned. Keeping those columns separate prevents a desired score from being published as an achieved one.

Measured gap to the v12 quality gate

Every non-IoT crate now has an audited ceiling of A or better, while IoT meets its approved B exception. The gap to the required grade is therefore zero. This also closes the repository-owned ceiling campaign, but it does not authorize a release: the exact RC SHA must still make every conditioning gate green, including the dedicated facade composition job.

Maximum-local v12 campaign

The release floor is not the stopping target. The table below records the provisional highest score that the current campaign can responsibly pursue with repository-owned implementation, deterministic fixtures, local services, CI and documentation. These targets do not alter the scorecard policy and must not appear as achieved scores until their evidence is implemented and green on the exact commit.

The campaign is scoped to the 15 non-IoT crates, v12 quality, and the historically promised [x] capabilities. IoT remains audited at its accepted 83/B evidence but is outside the remaining ceiling work. The campaign does not pull every open v13 idea into the RC. External provider acceptance, app-store/device testing, fiscal homologation, independent audit and production operation remain external even when a bounded implementation earns a high A.

All 15 active crates have now reached their audited local target: rullst-core, rullst-macros, rullst-orm-macros, rullst-messaging, rullst-capital, rullst-mail, rullst-auth, rullst-nexus, cargo-rullst, rullst-studio, rullst-orm, rullst-security, rullst-connect, rullst-ai, and the umbrella rullst facade.

On this planning scale, 100% of the maximum-local v12 target is now backed by committed evidence and zero planning points remain. Awarding those points is still conditional on every applicable gate succeeding for the exact SHA; this completion is not a release decision or an external validation claim. rullst-iot is the only accepted campaign result below A; its approved B exception reflects missing physical/device evidence rather than lowering the release gate for the other 15 crates. This table must be re-audited whenever implementation reveals a stronger or weaker boundary.

The final point allocation may differ from these candidate clusters after code review. External provider acceptance, fiscal homologation, device testing, store publication, and independent audit must stay explicitly external even when enough repository-owned evidence exists to reach A.

What the score does not measure

The score is not:

• feature completeness or roadmap percentage;
• a claim that every crate has the same maturity;
• provider acceptance, device/store validation, fiscal homologation, or a security/compliance certification;
• a benchmark or proof that Rullst is better than another framework;
• a substitute for the exact release gates on the candidate SHA.

Those questions belong to the capability status, the capability ledger, and the release evidence. Keeping these axes separate prevents a well-tested bounded foundation from being mistaken for a finished remote integration.

Interpreting changes between pushes

A score should change only when its evidence changes. The per-push review will call out:

1. the previous and current SHA;
2. repository score and changed crate rows;
3. the exact gate responsible for a gain or loss;
4. feature-completeness movement separately, when applicable.

No points are added for code volume, number of features, marketing claims, or raw test count alone.

v12 release audit follow-up

Status: in progress; RC is NO-GO while the findings and final gates below are open. This report supersedes blanket readiness interpretations of the earlier local-ceiling campaign. That campaign and hosted coverage measurements remain historical evidence for their recorded commits, not proof of the current tree.

Baseline and method

The integration baseline is 7743bab3 on fix/cli-logo-animation-speed, including the second-computer report in CLIFIX.md. Its earlier “uncommitted” wording describes the remote review session; that delivery is now committed and fetched here.

Review covers every published crate. IoT receives only a light triage under the owner’s explicit v12 exception. Each deep review traces public inputs through validation, state and side effects, compares documented behavior, and adds negative regressions for reproduced defects. Existing tests alone do not close a finding. Regressions are run before and after corrections when feasible.

This is repository-owned code review and testing, not an independent security assessment, provider certification, or a claim that every line or deployment configuration has been exhaustively analyzed. Tests are serialized on the memory-limited local machine. The final local workspace gate completed after the correction batch.

Evidence-bound repository grade

The authoritative scoring method remains the quality scorecard; this audit does not create a second, more flattering grading system. Under that policy, the reviewed implementation supports a maximum local aggregate of 94/A when all conditioning gates are green. Each of the 15 active non-IoT crates has an A ceiling, while rullst-iot retains the owner-approved 83/B exception because physical device and boot-chain evidence is outside the v12 campaign.

That is an evidence-bounded engineering grade, not a security certification, feature-completeness percentage, independent audit result, or release authorization. A candidate earns the recorded grade only when its exact SHA passes the applicable scorecard constraints. Until the final candidate’s automatic and manual gates, packaging checks, documentation review, and explicit GO decision are complete, the repository remains NO-GO regardless of its provisional grade.

Coverage ledger

Counts above describe separate focused runs and overlap; do not sum them into an invented coverage metric. In addition, the complete workspace test suite passed with all features, and workspace Clippy passed with all targets, all features and -D warnings.

Reproduced defects and correction boundaries

The parser correction also passed the exact local workspace gates: cargo test --workspace --all-features and cargo clippy --workspace --all-features -- -D warnings. This is local evidence only and does not replace the hosted final-candidate matrix.

The adversarial regressions use local databases, mock keys, signed synthetic tokens and loopback HTTP servers—not real credentials or real payment requests. Provider capability corrections are observable behavior changes: callers must handle explicit errors where previous code returned misleading success.

Website, README and first-run documentation

The organization root website and the framework Pages site were different deployments. The old organization site still described main as v5 and dev as v12, and its privacy page asserted unverified worldwide legal compliance. Both entry points now have prepared matching source, with separate deployment receipts still required. The new copy keeps v12 unreleased and v5 end-of-life.

The landing uses local CSS/JavaScript/images, finite reduced-motion-aware animation, thirteen owner-supplied social links and a concrete privacy notice. No analytics, social embeds or browser storage were added. Benchmark templates replace remote fonts with system fonts and pin Chart.js with integrity metadata; the remaining jsDelivr request is disclosed. The README preserves the top and bottom dedication, workflow dashboard, genuine coverage/Scorecard badges and evidence boundaries. It corrects the obsolete frontend-profile advertisement.

The beginner learning page links existing authoritative tutorials instead of creating another competing API reference. Initial guides clarify matching CLI installation, optional persistence, first-build time, actual generator paths and how to verify a visible result.

Verified locally: mdbook build docs, python3 .github/validate-site.py, node --check docs/site.js, and node .github/site-browser-smoke.mjs. The Chromium test passed desktop, 390/320-pixel layouts, keyboard/mobile menu behavior, clipboard success/denial, privacy disclosure, reduced motion, no-JavaScript navigation and no external landing requests or browser storage. The exported organization site also passed with --organization-site; this is not a WCAG or cross-browser certification.

Development reload decision

The public v12 development loop uses supervised process restart. Both cargo rullst dev and cargo rullst dash enable it automatically; plain cargo run remains ordinary execution. The wizard no longer asks for a DLL profile, and the legacy scaffold flag fails with migration guidance.

A successful build precedes stopping the existing child. Compilation errors leave that child serving. Each process runs an owned executable snapshot, so a Windows executable lock does not prevent the next Cargo build. The browser refreshes through a same-origin generation probe after a new server responds. State in memory resets; this does not promise zero-downtime deployment.

The tutorial explains the contract. The v13 decision is evidence-driven: compare measured reload time, failure recovery, process cleanup, memory and state ownership across databases and operating systems before considering a different architecture.

Evidence still required

• Review all changed paths together and freeze the candidate; the broad review above is bounded repository-owned evidence, not an independent audit.
• Repeat the real HTTP/Chromium acceptance pass for the representative Blog application on the final candidate; materialized compile/test contracts for every generated blueprint are already green.
• Review CI/dependency/security alerts and run the applicable manual release matrices on the actual candidate commit.
• Repeat the complete 40-target hosted fuzz campaign after the bounded parser diagnostic correction; the first campaign is evidence for 39 targets, not a pass that can be carried onto the replacement commit.
• Repeat package/preflight, site/browser and documentation checks on that candidate.
• Reassess quality/readiness using these results; do not carry forward 91.8% readiness or 100% local-ceiling completion as current audited facts.

Residual limitations for the next reviewer

• HTML escaping does not make RawHtml, custom escaping implementations, JavaScript contexts or URL policies safe automatically. RPC parameters are untrusted inputs, not identity assertions.
• Some direct session/passkey helpers depend on caller input-size bounds even when HTTP middleware limits requests. Cookie isolation matters for the unsigned double-submit scheme. Local rate controls are not distributed limits.
• OIDC fixtures do not establish live-account acceptance, JWKS stampede resistance or multi-host atomic callback consumption.
• NFS-e remains preparation/offline evidence, not official fiscal authorization. Payment fixtures do not homologate providers or fully model every event schema.
• SQLite cancellation tests prove rollback ownership before commit; they cannot make cancellation during a dispatched commit into exactly-once knowledge.
• Some older route smoke tests accept unavailable-database responses and prove route presence only. Real SQLite behavioral tests are identified separately.
• IoT received only the agreed manifest/README review. No physical devices, browser WebAuthn ceremony, store signing, live provider or deployment proxy certification was performed.

Evidence handling

Confirmed security defects remain local until corrections and regression evidence are ready for a coordinated commit. Findings are classified by impact, not by whether the previous scorecard happened to be green. Provider behavior that cannot be completed within the current v12 contract must fail explicitly and be documented as unsupported; mock success is not live-provider evidence.

Repeatable focused verification receipts

These focused commands and the final local preflight succeeded during the September 5–6 correction batch. The September 8 PR #183 tree, merged as adb83c8b, independently repeated cargo test --workspace --all-features, strict all-feature workspace Clippy, formatting and diff checks successfully:

CARGO_BUILD_JOBS=1 cargo test -p cargo-rullst --lib -- --test-threads=1
CARGO_BUILD_JOBS=1 cargo test -p rullst-core --lib server::dev_reload -- --test-threads=1
node rullst-core/src/server/dev_reload/client_tests.cjs
CARGO_BUILD_JOBS=1 cargo test -p rullst-nexus --lib --tests -- --test-threads=1
CARGO_BUILD_JOBS=1 cargo test -p rullst-security --lib rate_limit::tests -- --test-threads=1
CARGO_BUILD_JOBS=1 cargo test -p rullst-ai --lib
CARGO_BUILD_JOBS=1 cargo test -p rullst-mail --features sqlite --lib
CARGO_BUILD_JOBS=1 cargo test -p rullst-connect --features axum-session,sqlite --lib
CARGO_BUILD_JOBS=1 cargo test -p rullst-capital --features actix --lib --tests
CARGO_BUILD_JOBS=1 cargo test -p rullst-capital --features actix --lib middleware_rejects_duplicate_standard_webhook_headers
CARGO_BUILD_JOBS=1 cargo test -p rullst-messaging --features sqlite -- --test-threads=1 --quiet
CARGO_BUILD_JOBS=1 cargo clippy -p cargo-rullst -p rullst-core --lib -- -D warnings
CARGO_BUILD_JOBS=1 cargo clippy --workspace --all-targets --keep-going -- -D warnings
CARGO_BUILD_JOBS=1 cargo test --workspace --all-features
CARGO_BUILD_JOBS=1 cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
git diff --check
bash .github/check-historical-roadmap-ledger.sh
bash .github/check-crate-architecture.sh

ORM default/strict-SQLite/Redis and macro compile-fail results are recorded in the coverage ledger. Live-service backend verification remains distinct from the passing all-feature compile, lint and local workspace gates.

Website maintenance and privacy boundaries

The public entry points have different deployment sources:

The landing design and copy have one editable source: docs/home_template.html, docs/site.css and docs/site.js. Preserve the footer dedication and the v12 preview/v5 end-of-life notice. Use actual source and release evidence for claims; do not hardcode aspirational coverage, scorecard, speed or certification values.

Validate before deployment

From the framework checkout, using Node 24 and a locally installed Chromium (google-chrome, or set CHROME_BIN):

mdbook build docs
python3 .github/validate-site.py
node --check docs/site.js
node .github/site-browser-smoke.mjs

The browser test checks desktop and 390/320-pixel layouts, keyboard and mobile navigation, clipboard success/denial, privacy disclosure, reduced motion, no-JavaScript navigation, resource failures, CSP errors, external requests and browser storage. It is not a complete accessibility audit or cross-browser certification. Optional --screenshots /absolute/output/directory records viewport previews without adding binary artifacts to the repository.

The source landing has no analytics, social embeds, remote fonts, cookies or local/session storage. CSS and JavaScript are local; ambient, hero, workflow and scroll-reveal motion is finite, progressively enhanced and disabled by the reduced-motion preference. Content stays visible when JavaScript is unavailable. Clipboard access follows an explicit button click and copies only the displayed command.

Hosting still processes requests. The privacy notice links GitHub’s statement and does not promise control of its logs or retention. Benchmark dashboards load integrity-pinned Chart.js from jsDelivr; documentation can store display preferences and contain external content. Do not extend the landing’s narrower description to those surfaces or to user-built applications. New tracking, embeds, forms or storage require a fresh privacy review before deployment.

Keep the organization website synchronized

Preserve any work in the separate website checkout before running the exporter:

node .github/export-organization-site.mjs /path/to/clean/Rullst.github.io
node .github/site-browser-smoke.mjs --organization-site /path/to/Rullst.github.io

The exporter refuses a dirty tree or wrong repository. It replaces only the five known website files, derives privacy.html from the landing notice and does not commit, push or deploy. Review the diff and deploy matching framework documentation first, then the organization website. Keep independent commit and deployment receipts for each repository. A framework push alone does not update the organization’s root landing page.

The footer’s thirteen destination links are the owner’s supplied community list. Instagram, TikTok and YouTube handles are normalized to full profile URLs. These are normal links, not embedded feeds or a claim that account availability has been independently verified. Recheck ownership and links when the owner changes that list.

Rullst Academy product programme

Status: proposed reference product, not a shipped framework capability. Academy must live in a separate repository and depend only on published Rullst packages. Its operation is evidence for the framework; its product content and deployment are not part of the rullst crate.

Rullst Academy is a web-first platform for learning Rust and Rullst through short explanations, authoritative interactive exercises, review sessions and small practical projects. The target is an enjoyable learning product, not a claim that a framework can automatically produce good pedagogy or a universally better alternative to an existing course.

Product boundary

The browser-accessible web application is canonical. Server-side code owns identity, school scope, authorization, course versions, grading, progress, achievements and audit. Omni shells may later add narrowly scoped native capabilities without becoming a second security or business model.

The Academy repository must:

• pin one exact Rullst RC or stable release and contain no monorepo path dependencies;
• use public CLI scaffolds and escape hatches instead of private framework modules;
• keep curriculum, content, product UI, deployment and learner support in the application;
• contribute only proven, reusable abstractions back to optional framework crates;
• act as the first real upgrade, backup/restore and recovery consumer before a Rullst stable release is declared ready.

Focused first release

The first useful Academy release should complete one narrow journey well:

1. A learner creates an account, joins the appropriate school and enrolls in a published course.
2. The learner reads or watches an accessible lesson and resumes recorded progress.
3. A server-authoritative quiz, matching or typed-recall activity records an idempotent result without accepting client-authored points.
4. The review queue schedules a later activity and an achievement or certificate is derived from persisted rules.
5. A practical project is submitted to a constrained runner and receives deterministic test feedback.
6. An instructor drafts, reviews and publishes content; an administrator can audit the resulting events without crossing school boundaries.

Polish should concentrate on this journey: responsive SSR, keyboard operation, visible focus, reduced motion, clear errors, fast navigation and useful empty states. Payment, social features, advanced gamification, native-store releases, offline synchronization and a large course catalogue are not prerequisites for the first release.

Initial curriculum and projects

Two short tracks are enough to validate the product:

Every exercise must have a versioned ruleset, bounded input/output and retained test identity. Curriculum authors, not an LLM, define the expected concepts, tests, hints and completion conditions.

Safe practical-code runner

Learner code is hostile input. It must never execute inside the Academy web process or through a mounted host Docker socket. The application-owned runner must use a disposable rootless container or stronger microVM boundary with:

• no network by default and no cloud/application credentials;
• read-only base images and a fresh writable workspace per attempt;
• explicit CPU, memory, process, file, disk, output and wall-clock limits;
• a reviewed Rust toolchain/dependency policy and immutable image digest;
• bounded compile/test logs with control-character handling and secret redaction;
• an idempotent submission identity, queued execution, cancellation and terminal retry/dead-letter policy;
• cleanup after success, failure, timeout and worker restart;
• adversarial escape, fork-bomb, filesystem, network and output-amplification tests before public use.

The runner returns structured test evidence. It does not grant points directly; the Academy service binds that evidence to the authenticated learner, project version and server-owned scoring policy.

Local AI mascot

The mascot can be a friendly tutor backed by the existing Ollama path in rullst-ai, with a deterministic offline fallback for tests. It should use a bounded RAG corpus containing version-pinned official Rust material, Rullst documentation and Academy-authored hints.

The mascot may explain an error, ask a guiding question, retrieve a relevant lesson or suggest the next exercise. It must not:

• authoritatively grade code, invent completion or change persisted points;
• execute arbitrary tools or learner code outside the sandbox boundary;
• retrieve another learner’s conversation, submission or school data;
• receive secrets, raw session values or unnecessary personal data;
• present an uncited generated statement as official Rust or Rullst behavior.

Responses should carry source references and a visible “local AI tutor” label. Provider/model unavailability must leave the curriculum and deterministic grader usable. Prompt-injection regressions, context limits, tenant binding, PII masking and secret-minimized audit remain mandatory.

What exists and what remains application work

Repository and release boundary

Academy will be developed in a separate repository and conversation. This document records only the intended boundary and the reusable framework foundation that already exists; it does not authorize further Academy work in the Rullst repository and it is not a framework release gate.

• v12.0: close the framework independently through its coverage, CI/package/security, upgrade and release-candidate gates. Academy does not need to exist or run against the RC.
• v12.0.x: maintenance only for confirmed framework defects and security fixes, without an Academy capability programme.
• v13: the next feature line. Reusable improvements discovered by the future external Academy may be proposed with their own bounded contracts; research-heavy or breaking work remains explicitly governed by v13 criteria.

The 32 canonical milestones that are not fully closed belong to the long-term v13 horizon. They are not release blockers for v12.0, and Academy itself is not part of that milestone denominator.

Acceptance evidence

Before Academy can be treated as release evidence, record all of the following against immutable application and framework SHAs:

• the complete learner/instructor/admin journey on PostgreSQL, with SQLite kept as a local profile only when its declared limits are acceptable;
• anonymous, cross-user, cross-role and cross-school denial tests;
• browser accessibility and responsive-layout checks for the primary journey;
• sandbox abuse tests and bounded compile/test output;
• backup restoration, forward migration, rollback and framework-upgrade drills;
• dependency-only installation from crates.io with no Rullst path overrides;
• load and failure tests with unavailable AI, mail, cache and worker services;
• a documented human GO/NO-GO decision and remaining product risks.

Related reusable guides include accessible Academy media, server-authoritative activities, durable spaced review, tenant-bound RAG, and the assisted upgrade workflow.

The Rullst philosophy

Rullst exists to make ambitious software feel possible in Rust without hiding the language, the generated code, or the boundaries that keep an application safe. It aims to be productive and broad, but its convenience must remain inspectable: static dispatch, compile-time generation, typed errors, explicit middleware, and ordinary Rust escape hatches are deliberate choices.

A story that stayed with us

A widely reported account of Rust’s origin begins with a broken elevator in Graydon Hoare’s apartment building. Its software had crashed, leaving him to climb the stairs. Rust itself began as Hoare’s personal project in 2006 and grew into a language designed to combine systems-level performance with much stronger memory-safety guarantees.

The elevator account is an origin story reported by MIT Technology Review, not a claim that every elevator failure was a memory bug or that Rust can make all software infallible. The lesson Rullst takes from it is narrower and more useful: when an entire class of failure can be prevented by design, prevention is better than asking every developer to rediscover the same danger.

Why Venelouis started Rullst

Rullst also has its own practical origin. Long before modern AI systems became capable coding partners, Venelouis wanted to build an education platform. He first learned what was possible by operating a Moodle installation on a VPS. Later, Laravel and AI helped him create a far more ambitious education product than he had previously believed he could build.

That experience made Laravel’s greatest strength tangible: a framework can let one person concentrate on the product instead of repeatedly assembling its foundations. Venelouis then wanted to rebuild that kind of product in Rust to use fewer resources, gain performance, and inherit Rust’s stronger compile-time guarantees. He could not find a Rust framework that combined the particular Laravel-like product workflow, breadth, approachability, and explicit security boundaries he wanted. Rullst began as an attempt to build that missing bridge.

Rullst is not a Laravel clone, and Rust should not be forced to behave like PHP. The inspiration is the feeling that a complete product is within reach; the implementation follows Rust’s strengths rather than concealing them.

Why Rullst jumps from version 5 to version 12

The version jump records the history of the ecosystem rather than six hidden major releases of the unified framework. When Venelouis began recreating creio.eu in Rust with AI assistance, the Gemini model he was using at the time told him that there was no direct Rust counterpart to Laravel Socialite for the workflow he needed. Instead of abandoning that part of the product, he created the first independent Rullst crate. That project became rullst-connect, which still carries the identity and social-login mission of that original work.

The crates initially evolved in separate repositories and at different speeds. By the time the umbrella Rullst framework was at version 5, rullst-connect had already reached version 11. Bringing the projects into one monorepo made their dependency changes, cross-crate compatibility tests, and coordinated releases easier to maintain. Aligning every publishable package on one version line was the natural next step.

A clean reset to 1.0 might have described the beginning of this unified era, but a registry history cannot be reset that way: crates.io does not permit a published version to be overwritten or removed, and lower new versions would not erase the already published higher ones. Rullst therefore advances the whole ecosystem directly to version 12, monotonically beyond Connect’s version 11. From the version 12 line onward, coordinated releases can follow the usual Semantic Versioning sequence. The jump is thus an act of package alignment and honest continuity, not a claim that standalone Rullst versions 6 through 11 were released as complete framework generations.

Core tenets

1. Productive, not magical. Rullst coordinates routing, data, identity, security helpers, background work, AI, and developer tooling through APIs and generated source that users can inspect and replace.

2. Simple to begin, explicit when it matters. Good defaults should remove repetitive setup. Authorization, tenancy, provider behavior, persistence, deployment, and recovery must still expose their real application-owned decisions.

3. Prevent failure classes by design. Typed errors, bounded inputs, parameterized queries, compile-time generation, and fail-closed behavior are preferred to conventions that only work when every caller remembers them. This reduces risk; it does not create a universal security guarantee.

4. Built for humans and AIs. Stable vocabulary, focused modules, static contracts, executable examples, and documented limits give human developers and coding agents a shared map of the system. AI assistance never replaces review, testing, or accountable approval.

5. Evidence before claims. A feature claim must name its implemented scope and residual boundary. A test belongs to the revision and environment it exercised. Benchmarks describe measured workloads, not universal rankings.

6. Emotional productivity matters. The framework should make builders feel capable, curious, and supported. Removing boilerplate is valuable when it leaves more attention for users, learning, and the purpose of the product.

The ambition and the boundary

The long-term ambition is deliberately large: make Rullst a foundation from which people can build many kinds of applications without surrendering Rust’s performance or explicitness. That ambition is a direction, not a promise that one framework can finish every product, operate every provider, or replace the judgment of its developers.

Rullst will therefore grow through bounded, reviewable capabilities. Where the repository has proof, the documentation should show it. Where real devices, provider accounts, production operations, independent review, or application policy are still required, the documentation should say so plainly. The goal is not to look complete. It is to keep becoming more useful without losing the trust of the people building with it.

Getting Started

Welcome to the Rullst Getting Started guide!

Your goal: install the matching preview CLI, generate a small application, open it locally and make your first change. Prefer to write the first route yourself? Use Zero to Hello Rullst.

Rullst is a strictly typed Rust framework suite for full-stack applications, designed around explicit APIs, measurable performance, and defense-in-depth defaults.

1. Installation

First, ensure you have Rust installed. The official and recommended way is to visit rustup.rs.

For macOS and Linux:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

For Windows: Download and run rustup-init.exe from the website.

Next, install the Rullst CLI from the same release train as the framework. The registry command installs the latest published release; it does not install the unreleased v12 source documented by this branch:

cargo install cargo-rullst

To evaluate v12 before its first RC is published, clone this repository and install the CLI from that exact checkout instead:

git clone --branch main https://github.com/Rullst/Rullst.git
cd Rullst
cargo install --locked --path cargo-rullst
cd ..

During this source-only phase, the pre-release CLI reuses the exact checkout from which it was compiled, even when project creation is invoked from another directory, provided that checkout has not been moved or deleted. Generated manifests therefore contain absolute path dependencies and are not portable yet. Running from the repository root remains an explicit fallback. Once an immutable v12 RC exists on crates.io, install that exact CLI version and use its matching registry packages instead.

2. Creating Your First Project

We have completely redesigned the project creation experience. Instead of remembering complex flags, just run:

cargo rullst

The Rullst App Creator will launch an interactive wizard. The example below creates a Portfolio while v12 remains unpublished:

1. Select Create New App.
2. App Name: Provide a simple lowercase name (e.g., my_portfolio).
3. Starter Blueprint: Choose Portfolio. Labels and decorative suffixes can change; use the blueprint name as your reference.
4. Choose your primary database. SQLite is the simplest local first run; PostgreSQL, MySQL and MariaDB require their database service to be running.
5. Leave optional persistence capabilities empty unless you need an add-on. That selector accepts zero or more choices; it is not another required database.

cd my_portfolio
cargo rullst dev

Open the local URL reported by the command. Find the generated page code, change a heading and save. Confirm that the changed page appears after the successful rebuild/restart. Stop development with Ctrl+C before moving or removing the project directory.

Prefer a small deterministic starter without navigating the wizard?

cargo rullst new first_app --default --blueprint blank --database sqlite \
  --skip-initial-migration
cd first_app
cargo rullst dev

The first source build can take several minutes. --skip-initial-migration defers the generator’s bootstrap work; the development command runs the initial migration before starting a generated database-backed app. Never point this learning project at a production database.

Tip

The cargo rullst dev command compiles the project and starts the local server. Saving changes triggers a real rebuild and supervised process restart; a failed build leaves the previous application serving. The same-origin browser client refreshes after the new process responds with its generation marker. In-memory state resets. No hot-reload scaffold option is required. See the CLI reference.

Rullst v12 deliberately generates one audited application profile: Active Record with server-rendered html! views and HTMX enhancement. The framework still exposes lower-level repository and client-runtime foundations for application-owned integration. See the Architecture Choices Guide.

3. Rullst Blueprints Showcase

The Rullst framework accelerates your development by providing Blueprints. A Blueprint is a highly-polished, pre-built application template that serves as the foundation for your project.

When you run cargo rullst, the wizard asks you to select a blueprint. The blueprints use the Rullst color scheme and server-rendered HTML/HTMX patterns; allocation and latency depend on the generated page and runtime.

1. Blank Starter

Use Case: Custom, from-scratch development. This is the minimal template powered by server-rendered html! views and HTMX without a project-local JavaScript bundle. It includes a simple reactive counter to demonstrate server-driven communication. Other frontend foundations remain available as application APIs, but v12 does not advertise them as equivalent generated blueprints.

2. Portfolio 🔥

Use Case: Developer showcases and personal branding. Status: HOT! A visually stunning, glassmorphic portfolio template designed specifically for Rullst/AI developers. It includes:

• Profile Settings in Nexus CMS (/nexus): Edit your name, title, bio, email, website URL, avatar photo, GitHub, and LinkedIn links live without changing code.
• A responsive sidebar and Hero section with glowing glassmorphism effects.
• Interactive Experience timeline and Skills tags.
• Project cards showcase with live external links.

3. LMS Platform Starter

Use Case: Online learning products and course platforms. The complete profile is a bounded learning-domain foundation featuring:

• School-scoped curriculum, enrollment, progress and versioned publication.
• Quizzes, learning activities, assignments/rubrics, completion records and database-verifiable certificates.
• Roles, leaderboard updates, transactional outbox/workers, scheduling and localized in-app notifications.
• Accessible server-rendered catalog, course and media-player shells with explicit source, caption and transcript admission rules.

It remains a starter rather than a finished education product. Upload hosting, media transcoding and signed delivery, advanced/localized search, billing-linked entitlements, distributed failover, native offline playback, real-browser/WCAG evidence and PostgreSQL/MySQL isolation evidence remain application or roadmap work. Smaller auth, auth,learning and auth,learning,assessment profiles are available when the complete domain scaffold is unnecessary.

4. SaaS App Starter

Use Case: Subscription-based products and billing. An opinionated SaaS starting point, pre-wired with:

• User authentication (login, signup, session management).
• Stripe pricing panels and subscription checkout views.
• Secure user dashboard.

5. Blog / Press

Use Case: Content creation and articles. A database-backed, server-rendered blog/CMS blueprint. It features:

• A beautiful article reading view with typography optimized for readability.
• Article CRUD and a server-rendered reading view. Markdown parsing is not part of the current generated starter.
• SEO-friendly metadata injection.

6. ERP Pocket

Use Case: Business management, stock, and inventory tracking. An inventory-oriented back-office starter. It features:

• A complex relational database schema (Products and Orders).
• Full CRUD operations with HTMX.
• A sleek, split-pane dashboard for simultaneous product listing and order creation.

Tip

Blueprint evolution: Blueprints are continuously checked by generator smoke tests. Treat generated code as an application starting point: inspect its configuration and rerun cargo check and security tests after customization.

Local Studio and Nexus access

The Blog, Portfolio, LMS, ERP, and SaaS blueprints expose visible buttons for both control surfaces during local development:

• Nexus is mounted at /nexus and accepts only a verified loopback peer in a debug build, so the first local click needs no placeholder password.
• Studio starts as a separate debug-only service at http://127.0.0.1:5555.

This convenience cannot be enabled in a release binary through RULLST_ENV or the legacy APP_ENV alias. A release build does not start the generated Studio task and requires unique NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD values before Nexus can be constructed. Put production Nexus behind a verified TLS boundary and explicit application authorization; do not expose Studio publicly.

5. Database configuration and specialized stores

The wizard deliberately makes two separate decisions:

1. Choose the primary SQLx Active Record backend: SQLite, PostgreSQL, MySQL, or MariaDB. MariaDB uses the MySQL wire protocol but has its own executable container contract. The blank/API starter can instead select Turso/libSQL as its primary typed ORM.
2. Optionally add Turso/libSQL edge SQL to a SQLx application, MongoDB documents, DuckDB analytics, or SurrealDB documents/graph reads. These use explicit capability APIs and do not silently replace the primary pool.

After generation, the default flow compiles the new application once and runs its initial migration. A clean first build can take several minutes for larger blueprints. Use --skip-initial-migration when the network database is not yet configured, then run cargo rullst db:migrate from the generated project.

The non-interactive flags mirror the second step:

cargo rullst new edge_app --default --database mariadb --turso --mongodb \
  --skip-initial-migration

Automation can pin the supported blueprint, database and optional runtime capabilities. The v12 application architecture is intentionally fixed to Active Record plus server-rendered html!/HTMX:

cargo rullst new learning_portal --default --blueprint lms \
  --database postgres --ai \
  --skip-initial-migration

For a blank application with no primary relational database, use the explicit --no-database flag. It cannot be combined with --database. Generated SQLx profiles disable Rullst’s umbrella defaults and select exactly one strict relational backend, so a chosen PostgreSQL/MySQL/MariaDB profile is not accidentally compiled through an implicit SQLite default.

To create a Turso-primary API using the current bounded blank starter:

cargo rullst new edge_app --default --api --database turso \
  --skip-initial-migration
cd edge_app
cargo rullst db:migrate

The generated .env selects a persistent, real-SQL offline fallback and does not invent a SQLx DATABASE_URL:

TURSO_DATABASE_URL=mock_local
TURSO_AUTH_TOKEN=
TURSO_OFFLINE_PATH=turso-development.db

To use Turso Cloud, put the token in its own variable rather than in the URL:

turso db create my-app-db
turso db tokens create my-app-db

TURSO_DATABASE_URL=libsql://my-app-db-username.turso.io
TURSO_AUTH_TOKEN=replace-with-a-secret-token

The familiar derive explicitly selects the Turso backend:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "users", backend = "turso")]
struct User {
    id: i64,
    name: String,
}
}

User::all(), find, save, create, delete, count, filtering, ordering and pagination then execute through the primary TursoOrm store. make:model --migration, make:migration, db:migrate, db:status, and db:rollback preserve this backend. The current first-class scaffold contract is deliberately limited to the blank/API profile; SQLx-specific LMS, SaaS, blog, portfolio, and ERP blueprints reject --database turso until ported. Transparent embedded-replica synchronization is not claimed.

TursoStore remains available for prepared SQL, bounded result materialization, transactions and checksummed migrations in either primary or additive configurations. See Polyglot Persistence for complete setup, security constraints and examples for every optional store.

Architecture choices in generated projects

cargo rullst new records product capabilities that materially change the generated application. Version 12 intentionally exposes one audited application architecture instead of presenting incomplete compatibility markers as equal implementations. The framework specification and capability ledger remain authoritative.

ORM style

Version 12 database-backed projects are generated with Active Record. The CLI does not ask for a global ORM architecture and does not expose an --orm flag. The framework’s repository APIs remain available when an application needs an explicit persistence boundary.

Earlier v12 prerelease menus offered three labels, but Repository and Hybrid shared generation branches and support varied by blueprint. Removing those selectors does not remove ORM APIs; it prevents the generator from claiming equivalent end-to-end profiles before the generated routes, services and tests support them consistently. All database operations still need parameter binding, authorization and transaction design.

For most CRUD-oriented applications, start with Active Record and introduce a repository around domains that genuinely need a separate persistence boundary.

Database engines and capabilities

The first database selector chooses exactly one SQL Active Record backend:

A second multi-select adds zero or more independent capabilities and accepts Enter with no selection. Capabilities already selected by the primary profile or CLI flags are omitted. Turso supplies explicit edge SQL, transactions and checked migrations; MongoDB supplies portable document CRUD; DuckDB supplies bounded analytics; SurrealDB supplies document CRUD and bounded read-only graph queries; Qdrant supplies bounded dense-vector operations. Selecting one adds the precise Cargo features and environment keys, but does not make every model portable between different database families.

This split prevents a Turso, MongoDB, analytics, or graph label from generating an application whose SQL Active Record migrations cannot run. See the Polyglot Persistence guide for the APIs and limits.

Frontend profile

Version 12 generates server-rendered html! views with HTMX enhancement and does not ask for a frontend engine or expose a --frontend flag. The five labels shown by earlier prerelease wizards were not five complete, interchangeable renderers:

Version 13 should model independent capabilities instead of one misleading global frontend selector: rendering (SSR or API), interaction (HTMX, LiveView or Wasm islands), styling (the bundled design or an explicitly materialized CSS system), and templating (html! or a fully generated file-template path). A combination should appear only after its assets, routes and browser behavior have equivalent tests.

Full-stack versus headless API

• Full-stack blueprints include server-rendered routes and relevant local tool integration.
• --api generates a JSON-oriented Blank project without HTML view rendering; product blueprints reject it instead of silently retaining their HTML routes.

Generated code is application code. Review its routes, auth boundaries, database schema and dependencies before deployment.

Optional AI

Selecting AI adds rullst-ai and its provider-agnostic client foundation. Providers still require explicit credentials or the documented deterministic mock mode. Ollama can keep prompt traffic on infrastructure you operate, but “local” alone does not establish an air gap. Measure compile time, binary size, latency, quality and cost for the chosen provider and model.

Cache and queues

Without Redis, Rullst offers process-local memory cache and local queue options. With Redis selected, the generated project can configure the feature-gated Redis adapters.

There is deliberately no silent production fallback from Redis to memory: a distributed deployment that loses Redis must not pretend that independent process-local state is equivalent. Choose the backend explicitly and test its failure policy. Core realtime broadcast/presence remains in-process; Redis cache and queue support does not turn it into distributed WebSocket pub/sub.

Studio and Nexus

• Studio’s supported v12 launcher is debug-only, binds to loopback and verifies direct peer information. It shows only data supplied by real local probes.
• Nexus uses a local-development policy or explicit release credentials. A dependency or generated route does not remove the need for application RBAC.

Neither interface should be exposed publicly without an application-owned identity, authorization, TLS and network policy.

Omni packaging

Rullst uses a web-first, platform-enhanced model. The web application is the canonical universally reachable product; the server remains authoritative for domain rules, authentication, authorization, persistence, realtime and security. Omni may package that interface and later add scoped native capabilities, but it must not fork the business model or trust a client-side decision as authority.

cargo rullst make:omni scaffolds a Tauri-powered shell and commands for desktop and mobile targets. Deterministic generation pins the local Tauri CLI, requires an explicit validated backend URL and application-owned identifier for mobile, derives or validates product metadata, generates real platform icon assets and fails when an explicitly requested platform cannot be initialized. The packaged bootstrap exposes no remote IPC. A native navigation policy allows only Tauri’s local origin and the configured backend’s exact origin, leaving OAuth/external links for a reviewed system-browser/deep-link contract.

rullst::client_contract supplies one shared rullst.client v1 JSON boundary for browser, server and future platform-enhanced code. It negotiates positive versions, rejects unknown outer fields and oversized bodies, and carries typed payloads, correlation, optional mutation idempotency, server time and bounded failure codes. It deliberately has no user/tenant/role claim: authentication, authorization, domain validation and durable replay handling remain server work. This is a transport foundation for rich clients, not offline sync.

The opt-in native offline-sync profile builds a bounded state machine on that transport boundary. It keeps cached server records separate from queued local proposals, requires unique idempotency keys, uses explicit server revisions and cursors, isolates conflicts from automatic replay, and makes incremental/full resync transitions atomic within the state value. Its encrypted v1 snapshot is AES-256-GCM authenticated to an exact account and rotation-key id. The framework adds a static-dispatch foreground coordinator with request budgets, mandatory timeouts and cursor-progress checks, but does not choose client-wins, accept cached authorization, own a platform key, or silently write/contact an arbitrary filesystem, browser store or endpoint. Keychain/Keystore, atomic platform persistence, concrete authenticated HTTP, retry/background scheduling and later schema migrations remain application/platform decisions until dedicated adapters have evidence.

Path-aware workflows generate disposable applications and check desktop on Linux/macOS/Windows, an Android debug APK and an iOS simulator target. All three passed for commit 755fbd61933bed04369e0eb5de50b11275db5e3d.

That gate proves reproducible generation and simulator compilation only. It does not automatically mount offline synchronization, secure remote networking, platform signing, privacy declarations, physical-device behavior, store publication, native updater policy or every frontend profile. Push, biometrics, OS secure storage, deep links and offline state must be opt-in, least-privilege additions with platform tests. Treat the generated shell as application-owned packaging code that must be reviewed, signed and tested on each supported target.

Engineering invariants

Repository policy requires typed failures rather than production panic!, unwrap() or expect(), explicit SQL parameterization/sanitization, and the workspace test/Clippy/format gates. These are review and CI rules, not a claim that arbitrary application code or third-party dependencies cannot panic.

Rullst exposes Axum/Tower integration so applications can add middleware and routes directly. That escape hatch also means the final security and observability composition belongs to the application.

Practical starting points

• Single-process CRUD application: use the generated Active Record, html! SSR and HTMX profile with memory cache.
• Domain-heavy service on v12: introduce repositories per module with explicit transaction boundaries. In v13, select a Data Mapper / Repository project profile only after its blueprint has full generated-route and test parity.
• Multi-process application: a configured shared cache/queue plus deployment tests; do not assume realtime is distributed.
• Rich browser interaction: opt into LiveView or Wasm foundations only with application-owned integration and browser tests until a complete v13 profile exists.

Revisit these choices as evidence changes. Do not infer performance, security or availability from a wizard label.

Rullst AI: Developing with Autonomous Agents

Rullst is designed as an AI-native Rust framework. Here that term describes inspectable code-generation and explicit compile-time contracts; it is not a claim of historical priority or proof that an AI will produce correct code.

Some framework designs use runtime reflection, string-based dependency injection, or conventions that are harder to discover through static source inspection. Rullst instead favors visible types and generated Rust, while still retaining ordinary runtime state and framework abstractions where appropriate.

Rullst favors strong typing and compile-time diagnostics. The compiler catches type and ownership errors in generated code, but it cannot validate requirements, security intent, or business correctness; AI-generated changes still require review and tests.

For runtime LLM integrations, consult the machine-readable and documented provider capability matrix. Streaming, native tools, built-in deadlines/retries, and explicit cancellation are not implied by the existence of a provider adapter.

Local Rust tools use a separate guarded execution boundary with an exact allowlist, principal authorization, closed JSON schema, payload limits, call budget and mandatory audit sink. Destructive and financial calls also require a one-use approval bound to the exact payload.

1. Repository instructions for coding agents

The Rullst repository maintains a root AGENTS.md for contributors. The current cargo rullst new scaffold does not copy AGENTS.md, .ai-rules, or tool-specific instruction files into an application. Add reviewed project-local instructions yourself when using an autonomous coding tool; do not assume the framework’s repository policy applies to generated application code.

cargo rullst generate:ai-context can generate .llms.txt from recognized project dependencies and source directories. That snapshot can help a coding assistant navigate the application, but it is not an instruction-policy file and should be regenerated and reviewed after structural changes.

Example of the default content:

1. **Static Dispatch over Dynamic**: Prefer static dispatch (`impl Trait` or generics) over `dyn Trait` to ensure explicit concrete types for AI context tracking and optimization.
2. **Explicit APIs**: Avoid hidden state. Every controller and middleware should be explicit in its arguments.
3. **HTML Macros**: Boolean attributes in the `html!` macro must be quoted (e.g., `required="true"`).
4. **No Panics**: Never use `unwrap()` or `expect()` in production routes.

2. Rullst’s AI-Friendly Patterns

Rullst’s API is designed to give coding tools more explicit source landmarks; this can reduce ambiguity but does not measure or guarantee hallucination rates:

• Explicit Routes: The routes![ ... ] macro is visual and delimited. The AI knows exactly where to add a new route without having to search across scattered files.
• Rullst ORM: Based on Pure SQL (via SQLx) + Derives. AIs are much better at writing pure, correct SQL queries than learning an obscure query builder. Rullst takes advantage of this by using the database in a pure relational way.
• Clean Background Workers: The queue system does not require complex global registration; you simply create an async function.

3. How to Get the Best Results

When instructing an AI to add a feature in Rullst:

1. Ask it to read the instruction files that actually exist in your application and consult the matching version of the Rullst documentation.
2. Say: “Create a new Controller following the pattern established in auth_controller.rs”. Today’s AIs are brilliant at pattern matching. Rullst provides the skeleton, the AI fills in the meat.
3. Use the generators! Ask the AI to use cargo rullst make:controller in the terminal (if it’s an autonomous agent), ensuring the correct file structure.

Rullst Studio: local development control room

Rullst Studio is a developer-facing Axum dashboard. It can run as a standalone server bound to 127.0.0.1 (port 5555 by default) or its router can be mounted explicitly by an application.

Studio’s built-in boundary is deliberately limited to debug builds and verified loopback peers. It is not a shared-environment authentication system; do not expose raw subrouters publicly without application-level authentication, authorization, TLS, and network policy.

Generated Blog, Portfolio, LMS, ERP, and SaaS applications start the standalone server only in debug builds and link to http://127.0.0.1:5555. Release builds do not start it; runtime RULLST_ENV or legacy APP_ENV values cannot override that compile-time boundary.

Running Studio

The CLI can launch the local server:

cargo rullst studio

The library entry point is also available:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    rullst_studio::run_studio(5555_u16).await
}

Studio::new().into_router(LocalStudioAccess::loopback_only()) builds the same debug-only router for explicit composition. The serving stack must preserve Axum ConnectInfo<SocketAddr> or requests fail closed. Optional OpenAPI and queue views are enabled with with_openapi and with_horizon. with_cache opts a supported cache into metadata-only local inspection, while with_distributed_traces supplies the bounded store shared with a separately mounted push-only ingestion router.

Current views

• /studio: data browser and dashboard shell.
• /studio/radar: runtime probes and recorded spans. Process CPU sampling is implemented for Linux and Windows and the KPI cards refresh from /api/radar every two seconds. The first delta-based CPU sample, unsupported platforms, and disconnected probes display Unavailable; Studio does not synthesize a healthy value.
• /studio/security: counters and events emitted by the in-process security store. Audit-chain integrity displays Unavailable until a verifier is connected.
• /studio/capital: the in-process revenue view; it is not an accounting ledger.
• /studio/traces: local spans plus authenticated attribute-free distributed records and explicit slow/repeated SQL-label heuristics.
• /studio/cache: metadata-only view of an explicitly supplied Memory/Redis cache, using opaque identifiers and one-entry invalidation.
• /studio/migrations, /studio/ai, /studio/env, /studio/features, and /studio/er: development tools for their corresponding subsystems.

Some panels poll HTTP JSON endpoints and the request logger uses SSE. The current crate does not promise a separate WebSocket telemetry transport or zero runtime overhead.

Tooling boundaries

• The data browser reads, searches, and paginates allowlisted SQLx identifiers. Inside the verified debug-loopback/same-origin boundary, it may edit one primitive non-key value or delete one complete-primary-key-selected row. Inputs are bounded and parameterized; exact deletion confirmation is required, backend-specific types remain read-only, and anything other than exactly one affected row fails. SQLite, PostgreSQL, MySQL, and MariaDB run separate executable contracts. This does not supply application tenant/RBAC, audit history, rollback, or a shared-production database administrator.
• Swagger UI appears only when the application supplies its OpenApi document with Studio::with_openapi; Studio does not reverse-engineer arbitrary Axum routes.
• The request SSE records method, URI, status and latency. It deliberately does not capture bodies or headers, which commonly contain credentials and PII.
• The jobs view lists the bounded snapshot exposed by a supplied queue. SQLite deletes successful rows by default; an application can explicitly select Queue::sqlite_with_completed_history for bounded, transactionally pruned completion history and can purge that history from Studio. Retained payloads require host-controlled access and retention policy. Other drivers expose only the inspection/history contract they implement.
• The ER view inspects SQLite, PostgreSQL, MySQL, or MariaDB metadata with bound lookup values and normalizes Mermaid identifiers. An unconfigured or unsupported source remains visibly unavailable.
• The feature-flags page changes the database table used by DbFeatureDriver. A successful toggle invalidates already-warm drivers in the same process; other processes and direct writers converge by TTL unless the host distributes an invalidation signal.
• The environment page redacts values by default and adds only a safe projection of process-global RullstConfig; URLs, filesystem paths, secrets, cookies and credentials are omitted.
• Cache inspection returns at most 100 UI rows containing an opaque keyed identifier, value byte length and remaining TTL. Values and exact logical keys are never rendered, bulk flush is absent, and individual invalidation requires the verified local mutation marker. Custom cache drivers remain unavailable until they implement Core’s bounded metadata contract.

Telemetry contract

Studio reads runtime state exposed by RadarSnapshot, SpanCollector, the security store, queues, and configured database connections. A counter means only that the corresponding instrumentation path emitted it; it is not proof that all traffic passed through that control. Missing sources must remain visibly unavailable.

Remote producers do not connect to the viewer. The application separately mounts TraceIngestor::router, distributes a 32–128-byte TraceIngestionKey, and uses TraceBatchSigner for the exact body and four headers. Each ingestor binds one exact producer name to one key; multiple producers use separate endpoints/keys over the same store. The route accepts 1–128 closed v1 spans under 128 KiB, verifies HMAC-SHA256 plus a 60-second timestamp and one-time nonce, then commits to a bounded process-local store idempotently. It contains no Studio read or admin route. TLS/network policy, key custody and rotation, producer authorization, clock synchronization, label redaction, durable storage and OTLP integration remain deployment work.

Production boundary

Studio is an optional crate. Its supported run_studio and Studio::into_router paths reject credential-free use in release builds, but consumers should still exclude it from production features unless they are implementing and testing a separate authenticated administrator boundary. Built-in shared production access remains roadmap work, not a password environment-variable promise.

Rullst Nexus: Explicit Admin CMS

Rullst Nexus is a server-rendered administrative CMS for explicitly registered Rullst models.

NexusModel metadata defines the tables, fields, and widgets available in the panel. Rullst builds CRUD, search, pagination, and batch routes from that registration; it does not discover an arbitrary database schema automatically.

Derive and register a model

The Nexus derive generates NexusModel metadata for named-field structs. It infers booleans, numbers, dates and ordinary text; semantic widgets that Rust’s type alone cannot reveal are selected explicitly:

#![allow(unused)]
fn main() {
use rullst::db::{FromRow, Nexus, Orm};

#[derive(Debug, Clone, FromRow, Orm, Nexus)]
#[orm(table = "users")]
#[nexus(label = "Users", icon = "👥")]
pub struct User {
    pub id: i32,
    pub name: String,
    #[nexus(kind = "email")]
    pub email: String,
    #[nexus(kind = "textarea", label = "Biography")]
    pub bio: String,
    #[nexus(kind = "enum", options = "invited, active, suspended")]
    pub status: String,
    pub is_active: bool,
}
}

id is the default primary key. Use #[nexus(primary_key)] on a field or #[nexus(primary_key = "uuid")] on the struct for another key. Field options also include label, hidden, readonly, and the text, textarea, email, url, number, boolean, date, datetime, password, json, and enum widget kinds. Implementing NexusModel manually remains available when an application needs metadata that cannot be derived.

Then select an explicit access policy in your routing file (usually src/lib.rs or src/main.rs) and mount the resulting router:

let nexus_auth =
    rullst::nexus::NexusAuthPolicy::local_development_or_basic_from_env()?;
let nexus = rullst::nexus::Nexus::new()
    .with_auth_policy(nexus_auth)
    .with_brand("SaaS Admin")
    .register::<models::user::User>()
    .try_build()?;

// ... and add it to the final router:
let router = router.nest_axum("/nexus", nexus);

The helper is intentionally asymmetric: debug builds allow only requests whose ConnectInfo peer is loopback; release builds load and validate NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD. Missing connection metadata is denied, and neither RULLST_ENV nor legacy APP_ENV can turn credential-free access on in a release binary. Applications can call basic_from_env() directly in debug when testing the production authentication flow.

Tenant-scoped administration

Use an explicit tenant column when a registered model contains tenant-owned rows. The column must be a text, non-primary-key field. The derive makes it hidden and read-only so browser form data cannot choose the tenant:

#![allow(unused)]
fn main() {
use rullst::db::{FromRow, Nexus, Orm};

#[derive(Debug, Clone, FromRow, Orm, Nexus)]
#[orm(table = "projects", tenant = "organization_id")]
pub struct Project {
    pub id: i32,
    pub organization_id: String,
    pub name: String,
    pub active: bool,
}
}

Authentication middleware must resolve membership and install a trusted rullst::security::TenantContext. Do not construct it directly from X-Tenant-ID, a query parameter or another client assertion. Nexus applies the exact scope to list/search/edit/create/update/delete and batch routes; missing context denies a scoped model. A model without the attribute remains global by design.

Require transaction-coupled audit

Install the fixed audit schema as an explicit deployment step, then enable the policy on the panel:

rullst::nexus::create_nexus_audit_table().await?;

let nexus = rullst::nexus::Nexus::new()
    .with_auth_policy(nexus_auth)
    .register::<Project>()
    .with_required_audit()
    .try_build()?;

Each successful mutation and its minimized rullst_nexus_audits row commit in one database transaction. Audit failure rolls the mutation back. The record contains actor, optional tenant, table/action, optional known key, affected-row count, committed outcome, optional bounded request ID, timestamp and format version. verify_nexus_audit_table() checks deployment readiness and recent_nexus_audits() reads at most 1,000 newest rows, optionally tenant filtered; the application must authorize that export separately.

The table is neither append-only nor protected from a database administrator. It does not persist denied attempts, and automatically assigned create keys are not recovered uniformly across all supported SQL dialects. Protect database permissions and send records to an independently operated immutable sink when that property is required.

👤 Example: Dynamic Profile Settings in Blueprints

Starter blueprints like Portfolio use explicit Nexus metadata to expose single-row or multi-row site configuration settings (such as developer name, title, bio, email, personal website, avatar photo, and social links).

#![allow(unused)]
fn main() {
use rullst::db::{Orm, FromRow, Nexus};

#[derive(Debug, Clone, FromRow, Orm, Nexus)]
#[orm(table = "profile")]
pub struct Profile {
    pub id: i32,
    pub name: String,
    pub title: String,
    pub subtitle: String,
    pub email: String,
    pub website: String,
    pub avatar_url: String,
    pub github_url: String,
    pub linkedin_url: String,
}
}

When registered in Nexus:

let nexus_auth =
    rullst::nexus::NexusAuthPolicy::local_development_or_basic_from_env()?;
let nexus = rullst::nexus::Nexus::new()
    .with_auth_policy(nexus_auth)
    .with_brand("Portfolio Admin")
    .register::<models::profile::Profile>()
    .try_build()?;

Administrators can edit the registered profile fields at /nexus. A blueprint that reads those fields on each request can show the persisted values without a code change or redeployment; cache policy remains application-owned.

Batch deletion is available for every registered model. Batch deactivation is shown only when the model declares a writable Boolean is_active or active field; Nexus never guesses which arbitrary status value means inactive.

Benefits of Nexus

1. Small Front-end Surface: Nexus renders responsive tables, forms and actions with server-side HTML and HTMX.
2. Fail-closed Construction: Nexus cannot build without a selected access policy. Being in the same binary is not itself a security guarantee; the application still owns TLS, trusted proxies, roles, ownership, field policy and database permissions.
3. Server-side Field Policy: hidden and readonly metadata improve the UI, while authorization and write restrictions are also enforced on the server.

In a generated debug application, open /nexus from the same machine. In a release deployment, configure strong unique credentials and the verified TLS boundary before exposing the route.

Rullst Capital: billing and fiscal boundaries

Vision preserved: capabilities removed from the usable-today contract are still evaluated item by item in the capability ledger, including whether each one is worth implementing and why.

rullst-capital provides billing abstractions, revenue metrics, payment-provider adapters, payout helpers, and verified webhook plumbing. Provider capabilities are not uniform: consult the adapter API and its tests before depending on a particular checkout, refund, payout, or webhook operation.

RevenueDashboardManager is a bounded process-local presentation source. Applications call update_metrics with values reconciled from their durable billing database and call record_event after a verified webhook path. Recording an event deliberately does not invent a plan price, fee, currency or subscriber count from its event name.

Payment providers

Initialize only the provider required by the application and treat credentials as deployment secrets. Empty credentials are configuration errors for live operations. Credentials deliberately prefixed with mock_ select deterministic offline behavior where that adapter documents support for it.

Every reviewed live method uses the same pooled outbound client with a five-second connect timeout, twenty-second whole-request timeout, disabled redirects and ambient proxy discovery, and one-MiB JSON limit. Returned checkout locations must be bounded absolute HTTPS URLs without credentials or fragments. CapitalError::Provider exposes redacted static provider/operation labels, failure kind, optional HTTP status and bounded numeric Retry-After. Its permanent/transient/rate-limited class is evidence for application policy, not permission to repeat a mutation. Only retry after proving that the exact operation forwards a persisted idempotency key and retaining reconciliation.

Immediate charges without raw payment data

Billable::charge_with accepts only a provider-tokenized customer and payment method. Amounts are integer minor units and every attempt needs an application-owned idempotency key. The reviewed live adapter is Stripe Payment Intents; other billing adapters fail with UnsupportedOperation instead of pretending to charge.

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, StripeProvider};

async fn collect_order<Account>(
    account: &Account,
    stripe: &StripeProvider,
) -> Result<(), CapitalError>
where
    Account: rullst_capital::Billable + Sync,
{
    let receipt = account
        .charge_with(
            stripe,
            4_990, // BRL 49.90 in cents
            "BRL",
            "cus_provider_owned",
            "pm_provider_tokenized",
            "order_42-attempt_1",
        )
        .await?;
    if receipt.is_succeeded() {
        // Reconcile durable order state; do not grant access from this alone.
    }
    Ok(())
}
}

The application must establish the customer’s authority over both provider IDs, retain the key with its order, reconcile signed webhooks and handle mandate/SCA rules. Empty/mock_* credentials produce a deterministic receipt with the distinct non-success ChargeStatus::Mock; it must never grant access or be booked as revenue. This API has no raw-card field and never guesses currency.

Provider-specific metered usage

Use the static-dispatch MeteredBillingProvider boundary for new code. StripeMeterEvent requires the authoritative cus_* customer, configured meter event name, positive quantity, timestamp and a unique visible identifier; the adapter sends the default stripe_customer_id/value payload and binds all of those fields in the accepted response. LemonSqueezyUsageRecord requires the provider’s numeric subscription-item ID plus the explicit Increment or Set action and binds item/quantity/action from the JSON:API response.

Both responses are capped at one MiB and offline credentials return a deterministic UsageStatus::Mock. Stripe provides only rolling identifier deduplication. The reviewed Lemon request has no provider event-key field, so the application must atomically claim event_key() in a durable outbox before sending. It must also configure the matching aggregation, reconcile invoices and derive quotas/entitlements from authoritative state. The old uniform BillingProvider::report_usage remains source-compatible for mocks but fails closed in live Stripe/Lemon configurations instead of guessing required fields.

Coupons and relative trial extensions

CouponCode validates/redacts the provider coupon identifier, while a statically dispatched SubscriptionHandle applies it. Stripe uses the current expanded discounts[0][coupon] update and binds the response to the requested subscription/coupon. Lemon Squeezy codes are checkout-only; Lemon and adapters without reviewed subscription-discount contracts return UnsupportedOperation for live credentials instead of silently succeeding.

handle.extend_trial(15) resolves a bounded 15-day expiration from the current UTC clock. Retryable workers should persist the command creation time and call extend_trial_days_at(15, command_created_at); this emits the same absolute expiration on every attempt. set_trial_end is available for explicit reconciliation. Stripe and Lemon Squeezy have bounded protocol/response-binding tests for trial updates. Authorization, command serialization, billing-cycle policy, webhook reconciliation and live account acceptance remain host/release responsibilities. See the billing tutorial.

Shared subscriptions and strict resource quotas

One Team/Workspace model can own Billable and its tier policy while every authorized member uses the same bounded BillingSubject. Derive that subject from trusted TenantContext, never from a client-selected owner ID. Billable::quota_request derives the limit from tier_limit; QuotaGate reserves before invoking a create operation, suppresses an exact retry and compensates an ordinary callback error.

InMemoryQuotaStore provides deterministic process-local behavior. Enable quota-sql directly or capital-quota-sql on the umbrella crate for a durable unique-claim and conditional-counter implementation on SQLite, PostgreSQL, MySQL and MariaDB. Use reserve_with_transaction and perform the domain insert in that same transaction whenever quota and creation must commit atomically. The complete tutorial shows this path and its replay semantics.

The application still owns membership, authoritative tier/webhook state, migrations, reconciliation of abandoned standalone reservations and adapters for Turso or non-relational stores. Rullst does not intercept writes performed outside the explicit quota boundary.

Payment-bound invoice PDF and delivery

Enable the umbrella capital-mail feature (or Capital’s invoice-pdf and Mail’s capital-invoice features separately). Invoice::bind_succeeded_charge rejects non-final/mock receipts and any recipient, minor-unit total or currency mismatch. PaidInvoiceDelivery::prepare then creates escaped HTML, a bounded native PDF attachment and a message that has already passed Mail pre-flight. It can use the configured facade, a tenant route or an explicit static driver.

The returned stable delivery_key is for a unique durable outbox record owned by the application. Rullst does not infer a webhook, claim that key atomically, guarantee attachment support at every provider or promise exactly-once delivery. See the SaaS billing tutorial.

Webhook endpoints must use the Capital verification middleware. Its Axum and opt-in Actix adapters call the same canonical verifier. For supported protocols it performs cryptographic verification, freshness checks, a two-megabyte body limit, and bounded replay protection before the application receives a normalized event. A webhook route may receive a narrowly scoped CSRF exemption only when this verifier remains mandatory on that exact route. See the payment guide for Actix setup.

The default store is process-local. The opt-in webhook-sql feature persists bounded provider-scoped payload digests or stable event IDs across SQLite, PostgreSQL, MySQL, and MariaDB processes. SQL-backed middleware is a replay firewall that claims before dispatch, not exactly-once delivery. For an atomic relational business transition, use the verified provider event ID with check_and_record_event_key_with_transaction in the domain transaction and do not pre-claim it through SQL middleware. Cross-system effects still require an outbox, idempotent consumers, and reconciliation.

#![allow(unused)]
fn main() {
use axum::{routing::post, Router};
use rullst_capital::verify_webhook;

async fn billing_webhook() {
    // Read the verified event inserted by the middleware in real handlers.
}

let router: Router = Router::new()
    .route("/webhooks/billing", post(billing_webhook))
    .layer(axum::middleware::from_fn(verify_webhook));
}

NFS-e Nacional: bounded homologation preparation

The fiscal module can construct a strict ordinary-service DPS 1.01 subset, validate it against checksum-pinned official schema sources with the one documented production regex normalization, sign its infDPS/@Id with a matching RSA key/certificate from PKCS#12, independently verify the local XMLDSig, and construct the bounded rustls mTLS client. These local properties do not constitute an authorization from the Brazilian National NFS-e service.

• NfseEnvironment::Mock returns FiscalResponseKind::OfflineMock, status MOCK_NOT_AUTHORIZED, and is_officially_authorized() == false.
• NfseEnvironment::Homologation and NfseEnvironment::Production fail closed with FiscalError::Unsupported.
• sign_dps_xml rejects malformed, duplicate-ID, already-signed, non-RSA, and mismatched key/certificate inputs instead of returning partial signature XML.
• NfseIssueRequest verifies the embedded DPS signature, produces the exact deterministic dpsXmlGZipB64 JSON object and parses bounded signed success or structured rejection material without performing network I/O.
• transmission and the external homologation gates remain deliberately disconnected from the network path.

#![allow(unused)]
fn main() {
use rullst_capital::fiscal::{
    issue_nfse_direct, FiscalCertificate, FiscalCustomer, FiscalEmitter,
    FiscalResponseKind, NfseDps, NfseEnvironment,
};

async fn offline_preview(
    emitter: &FiscalEmitter,
    customer: &FiscalCustomer,
    dps: &NfseDps,
) -> Result<(), rullst_capital::fiscal::FiscalError> {
    let unused_certificate = FiscalCertificate::offline_mock();
    let response = issue_nfse_direct(
        emitter,
        customer,
        dps,
        &unused_certificate,
        NfseEnvironment::Mock,
    )
    .await?;

    assert_eq!(response.kind, FiscalResponseKind::OfflineMock);
    assert!(!response.is_officially_authorized());
    Ok(())
}
}

The offline protocol boundary is intentionally separate from transport:

#![allow(unused)]
fn main() {
use rullst_capital::fiscal::NfseIssueRequest;

fn prepare(signed_dps: &str) -> Result<Vec<u8>, rullst_capital::fiscal::FiscalError> {
let request = NfseIssueRequest::try_from_signed_dps(signed_dps)?;
let exact_json_body = request.to_json()?;
Ok(exact_json_body)
}
}

An application may retain this material for a reviewed homologation fixture, but the Rullst client does not send it. parse_response accepts only the documented 201/400/403/500 issuance outcomes, applies four-MiB/cardinality/text limits, binds the selected environment to the signed infDPS/tpAmb, and never turns a rejection or unsigned/tampered XML into authorization.

The same nfse feature exposes FiscalCommandJournal: a bounded, single-active-writer HMAC-chained file that synchronizes a prepared command before a caller-owned transport, records one bound terminal response, suppresses exact replay, and recovers minimized pending descriptors after restart. It stores no XML, access key, processing message, provider body, or certificate. The host must retain the actual request/outbox and the journal checkpoint separately, protect and rotate the 32-byte key, enforce an exclusive writer, and own reconciliation, retry, retention, and backup.

Live issuance remains disabled until full certificate/emitter and ICP-Brasil policy, deployment of the local journal and authoritative request/outbox, retained official fixtures, real A1 restricted-environment tests, independent review, and official end-to-end homologation are complete. Follow the NFS-e homologation-preparation tutorial and never account an offline fixture as an issued invoice.

Operational checklist

• Derive tenant identity from an authenticated context, not an arbitrary client header.
• Keep webhook secrets non-empty, rotate them, and retain replay state according to the provider contract.
• Reconcile provider events idempotently in the application database.
• Treat Studio revenue panels as observability views, not an accounting ledger.
• Verify every adapter capability in a sandbox before enabling live traffic.

Integrating AI into Rullst

rullst-ai provides guarded adapters for OpenAI, Anthropic, Gemini, DeepSeek, Ollama, and explicitly configured OpenAI-compatible local/cloud endpoints. The high-level AiClient applies prompt-injection heuristics and PII masking before dispatch. Those controls reduce known risks; passing them does not prove that a prompt or model response is safe or correct.

Start with the provider capability matrix. It separates implemented transport paths from model-dependent behavior and lists unsupported streaming, tool, timeout, retry, and cancellation boundaries.

1. Enable the AI facade

[dependencies]
rullst = {
    version = "12.0.0-rc.1",
    default-features = false,
    features = ["ai"]
}
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Use the exact published v12 version being evaluated. The RC value above is a planned prerelease and must not be used before it exists on crates.io.

2. Create a guarded client

#![allow(unused)]
fn main() {
use rullst::ai::{AiClient, providers::openai::OpenAiProvider};

fn ai_client() -> Result<AiClient, std::env::VarError> {
    let api_key = std::env::var("OPENAI_API_KEY")?;
    Ok(AiClient::new(OpenAiProvider::new(api_key)))
}
}

Empty and mock_* keys intentionally select deterministic offline behavior. Requiring the environment variable, as above, prevents a live deployment from silently becoming a demo. Tests can construct OpenAiProvider::new("") explicitly when offline behavior is desired.

Other built-in constructors are available under:

• providers::anthropic::AnthropicProvider;
• providers::gemini::GeminiProvider;
• providers::deepseek::DeepSeekProvider;
• providers::ollama::OllamaProvider.

For a local server exposing an OpenAI-compatible endpoint, declare only the request shapes verified for the exact model:

#![allow(unused)]
fn main() {
use rullst::ai::{
    AiClient,
    providers::openai_compatible::{
        OpenAiCompatibleCapabilities, OpenAiCompatibleProvider,
    },
};

fn local_client() -> Result<AiClient, rullst::ai::AiError> {
    let provider = OpenAiCompatibleProvider::try_local(
        "http://127.0.0.1:8080/v1",
        "my-local-model",
    )?
    .with_capabilities(
        OpenAiCompatibleCapabilities::chat_only()
            .with_embeddings()
            .with_json_mode(),
    )
    .try_with_embedding_model("my-embedding-model")?;
    Ok(AiClient::new(provider))
}
}

try_local accepts HTTP only on literal loopback IPs and sends no authorization header. Use try_local_with_bearer for an authenticated loopback server or try_cloud(https_base_url, api_key, model) for a Bearer-authenticated cloud endpoint. None of these constructors discovers model capabilities; false declarations become provider errors, while omitted capabilities fail locally with UnsupportedCapability. A non-compatible API implements the public AiProvider trait instead.

3. Call it from an Axum handler

This bounded handler rejects oversized input before invoking the client and does not expose the provider’s full error details to the HTTP caller:

#![allow(unused)]
fn main() {
use rullst::{Server, ai::AiClient};
use rullst::web::axum::{
    Json, Router,
    extract::State,
    http::StatusCode,
    routing::post,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct ChatPrompt {
    prompt: String,
}

#[derive(Serialize)]
struct ChatResponse {
    answer: String,
}

async fn chat(
    State(client): State<AiClient>,
    Json(body): Json<ChatPrompt>,
) -> Result<Json<ChatResponse>, (StatusCode, &'static str)> {
    if body.prompt.len() > 8_192 {
        return Err((StatusCode::PAYLOAD_TOO_LARGE, "prompt is too large"));
    }

    let answer = client
        .prompt(&body.prompt)
        .await
        .map_err(|_| (StatusCode::BAD_GATEWAY, "AI request failed"))?;
    Ok(Json(ChatResponse { answer }))
}

async fn serve(client: AiClient) -> Result<(), rullst::ServerError> {
    let app = Router::new()
        .route("/api/chat", post(chat))
        .with_state(client);
    Server::new(app.into()).run(3000).await
}
}

Production applications should authenticate and rate-limit this route, bind tenant identity from authenticated state, cap response sizes, and record an audit event without logging prompts or secrets verbatim.

4. Inspect capabilities before optional operations

#![allow(unused)]
fn main() {
use rullst::ai::{AiClient, EgressFetcher, EgressPolicy, LocalImagePolicy, providers::openai::OpenAiProvider};
async fn example() -> Result<(), Box<dyn std::error::Error>> {
let client = AiClient::new(OpenAiProvider::new("mock_local"));
let capabilities = client.capabilities();

if capabilities.vision {
    // Bytes have already crossed the application's own admission boundary.
    let png = b"\x89PNG\r\n\x1a\n\x00";
    client.prompt_with_image("Describe this image", png).await?;

    // Local files must remain under an exact canonical allowlisted root.
    let local = LocalImagePolicy::new(["./private-uploads"])?;
    client
        .prompt_with_image_file("Describe this image", "./private-uploads/photo.png", &local)
        .await?;

    // URLs require an explicit HTTPS egress allowlist and resource budget.
    let remote = EgressPolicy::strict()
        .with_allowed_hosts(["images.example.com"])?
        .with_max_response_bytes(2 * 1_024 * 1_024)?;
    client
        .prompt_with_image_url(
            "Describe this image",
            "https://images.example.com/photo.png",
            &EgressFetcher::new(remote),
        )
        .await?;
}
Ok(())
}
}

Capability inspection prevents avoidable requests but is not a substitute for handling UnsupportedCapability and upstream model errors. Configuration can select a model that supports less than its provider transport. File and URL helpers check capability and guard the text before I/O, cap images at 10 MiB, sniff JPEG/PNG/WebP/GIF bytes and require a supplied remote Content-Type to match. The host must authorize the source and protect allowed local directories; Rullst does not infer tenant ownership from a path or URL.

5. Request structured output

json_prompt requests parseable JSON. It does not claim JSON Schema enforcement. Use structured_prompt_with_schema only when the reported provider capability and configured model support it:

use rullst::ai::StructuredOutputSchema;

let schema = StructuredOutputSchema::new(
    "answer",
    serde_json::json!({
        "type": "object",
        "properties": {"answer": {"type": "string"}},
        "required": ["answer"],
        "additionalProperties": false
    }),
)?;

let answer: serde_json::Value = client
    .structured_prompt_with_schema("Summarize the incident", &schema)
    .await?;

Validate business rules after deserialization. Schema-conforming model output can still be false, malicious, stale, or unauthorized.

6. Streaming and tools

The built-in v12 provider transports do not expose token streaming. Rullst can host ordinary Axum SSE responses, but an application that uses a third-party streaming SDK owns its authentication, guardrails, backpressure, deadlines, cancellation, error mapping, and dependency lifecycle. Do not present that escape hatch as native rullst-ai streaming.

ToolRegistry stores local tools but is not wired to provider function calling. Its guarded execution API requires an exact allowlist, principal authorization, closed JSON validation, size/call limits and an audit sink. Destructive and Financial tools additionally require a one-use human approval bound to the exact JSON payload. Treat model output as untrusted input; the application still authenticates the principal/approver, enforces domain ownership and supplies durable production auditing.

7. RAG boundary

Rullst supplies prompt construction and an in-memory vector index. Applications must still enforce document authorization before retrieval, prevent SSRF in any fetcher, bound document and prompt sizes, identify tenant provenance, and avoid sending secrets to a provider. Similarity is a ranking signal, not an access control decision.

8. Durable chat memory

Enable the dedicated SQL memory feature when the application wants the framework-owned fixed schema rather than generated models:

rullst = {
    version = "12.0.0-rc.1",
    default-features = false,
    features = ["ai-sql-memory"]
}

The same adapter supports SQLite, PostgreSQL, MySQL, and MariaDB URLs:

#![allow(unused)]
fn main() {
use rullst::{
    ai::{
        AiClient, ChatMemoryConfig, ConversationId, SqlChatMemory, StatefulChat,
        providers::openai::OpenAiProvider,
    },
    security::TenantContext,
};

async fn chat_service(
    database_url: String,
    api_key: String,
) -> Result<
    (StatefulChat<SqlChatMemory>, TenantContext, ConversationId),
    Box<dyn std::error::Error>,
> {
    let memory = SqlChatMemory::connect(database_url, ChatMemoryConfig::default()).await?;
    memory.prepare_schema().await?;
    let service = StatefulChat::new(
        AiClient::new(OpenAiProvider::new(api_key)),
        memory,
    );
    let tenant = TenantContext::try_new("tenant-42")?;
    let conversation = ConversationId::try_new("support:case-7")?;
    service.ensure_conversation(&tenant, &conversation).await?;
    Ok((service, tenant, conversation))
}
}

service.send(&tenant, &conversation, text).await loads only the configured recent message pairs, applies the ordinary AI guardrails, and stores the user and assistant messages in one transaction. If another process committed from the same observed revision, the slower StatefulChat call receives StatefulChatError::Memory(ChatMemoryError::RevisionConflict). Decide explicitly whether the UI asks the user to retry; the library will not repeat a potentially billable provider call.

The table stores raw message text. Production code must authenticate conversation ownership inside the selected tenant, decide encryption and key management, implement retention/erasure and backup policy, audit provider use without logging secrets, and manage schema changes through its release process. Use cargo rullst make:chat-session instead when you need application-owned models/migrations or the Turso-primary profile.

AI-friendly architecture and local model endpoints

Rullst favors explicit types, conventional file locations, bounded macros and generated .llms.txt context. These choices can make a project easier for a human or coding assistant to navigate, but the repository has no controlled evidence for a universal token-saving percentage. Prompt size depends on the task, tool, repository state and model.

What “AI-native” means here

• routes! and html! provide recognizable syntax boundaries.
• Public APIs prefer concrete types and static dispatch where practical.
• cargo rullst make:* generates conventional, inspectable source files.
• cargo rullst generate:ai-context records a compact structural summary.
• External provider integrations have deterministic offline behavior for empty or mock_* credentials.

This does not guarantee that an assistant understands the application, chooses the right edit, uses fewer tokens or produces secure code. Keep source review, tests and application threat models authoritative.

The AI maintainability and project-building roadmap records the measurable post-v12-RC work needed to improve generated agent instructions, bounded task-oriented context and reproducible model evaluations. Those planned evaluation profiles are not current compatibility guarantees.

Ollama through AiClient::auto

The high-level client recognizes OLLAMA_HOST and OLLAMA_MODEL:

export OLLAMA_HOST="http://127.0.0.1:11434"
export OLLAMA_MODEL="llama3"

#![allow(unused)]
fn main() {
use rullst_ai::ai::AiClient;

async fn example() -> Result<(), rullst_ai::ai::AiError> {
let client = AiClient::auto()?;
let response = client.prompt("Summarize this bounded input").await?;
println!("{response}");
Ok(())
}
}

AiClient::auto() also recognizes the built-in cloud-provider API-key variables. With no configured provider it selects a deterministic offline mock; that fallback is not a live model.

OpenAI-compatible endpoints

An OpenAI-compatible server is configured explicitly rather than inferred from an arbitrary environment variable:

#![allow(unused)]
fn main() {
use rullst_ai::ai::{
    AiClient,
    providers::openai_compatible::{
        OpenAiCompatibleCapabilities, OpenAiCompatibleProvider,
    },
};

let provider = OpenAiCompatibleProvider::try_local(
    "http://127.0.0.1:1234/v1",
    "configured-model-name",
)?
.with_capabilities(OpenAiCompatibleCapabilities::chat_only());
let client = AiClient::new(provider);
Ok::<(), rullst_ai::ai::AiError>(())
}

The same adapter can be used with local runtimes such as llama.cpp server, LocalAI, LM Studio, or vLLM when the exact installed version and configuration expose the request shapes declared in Rullst. Those product names are examples, not compatibility certification; check the runtime’s API and model documentation. A server with a different protocol implements the public AiProvider contract instead.

Compatibility must be tested for the methods the application uses. An endpoint may implement chat while differing on embeddings, vision, JSON Schema, errors or streaming. Optional request shapes are disabled until explicitly declared. Use try_local_with_bearer for an authenticated loopback server and try_cloud for HTTPS/Bearer cloud endpoints. Consult the provider capability matrix.

Privacy boundary

Using a loopback endpoint can avoid sending model requests to a cloud provider, but it does not prove an air gap or zero leakage. The model runtime, host network, proxy variables, logs, tracing, crash dumps and application code still determine the real data path. The compatible adapter ignores ambient proxies and redirects, but that is only one transport boundary. The built-in prompt and PII checks are bounded heuristics, not authorization or a complete data-loss-prevention guarantee.

AI Maintainability and Project-Building Roadmap

Rullst aims to be understandable to humans and coding assistants without making model-independent quality claims. Explicit Rust types, conventional project structure and generated context can reduce ambiguity, but no framework can guarantee that an arbitrary model will produce correct, secure or maintainable software.

This document records the measurable work required to make Rullst excellent for AI-assisted framework maintenance and application development. It is a post-v12-RC roadmap, not a v12 release gate and not a description of capabilities that have already shipped.

Current foundation

The repository already provides useful controls:

• AGENTS.md defines the framework architecture, coding invariants, security boundaries, validation commands and release order.
• spec.md is the architectural Single Source of Truth.
• capability-status.md and the quality-scorecard.md separate implementation claims from engineering evidence.
• cargo rullst make:* emits conventional, inspectable Rust source instead of hiding application behavior behind runtime reflection.
• cargo rullst generate:ai-context emits .llms.txt with selected application source and dependency context.
• Generated-project tests, compile-fail tests, deterministic provider mocks and the workspace validation gates catch classes of mistakes independently of the assistant that proposed a change.

These controls are a good foundation. They do not yet prove that a smaller or less capable model can maintain the framework or build a complete application at a defined quality level.

Known limitations

The current AI context generator primarily concatenates Cargo.toml and Rust files from selected conventional directories. That format can become noisy, does not rank information by task relevance and does not provide a complete project contract for routes, configuration, migrations, tests, authorization or operational commands.

The framework documentation is extensive. Breadth helps difficult work, but a model with weaker retrieval or reasoning can select an obsolete example, miss a more specific invariant or consume too much context unless it receives a short task-oriented map first.

Maintaining framework internals is also substantially harder than building an application from stable public APIs. Cross-crate feature unification, procedural macros, database dialects, authentication, cryptography and release engineering require stronger review and broader gates than ordinary application CRUD.

Post-v12-RC workstreams

1. Project-specific agent instructions

Generate a concise AGENTS.md for each new application, derived from the selected blueprint and feature set. It must describe:

• the chosen database, rendering mode and enabled Rullst subsystems;
• the canonical locations for routes, models, controllers, policies, migrations, jobs and tests;
• the exact format, lint and test commands for that application;
• mandatory ownership, CSRF, headers, WAF and secret-handling boundaries;
• which generated files are application-owned and which commands may refresh them; and
• links to version-matched Rullst documentation.

Acceptance requires snapshot tests for every supported blueprint and a generated-project compile gate. The generated document must not claim that an optional integration is active merely because its crate is available.

2. Structured and bounded AI context

Evolve generate:ai-context from a source concatenator into a deterministic, versioned project map. The output should present summaries and file paths before including bounded source excerpts. It should cover:

• dependency and feature selections;
• routes and their authentication/ownership policies;
• models, relationships and migrations;
• controllers, middleware, jobs and external-provider boundaries;
• configuration keys by name, never secret values;
• tests and the commands that exercise each subsystem; and
• freshness metadata sufficient to detect stale generated context.

The generator must enforce an explicit size budget, stable ordering, secret and binary exclusions, path confinement and deterministic output. Large projects should receive an index plus task-selectable context shards rather than one unbounded prompt payload.

3. Golden application tasks

Create small, executable reference tasks that represent common real work:

1. add a validated CRUD resource with tenant ownership;
2. add session authentication and a role-protected route;
3. add a migration and repository query without SQL injection;
4. enqueue an idempotent background effect through an outbox;
5. verify a signed webhook and reject replay or invalid signatures;
6. add a provider integration with a deterministic offline mock;
7. diagnose and repair a deliberately broken generated application; and
8. perform an assisted framework upgrade and verify rollback.

Each task needs a fixed starting fixture, an executable acceptance suite, security-negative cases and a reference solution. Tutorials alone are not evidence; the fixture must compile and its assertions must prove the behavior.

4. Reproducible AI evaluation harness

Evaluate candidate assistants using the same repository revision, task fixture, tool permissions, time budget and acceptance tests. Record at least:

• functional correctness and hidden-test pass rate;
• formatting, strict Clippy and test results;
• security-invariant violations;
• unsupported or hallucinated APIs and dependencies;
• unnecessary diff size and changes outside the requested scope;
• ability to recover from compiler and test failures;
• documentation truthfulness; and
• elapsed time, model/tool configuration and cost when publishable.

Results must name the exact model/version, agent harness, reasoning setting, date and commit SHA. A vendor description or one successful demonstration is not compatibility evidence. Preview and mutable model aliases must be reported as such.

The first matrix should distinguish at least two profiles:

• application builder: works through documented, stable public APIs and generated projects; and
• framework maintainer: changes crate internals, feature combinations, macros, security boundaries or release infrastructure.

A model may qualify for one profile without qualifying for the other.

5. Task-oriented documentation routing

Add a short machine-readable and human-readable entry map that answers “which document should I read for this task?” before exposing the full manual. It must route architecture changes to the SST, release work to the release programme, security changes to the relevant threat model and ordinary application work to the smallest applicable tutorial and API reference.

Where documents overlap, one must be declared authoritative and the others must link to it rather than restating mutable facts. Documentation examples should continue to be compiled or exercised wherever practical.

6. Governance and review boundaries

AI assistance never replaces contributor accountability or independent review. The disclosure and verification rules in CONTRIBUTING.md apply to every model and tool. Exact prompt disclosure remains optional context, not proof of authorship, completeness or safety.

Routine documentation, test and mechanical dependency work may use a faster model when the gates prove the result. Authentication, cryptography, ORM/macro contracts, release signing and cross-crate security changes require heightened human review regardless of the model used. No evaluation score authorizes unattended merge or production mutation.

Delivery sequence

Phases begin after the v12 RC is cut. Compatible documentation corrections may land in v12 maintenance, but new generator formats, fixtures and public support profiles belong to the v13 feature line unless a separate release decision says otherwise.

Completion criteria

This roadmap may be called complete only when:

• every supported blueprint produces accurate, tested agent instructions;
• context generation is bounded, deterministic, secret-safe and task-routable;
• the golden application and maintenance suites run from clean fixtures;
• published results are tied to exact models, harnesses, commits and dates;
• at least one lower-cost model completes the application-builder profile at the project-defined quality threshold without security-critical failures; and
• failure cases and unsupported maintenance classes are documented as clearly as successful ones.

Until then, the honest claim is narrower: Rullst is intentionally structured to support AI-assisted work and provides useful safeguards, but model suitability must be evaluated for the concrete task and reviewed like any other contribution.

Non-goals

• guaranteeing correct output from every current or future model;
• detecting all AI-generated code or proving the complete prompt history;
• replacing human ownership, security review or coordinated disclosure;
• auto-merging changes based on a model name or benchmark score; or
• claiming superiority over other frameworks without dated, reproducible comparative evidence.

Redis, Local Cache & Queue Drivers

Rullst v12 keeps cache and queue backends explicit. Enabling a Cargo feature only compiles the adapter; it does not inspect REDIS_URL, switch drivers, or silently fall back when Redis is unavailable.

Cache choices

Cache::memory() uses a process-local DashMap. Values disappear on restart and are not shared between replicas:

#![allow(unused)]
fn main() {
use rullst_core::cache::{Cache, CacheError};
use std::sync::Arc;

async fn load_profile(cache: &Cache) -> Result<Arc<String>, CacheError> {
    cache
        .remember("profile:42", 300, || async {
            Ok("serialized profile".to_string())
        })
        .await
}

async fn read_profile() -> Result<(), CacheError> {
let cache = Cache::memory();
let profile = load_profile(&cache).await?;
let _ = profile;
Ok(())
}
}

For a shared Redis cache, enable cache-redis (or the umbrella redis feature) and construct the adapter explicitly:

[dependencies]
rullst-core = { version = "12.0.0-rc.1", features = ["cache-redis"] }

#![allow(unused)]
fn main() {
use rullst_core::cache::Cache;

async fn cache_featured_catalog() -> Result<(), Box<dyn std::error::Error>> {
let redis_url = std::env::var("REDIS_URL")?;
let cache = Cache::redis(redis_url)?;
cache.put("catalog:featured", "[...]", Some(600)).await?;
Ok(())
}
}

Constructing the driver validates the Redis URL but does not establish a connection. Operations open a multiplexed async connection and return a typed CacheError if Redis is unavailable. Choose an application-specific policy: fail startup, retry with bounds, or explicitly select Cache::memory() for a documented single-instance development mode.

The built-in Redis cache prefixes keys with rullst:cache:. flush() scans and unlinks keys under that prefix; use dedicated credentials/database boundaries when multiple applications share a Redis service.

ORM .remember(...) queries

The ORM has a separate opt-in query-cache contract behind its redis feature:

[dependencies]
rullst-orm = { version = "12.0.0-rc.1", features = ["redis"] }

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
struct User {
    id: i32,
    active: bool,
}

async fn load_recent_users() -> Result<(), Box<dyn std::error::Error>> {
let redis_url = std::env::var("REDIS_URL")?;
Orm::init_redis_with_namespace(&redis_url, "academy-production").await?;

let recent = User::query()
    .where_eq("active", true)
    .remember(30)
    .get()
    .await?;
let _ = recent;
Ok(())
}
}

Use a stable, unique namespace for every application that shares a Redis database. Query keys bind that namespace, an opaque digest of the active tenant scope, table, generated SQL and typed bindings. They do not expose raw tenant identifiers. The older Orm::init_redis(url) API remains available and uses default; only use it with a dedicated Redis database.

The failure and consistency rules are explicit:

• remember(0) is rejected.
• Missing Redis initialization is a configuration error for a remembered query outside a transaction.
• Redis command failures or corrupt JSON fall back to the authoritative database; a successful read is returned even if cache population fails.
• Explicit and task-scoped ORM transactions always bypass query cache.
• Generated model saves/deletes invalidate the active tenant/table’s remembered results only after a managed commit; rollback keeps existing cache entries. Raw SQL, bulk builders and writes from another process cannot be inferred. Keep defensive TTLs and do not cache authorization or reads that require a stronger distributed consistency contract.

The Core Cache facade and ORM query cache use different keyspaces and APIs; initializing one does not initialize the other.

Queue choices

Rullst provides explicit SQLite and Redis queue constructors:

[dependencies]
rullst-core = { version = "12.0.0-rc.1", features = ["queue-sqlite"] }
serde_json = "1"

#![allow(unused)]
fn main() {
use rullst_core::queue::Queue;
use serde_json::json;

async fn enqueue_receipt() -> Result<(), Box<dyn std::error::Error>> {
let queue = Queue::sqlite("sqlite://jobs.sqlite?mode=rwc").await?;
let job_id = queue
    .dispatch("send_receipt", json!({ "invoice_id": 42 }))
    .await?;
println!("queued {job_id}");
Ok(())
}
}

With queue-redis, construct Queue::redis(redis_url) instead. The Redis driver uses atomic Lua transitions for pending, processing, failed, and dead-letter state. Production validation must still cover Redis persistence, eviction policy, credentials/TLS, failover, monitoring, and worker recovery in the target topology.

There is no automatic interchange between the SQLite and Redis queues: they store independent state. Switching a live deployment requires an explicit drain/migration plan.

Real-time boundary

Core’s current WebSocket broadcast/presence helpers are process-local. Redis Streams, Redis Pub/Sub, Kafka, and RabbitMQ transports remain roadmap work; do not describe the cache or queue adapter as cross-instance real-time sync.

Deployment checklist

• Choose the backend in application configuration and make fallback policy explicit.
• Never commit Redis credentials; prefer TLS and least-privilege network access.
• Namespace application/tenant keys above the built-in driver prefix where isolation is required. TenantCache supplies validated tenant namespaces.
• Test disconnects, timeouts, retries, eviction, restart, and worker recovery.
• Benchmark the deployed service. Rullst does not claim universal cache latency, memory usage, or infrastructure cost.

Tutorial 01: From Zero to Hello Rullst 🚀

What you will build: one complete web application with a typed route and server-rendered HTML. No database account or AI provider is needed. By the end, you will be able to point to the handler that produced the page in your browser.

Choose a different starting path · Next: CLI generators

This tutorial takes a new developer from installing Rust to a running Rullst web application. It uses the unreleased v12 development snapshot documented by this site. It is not a production recommendation. A future production adoption needs a supported release and reviewed immutable artifacts; neither moving main nor merely pinning end-of-life v5 satisfies that requirement.

1. Install Rust and Cargo

On Linux or macOS, use the official rustup installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download rustup from rustup.rs or run:

winget install --id Rustlang.Rustup

Restart the terminal if necessary, then verify the toolchain:

rustc --version
cargo --version

Rullst v12 requires the MSRV recorded in the compatibility policy.

2. Create a project

cargo new my_first_app
cd my_first_app

Every command below must run in this directory, where Cargo.toml lives.

3. Add the v12 preview

Until v12 is published, select the development source explicitly:

cargo add rullst --git https://github.com/Rullst/Rullst.git --branch main
cargo add tokio --features full

Cargo records the resolved Git commit in Cargo.lock. This makes one checkout repeatable, but a future dependency update can select a newer main commit. Do not use this mutable preview source in production.

Applications that must remain on end-of-life v5 should use its versioned API documentation instead; the v12 API below is intentionally different. That reference preserves the old API, not a promise of ongoing maintenance or a deployment recommendation.

4. Define the first route

Replace src/main.rs with:

use rullst::{html, response::Html, routes, Server};

async fn home() -> Html<String> {
    Html(html! {
        <div class="min-h-screen bg-slate-900 text-emerald-400 flex flex-col items-center justify-center font-sans">
            <h1 class="text-5xl font-extrabold mb-4">"Hello, Rullst! 📜🦀"</h1>
            <p class="text-slate-400 text-lg">"Your first typed route is running."</p>
        </div>
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![
        get("/" => home)
    ];

    Server::new(app).run(3000).await?;
    Ok(())
}

The fallible server startup uses ?, so bind and runtime failures are returned to the process instead of causing a framework-originated panic.

5. Run the application

Start the server:

cargo run

Open http://localhost:3000. Stop it with Ctrl+C.

Make it yours: change the heading to your project name, restart with cargo run, and confirm the response changed. The example’s utility class names do not install Tailwind by themselves; seeing an unstyled page is not a server failure. Use a generated HTML blueprint for a bundled local stylesheet.

If the port is already occupied, stop the conflicting process you own or change the .run(3000) port above. Keep the terminal output: it is the first place to look for a build or startup diagnostic.

6. Continue with the CLI

The v12 CLI can generate complete starters and project modules. While working from a source checkout, install the same revision locally:

git clone --branch main https://github.com/Rullst/Rullst.git
cd Rullst
cargo install --locked --path cargo-rullst
cargo rullst --help

The CLI’s new generator will target the CLI’s framework version. Until v12 is published, a pre-release CLI built from this checkout emits absolute path dependencies to that exact checkout, including when invoked elsewhere. Keep the checkout in place and review those sources before sharing the generated project. See the CLI reference for every command and boundary.

Key takeaways

• The rullst::html! macro generates ordinary Rust string-building code and escapes dynamic values. Rendering still performs the allocations/work implied by the generated template.
• All boolean HTML attributes inside html! must be explicitly quoted (e.g. required="true").
• Fallible handlers can return Result<Response, YourAppError> using an application-defined error that converts the relevant typed framework/domain errors; server startup propagates ServerError with ?.
• The v12 main branch is an evaluation source, not a stable release channel.

Create Your First Rullst REST API

Your result: a typed JSON response you can verify from another terminal. Start here when your frontend is a separate app, mobile client or integration. Explore all beginner paths.

This quickstart creates one runnable JSON endpoint without a database or an AI provider. It targets the unreleased v12 snapshot on main, for local evaluation only. Production adoption needs a supported release and reviewed immutable artifacts; pinning end-of-life v5 does not make it supported again.

1. Create the application

cargo new first_rullst_api
cd first_rullst_api
cargo add rullst --git https://github.com/Rullst/Rullst.git --branch main
cargo add tokio --features macros,rt-multi-thread
cargo add serde --features derive

Keep the generated Cargo.lock so every checkout resolves the same framework commit.

2. Add a JSON route

Replace src/main.rs with:

use rullst::{Server, ServerError, routes, server::Json};
use serde::Serialize;

#[derive(Serialize)]
struct HealthResponse {
    status: &'static str,
    framework: &'static str,
}

async fn health() -> Json<HealthResponse> {
    Json(HealthResponse {
        status: "ok",
        framework: "Rullst",
    })
}

#[tokio::main]
async fn main() -> Result<(), ServerError> {
    let app = routes![
        get("/api/health" => health),
    ]
    .layer(rullst::server::from_fn(
        rullst::security::headers_middleware,
    ));

    Server::new(app).run(3000).await
}

The response is serialized from a typed Rust value. The secure-header layer is included explicitly because transport, proxy, authentication, authorization, CSRF, and application-specific input policy remain deployment responsibilities; a JSON response alone is not a production security boundary.

3. Run and verify it

Start the application:

cargo run

From another terminal, request the route:

curl -i http://127.0.0.1:3000/api/health

The body is:

{"status":"ok","framework":"Rullst"}

Stop the server with Ctrl+C.

4. Prefer a generated API foundation?

After installing the matching v12 CLI, it can scaffold a headless API directly. Use a different directory from the hand-written example above:

cargo rullst new generated_api --default --api --no-database \
  --skip-initial-migration
cd generated_api
cargo run

This generates the blueprint’s own routes, not an exact copy of the health handler above. Read its controller and route registration before choosing a URL to test. Use cargo rullst make:controller project --api for additional JSON controllers. Generated parameterized data routes still require explicit ownership or tenant authorization; see RBAC and IDOR protection.

Tutorial 02: CLI Automation & Generators ⚡

Your goal: generate a small piece of the application, find the resulting files and understand what still needs your code. Run these commands from an existing generated project’s root, where Cargo.toml and Rullst.toml live. The commands below are independent examples; do not generate Product twice unless you have deliberately removed or renamed your own earlier fixture.

Rullst provides opinionated code generators (make:*) for controllers, models, migrations, and resources. The current generators register generated Rust modules when possible; they do not silently add application routes or rewrite AI context. Review every generated file and mount the intended routes yourself.

🛠️ Essential Scaffolding Commands

1. Generate a Controller

cargo rullst make:controller ProductsController

Creates src/controllers/products_controller.rs with placeholder index, show, store, update, and delete handlers and registers the module.

2. Generate a Model & Migration

cargo rullst make:model Product --migration

Creates the model in src/models/product.rs and a timestamped Rust migration in src/migrations/. Review its columns before applying it to a local database.

3. Generate a Full-Stack Resource Starting Point

cargo rullst make:resource Product

Scaffolds a model, Rust migration, controller, and HTML view placeholders (views/product/index.html and views/product/form.html) in one command. The generated controller is not a complete authorized CRUD implementation.

🔍 Static CLI Code Inspection

Inspect recognizable source declarations without launching a server:

# Inspect recognizable routes! declarations
cargo rullst inspect route

# Print ORM models and field types
cargo rullst inspect model

💡 Key Takeaways

• Scaffolding generators maintain architectural consistency across team members.
• cargo rullst inspect performs bounded source-text inspection. Route output recognizes explicit single-line routes! entries; model output lists public declarations from src/models. It is not complete macro expansion or a Rust semantic analysis.

Tutorial 03: Active Record CRUD Operations 🗄️

rullst-orm derives a typed query builder and persistence methods from a Rust struct. The SQLx-backed model uses an i32 primary key named id; a zero value means that save() inserts, while a non-zero value means that it updates.

Step 1: Define an Active Record model

In src/models/user.rs:

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
pub struct User {
    pub id: i32,
    pub name: String,
    pub email: String,
}
}

The database table must contain matching columns. Run migrations before using the model.

Step 2: Perform CRUD operations

Create

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
struct User { id: i32, name: String, email: String }
async fn create_user() -> Result<(), rullst_orm::Error> {
let mut user = User {
    id: 0,
    name: "Alice Developer".to_string(),
    email: "alice@example.com".to_string(),
};
user.save().await?;
// `user.id` now contains the inserted primary key.
Ok(())
}
}

Read and filter

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
struct User { id: i32, name: String, email: String }
async fn read_users() -> Result<(), rullst_orm::Error> {
let user = User::find(1).await?; // Result<Option<User>, rullst_orm::Error>
let example_users = User::query()
    .where_like("email", "%@example.com")
    .get()
    .await?;
let _ = (user, example_users);
Ok(())
}
}

Builder values are bound as query parameters. Column names are validated as identifiers, but they should still be application-owned constants rather than untrusted request input.

Update

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
struct User { id: i32, name: String, email: String }
async fn update_user() -> Result<(), rullst_orm::Error> {
if let Some(mut user) = User::find(1).await? {
    user.name = "Alice Smith".to_string();
    user.save().await?;
}
Ok(())
}
}

Delete

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
struct User { id: i32, name: String, email: String }
async fn delete_user() -> Result<(), rullst_orm::Error> {
if let Some(user) = User::find(1).await? {
    user.delete().await?;
}
Ok(())
}
}

Soft deletes

A deleted_at: Option<String> field opts the model into the default soft-delete contract. For a different sentinel, configure it explicitly and ensure the migration uses the same representation:

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Debug, Clone, FromRow, Orm)]
#[orm(
    table = "users",
    soft_delete(field = "is_deleted", value = "0", delval = "1")
)]
pub struct SoftUser {
    pub id: i32,
    pub name: String,
    pub is_deleted: i32,
}
}

query() applies the model’s configured scopes. unscoped() is an explicit administrative escape hatch and should not be used directly from request data.

Key takeaways

• save, find, all, query, and delete are generated for SQLx-backed Orm models.
• Creation uses a normal Rust struct, not a JSON map.
• CRUD errors are returned as rullst_orm::Error; a missing row is Ok(None).
• Use a caller-owned transaction and the generated *_with_tx methods when a business operation must commit multiple writes atomically.

Tutorial 04: Data Mapper & Repository Pattern 🏗️

For domain-heavy code, Rullst exposes a small Repository<T> contract. The framework does not invent SQL for this trait: your adapter owns its pool, queries, transactions, and error type. This keeps persistence behavior explicit and makes an in-memory implementation straightforward in unit tests.

GenericRepository<T> is currently only a zero-state marker/helper. It does not accept a pool and does not provide methods such as find_one_by.

Step 1: Implement a PostgreSQL repository

#![allow(unused)]
fn main() {
use rullst_orm::{async_trait, sqlx, FromRow, Repository};

#[derive(Debug, Clone, FromRow)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[derive(Clone)]
pub struct PgUserRepository {
    pool: sqlx::PgPool,
}

impl PgUserRepository {
    pub fn new(pool: sqlx::PgPool) -> Self {
        Self { pool }
    }

    pub async fn find_by_email(
        &self,
        email: &str,
    ) -> Result<Option<User>, sqlx::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users WHERE email = $1",
        )
        .bind(email)
        .fetch_optional(&self.pool)
        .await
    }
}

#[async_trait]
impl Repository<User> for PgUserRepository {
    type Id = i64;
    type Error = sqlx::Error;

    async fn find_by_id(&self, id: i64) -> Result<Option<User>, Self::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users WHERE id = $1",
        )
        .bind(id)
        .fetch_optional(&self.pool)
        .await
    }

    async fn find_all(&self) -> Result<Vec<User>, Self::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users ORDER BY id",
        )
        .fetch_all(&self.pool)
        .await
    }

    async fn save(&self, user: &User) -> Result<(), Self::Error> {
        sqlx::query(
            "INSERT INTO users (id, name, email) VALUES ($1, $2, $3) \
             ON CONFLICT (id) DO UPDATE SET name = $2, email = $3",
        )
        .bind(user.id)
        .bind(&user.name)
        .bind(&user.email)
        .execute(&self.pool)
        .await?;
        Ok(())
    }

    async fn delete(&self, id: i64) -> Result<(), Self::Error> {
        sqlx::query("DELETE FROM users WHERE id = $1")
            .bind(id)
            .execute(&self.pool)
            .await?;
        Ok(())
    }
}
}

All values are parameterized. SQL identifiers and the query shape remain application-owned source code.

Step 2: Inject the concrete adapter through Axum state

use std::sync::Arc;
use axum::{extract::State, http::StatusCode, Json};

pub async fn get_user_by_email(
    State(repository): State<Arc<PgUserRepository>>,
    email: String,
) -> Result<Json<User>, StatusCode> {
    repository
        .find_by_email(&email)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
        .map(Json)
        .ok_or(StatusCode::NOT_FOUND)
}

Production handlers should map internal database errors to an application error without returning query or credential details to clients.

Key takeaways

• Use derived Active Record models for direct typed CRUD.
• Use Repository<T> when the domain needs an explicit persistence boundary.
• The repository implementation, not the trait, determines the supported backend and SQL dialect.
• Add tenant/owner predicates inside repository queries where the resource is tenant- or user-scoped; dependency injection is not an authorization check.

Tutorial 05: Database Migrations & Seeders 🗄️

Rullst uses timestamped Rust migration modules for SQLx-primary projects. Turso primary projects receive explicit, reversible TursoMigration statements instead. This tutorial shows the SQLx path.

Step 1: Create a migration

cargo rullst make:migration create_products_table

The command creates src/migrations/m<timestamp>_create_products_table.rs and regenerates src/migrations/mod.rs. Edit the generated up and down methods:

#![allow(unused)]
fn main() {
use rullst_orm::{async_trait, schema::{Migration, Schema}};

pub struct MigrationImpl;

#[async_trait]
impl Migration for MigrationImpl {
    fn name(&self) -> &'static str {
        "m20260901000000_create_products_table"
    }

    async fn up(&self) -> Result<(), rullst_orm::Error> {
        Schema::create("products", |table| {
            table.id();
            table.string("name").not_null();
            table.integer("price_cents").not_null();
            table.timestamps();
        })
        .await
    }

    async fn down(&self) -> Result<(), rullst_orm::Error> {
        Schema::drop_if_exists("products").await
    }
}
}

Keep the generated timestamp/name in name(); the runner uses that stable value to record migration state.

Step 2: Run, inspect, and roll back migrations

cargo rullst db:migrate
cargo rullst db:status
cargo rullst db:rollback

db:rollback runs down() for the last recorded batch, in reverse order. The current SQLx migration runner does not wrap the whole batch automatically in one database transaction. Make every migration reversible, test both directions against each supported database, and use backend-appropriate transactional DDL inside the migration when atomicity is required.

Step 3: Define and register a seeder

use rullst_orm::{async_trait, Seeder};

pub struct AdminSeeder;

#[async_trait]
impl Seeder for AdminSeeder {
    async fn run(&self) -> Result<(), rullst_orm::Error> {
        let mut admin = crate::models::User {
            id: 0,
            name: "Admin User".to_string(),
            email: "admin@example.test".to_string(),
        };
        admin.save().await
    }
}

pub fn get_seeders() -> Vec<Box<dyn Seeder>> {
    vec![Box::new(AdminSeeder)]
}

Register migrations and seeders before starting the server:

rullst::artisan!(
    crate::migrations::get_migrations(),
    crate::seeds::get_seeders(),
);

Then run:

cargo rullst db:seed

Seeders execute sequentially. Make development/CI seeders idempotent if the command may run more than once. Never commit real passwords or provider secrets; for authentication records, hash a test password with rullst-auth or create a non-login fixture.

Key takeaways

• Migrations are Rust modules, not split up/down SQL files.
• Migration names and order are generated deterministically from timestamps.
• Batch tracking exists, but batch-wide transactional rollback is not implied.
• db:seed executes only seeders explicitly registered with artisan!.

Tutorial 06: HTMX-oriented server rendering 🎨

Rullst’s default scaffold renders HTML on the server and can use HTMX attributes for targeted requests and fragment swaps. It does not require a project-local SPA bundle, but HTMX itself is browser JavaScript and must be supplied, pinned, and permitted by the application’s CSP.

🛠️ Step 1: Render HTMX Components

In your controller or view:

#![allow(unused)]
fn main() {
use axum::response::Html;
use rullst::html;
use rullst::html::RawHtml;

pub async fn search_users() -> Html<String> {
    let results = vec!["Alice", "Bob", "Charlie"];
    let rows = results
        .into_iter()
        .map(|name| html! {
            <li class="py-2 text-slate-200">{name}</li>
        })
        .collect::<String>();

    Html(html! {
        <ul id="user-list" class="divide-y divide-slate-700">
            {RawHtml(rows)}
        </ul>
    })
}
}

RawHtml is appropriate here only because rows is composed exclusively from already-escaped html! fragments. Do not wrap untrusted request data directly in RawHtml.

💻 Step 2: Wire HTMX Attributes in Front-End HTML

<div class="max-w-md mx-auto p-6 bg-slate-800 rounded-xl shadow-md">
    <input 
        type="text" 
        name="query" 
        placeholder="Search users..." 
        class="w-full px-4 py-2 bg-slate-900 text-white rounded border border-slate-700 focus:outline-none"
        hx-post="/api/users/search" 
        hx-trigger="keyup changed delay:300ms" 
        hx-target="#user-list" 
        hx-swap="outerHTML" 
    />
    
    <div id="user-list" class="mt-4 text-slate-400">
        "Start typing to search..."
    </div>
</div>

💡 Key Takeaways

• Small application-owned client surface: business logic can remain on the server while HTMX coordinates browser requests.
• Partial rendering: handlers can return fragments instead of full pages. Measure page weight and latency for the actual application; no fixed size or load-time guarantee follows from the rendering style.

Tutorial 07: Forms & DTO Validation 📝

Rullst provides ValidatedForm<T> and ValidatedJson<T> extractors. They parse the request and run validator constraints before the handler is called. Invalid payloads become bounded 400 or 422 responses; HTMX requests receive an HTML error fragment and other clients receive JSON.

Step 1: Define a validated DTO

#![allow(unused)]
fn main() {
use serde::Deserialize;
use rullst::Validate;

#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserForm {
    #[validate(length(min = 3, max = 100))]
    pub name: String,

    #[validate(email)]
    pub email: String,

    #[validate(length(min = 12, max = 72))]
    pub password: String,
}
}

The 72-byte upper bound matches the current password hashing contract. Add a request-body limit at the router/proxy boundary as validation happens after body extraction.

Step 2: Validate and hash before persistence

The following handler assumes the User model generated by cargo rullst auth:

use axum::{http::StatusCode, response::Html};
use rullst::{html, ValidatedForm};
use rullst_auth::hash_password_async;

pub async fn store(
    ValidatedForm(form): ValidatedForm<CreateUserForm>,
) -> Result<Html<String>, StatusCode> {
    let password_hash = hash_password_async(form.password)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    let mut user = crate::models::User {
        id: 0,
        name: form.name.trim().to_owned(),
        email: form.email.trim().to_ascii_lowercase(),
        password_hash: Some(password_hash),
        oauth_provider: None,
        oauth_id: None,
        created_at: String::new(),
        updated_at: String::new(),
    };
    user.save()
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Html(html! {
        <div class="p-4 bg-emerald-900/50 text-emerald-300 rounded border border-emerald-500">
            <p>"User created successfully"</p>
        </div>
    }))
}

This is a continuation snippet because the generated model lives in the application crate. The checked extractor implementation itself is covered by rullst-core tests.

For a JSON endpoint, replace ValidatedForm with ValidatedJson; the DTO and handler body remain the same.

Key takeaways

• Validation is not sanitization and not authorization; enforce all three at their respective boundaries.
• Never store, log, or echo a plaintext password. Use the asynchronous Argon2id helper in request handlers.
• Enforce a unique database index on normalized email rather than relying only on a pre-insert lookup.
• Keep internal validation/database details out of production client errors.

Tutorial 08: Controllers, Routing & Middleware 🚦

Rullst’s Router wraps Axum’s router while preserving explicit Tower middleware composition. This example uses the Axum 0.8 request and Next types.

Step 1: Create a custom middleware

In src/middlewares/logger.rs:

#![allow(unused)]
fn main() {
use rullst::web::axum::{
    extract::Request,
    middleware::Next,
    response::Response,
};

pub async fn log_request(req: Request, next: Next) -> Response {
    let method = req.method().clone();
    let path = req.uri().path().to_owned();
    let response = next.run(req).await;

    // Prefer structured tracing in production; do not log query strings,
    // cookies, authorization headers, or request bodies by default.
    println!("[HTTP] {method} {path} -> {}", response.status());
    response
}
}

Step 2: Organize sub-routers

use rullst::{Router, Server, ServerError};
use rullst::routing::{get, post};
use rullst::web::axum::middleware;

async fn list_users() -> &'static str { "users" }
async fn create_user() -> &'static str { "created" }
async fn login() -> &'static str { "login" }

async fn log_request(
    request: rullst::web::axum::extract::Request,
    next: rullst::web::axum::middleware::Next,
) -> rullst::web::axum::response::Response {
    next.run(request).await
}

#[tokio::main]
async fn main() -> Result<(), ServerError> {
    let api = Router::new()
        .route("/users", get(list_users).post(create_user))
        .layer(middleware::from_fn(log_request));

    let auth = Router::new().route("/login", post(login));
    let app = Router::new()
        .nest("/api/v1", api)
        .nest("/auth", auth);

    Server::new(app).run(3000).await
}

Use nest_axum or merge_axum when integrating a third-party raw axum::Router.

Key takeaways

• Middleware order is security-sensitive. Use the canonical production baseline for secure headers, CSRF, CORS, and WAF rather than assembling those controls ad hoc.
• Authentication middleware establishes identity; handlers/repositories must still enforce resource ownership or role authorization.
• Apply request-body and concurrency limits before handlers that parse expensive or attacker-controlled input.

Tutorial 09: Environment Management & Configuration ⚙️

Rullst provides a validated runtime environment shared by its subsystems. New projects use RULLST_ENV; APP_ENV remains a legacy compatibility alias.

🛠️ Step 1: Define Environment Variables in .env

RULLST_ENV=development
PORT=3000
APP_KEY=REPLACE_WITH_YOUR_32_CHAR_RANDOM_KEY
DATABASE_URL=postgres://postgres:password@localhost:5432/my_app

💻 Step 2: Access Configuration in Rust

#![allow(unused)]
fn main() {
use rullst_core::config::RullstConfig;

fn report_environment() -> Result<(), Box<dyn std::error::Error>> {
    let environment = RullstConfig::global().environment()?;
    let database_is_configured = std::env::var_os("DATABASE_URL").is_some();

    println!(
        "Booting Rullst in {environment} mode; database configured: {database_is_configured}"
    );
    Ok(())
}
}

Do not log DATABASE_URL: it commonly embeds a username and password. Report only whether configuration is present, and redact sensitive fields in structured telemetry.

The generated server bootstrap loads .env before applying its runtime policy. Standalone utilities must load a dotenv file themselves or receive exported process variables. Environment precedence is exact: RULLST_ENV, legacy APP_ENV, then [app].env in Rullst.toml. Unknown values are configuration errors rather than silently becoming development.

Step 3: Configure the Browser Security Baseline

Server applies the same public apply_security_baseline composition in staging and production. CORS is deny-by-omission: list exact origins without a trailing slash, and enable credentialed cross-origin requests only when the application genuinely needs them.

[security]
csrf_same_site = "Strict"
cors_allow_origins = ["https://academy.example"]
cors_allow_credentials = false
csp = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self' 'nonce-{NONCE}'; style-src 'self' 'nonce-{NONCE}'"

Wildcard, path-bearing, credential-bearing, queried or duplicate CORS origins are configuration errors. When credentials are enabled, Core still grants them only to an origin in the exact allowlist. Test the final policy behind the real TLS proxy because an intermediary can change headers and cookie behavior.

💡 Key Takeaways

• Never hardcode credentials, database passwords, or JWT secrets in .rs source code.
• Add .env to .gitignore and commit .env.example to document required keys for team members.
• Prefer RULLST_ENV; keep APP_ENV only while migrating an existing project.

Tutorial 10: Static Assets & Pre-Compression 📦

The standard Server serves an existing static/ directory at /static. Production builds can create Brotli and Zstandard sidecars for eligible text and Wasm assets in that directory.

Step 1: Use the standard static directory

static/
├── css/
│   └── app.css
├── js/
│   └── app.js
└── favicon.svg

Reference those files through /static/..., for example /static/css/app.css. Server::run mounts the directory when it exists; no additional ServeDir layer is required for this standard path.

use rullst::{routes, routing::get, Server};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![get("/" => || async { "Rullst" })];
    Server::new(app).run(3000).await?;
    Ok(())
}

If you mount a different directory manually through Axum/Tower, its routing and pre-compressed negotiation become application responsibilities.

Step 2: Build production sidecars

cargo rullst build

The release-mode command builds the application and creates .br and .zst siblings for html, css, js, json, svg, wasm, xml, and txt files under static/. The standard server negotiates Brotli through ServeDir and Zstandard through its static middleware.

Verify deployed behavior rather than assuming negotiation worked:

curl --compressed -I -H 'Accept-Encoding: br' \
  http://127.0.0.1:3000/static/css/app.css
curl -I -H 'Accept-Encoding: zstd' \
  http://127.0.0.1:3000/static/css/app.css

Check Content-Encoding, Content-Type, cache headers, and Vary through the actual TLS proxy/CDN. Pre-compression avoids compression work per request; it does not eliminate file I/O or network latency.

Key takeaways

• Use static/ for the framework’s standard asset path and build integration.
• Keep source files alongside generated sidecars in the deployed artifact.
• Fingerprint immutable asset names and configure cache policy at the application/CDN boundary.

Tutorial 11: Authentication Scaffolding 🔒

The authentication generator creates a reviewable starting point for cookie-session login and registration. It is application source code, not a hosted identity service or a claim that every production policy is automatic.

Step 1: Run the generator

Run this from a Rullst project root:

cargo rullst auth

The current command creates or updates:

• src/models/user.rs;
• src/migrations/m<timestamp>_create_users_table.rs and the migrations module;
• src/controllers/auth_controller.rs;
• src/middlewares/auth_middleware.rs;
• src/pages/auth.rs; and
• the corresponding module declarations.

It does not support an auth --api flag, and it does not silently register application routes. Review the generated diff before editing or rerunning the command.

Step 2: Register the generated handlers

Wire the generated view, submit, logout, and authenticated routes in the application router. The exact route tree is an application decision; a typical mapping is:

use rullst::{routes, routing::{get, post}};
use crate::controllers::auth_controller;

let public_auth = routes![
    get("/login" => auth_controller::login_view),
    post("/login" => auth_controller::login_submit),
    get("/register" => auth_controller::register_view),
    post("/register" => auth_controller::register_submit),
    post("/logout" => auth_controller::logout),
];

The generated form pages expect the Core CSRF and CSP-nonce extensions. Apply the canonical security baseline and place authenticated routes behind the generated authentication middleware.

Step 3: Migrate and test

cargo rullst db:migrate
cargo rullst dev

Before production, exercise registration, login, logout, invalid credentials, duplicate email, expired/tampered cookies, CSRF failure, rate limiting, and key rotation. Configure a strong APP_KEY through a secret manager and HTTPS at the edge.

What the scaffold currently enforces

• Passwords are hashed with the asynchronous Argon2id helper; plaintext is not written to the user model.
• Registration accepts passwords from 12 through 72 bytes and normalizes email.
• Login performs a dummy password verification for unknown users to reduce the obvious account-enumeration timing difference.
• Session values use authenticated encryption and are emitted as cookie headers through rullst-auth helpers.

These controls do not replace application review. Add account verification, password reset/recovery, abuse controls, audit policy, MFA/passkeys, session revocation, and privacy/retention behavior according to the product’s threat model.

Tutorial 12: JWT and Cookie Sessions 🔑

Cookie sessions and bearer JWTs are transport choices with different operational trade-offs. Neither is automatically “for web” or “for mobile,” and neither removes the need for TLS, authorization, rotation, expiry, and revocation design.

Step 1: Generate JWT middleware

cargo rullst make:jwt

This creates src/middlewares/jwt_auth.rs, registers its module, and adds the direct jsonwebtoken, chrono, and serde dependencies when missing.

Configure a high-entropy secret plus exact issuer and audience values:

export JWT_SECRET="$(openssl rand -base64 48)"
export JWT_ISSUER="https://identity.example.test"
export JWT_AUDIENCE="rullst-api"

The generated HS256 validator requires sub, iss, aud, iat, and exp, checks expiry, and rejects secrets shorter than 32 bytes or with weak character diversity. Keep the secret out of source control and logs.

Step 2: Protect a route group

use rullst::{Router, routing::get};
use rullst::web::axum::middleware;
use crate::middlewares::jwt_auth::jwt_middleware;

pub fn protected_routes() -> Router {
    Router::new()
        .route("/profile", get(user_profile))
        .route("/orders", get(user_orders))
        .layer(middleware::from_fn(jwt_middleware))
}

Valid claims are inserted into request extensions. The handler must still map sub to a current account and enforce resource/tenant authorization. For long-lived systems, design key rotation and immediate revocation rather than assuming expiry alone is sufficient.

Choosing deliberately

• An HttpOnly, Secure, appropriately SameSite cookie reduces direct token reads by browser JavaScript. It does not neutralize XSS: injected code can still act as the user, and cookie requests need CSRF protection.
• A bearer token is convenient for interoperable API clients, but storage in a browser or native app is an application security decision. A stolen bearer token can be replayed until rejected or expired.
• Cookie and JWT strategies can coexist at different boundaries, but keep one authoritative identity/session lifecycle and test logout/revocation behavior.

Tutorial 13: RBAC, Ownership, and IDOR/BOLA Protection 🛡️

rullst-security provides role, owner, and tenant checks over a trusted UserContext. The framework cannot infer ownership from a route parameter: the application must load the resource and pass its stored owner/tenant identifiers to the guard.

Step 1: Authorize a trusted user context

#![allow(unused)]
fn main() {
use rullst_security::{RbacGuard, SecurityError, UserContext};

pub fn authorize_admin(user: &UserContext) -> Result<(), SecurityError> {
    RbacGuard::authorize(user, "admin")
}
}

Construct UserContext only after authentication. Roles, permissions, and tenant membership must come from trusted server-side state, not request headers or JSON supplied by the caller.

Step 2: Check the resource record, not request ownership

#![allow(unused)]
fn main() {
use rullst_security::{RbacGuard, SecurityError, UserContext};

pub struct DocumentAccess {
    pub owner_user_id: String,
    pub tenant_id: String,
}

pub fn authorize_document_update(
    user: &UserContext,
    stored: &DocumentAccess,
) -> Result<(), SecurityError> {
    RbacGuard::authorize_tenant_owner_or_role(
        user,
        &stored.tenant_id,
        &stored.owner_user_id,
        "document-editor",
    )
}
}

Load DocumentAccess with a parameterized query by the route’s document ID. Do not accept owner_user_id or tenant_id from the update payload. The tenant guard is evaluated first and roles — including admin — do not bypass a tenant mismatch.

For particularly sensitive paths, make the database query itself tenant-scoped and then apply the guard as a second boundary. Return the same not-found/forbidden shape where revealing resource existence would leak information.

Key takeaways

• authorize checks a role (and recognizes the framework’s admin role).
• authorize_owner_or_role is safe only when the owner ID came from trusted resource state.
• Use authorize_tenant_owner_or_role for tenant-bound resources.
• A helper contributes to IDOR/BOLA prevention only when every parameterized resource route invokes it or an equivalent scoped repository policy.

Tutorial 14: RASP — Runtime Application Self-Protection ⚡

rullst-security::rasp applies bounded heuristic signatures to request targets, non-secret headers, and supported textual bodies. Its current signatures cover common SQL injection, path traversal, SSRF, shell/RCE, and JNDI indicators. It does not claim general exploit detection.

🛠️ Step 1: Mount RaspSecurityLayer in main.rs

use axum::Router;
use rullst_security::rasp::RaspSecurityLayer;
use rullst::Server;

#[tokio::main]
async fn main() -> Result<(), rullst::ServerError> {
    let app = Router::new()
        // ... routes
        .layer(RaspSecurityLayer::default());

    Server::new(app.into()).run(3000).await
}

🧪 Step 2: Test Malicious Attack Payload Interception

Send an attack payload in query string:

curl "http://localhost:3000/api/users?query=SELECT%20*%20FROM%20users;--' OR 1=1"

For a recognized bounded signature, the layer returns 403 Forbidden and adds a process-local event to SecurityStore. A Studio instance running in the same process can display that event at http://127.0.0.1:5555/studio/security.

The body inspector accepts identity-encoded UTF-8 text, JSON, form, and XML media types up to 1 MiB. It fails closed for oversized declared bodies and encoded textual bodies that it cannot inspect. Put an independent request-body limit outside this layer as well.

💡 Key Takeaways

• Inspection has runtime cost and uses bounded pattern heuristics, with possible false positives and false negatives.
• RASP is defense in depth; parameterized SQL, validation, authorization, body limits, and dependency review remain required.

Tutorial 15: Vault and ORM field encryption

Rullst v12 can encrypt String and Option<String> model fields before they reach the database and decrypt them when a generated ORM query loads the model. The implementation uses AES-256-GCM with a fresh random nonce and an authenticated, versioned envelope.

1. Configure a current key

Generate 32 random bytes and store them as a prefixed base64 value. Do not commit this value to source control:

export RULLST_ENCRYPTION_KEY="base64:$(openssl rand -base64 32)"
export RULLST_ENCRYPTION_KEY_ID="production-2026-01"

RULLST_ENCRYPTION_KEY accepts base64:<value>, hex:<value>, or a legacy raw value containing exactly 32 UTF-8 bytes. A secret manager or KMS-backed deployment adapter should inject it at runtime. Rullst does not provide key custody.

2. Mark model fields

#![allow(unused)]
fn main() {
use rullst_orm::FromRow;

#[derive(Clone, Debug, FromRow, rullst_orm::Orm)]
#[orm(table = "users")]
pub struct User {
    pub id: i32,
    pub email: String,
    #[orm(encrypted)]
    pub tax_id: String,
    #[orm(encrypted)]
    pub recovery_note: Option<String>,
}
}

Generated save, update_partial, find, all, query-builder loads and streams preserve plaintext in the Rust model while storing an envelope shaped like this in the SQL column:

RULLST:v2:<key_id>:<base64url_nonce>:<base64url_ciphertext_and_tag>

The table and column names are authenticated as additional data. Copying a ciphertext into a different annotated column therefore fails decryption.

3. Rotate a key without downtime

Set the new current key and keep old readable keys in a JSON keyring:

export RULLST_ENCRYPTION_KEY="base64:<new-32-byte-key>"
export RULLST_ENCRYPTION_KEY_ID="production-2027-01"
export RULLST_ENCRYPTION_KEYRING='{
  "production-2026-01": "base64:<old-32-byte-key>"
}'

Reads select the key named by the envelope. A normal full save() rewrites all annotated values with the current key. Keep every key needed by existing rows until a separately monitored migration has rewritten and verified them; then remove the retired key.

4. Understand query limits

AES-GCM encryption is randomized, so the same plaintext produces different ciphertexts. Generated queries reject encrypted fields in WHERE, ORDER BY, GROUP BY, and explicit SELECT clauses rather than silently returning wrong results. pluck_string supports non-null encrypted strings; load the model for nullable encrypted strings.

For lookup, add a separate application-designed blind-index column and assess its equality-leakage and key-rotation trade-offs. Rullst v12 does not generate a blind index automatically. Raw SQL is an explicit escape hatch and does not automatically encrypt bindings or decrypt arbitrary projections.

5. Reduce secret lifetime in memory

VaultSecret<T> redacts Debug/Display and calls Zeroize on the wrapped value when dropped:

#![allow(unused)]
fn main() {
use rullst_security::VaultSecret;

fn use_api_key() {
    let Ok(value) = std::env::var("EXAMPLE_PROVIDER_KEY") else {
        return;
    };
    let api_key = VaultSecret::new(value);
    send_request(api_key.expose_secret());
}

fn send_request(_: &str) {}
}

Zeroization is defense in depth, not secure memory. It cannot erase prior copies or prevent a debugger, core dump, swap, allocator behavior, or another process-memory capture while the secret is live.

Operational checklist

• Back up the database and keyring together, with separate access controls.
• Test restore and rotation before retiring any key.
• Restrict environment and crash-dump access.
• Never log plaintext model fields or expose them through serialization by accident; add #[orm(hidden)] when a field must be omitted from generated to_json() output.
• Treat authentication failure as possible corruption, wrong context, wrong key, or tampering; do not replace it with an empty value.

Tutorial 16: LiveView Server-Driven UI (rullst::live) ⚡

Build a per-connection Rust component that receives JSON events and sends rendered HTML over WebSockets. The browser still needs the HTMX WebSocket extension (or a compatible client transport).

🛠️ Step 1: Scaffold a LiveComponent

cargo rullst make:live CounterComponent

This creates src/live/counter_component.rs.

💻 Step 2: Implement the Component Lifecycle

The following controller fragment expects the generated crate::live::counter_component module from Step 2:

#![allow(unused)]
fn main() {
use async_trait::async_trait;
use rullst::live::LiveComponent;
use serde_json::Value;

#[derive(Default)]
pub struct CounterComponent {
    pub count: i32,
}

#[async_trait]
impl LiveComponent for CounterComponent {
    async fn mount(&mut self) {
        self.count = 10;
    }

    async fn handle_event(&mut self, payload: Value) {
        if let Some(action) = payload.get("action").and_then(|v| v.as_str()) {
            match action {
                "increment" => self.count += 1,
                "decrement" => self.count -= 1,
                _ => {}
            }
        }
    }

    fn render(&self) -> String {
        format!(
            r#"<div id="counter-component" class="p-6 bg-slate-800 text-white rounded-xl">
    <h2 class="text-xl font-bold">Counter: {}</h2>
    <button ws-send name="action" value="increment" class="px-4 py-2 bg-emerald-600 rounded">+1</button>
</div>"#,
            self.count
        )
    }
}
}

💻 Step 3: Mount Component in a Controller

This route fragment belongs in the same application module where CounterComponent is in scope:

use rullst::live::Live;
use crate::live::counter_component::CounterComponent;

pub async fn page_handler() -> String {
    Live::mount::<CounterComponent>("/ws/counter").await
}

Register the matching Axum WebSocket route:

use axum::{routing::get, Router};
use rullst::live::live_ws_handler;

let app = Router::new().route(
    "/ws/counter",
    get(live_ws_handler::<CounterComponent>),
);

💡 Key Takeaways

• Event payloads travel over WebSocket connections; render() produces updated HTML fragments.
• The current component state lives in one socket task. Authentication, authorization, reconnect/replay, backpressure and multi-process state remain application concerns.
• Include and pin the HTMX WebSocket extension; Rullst does not inject that browser dependency automatically.

Tutorial 17: In-process realtime and presence

Rullst Core provides bounded in-process broadcast channels and presence state. These primitives do not create an HTTP WebSocket endpoint by themselves and do not synchronize independent server processes.

Subscribe before publishing

#![allow(unused)]
fn main() {
use std::sync::Arc;

use rullst::realtime::{BroadcastManager, RealtimeError, RealtimeMessage};

async fn local_exchange() -> Result<RealtimeMessage, RealtimeError> {
    let manager = Arc::new(BroadcastManager::new());
    let mut receiver = manager.get_or_create("room:general").subscribe();

    manager.publish(
        "room:general",
        "message.created",
        r#"{"sender":"alice","content":"hello"}"#,
    )?;

    receiver
        .recv()
        .await
        .map_err(|error| RealtimeError::BroadcastError(error.to_string()))
}
}

Channel uses tokio::sync::broadcast: a slow receiver can lag, and publishing without any receiver returns RealtimeError::BroadcastError.

Bind channels and presence to an authenticated tenant

Construct TenantContext only from trusted authentication/membership state. The wrappers validate logical names and ensure that identical room names use different backend namespaces:

#![allow(unused)]
fn main() {
use std::sync::Arc;

use rullst::realtime::{
    BroadcastManager, PresenceTracker, TenantPresence, TenantRealtime,
};
use rullst::security::TenantContext;

fn publish_for_school() -> Result<(), Box<dyn std::error::Error>> {
    let context = TenantContext::try_new("school-alpha")?;
    let realtime = TenantRealtime::from_context(
        Arc::new(BroadcastManager::new()),
        &context,
    );
    let presence = TenantPresence::from_context(
        Arc::new(PresenceTracker::new()),
        &context,
    );

    let mut receiver = realtime.subscribe("course/42")?;
    presence.user_joined("course/42", "learner-7")?;
    realtime.publish("course/42", "lesson.completed", r#"{"lesson_id":9}"#)?;

    assert_eq!(presence.count_online("course/42")?, 1);
    assert!(receiver.try_recv().is_ok());
    Ok(())
}
}

The tenant wrapper limits names and payloads (64 KiB), but the application still owns authentication, room-level authorization, connection lifecycle and replay. Use rullst::live::live_ws_handler for the separate per-connection LiveComponent flow, or build an Axum WebSocket handler around these primitives. A distributed transport is still roadmap work.

Tutorial 18: Wasm Island foundation

Rullst can generate a dual-target Island function: native builds emit a host element with serialized props, while wasm32-unknown-unknown builds export a hydration function.

Generate the component

cargo rullst make:island InteractiveChart

The generated src/islands/interactive_chart.rs uses the supported macro:

#![allow(unused)]
fn main() {
use rullst::island;

#[cfg(target_arch = "wasm32")]
use wasm_bindgen::{closure::Closure, JsCast};

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InteractiveChartProps {
    pub initial_value: i32,
}

#[island]
pub fn interactive_chart(props: InteractiveChartProps) {
    #[cfg(not(target_arch = "wasm32"))]
    {
        format!(
            "<button type=\"button\">Count: {}</button>",
            props.initial_value
        )
    }

    #[cfg(target_arch = "wasm32")]
    {
        let mut value = props.initial_value;
        element.set_text_content(Some(&format!("Count: {value}")));

        let button = element.clone();
        let closure = Closure::<dyn FnMut()>::new(move || {
            value = value.saturating_add(1);
            button.set_text_content(Some(&format!("Count: {value}")));
        });
        if element
            .add_event_listener_with_callback("click", closure.as_ref().unchecked_ref())
            .is_ok()
        {
            closure.forget();
        }

        String::new()
    }
}
}

The element binding in the Wasm block is supplied by #[island].

Build and load the artifact

cargo rullst build:client

The command parses Cargo.toml, adds cdylib to the existing [lib] crate-type array when needed, installs/checks the Wasm target and wasm-bindgen-cli, builds the library, locates the artifact using lib.name or package.name, writes bindings under static/, and generates a hydration orchestrator. Review these manifest, network, and toolchain side effects in CI and pin the required tools for reproducible releases. Load the generated ES module from the page as instructed by the command output.

This is a useful foundation, not a complete frontend framework: routing, application state, accessibility, CSP-compatible asset delivery, cache busting, error reporting and browser E2E remain application/release work.

Tutorial 19: SaaS billing with Rullst Capital 💳

This tutorial creates a checkout adapter boundary and explains how to feed the optional local Studio view without treating it as an accounting system.

1. Scaffold and configure the selected adapter

cargo rullst make:billing --model Workspace

The command detects a relational SQLx or Turso-primary project, adds the exact orm and capital facade features once, generates a reversible matching migration, registers the models/controller/page modules, and refuses to overwrite an earlier billing scaffold. The generated runtime supports the selected stripe or lemonsqueezy adapter. It deliberately does not imply support for every Capital adapter or mount application routes without review.

Set BILLING_ALLOWED_PLAN_IDS to the exact comma-separated provider price or variant IDs the server may accept. Production startup rejects a missing allowlist; a query-string plan outside it is denied before creating a billing customer.

Use the exact environment names emitted by the generated files and keep live credentials outside source control. Credentials beginning with mock_ select a documented deterministic offline path; they are not accepted by the production-safe webhook middleware.

2. Create a checkout session

#![allow(unused)]
fn main() {
use rullst_capital::{init_provider, provider, StripeProvider};

async fn checkout_url() -> Result<String, String> {
    let api_key = std::env::var("STRIPE_SECRET_KEY")
        .map_err(|error| format!("missing Stripe key: {error}"))?;
    let webhook_secret = std::env::var("STRIPE_WEBHOOK_SECRET")
        .map_err(|error| format!("missing webhook secret: {error}"))?;

    init_provider(Box::new(StripeProvider::new(api_key, webhook_secret)));
    let selected = provider().ok_or_else(|| "billing provider is not configured".to_string())?;
    selected
        .create_checkout_session(
            "customer@example.com",
            "price_pro_monthly",
            "https://app.example/billing/success",
        )
        .await
        .map_err(|error| error.to_string())
}
}

The scaffold requires an authenticated BillingIdentity for checkout/portal, enforces that server-owned plan allowlist, and rejects subscription reuse across owners. The application still owns the identity middleware, correct plan configuration, return-URL policy, durable provider-event idempotency/reconciliation, and provider sandbox validation.

2.1 Handle provider failure without blindly repeating a charge

Built-in live adapters return a redacted CapitalError::Provider for outbound request construction, transport, HTTP status, bounded-response, JSON, and response-contract failures. Inspect its stable class for telemetry or a durable job decision:

#![allow(unused)]
fn main() {
use rullst_capital::{CapitalError, ProviderFailureClass};

fn provider_disposition(error: &CapitalError) -> Option<ProviderFailureClass> {
    match error {
        CapitalError::Provider(failure) => Some(failure.class()),
        _ => None,
    }
}
}

Do not turn Transient or RateLimited into an unconditional loop. Persist the original command and idempotency identity, confirm that the selected operation actually forwards that identity, cap attempts with backoff/jitter, and reconcile signed provider events. Checkout creation in the legacy unified trait does not accept an application idempotency key, so reconcile before repeating it. The shared client already applies finite timeouts, disables redirects and ambient proxies, caps JSON to one MiB, and validates returned checkout URLs as absolute credential-free HTTPS.

3. Make a bounded immediate charge when checkout is not the right flow

For a payment method already tokenized and authorized for off-session reuse at Stripe, the model deriving Billable can perform one fully specified charge:

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, StripeProvider};

async fn charge_saved_method(
    account: &(impl rullst_capital::Billable + Sync),
    stripe: &StripeProvider,
) -> Result<String, CapitalError> {
    let receipt = account
        .charge_with(
            stripe,
            2_500,
            "BRL",
            "cus_from_authoritative_state",
            "pm_from_authoritative_state",
            "order_2026_0001-attempt_1",
        )
        .await?;
    Ok(receipt.charge_id().to_string())
}
}

This deliberately is not charge(amount): currency, provider customer, tokenized payment method and retry identity cannot be inferred safely. The Stripe adapter uses Payment Intents with immediate off-session confirmation and the provider idempotency header. Only succeeded and processing are accepted; an amount/currency mismatch or a flow requiring customer action fails closed. Credentials beginning with mock_ return the same deterministic receipt with the distinct non-success ChargeStatus::Mock for an exact retry. The mock is not a mandate, durable idempotency store or live sandbox test. Other adapters return UnsupportedOperation until reviewed individually.

4. Render and deliver the invoice only after final success

Enable capital-mail on the umbrella crate (or invoice-pdf on Capital plus capital-invoice on Mail). Build the invoice from authoritative order state, then bind it to the returned receipt:

#![allow(unused)]
fn main() {
use chrono::Utc;
use rullst::capital::{ChargeReceipt, Invoice, InvoiceItem};
use rullst::mail::PaidInvoiceDelivery;

async fn deliver_invoice(receipt: &ChargeReceipt) -> Result<(), Box<dyn std::error::Error>> {
    let invoice = Invoice {
        invoice_id: "INV-2026-0001".to_string(),
        customer_email: "customer@example.com".to_string(),
        date: Utc::now(),
        items: vec![InvoiceItem {
            description: "Pro subscription".to_string(),
            amount: 25.00,
        }],
        total: 25.00,
        currency: "BRL".to_string(),
    };

    let paid = invoice.bind_succeeded_charge(receipt)?;
    let delivery = PaidInvoiceDelivery::prepare(&paid)?;

    // In production, atomically claim this stable key in a durable outbox.
    let _delivery_key = delivery.delivery_key();
    delivery.send().await?;
    Ok(())
}
}

The binding rejects Processing, Mock, a mismatched recipient, amount or currency. The default PDF is paginated, bounded to sixteen MiB and supports WinAnsi text (including common Portuguese characters); pass a checked TTF/OTF to Capital for other scripts. Mail applies its mandatory pre-flight before the facade queues or sends the HTML message and attachment.

This helper does not subscribe to webhooks by itself. Reconcile the provider event, build the authoritative invoice and insert delivery_key under a unique database constraint in the same application workflow. Mail delivery remains at least once: a crash and retry can still require provider/application deduplication.

5. Report metered usage without confusing provider identities

Use the provider-specific static trait for new code. Stripe Meter Events need a customer ID and configured event name, not a subscription-item ID:

#![allow(unused)]
fn main() {
use rullst_capital::{
    CapitalError, MeteredBillingProvider as _, StripeMeterEvent, StripeProvider,
};

async fn report_ai_exercises(stripe: &StripeProvider) -> Result<(), CapitalError> {
    let event = StripeMeterEvent::new(
        "cus_from_authoritative_state",
        "ai_exercises",
        3,
        "usage:school-7:attempt-99",
    )?;
    let receipt = stripe.report_metered_usage(&event).await?;
    assert_eq!(receipt.quantity(), 3);
    Ok(())
}
}

Lemon Squeezy instead needs its numeric subscription-item relationship and an aggregation action:

#![allow(unused)]
fn main() {
use rullst_capital::{
    CapitalError, LemonSqueezyProvider, LemonSqueezyUsageAction,
    LemonSqueezyUsageRecord, MeteredBillingProvider as _,
};

async fn report_lesson_minutes(
    lemon: &LemonSqueezyProvider,
) -> Result<(), CapitalError> {
    let record = LemonSqueezyUsageRecord::new(
        "42",
        "lesson_minutes",
        15,
        LemonSqueezyUsageAction::Increment,
        "usage:school-7:lesson-session-123",
    )?;

    // Atomically claim record.event_key() in a durable outbox before this call.
    let receipt = lemon.report_metered_usage(&record).await?;
    assert_eq!(receipt.quantity(), 15);
    Ok(())
}
}

Use Increment only with a sum-of-usage aggregation and Set only with the matching latest-value aggregation. Stripe receives the identifier but enforces it only within a rolling window. Lemon’s request does not receive the application event key at all, so durable application deduplication is mandatory. The adapters cap and bind responses, while provider sandbox/live acceptance, retry, invoice reconciliation and entitlement updates remain release and application work. Empty or mock_* API keys produce a deterministic UsageStatus::Mock, never billable evidence.

6. Verify webhooks before business processing

Mount rullst_capital::verify_webhook on the exact provider callback route as shown in the Capital crate guide. Apply any CSRF exemption only to that exact signed route. Never update access or subscription state from an unverified request.

The default replay store protects one process. For multiple processes, rullst-capital/webhook-sql provides a bounded SQL ledger for SQLite, PostgreSQL, MySQL, and MariaDB. Its middleware form claims the signed payload before dispatch and therefore does not guarantee exactly-once processing after a crash. When a subscription mutation must be atomic, use the provider’s verified stable event ID with SqlWebhookReplayStore::check_and_record_event_key_with_transaction in the same database transaction as that mutation; do not also pre-claim that event through SQL middleware. See the payment guide for setup and operational boundaries.

7. Use a bounded subscription handle and grace period

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, GracePeriod, StripeProvider};

async fn pause_with_local_policy(
    workspace: &impl rullst_capital::Billable,
    provider: &StripeProvider,
) -> Result<(), CapitalError> {
    let grace = GracePeriod::new(1_900_000_000, 1_900_604_800)?;
    let handle = workspace
        .subscription_with(provider)?
        .with_grace_period(grace);
    handle.pause().await
}
}

The grace value does not schedule the pause or grant access by itself. Persist it with authoritative subscription state, evaluate it against a trusted clock inside the entitlement check, and confirm the selected adapter’s live pause or cancel semantics.

The same statically dispatched handle validates coupon IDs and gives the historical relative-trial API its intended meaning:

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, StripeProvider};

async fn grant_a_retention_offer(
    workspace: &impl rullst_capital::Billable,
    stripe: &StripeProvider,
    command_created_at: i64,
) -> Result<(), CapitalError> {
    let subscription = workspace.subscription_with(stripe)?;
    subscription.apply_coupon("RETENTION_25").await?;

    // Fifteen whole days. Persist command_created_at and reuse it on retries.
    subscription
        .extend_trial_days_at(15, command_created_at)
        .await
}
}

extend_trial(15) uses the current UTC time for interactive convenience. Workers should persist their command time and use extend_trial_days_at so a retry sends the identical expiration; set_trial_end is the explicit absolute timestamp operation. Stripe has the reviewed live coupon path. Lemon Squeezy discount codes belong to checkout and therefore fail explicitly when applied to an existing live subscription; both Stripe and Lemon Squeezy have reviewed trial-update protocol fixtures. Authorize the subscription owner before building the handle, serialize conflicting updates, and reconcile the signed provider webhook because trial changes can affect billing anchors and charges.

8. Enforce one shared workspace quota before creation

Enable quota-sql directly, or capital-quota-sql on the umbrella crate. The authenticated middleware must first establish the active TenantContext; do not build a billing subject from an arbitrary header or request field.

Billable::quota_request reads the limit from the subscription owner’s tier_limit implementation. Give every attempted creation a stable event key, normally the ID of the application command/request rather than a random value generated on every retry.

#![allow(unused)]
fn main() {
use rullst::{
    capital::{Billable as _, BillingSubject, QuotaError, SqlQuotaStore},
    security::TenantContext,
};

async fn create_project(
    workspace: &impl rullst::capital::Billable,
    tenant: &TenantContext,
    quotas: &SqlQuotaStore,
    project_id: &str,
) -> Result<bool, Box<dyn std::error::Error>> {
    let subject = BillingSubject::from_tenant(tenant)?;
    let request = workspace.quota_request(
        subject,
        "projects",
        format!("create-project:{project_id}"),
        1,
    )?;

    let mut transaction = quotas.pool().begin().await?;
    let grant = match quotas
        .reserve_with_transaction(&mut transaction, &request)
        .await
    {
        Ok(grant) => grant,
        Err(QuotaError::LimitExceeded { .. }) => {
            transaction.rollback().await?;
            return Ok(false);
        }
        Err(error) => {
            transaction.rollback().await?;
            return Err(error.into());
        }
    };

    if grant.is_replay() {
        transaction.rollback().await?;
        return Ok(true);
    }

    let inserted = rullst::orm::sqlx::query(
        "INSERT INTO projects (id, workspace_id) VALUES (?, ?)",
    )
    .bind(project_id)
    .bind(tenant.tenant_id.as_str())
    .execute(&mut *transaction)
    .await;
    if let Err(error) = inserted {
        transaction.rollback().await?;
        return Err(error.into());
    }
    transaction.commit().await?;
    Ok(true)
}
}

The placeholder above is SQLite/MySQL syntax; use $1, $2 for a raw PostgreSQL insert, or use the ORM operation that participates in the same transaction. SqlQuotaStore uses a unique event claim plus a conditional counter update, so concurrent members cannot both pass the last available unit. An exact retry returns is_replay() without consuming again; reusing the same key with different units or a different limit fails closed.

For work that cannot share the SQL transaction, QuotaGate::execute still blocks the callback before an over-limit/replayed operation and releases the reservation after an ordinary callback error. A process crash between a standalone reservation and the external side effect is intentionally conservative and needs application reconciliation; the framework never risks exceeding the quota to guess whether that external effect happened.

9. Supply an optional local revenue snapshot

RevenueDashboardManager does not derive money or subscribers from event names. After durable reconciliation, the application may call update_metrics with its authoritative snapshot and record_event with a bounded inspection record. The standalone Studio can display that process-local source at /studio/capital when it is explicitly connected. It neither auto-discovers webhook routes nor auto-syncs the application database.

Provider-hosted checkout normally keeps card collection away from the application, but the final data boundary depends on the selected provider flow, application logs, analytics, and deployment.

Tutorial 20: Background Jobs & Task Queues ⚙️

Rullst Core provides named JSON jobs, SQLite and Redis storage drivers, and a bounded-concurrency worker. Job handlers are closures registered against a stable name; there is no Job trait or process-global Queue::dispatch API.

Step 1: Scaffold a handler module

cargo rullst make:worker EmailWorker

This creates src/workers/email_worker.rs, registers it in src/workers/mod.rs, and provides start_workers. Replace the generated log-only body with the application operation. Avoid logging the complete job payload, because it can contain personal or secret data.

Step 2: Create a queue and keep its worker handle alive

#![allow(unused)]
fn main() {
use rullst::queue::{Queue, QueueError, Worker, WorkerHandle};
use serde_json::json;

fn start_email_worker(queue: &Queue) -> Result<WorkerHandle, QueueError> {
    let mut worker = Worker::new(queue)
        .max_concurrency(8)
        .poll_interval(250);
    worker.register("email", |payload| async move {
        let recipient = payload
            .get("recipient")
            .and_then(|value| value.as_str())
            .ok_or_else(|| {
                std::io::Error::new(std::io::ErrorKind::InvalidData, "missing recipient")
            })?;

        // Call an idempotent mail service with a stable delivery key here.
        let _ = recipient;
        Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
    });
    worker.run()
}

async fn configure() -> Result<(Queue, WorkerHandle), QueueError> {
    let queue = Queue::sqlite("sqlite://queue.db?mode=rwc").await?;
    let handle = start_email_worker(&queue)?;
    queue
        .dispatch(
            "email",
            json!({"recipient": "learner@example.test", "delivery_key": "welcome:42"}),
        )
        .await?;
    Ok((queue, handle))
}
}

Dropping WorkerHandle stops processing. On graceful shutdown, call handle.shutdown().await and inspect its typed error.

Use Queue::redis(redis_url) with the queue-redis feature when independent processes must share work. SQLite is durable local state and supports atomic claims, but it is not a distributed queue.

Failure, retry, and delivery semantics

• A handler error, panic, or timeout is recorded as failed. Core does not automatically retry it with exponential backoff.
• retry_failed_job(job_id) explicitly returns a failed job to pending state.
• SQLite and Redis recover stale processing leases and support scheduled jobs, but execution time is the first worker poll after the due timestamp.
• Queue processing is at least once around crashes and external side effects. Give provider operations stable idempotency keys and reconcile ambiguous outcomes.
• Successful payloads are deleted by default. SQLite completed history is an explicit bounded opt-in with its own privacy/access-control obligations.

See the Redis Architecture Guide for deployment boundaries.

Tutorial 21: Explicit Local AI with Ollama 🤖

Use an explicit OllamaProvider when a workload must not fall through to a configured cloud provider. AiClient::auto() is a convenience fallback chain; it is not an isolation policy when cloud API keys are also present.

Step 1: Configure the local endpoint

OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=llama3:8b

Bind Ollama to loopback or a controlled private interface. Pull and license the chosen model through a reviewed provisioning step rather than silently during a request.

Step 2: Construct the provider explicitly

#![allow(unused)]
fn main() {
use rullst_ai::ai::{AiClient, AiError, providers::ollama::OllamaProvider};

pub async fn summarize_lesson(text: &str) -> Result<String, AiError> {
    let host = std::env::var("OLLAMA_HOST")
        .map_err(|_| AiError::ConfigError("OLLAMA_HOST is required".to_string()))?;
    let model = std::env::var("OLLAMA_MODEL")
        .map_err(|_| AiError::ConfigError("OLLAMA_MODEL is required".to_string()))?;
    let client = AiClient::new(OllamaProvider::new(host, model));

    client
        .prompt(&format!(
            "Summarize this lesson in three factual bullet points:\n{text}"
        ))
        .await
}
}

The high-level client applies Rullst’s mandatory prompt/PII guardrails before dispatch. Model output remains untrusted: escape it for HTML, validate structured data, and never use an LLM verdict as the only authentication, authorization, malware, or abuse-control decision.

Isolation checklist

• Confirm the resolved endpoint, host firewall, container network, DNS, proxy, and telemetry configuration.
• Remove cloud-provider credentials from the process when policy requires local only; an explicit provider prevents fallback but least privilege still helps.
• Review application/Ollama logs, model caches, backups, crash dumps, and swap for sensitive data.
• Empty or mock_* Ollama hosts select deterministic offline mock behavior; a mock response is test evidence, not evidence that a live model ran.

“Local” does not prove an air gap. Verify the complete deployed data flow.

22. RAG Systems & Vector Search

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Rullst provides three deliberately separate vector paths: a deterministic in-memory index in rullst-ai, parameterized PostgreSQL pgvector queries, and a bounded Qdrant HTTP adapter in rullst-orm. None silently invent tenant authorization, context budgets, an embedding model, or a production RAG policy.

In-memory retrieval

VectorIndex is useful for bounded local datasets and tests:

[dependencies]
rullst = { version = "12.0.0-rc.1", default-features = false, features = ["ai"] }
serde_json = "1.0"

#![allow(unused)]
fn main() {
use rullst::ai::VectorIndex;

let mut index = VectorIndex::new();
index.add(
    "rullst",
    vec![1.0, 0.0, 0.0],
    serde_json::json!({"text": "Rullst is a Rust framework suite."}),
);
index.add(
    "other",
    vec![0.0, 1.0, 0.0],
    serde_json::json!({"text": "An unrelated document."}),
);

let matches = index.search(&[0.9, 0.1, 0.0], 3);
assert_eq!(matches[0].1.id, "rullst");
}

The caller supplies the embedding and the limit. This process-local index is not durable, distributed, tenant-aware, or an approximate-nearest-neighbor service.

PostgreSQL + pgvector

Enable the typed vector and concrete PostgreSQL paths:

[dependencies]
rullst = { version = "12.0.0-rc.1", default-features = false, features = [
  "orm-pgvector",
  "strict-postgres",
  "ai",
] }

Install the extension through a reviewed PostgreSQL migration and choose the dimension used by your embedding provider:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE knowledge_chunks (
    id SERIAL PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536) NOT NULL
);

The model can use the re-exported typed Vector:

#![allow(unused)]
fn main() {
use rullst::orm::{FromRow, Orm, Vector};

#[derive(Clone, Debug, FromRow, Orm)]
#[orm(table = "knowledge_chunks", tenant_column = "tenant_id")]
struct KnowledgeChunk {
    id: i32,
    tenant_id: String,
    content: String,
    embedding: Vector,
}
}

Generate the query embedding through a configured guarded AI client, establish the authenticated tenant scope, and then use the native operators:

#![allow(unused)]
fn main() {
use rullst::ai::AiClient;
use rullst::orm::{FromRow, Orm, Vector, with_tenant};

#[derive(Clone, Debug, FromRow, Orm)]
#[orm(table = "knowledge_chunks", tenant_column = "tenant_id")]
struct KnowledgeChunk {
    id: i32,
    tenant_id: String,
    content: String,
    embedding: Vector,
}

async fn retrieve(
    client: &AiClient,
    question: &str,
) -> Result<Vec<KnowledgeChunk>, Box<dyn std::error::Error>> {
let embedding = client.embed(question).await?;
let query: Vec<f64> = embedding.iter().map(|value| f64::from(*value)).collect();

let chunks = with_tenant("tenant-42", async move {
    KnowledgeChunk::query()
        .where_similar("embedding", query.clone(), 0.8)
        .order_by_cosine_distance("embedding", query)
        .limit(5)
        .get()
        .await
})
.await?;
Ok(chunks)
}
}

Vector and distance values are SQL bindings, not interpolated literals. Column names use the normal identifier validation, vectors must be finite/non-empty, and the distance must be finite and non-negative. The pgvector feature also supplies SQLx encode/decode for the typed field. Rullst’s live contract creates the extension, inserts typed vectors, and executes L2 and cosine queries against a digest-pinned pgvector/pgvector container.

Qdrant dense-vector store

Use Qdrant when the application deliberately chooses a specialized external vector service rather than keeping vectors in PostgreSQL:

[dependencies]
rullst = { version = "12.0.0-rc.1", default-features = false, features = [
  "orm-qdrant",
  "ai",
] }
serde_json = "1.0"

#![allow(unused)]
fn main() {
use rullst::orm::{
    QdrantConfig, QdrantStore, VectorCollectionName, VectorDimensions,
    VectorPoint, VectorQueryLimit, VectorRepository,
};
use serde_json::{Map, Value};

async fn qdrant_example() -> Result<(), Box<dyn std::error::Error>> {
let config = QdrantConfig::new(
    std::env::var("QDRANT_URL").unwrap_or_default(),
    std::env::var("QDRANT_API_KEY").unwrap_or_default(),
);
let vectors = QdrantStore::connect_or_mock(config)?;
let collection = VectorCollectionName::new("knowledge-v1")?;
vectors
    .create_collection(&collection, VectorDimensions::new(3)?)
    .await?;

let mut payload = Map::new();
payload.insert("chunk_id".into(), Value::String("chunk-42".into()));
vectors
    .upsert(
        &collection,
        VectorPoint::new(42, vec![1.0, 0.0, 0.0], payload)?,
    )
    .await?;
let matches = vectors
    .search(
        &collection,
        &[0.9, 0.1, 0.0],
        VectorQueryLimit::new(5)?,
    )
    .await?;
let _ = matches;
Ok(())
}
}

Empty or mock_* endpoint/API-key values select the deterministic in-process backend. An explicit QdrantConfig::unauthenticated_local is available only for loopback self-hosting. The live contract is deliberately limited to one unnamed dense cosine vector per numeric point. It bounds identifiers, dimensions, finite/non-zero-norm vectors, 1 MiB object payloads, top-k, request and response memory, deadlines and redirects. It does not claim named, sparse or multivectors, arbitrary filters, hosted availability, ANN index tuning or tenant authorization. A digest-pinned Qdrant lifecycle proves the supported operations.

Orchestrate one bounded RAG operation

The compatibility build_rag_prompt helper only formats already-authorized text. Prefer RagPipeline when the application needs one typed operation for embedding, retrieval, context budgets, guarded generation, source metadata, and mandatory auditing:

#![allow(unused)]
fn main() {
use rullst::ai::rag::{RagPipeline, RagRetriever};

fn compose<R, A>(client: rullst::ai::AiClient, retriever: R, audit: A)
where
    R: RagRetriever,
    A: rullst::ai::rag::RagAuditSink,
{
let pipeline = RagPipeline::new(client, retriever, audit);
let _ = pipeline;
}
}

The retriever receives a trusted tenant context and must enforce authoritative tenant and ownership predicates in its datastore query. The pipeline also rejects differently tagged documents and refuses ungrounded generation when no safe context remains. Follow the complete Tenant-Bound RAG tutorial for the offline index, production adapter boundary, and secret-minimized audit contract.

The application still owns embedding dimension/model compatibility, durable ingestion and deletion, citation evaluation, index tuning, authorization, output policy, observability, and recovery.

Tutorial 23: Process Telemetry & Prometheus Exporter 📡

Monitor process RSS memory, Tokio runtime tick latency, and active tasks using Rullst Radar (rullst::radar) and Prometheus (GET /metrics).

🛠️ Step 1: Mount Prometheus Exporter

In src/main.rs:

use axum::Router;
use rullst_core::radar::radar_metrics_router;
use rullst::Server;

#[tokio::main]
async fn main() -> Result<(), rullst_core::server::ServerError> {
    let app = Router::new()
        .merge(radar_metrics_router()); // Exposes GET /metrics

    Server::new(app.into()).run(3000).await
}

📊 Step 2: Prometheus Metrics Scrape Output

Query GET /metrics:

# HELP rullst_memory_rss_bytes Process RSS memory consumption
# TYPE rullst_memory_rss_bytes gauge
rullst_memory_rss_bytes 24510464

# HELP rullst_tokio_latency_microseconds Tokio runtime tick latency in microseconds
# TYPE rullst_tokio_latency_microseconds gauge
rullst_tokio_latency_microseconds 42

Visual dashboard available in Studio: http://localhost:5555/studio/radar.

/metrics is not authenticated by radar_metrics_router(). Restrict it with a private network, service-mesh policy, or reviewed authentication middleware; process and runtime measurements can disclose operational information.

💡 Key Takeaways

• The response is a point-in-time local snapshot and allocates its text body.
• Linux and Windows expose supported process RSS/CPU probes. Tokio task data is available only inside a Tokio runtime; unsupported probes are omitted.
• The scheduler-yield observation is not a universal request-latency target.

Tutorial 24: Interactive Scalar API Documentation 📖

Scaffold a Scalar OpenAPI documentation router served at /docs.

🛠️ Step 1: Scaffold Scalar Docs

cargo rullst make:scalar

This generates src/controllers/docs_controller.rs. The application must merge the returned router; the command does not edit route registration automatically.

💻 Step 2: Mount in Application

use rullst::{Router, Server};
use rullst::scalar::scalar_docs_router;

#[tokio::main]
async fn main() -> Result<(), rullst::ServerError> {
    let app = Router::new().merge_axum(scalar_docs_router("/openapi.json"));

    Server::new(app).run(3000).await
}

Open http://localhost:3000/docs in your browser to test endpoints interactively!

💡 Key Takeaways

• The current page loads a version-pinned Scalar asset from jsDelivr. A failed CDN load shows only a link to the OpenAPI JSON; it is not an offline interactive UI.
• The status-only fallback prints the configured OpenAPI location as text; it does not create an executable link from the configured value.
• A strict CSP may block the remote and inline assets. Vendor the asset and integrate the page with the application’s nonce/hash policy before using it outside local development.
• The router reads openapi.json; if it is missing or malformed, the endpoint fails with 503 Service Unavailable instead of fabricating an empty specification. Validate the release artifact in CI.

Tutorial 25: Kubernetes Manifests & Health Probes ☸️

cargo-rullst can generate a Kubernetes starter set. The files contain project name/port defaults and must be reviewed for the target cluster, registry, secrets, storage, network policy, ingress, workload identity, and security policy before deployment.

Step 1: Generate the starter manifests

cargo rullst make:k8s

The command writes deployment.yaml, service.yaml, configmap.yaml, hpa.yaml, ingress.yaml, and all-in-one.yaml under k8s/. It may overwrite files with those names, so run it in a clean worktree and review the diff.

Replace the placeholder image: <project>:latest with an immutable registry reference (preferably a digest). The generated ConfigMap contains non-secret settings only; use a Kubernetes Secret/external secret manager for credentials.

Step 2: Mount lifecycle-aware health routes

use rullst::{ApplicationLifecycle, Router, Server};
use rullst::health::{health_router_with_lifecycle, init_health_boot_time};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_health_boot_time();
    let lifecycle =
        ApplicationLifecycle::with_required_components(["database", "queue"])?;

    // Set these only after the application's own bounded checks succeed.
    lifecycle.set_component_ready("database", true)?;
    lifecycle.set_component_ready("queue", true)?;

    let app = Router::new()
        .merge_axum(health_router_with_lifecycle(lifecycle.clone()));
    Server::new(app)
        .with_lifecycle(lifecycle)
        .run(3000)
        .await?;
    Ok(())
}

/health remains process-only so an external database outage does not create a restart loop. /ready returns 503 during startup, while any registered component is unavailable, during drain, and after stop. The JSON carries only aggregate counts; it never emits the component labels or their error messages.

The component registry is immutable, accepts at most 32 validated labels, and does not execute probes by itself. The application must perform bounded, timeout-protected checks and update each bit. Server marks startup complete after binding, closes new application admission before graceful shutdown, and waits through Axum for accepted requests. run_with_shutdown accepts a supervisor future when OS signals are not the desired trigger.

This is one process contract. Kubernetes removes an unready Pod from service according to its own timing; Rullst does not coordinate replica consensus, load-balancer propagation, dependency failover, preStop, or the Pod’s terminationGracePeriodSeconds. Measure those together in staging. The legacy health_router() remains the simpler process-only pair when dependency-aware admission is not requested.

Step 3: validate before applying

kubectl apply --dry-run=client -f k8s/all-in-one.yaml
kubectl diff -f k8s/all-in-one.yaml
kubectl apply -f k8s/all-in-one.yaml

The generated HPA uses autoscaling/v2 and requires a working resource metrics pipeline. Validate against the actual cluster version and admission policies.

Release checklist

• add pod/container security contexts compatible with the reviewed image user;
• define CPU/memory requests and limits from measurements;
• add PodDisruptionBudget, topology spread/anti-affinity, NetworkPolicy, and service account/workload identity as required;
• terminate TLS with a configured issuer and real hostname;
• provision durable storage only where application state truly needs it; and
• verify probes, graceful termination, migrations, rollback, and autoscaling in a staging cluster.

Tutorial 26: Guided Cloud Deployment & Foundry SSH Pipeline 🚀

Rullst provides two deployment scaffolds that require provider credentials, application-specific review, and rollback planning:

1. cargo rullst deploy: guided PaaS manifest/CLI helper (Fly.io, Railway, Render, or local Docker Compose).
2. cargo rullst foundry:deploy: reviewed SSH pipeline for a compatible systemd-based Linux VPS.

⚡ Comparison: deploy vs foundry:deploy

🛠️ Strategy 1: PaaS Cloud Deploy Wizard (cargo rullst deploy)

Launch the interactive PaaS deployment wizard:

cargo rullst deploy

Or target a specific platform directly:

# Deploy to Fly.io (Global Edge Containers)
cargo rullst deploy --platform=fly

# Deploy to Railway (Zero-config PaaS)
cargo rullst deploy --platform=railway

# Deploy to Render (Managed Cloud Services)
cargo rullst deploy --platform=render

# Scaffold Local VPS Production Stack (Docker Compose + Caddy SSL)
cargo rullst deploy --platform=vps

🏭 Strategy 2: Rullst Foundry SSH Pipeline (cargo rullst foundry:*)

Rullst Foundry is a bounded deployment helper for compatible systemd-based Linux servers. Its current provisioning commands require root or passwordless non-interactive sudo; it is not portable to every SSH host and does not support IPv6 SCP targets.

Step 1: Initialize Foundry.toml

cargo rullst foundry:init

This generates Foundry.toml at your project root and automatically adds it to .gitignore to protect sensitive server credentials:

# Foundry.toml — Rullst Deployment Manifest
[app]
name = "my_rullst_app"
domain = "api.mycompany.com"

[server]
host = "203.0.113.50"
user = "root"
ssh_port = 22
ssh_key = "~/.ssh/id_ed25519"

[env]
RULLST_ENV = "production"
PORT = "3000"
DATABASE_URL = "sqlite:///opt/rullst/my_rullst_app/data/db.sqlite"
APP_KEY = "REPLACE_WITH_A_STRONG_RANDOM_KEY"

Step 2: Run the reviewed deployment command

cargo rullst foundry:deploy

What the current foundry:deploy does

1. Builds the selected profile and optional target locally.
2. Connects over SSH, checks the preinstalled curl, systemctl, and caddy executables, creates /opt/rullst/<app>/{bin,config,data}, and fails if that step fails. Foundry does not install operating-system packages and never pipes an unpinned network script into a shell.
3. Uploads the application binary with scp to a staging path. It does not currently upload static directories or perform a separate remote checksum comparison.
4. Writes staged environment, Caddy, systemd and binary files, validates the candidate Caddy configuration, renames each staged file, then restarts the services. A validation/reload/restart failure aborts the command. The prior binary, environment, systemd unit, and global Caddyfile are retained as .previous, but rollback is manual and the application restart is not zero-downtime. This version manages one global /etc/caddy/Caddyfile; review that replacement before using the server for multiple independently managed sites.
5. Requires GET /health to succeed within ten bounded attempts before printing that the remote process answered locally. It does not prove public DNS, TLS, firewall, proxy, or external reachability.

SSH uses StrictHostKeyChecking=accept-new: verify the host fingerprint through an independent channel before the first connection. The command does not compare a separate remote checksum, run database migrations, back up/restore data, coordinate multiple instances, or automatically roll back a failed release.

💡 Summary & Best Practices

• Use cargo rullst deploy when hosting on serverless container platforms (Fly.io, Railway, Render).
• Use cargo rullst foundry:deploy only after reviewing the generated SSH, systemd, Caddy, secret, migration, backup, and rollback plan for the target VPS.

Tutorial 27: Typed Dependency Injection (rullst::di) 💉

Rullst DI uses Rust types as keys and avoids runtime reflection metadata. It is not literally zero-cost: registration uses a map, resolution performs a type-indexed lookup/downcast, and each injection clones an Arc.

Step 1: Register services without embedding secrets in source

#![allow(unused)]
fn main() {
use std::sync::Arc;
use rullst::di::Container;
use rullst::security_runtime::VaultSecret;

pub struct PaymentGateway {
    api_key: VaultSecret<String>,
}

impl PaymentGateway {
    pub fn is_configured(&self) -> bool {
        !self.api_key.expose_secret().is_empty()
    }
}

pub struct UserService {
    pub gateway: Arc<PaymentGateway>,
}

pub fn configure_di() -> Result<Arc<Container>, std::env::VarError> {
    let key = std::env::var("PAYMENT_API_KEY")?;
    let mut container = Container::new();
    let gateway = Arc::new(PaymentGateway {
        api_key: VaultSecret::new(key),
    });

    container.register_arc(Arc::clone(&gateway));
    container.register(UserService { gateway });
    Ok(Arc::new(container))
}
}

security_runtime requires the umbrella security feature. A secret manager should inject the real value in production; VaultSecret reduces accidental formatting and zeroizes its owned allocation on drop, but it is not key custody or secure memory.

Step 2: Attach the container and extract a service

use axum::{Extension, Json, routing::post};
use rullst::{Router, di::Inject};

pub async fn process_payment(
    Inject(user_service): Inject<UserService>,
) -> Json<&'static str> {
    // Use a bounded provider adapter; never log the key or full request payload.
    let _configured = user_service.gateway.is_configured();
    Json("Payment request accepted")
}

let container = configure_di()?;
let app = Router::new()
    .route("/payments", post(process_payment))
    .layer(Extension(container));

The continuation is application code because its error type and provider adapter belong to the project. If the requested type or container extension is missing, Inject<T> fails closed with a 500 rejection.

Key takeaways

• Services are registered as type-safe Arc<T> singletons.
• DI controls construction and lookup; it does not provide authorization, transaction boundaries, or secret management.
• Prefer ordinary constructors when a small service graph does not benefit from a container.

Tutorial 28: gRPC Microservices with Tonic 🌐

Generate a Tonic/Protobuf starting point using cargo rullst make:grpc. The command does not start a gRPC server, add every build dependency, or define production transport/authentication policy for the application.

🛠️ Step 1: Generate a gRPC Service

cargo rullst make:grpc UserService

This generates:

• proto/user_service.proto (Protobuf definition)
• src/grpc/user_service.rs (Tonic service implementation)

Names ending in Service remain a single service suffix: UserService produces the user_service_server::UserService trait rather than UserServiceService.

💻 Step 2: Implement the gRPC Handler

In src/grpc/user_service.rs, after the generated application’s build.rs has compiled proto/user_service.proto and made the Tonic dependencies available:

use tonic::{Request, Response, Status};

pub mod proto {
    tonic::include_proto!("user_service");
}

use proto::user_service_server::UserService;
use proto::{HelloRequest, HelloResponse};

#[derive(Debug, Default)]
pub struct UserServiceImpl;

#[tonic::async_trait]
impl UserService for UserServiceImpl {
    async fn say_hello(
        &self,
        request: Request<HelloRequest>,
    ) -> Result<Response<HelloResponse>, Status> {
        let reply = HelloResponse {
            message: format!("Hello {} from Rullst gRPC!", request.into_inner().name),
        };
        Ok(Response::new(reply))
    }
}

💡 Key Takeaways

• The generator creates a starting point for tonic and prost; inspect the generated service and add/review the required build.rs, dependencies, reflection/health endpoints, and server bootstrap before deployment.
• Apply TLS or mTLS, authentication, per-method authorization, deadlines, message-size/concurrency limits, and proxy policy explicitly.
• Network, serialization, handler, and proxy latency must be measured in the target environment. Rullst does not claim a universal latency bound.

Tutorial 29: IoT data and frame helpers (rullst-iot)

rullst-iot provides telemetry/state models and protocol frame builders that compile without std. Some APIs use alloc, so a bare-metal application must supply an allocator.

The crate does not currently read hardware registers or provide MQTT, OPC-UA, Sparkplug B, HSM, or post-quantum implementations.

Build a telemetry model and Modbus request

#![allow(unused)]
fn main() {
use rullst_iot::{AnomalyDetector, ModbusFrame, SensorTelemetry};

let telemetry = SensorTelemetry::new(
    "sensor-01",
    "temperature",
    38.5,
    1_700_000_000,
);
let detector = AnomalyDetector::new(25.0, 5.0);
let state = detector.evaluate(telemetry.value);

// This builds bytes for a request. Platform code must send them over a real
// serial/TCP transport and handle timeouts, retries, and the response.
let request = ModbusFrame::read_holding_registers(1, 0, 10);
assert_eq!(request.len(), 8);
let _ = state;
}

Signed firmware artifacts

Use OtaManifest and OtaManager::new_with_trusted_key to verify a firmware artifact before selecting an inactive partition. See the crate guide for the trust, persistence, and bootloader requirements that remain the integrator’s responsibility.

Experimental fixtures

The opt-in experimental-simulators feature contains explicitly named Simulated* fixtures. They are deterministic test data generators, not hardware or protocol implementations.

Tutorial 30: Axum Escape-Hatch Snapshot (cargo rullst eject) 🔓

eject generates a minimal Axum/Tokio entry point that can begin a manual migration away from Rullst’s server wrapper. It does not statically expand macros, copy the application’s route graph, convert middleware, or remove Rullst dependencies automatically.

Step 1: Generate a separate starting point

cargo rullst eject

The default output is src/ejected_main.rs; the existing src/main.rs remains unchanged. The generated server contains only a demonstration root route:

use axum::{routing::get, Router};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = Router::new()
        .route("/", get(|| async { "Ejected Axum server" }));
    let listener = TcpListener::bind("127.0.0.1:3000").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

Move application routes one bounded group at a time and retain equivalent security headers, CSRF/CORS/WAF order, limits, telemetry, graceful shutdown, health behavior, state, and authorization tests.

Step 2: Treat --force as a deliberate replacement

cargo rullst eject --force

The hardened command first preserves the original entry point as src/main.rs.rullst-backup and refuses to overwrite an existing backup. Keep a normal version-control commit as the authoritative recovery path. Custom output paths are restricted to relative Rust files under src/ and existing targets are not overwritten implicitly.

Key takeaways

• Ejection is a migration aid, not a semantics-preserving compiler transform.
• The application remains responsible for dependency cleanup and replacements for ORM, auth, queues, Studio, Nexus, Capital, AI, and other selected crates.
• Run cargo fmt, strict Clippy, the complete test suite, and application security/operational checks after every migrated route group.

Tutorial 31: SaaS deployment preparation for AWS or GCP

This guide prepares a generated SaaS application for a cloud deployment. It is not an end-to-end production certification: identity, network policy, database operation, secrets, billing and recovery remain deployment responsibilities.

1. Materialize and verify the SaaS starter

While v12 is unreleased, use a reviewed main checkout pinned by Cargo.lock. After a prerelease ships, install the matching versioned CLI and generate deterministically:

cargo rullst new my_cloud_saas --default --blueprint saas --docker
cd my_cloud_saas
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Review every generated route, access policy, migration and environment placeholder before supplying live credentials.

2. Supply secrets outside source control

Use AWS Secrets Manager, Google Secret Manager or an equivalent deployment boundary for values such as DATABASE_URL, provider keys, webhook secrets and the Rullst field-encryption key. Do not bake .env into an image.

Set RULLST_ENV=production and make startup fail when a required production adapter or credential is missing. Empty and mock_* provider credentials are for deterministic offline development, not live operation.

3. Build and scan the exact image

docker build --pull --tag my-cloud-saas:<git-sha> .
docker inspect my-cloud-saas:<git-sha>

Pin the deployed image by digest. Run the application’s tests and a container scanner against the exact candidate. The CLI’s deploy command scaffolds or invokes Fly.io, Railway, Render and VPS paths; AWS App Runner/ECS and Google Cloud Run configuration remains explicit cloud work.

4. Configure the cloud boundary

For AWS or GCP, define and review:

• private database connectivity, TLS and least-privilege credentials;
• trusted proxy handling and the application’s external origin policy;
• ingress authentication, rate limits, body limits and request timeouts;
• readiness/liveness behavior and a bounded shutdown grace period;
• immutable image rollout and a tested rollback procedure;
• logs, metrics and alerts that avoid secrets and unnecessary PII.

Managed services have provider-specific scaling floors, quotas, cold starts and costs. Verify current provider documentation and load-test your selected region and topology rather than assuming scale-to-zero or a request rate.

5. Exercise stateful recovery

Before production traffic, rehearse migrations, backup, restore, webhook replay, field-encryption key rotation, a failed rollout and database unavailability. Health endpoints only report the checks implemented by the application; they do not create zero-downtime deployment by themselves.

Tutorial 32: Bounded security telemetry in Studio

Rullst’s honeypot, RASP and Studio security page provide local defense-in-depth signals. They are not an autonomous SOC, a universal blocker, an AI incident responder or a durable SIEM integration.

1. Compose local request controls

#![allow(unused)]
fn main() {
use axum::Router;
use rullst_security::{CspSecurityLayer, HoneypotLayer, HoneypotState, RaspSecurityLayer};
use std::net::SocketAddr;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
let app = Router::new()
    // Add application routes first.
    .layer(RaspSecurityLayer)
    .layer(CspSecurityLayer)
    .layer(HoneypotLayer::new(HoneypotState::default()));

let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
axum::serve(
    listener,
    app.into_make_service_with_connect_info::<SocketAddr>(),
)
.await?;
Ok(())
}
}

ConnectInfo supplies the accepted socket peer used by the honeypot. Deployments behind a proxy must establish and test a trusted client-identity boundary; the middleware deliberately does not trust arbitrary forwarding headers.

2. Understand each signal

• Honeypots match configured exact synthetic paths and keep bounded, expiring process-local bans.
• RASP performs bounded heuristic inspection for selected patterns and can have false positives and negatives.
• CSP and headers depend on the final rendered page, proxy, browser and TLS deployment.
• SecurityStore is local telemetry. An event is not HMAC-verified or durably delivered merely because it appears in Studio.

No built-in path asks an LLM to ban a peer or automatically mounts a blocking policy. The opt-in ThreatSentinel can classify three bounded, caller-supplied aggregate patterns and issue an HMAC-authenticated, subject-bound, expiring, one-shot process-local proof-of-work challenge. The application must supply trustworthy observations and subject identity, translate the outcome into an HTTP protocol, and decide where that gate belongs. It is not AI attribution, a distributed replay store, or an autonomous ban. Sensitive automated actions still require authenticated policy, limits, durable audit and human approval where appropriate.

3. Inspect the local Studio view

Mount Studio only through its documented access capability and open /studio/security. The page renders current local telemetry and keeps unavailable sources visibly unavailable. A multi-instance deployment needs a shared, authenticated event pipeline with retry, acknowledgement, retention and dead-letter handling before it can be described as an operational SIEM.

See the Threat Radar and SOC guide and the v12 security evidence ledger for exact boundaries.

Tutorial 33: Auth-bound multi-tenancy

Rullst Core can select a tenant from a request hint only after application authentication has inserted a trusted TenantMembership. A hostname, header, query parameter or request body is never sufficient proof of membership.

1. Configure the selection layer

#![allow(unused)]
fn main() {
use axum::{Extension, Router, routing::get};
use rullst_core::{
    multitenant::{TenantConfig, TenantLayer, TenantStrategy},
    security::TenantContext,
};

async fn tenant_dashboard(Extension(tenant): Extension<TenantContext>) -> String {
    format!("Selected workspace: {}", tenant.tenant_id)
}

fn tenant_routes() -> Router {
    let selection = TenantLayer::new(TenantConfig::new(TenantStrategy::Subdomain));
    Router::new()
        .route("/dashboard", get(tenant_dashboard))
        .layer(selection)
}
}

An outer, application-owned authentication layer must first validate the session/token and insert TenantMembership::try_new(...) from trusted identity claims. Without that extension, TenantLayer returns 403 Forbidden. If the requested subdomain is not in the authenticated membership set, it also returns 403. In Axum, remember that subsequently added layers run first; test the final middleware order in-process.

TenantStrategy::Header and TenantStrategy::Parameter are also available, but they remain untrusted selection hints. Query parameters additionally leak more easily through history, referrers and access logs. The built-in subdomain parser selects the first label only for hostnames with at least three labels; custom-domain ownership and trusted-proxy normalization remain application and deployment work.

2. Bind every database query

Tenant selection does not rewrite arbitrary SQL or automatically add a tenant predicate to every ORM query. Bind the authenticated tenant explicitly:

#![allow(unused)]
fn main() {
use rullst_core::security::TenantContext;
use sqlx::{FromRow, PgPool};

#[derive(FromRow)]
struct Invoice {
    id: i64,
    tenant_id: String,
    total_minor: i64,
}

async fn list_tenant_invoices(
    pool: &PgPool,
    tenant: &TenantContext,
) -> Result<Vec<Invoice>, sqlx::Error> {
    sqlx::query_as::<_, Invoice>(
        "SELECT id, tenant_id, total_minor FROM invoices WHERE tenant_id = $1",
    )
    .bind(&tenant.tenant_id)
    .fetch_all(pool)
    .await
}
}

Use database constraints and, where appropriate, database-native row-level security as additional defense. Negative tests must prove that one tenant cannot read, update or delete another tenant’s records through every relevant route, repository, background job and administrative surface.

3. Operational boundaries

• TenantContext is server-selected state, not a claim accepted from JSON.
• current_tenant_id() is task-local convenience; passing an explicit TenantContext to domain/storage APIs is easier to audit.
• TenantCache, TenantStorage, TenantRealtime and TenantPresence provide validated namespaces, but applications still own business authorization and remote provider policy.
• Cross-process membership updates, custom-domain verification, database policy, audit retention and incident response are not automatic framework guarantees.

Tutorial 34: Live Analytics Dashboard (rullst::live & WebSockets) 📈

Build a per-connection analytics view with rullst::live. Feed it values from your own authoritative metrics source; the example below uses explicit state only to demonstrate the component lifecycle.

🛠️ Step 1: Create Analytics LiveComponent

This fragment expects the crate::live::analytics_dashboard module created in Step 1 to be registered by the generated application:

#![allow(unused)]
fn main() {
use async_trait::async_trait;
use rullst::live::LiveComponent;
use serde_json::Value;

#[derive(Default)]
pub struct AnalyticsDashboard {
    pub revenue_mrr: f64,
    pub active_users: usize,
}

#[async_trait]
impl LiveComponent for AnalyticsDashboard {
    async fn mount(&mut self) {
        // Replace these initial values with an application-owned metrics query.
        self.revenue_mrr = 0.0;
        self.active_users = 0;
    }

    async fn handle_event(&mut self, payload: Value) {
        if let Some(event) = payload.get("event").and_then(|v| v.as_str()) {
            if event == "refresh" {
                self.revenue_mrr += 100.00;
                self.active_users += 1;
            }
        }
    }

    fn render(&self) -> String {
        format!(
            r#"<div id="analytics-dashboard" class="p-8 bg-slate-900 text-white rounded-2xl shadow-2xl border border-slate-800">
    <h2 class="text-2xl font-bold mb-6">Live Analytics Stream</h2>
    <div class="grid grid-cols-2 gap-6 mb-6">
        <div class="p-4 bg-slate-800 rounded-xl">
            <p class="text-slate-400 text-sm">MRR</p>
            <p class="text-3xl font-mono text-emerald-400">${:.2}</p>
        </div>
        <div class="p-4 bg-slate-800 rounded-xl">
            <p class="text-slate-400 text-sm">Active Users</p>
            <p class="text-3xl font-mono text-cyan-400">{}</p>
        </div>
    </div>
    <button ws-send name="event" value="refresh" class="px-6 py-3 bg-indigo-600 hover:bg-indigo-500 font-semibold rounded-xl">
        ⚡ Refresh Live Stream
    </button>
</div>"#,
            self.revenue_mrr, self.active_users
        )
    }
}
}

💻 Step 2: Render in View Page

use rullst::live::Live;
use crate::live::analytics_dashboard::AnalyticsDashboard;

pub async fn analytics_page() -> String {
    Live::mount::<AnalyticsDashboard>("/ws/analytics").await
}

Register /ws/analytics with axum::routing::get(rullst::live::live_ws_handler::<AnalyticsDashboard>) and load a pinned HTMX WebSocket extension in the page.

💡 Key Takeaways

• Rullst owns the server-side component lifecycle; a browser transport is still required.
• The current implementation re-renders an HTML fragment after each valid JSON event. It does not provide distributed state, replay, authorization or a metrics source automatically.

Tutorial 35: Performance measurement and resilient operation

Performance is a property of a concrete application, build, host and workload. Rullst includes Criterion microbenchmarks and production helpers, but does not promise a universal latency, throughput or availability number.

1. Build an application-specific release binary

[profile.release]
opt-level = 3
lto = "thin"
codegen-units = 1
strip = "debuginfo"

Alternative linkers such as mold or lld can improve developer link time on supported hosts. target-cpu=native can improve a host-specific binary but makes it less portable; do not put it in a generally distributed artifact without an explicit CPU baseline.

2. Configure and measure the database pool

#![allow(unused)]
fn main() {
use rullst_orm::Orm;

async fn configure() -> Result<(), rullst_orm::Error> {
Orm::init_with_options(
    "postgres://app:password@127.0.0.1/app",
    20, // maximum connections
    10, // acquire timeout in seconds
)
.await?;
Ok(())
}
}

Choose limits from database capacity and measured concurrency. More connections can increase contention and resource use instead of increasing throughput.

3. Run reproducible benchmarks

cargo bench --workspace

Record at least:

• exact commit, Rust version, features and release profile;
• CPU, memory, operating system and power/virtualization settings;
• database/provider version and topology;
• warm-up, sample count, concurrency and payload distribution;
• median and tail latency, throughput, errors and resource use.

Criterion microbenchmarks detect regressions in selected functions. They do not model a production network, database, proxy or user journey. The separate cross-framework repository currently exercises historical Rullst 4.x and is not v12 evidence until refreshed.

The public benchmark hub links the eight published groups: facade/HTTP, Core primitives, ORM, Auth, Connect, Security, AI and Capital. Nine Criterion binaries back those groups because ORM has both local and cross-ORM inputs. A crate without a microbenchmark is not automatically less mature: protocol vectors, generated-project compilation, restart/failure contracts, no_std target builds or whole-request tests can fit its dominant risk better. Add a new benchmark only with a stable operation, input, unit and interpretation.

The repository now also contains a v12 cross-ORM SQLite harness:

cargo bench -p rullst-orm --features strict-sqlite \
  --bench orm_comparison

It pins Diesel and SeaORM in the lockfile and gives all three ORMs one typed SQLite connection, separate database files, the same schema/unique index, 100 equivalent rows and identical WAL/synchronous/busy-timeout policy. Criterion measures primary-key lookup, indexed filtered lookup, count, ordered list-ten and insert/delete. This makes the input inspectable; it does not make the architectures identical. Diesel’s synchronous call path and the async Rullst/SeaORM executor paths remain part of what is measured.

The first local smoke run contradicted the old “negligible overhead versus Diesel” wording: Diesel led these five SQLite shapes. Rullst was competitive with SeaORM on reads but did not lead every operation. Keep the per-commit CI history as regression/comparison evidence and never generalize it to networked PostgreSQL/MySQL, concurrency, memory use or complete applications.

4. Test failure behavior separately

Availability requires deployment exercises: health/readiness semantics, timeouts, overload, cancellation, database failover, backup/restore, migration rollback and secret rotation. Miri, sanitizers, fuzzing and Kani are target-specific correctness tools; none measures availability or proves the absence of every memory error.

36. Assisted framework upgrades

Rullst v12 introduces a bounded upgrade transaction for existing applications. The goal is to make the safe, repeatable part a single command while refusing to guess about application data or security policy.

v12 is currently unreleased and NO-GO for production. The examples use 12.0.0-rc.1 as a placeholder for the planned first RC. Install or request that version only after it exists on crates.io.

What the command can guarantee

cargo rullst upgrade can inventory the Cargo workspace, update the Rullst release train, apply compiler suggestions, require cargo check, and restore the files it controls after a failure. It cannot prove that a database upgrade, authorization rule, provider integration or deployment still behaves correctly.

The automatic transaction owns only:

• versioned Rullst dependencies in exact Cargo workspace manifests;
• the root Cargo.lock produced by Cargo resolution;
• Rust edits proposed by cargo fix;
• a cargo check --workspace --all-targets gate using the application’s selected features.

It never runs migrations, changes secrets, invents tenant/ownership policy, opens Nexus or Studio, contacts application providers, or marks the result production-ready.

1. Prepare the application

Create a branch, make the worktree reviewable, record the old test result, and back up every database. Prove the database backup can be restored before changing the framework.

Install the exact CLI from the same release train as the target framework:

cargo install cargo-rullst --version 12.0.0-rc.1 --locked --force

The framework command does not update its own executable. This matters for v5: the already-published v5 CLI cannot gain the new v12 migration engine retroactively. Install the v12 CLI first, then run the command inside the application.

2. Inspect without writing

cargo rullst upgrade --dry-run

The plan shows every dependency edit and source finding. BLOCKER means a known old API requires attention; REVIEW means the CLI found a boundary that must be revalidated. Neither label means that unreported code is automatically safe.

For automation, request JSON:

cargo rullst upgrade --dry-run --json > upgrade-plan.json

The root object uses schema_version: "rullst.upgrade-plan.v1" and identifies the rule catalog, exact target, manifest changes, detected source majors, findings, automatic scope and mandatory manual gates. Consumers must reject an unknown schema version rather than silently interpreting it as v1.

Use an explicit target only when intentionally evaluating another release in the installed CLI’s major train:

cargo rullst upgrade --to 12.0.0-rc.2 --dry-run

The same-major restriction prevents a v12 rules engine from pretending it understands an eventual v13 migration.

3. Apply the transaction

After resolving or accepting every finding:

cargo rullst upgrade

Before the first write, the CLI snapshots Cargo workspace manifests, the root lockfile and Rust sources under:

target/rullst-upgrades/<UTC-run-id>/
├── files/
├── index.tsv
├── report.md
└── report.json

It then edits the TOML while preserving comments and relative order, runs compiler-provided fixes and executes the Cargo check gate. A failing gate restores the controlled files automatically and returns a non-zero status.

To deliberately keep a partial result for diagnosis:

cargo rullst upgrade --keep-on-failure

To restore a persisted snapshot after that mode or after an interrupted run:

cargo rullst upgrade \
  --restore target/rullst-upgrades/<UTC-run-id>

Restore accepts only a path-validated snapshot inside the current project’s target/rullst-upgrades directory. cargo clean deletes target, so retain a normal version-control commit or copy a needed diagnostic report before cleaning.

4. Finish a v5 to v12 migration

The v5 README used attribute-style routing and a server builder with no router or port. The scanner reports these markers instead of applying a global text replacement. Replace the old shape:

#[routes]
fn home() -> Response {
    // ...
}

Server::new()
    .route("/", get(home))
    .run()
    .await;

with an explicit v12 router and typed error propagation:

use rullst::{Server, response::Html, routes};

async fn home() -> Html<&'static str> {
    Html("Hello from v12")
}

#[rullst::runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![get("/" => home)];
    Server::new(app).run(3000).await?;
    Ok(())
}

Then follow the complete v5 → v12 guide, including feature selection, disposable database migration/rollback, explicit Nexus and Studio boundaries, provider validation and authorization negatives.

5. Run the application-owned gates

At minimum:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --release

Also test the actual production feature set, restore/migrate/rollback against a production-shaped database copy, cross-user and cross-tenant denials, proxy/TLS identity, CSRF/CORS, Nexus/Studio exposure and every configured live provider.

Future upgrades such as v12 to v13

The engine and migration knowledge are intentionally separated. Each new major must ship a new CLI from that major, extend the versioned rule catalog, document the supported source baselines, and add process-level fixtures for dry-run, machine-readable output, successful application and rollback. A v13 CLI can therefore reuse the transaction while owning v13-specific rules; a v12 CLI is not allowed to guess them.

Is this unique?

No. Assisted upgrades are an established framework practice: Rails documents interactive bin/rails app:update, Angular provides ng update, and Dart offers preview/apply analysis fixes through dart fix. Microsoft’s .NET Upgrade Assistant also analyzed and changed projects, although Microsoft now marks it deprecated in favor of its modernization tooling.

Rullst’s useful distinction is the bounded composition: Cargo-workspace-aware TOML edits, a version-selected framework rule catalog, human and JSON plans, controlled snapshots, default rollback, explicit recovery and Cargo gates in one CLI flow. This is a testable design choice, not evidence that Rullst is the first or universally the best updater.

Official references:

• Upgrading Ruby on Rails
• Angular ng update
• Dart dart fix
• .NET Upgrade Assistant overview

Polyglot Persistence

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Rullst v12 keeps explicit relational and specialized persistence contracts. SQLx Active Record supports SQLite, PostgreSQL, MySQL, and MariaDB. The bounded blank/API profile can instead use Turso/libSQL as its typed primary ORM. MongoDB is for documents, DuckDB is for embedded OLAP/analytics, SurrealDB exposes documents plus bounded read-only graph queries, Qdrant exposes dense vector search, and Redis exposes selected native structures. No optional adapter silently changes the application’s primary database.

Choose the smallest feature

Using the umbrella crate:

[dependencies]
rullst = { version = "12.0.0-rc.1", features = ["orm-mongodb"] }

Available umbrella features are orm-turso, orm-mongodb, orm-duckdb, orm-surrealdb, orm-qdrant, orm-redis, and the convenience orm-polyglot. Direct rullst-orm users select turso, mongodb, duckdb, surrealdb, qdrant, redis, or polyglot.

Features are additive. Prefer one adapter unless the application genuinely uses several, and inspect the final dependency graph with:

cargo tree -e features

The project wizard first asks for a primary backend. SQLite, PostgreSQL, MySQL, and MariaDB use SQLx; Turso is available as a typed primary for the blank/API starter. The wizard then offers explicit additive capability adapters. For a hybrid SQLx application, use one or more explicit flags:

cargo rullst new edge_app --default --database mariadb --turso --mongodb \
  --qdrant --skip-initial-migration

MariaDB shares the SQLx MySQL protocol implementation but has its own live container contract. --turso is additive; --database turso is the explicit primary selection and currently rejects SQLx-specific non-blank blueprints.

Turso / libSQL as the primary ORM

cargo rullst new edge_app --default --api --database turso
cd edge_app
cargo rullst make:model Event --migration
cargo rullst db:migrate

The generated manifest enables orm-turso without a direct SQLx dependency, and the environment contains TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, and TURSO_OFFLINE_PATH rather than a fictitious DATABASE_URL. Models use the same public derive with an explicit backend:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "events", backend = "turso")]
struct Event {
    id: i64,
    label: String,
    active: bool,
}
}

Initialize once before using the generated inherent methods:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "events", backend = "turso")]
struct Event {
    id: i64,
    label: String,
    active: bool,
}
async fn use_turso_model() -> Result<(), Box<dyn std::error::Error>> {
rullst_orm::polyglot::TursoOrm::init_from_env().await?;

let mut event = Event {
    id: 0,
    label: "started".into(),
    active: true,
};
event.save().await?;
let current = Event::find(event.id).await?;
let _ = current;
Ok(())
}
}

The typed contract includes CRUD, equality filters, ordering, bounded pagination/counts, app-assigned or generated primary keys, checksummed migrations, status, and rollback. Generated make:model and make:migration commands retain the Turso backend. It does not yet provide SQLx ORM relations, hooks, automatic timestamps, seed generation, schema auto-diff, or transparent embedded-replica synchronization. Those limits are why only the blank/API starter is currently advertised as Turso-primary. The derive rejects unsupported SQLx-specific model behaviors at compile time instead of silently ignoring their attributes.

Turso / libSQL explicit edge SQL

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    TursoConfig, TursoMigration, TursoQueryLimit, TursoStatement, TursoStore,
    TursoValue,
};

async fn use_edge_sql() -> Result<(), Box<dyn std::error::Error>> {
let config = TursoConfig::new(
    std::env::var("TURSO_DATABASE_URL").unwrap_or_default(),
    std::env::var("TURSO_AUTH_TOKEN").unwrap_or_default(),
);
let edge = TursoStore::connect(config).await?;
let create = TursoStatement::new(
    "CREATE TABLE events (id INTEGER PRIMARY KEY, label TEXT NOT NULL)",
    vec![],
)?;
edge.migrate(vec![TursoMigration::new("m20260829_events", vec![create])?])
    .await?;

edge.execute(TursoStatement::new(
    "INSERT INTO events VALUES (?1, ?2)",
    vec![TursoValue::Integer(1), TursoValue::Text("started".into())],
)?).await?;
let rows = edge.query(
    TursoStatement::new(
        "SELECT id, label FROM events WHERE id = ?1",
        vec![TursoValue::Integer(1)],
    )?,
    TursoQueryLimit::new(100)?,
).await?;
let _ = rows;
Ok(())
}
}

The live path speaks the official Hrana HTTP v3 protocol directly through the workspace’s Rustls-backed HTTP client; it does not embed the native SQLite engine or the legacy remote SDK dependency chain. URLs must use libsql:// or HTTPS; cleartext HTTP requires an explicit loopback-development opt-in. Requests reject redirects and have a 30-second deadline. Tokens and endpoint details are redacted from Debug; remote responses are capped at 16 MiB, result materialization at 1–10,000 rows, each statement at 1,024 positional parameters/8 MiB of parameter data, and each transaction at 1,024 statements/16 MiB of raw SQL plus parameters. SQL result cells can still be large, so applications must also constrain selected columns and data at the schema/query boundary.

An empty or mock_* endpoint selects a single-connection SQLite in-memory fallback. It executes real SQL and migrations deterministically but does not simulate remote replication, latency, failover, or Turso Cloud. The live CI contract runs the same API against the official sqld container and proves that a failed multi-statement batch rolls back its earlier writes.

The portable document contract

MongoDB, SurrealDB, and the deterministic offline store implement the same bounded document operations:

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentId, DocumentPage, DocumentRepository,
};

fn bounded_document_inputs() -> Result<(), Box<dyn std::error::Error>> {
let collection = CollectionName::new("audit_events")?;
let id = DocumentId::new("event-2026-0001")?;
let page = DocumentPage::new(0, 50)?;
let _ = (collection, id, page);
Ok(())
}
}

Collection names use a portable ASCII identifier grammar, IDs are bounded to letters, digits, _ and -, and every list requires a 1–500 row page. Models must serialize as objects and must not own the driver ID field (_id for MongoDB, id for SurrealDB); the portable DocumentId owns that concern.

Encrypted export and crash-resumable restore

MongoDB, SurrealDB and the deterministic store also implement DocumentInventory<T>, which retains each validated identifier. That enables one deliberately conservative recovery path without pretending the engines share transactions:

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentRecoveryBinding, DocumentRecoveryKey,
    DocumentRecoveryPolicy, export_document_snapshot,
    restore_document_snapshot,
};

async fn recovery<S, D, Event>(source: &S, destination: &D) -> Result<(), Box<dyn std::error::Error>>
where
    S: rullst_orm::polyglot::DocumentInventory<Event>,
    D: rullst_orm::polyglot::DocumentInventory<Event>,
    Event: serde::Serialize + serde::de::DeserializeOwned + Send + Sync,
{
let collection = CollectionName::new("audit_events")?;
let binding = DocumentRecoveryBinding::try_new(
    "my_application.production",
    collection,
)?;
let key = DocumentRecoveryKey::try_new(
    "recovery-2026-09",
    [42_u8; 32], // load 32 random bytes from a secret manager
)?;
let policy = DocumentRecoveryPolicy::try_new(100, 10_000, 16 * 1024 * 1024)?;

// Persist this opaque envelope in application-owned durable storage.
let snapshot = export_document_snapshot(source, &binding, &key, policy).await?;
let report = restore_document_snapshot(
    destination,
    &snapshot,
    &binding,
    &key,
    policy,
).await?;
assert_eq!(report.verified(), report.inserted() + report.replayed());
Ok(())
}
}

The key uses AES-256-GCM and a fresh nonce; its authenticated data binds the rotation ID, trusted application namespace and exact collection. Key material passes through a zeroizing temporary and key/snapshot Debug output is redacted. The policy permits pages of 1–500, 1–100,000 documents and a 1 KiB–64 MiB plaintext ceiling. Models in this portability path must be JSON objects without either id or _id.

Export scans twice and refuses to seal unequal observations. This detects ordinary concurrent changes, but it is not a database snapshot isolation primitive: pause writers or use a source-side transaction/export facility. Restore accepts only an empty destination or a matching subset left by an earlier attempt. It inserts without replacement, rejects different or extra rows before mutation and verifies an exact final inventory. A failed attempt can retain earlier successful inserts, so retry the same authenticated snapshot. Keep unrelated destination writers paused until verification. The destination database, namespace and collection/table must already be provisioned where the engine requires them; schema or permission failures stay visible and are never reclassified as an empty destination.

The live release matrix exercises MongoDB → SurrealDB → MongoDB. It proves the bounded adapter contract on that runner, not backup retention, key custody, replication, point-in-time recovery, topology failover or vendor operations.

MongoDB

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentId, DocumentRepository, MongoDbStore,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct AuditEvent {
    action: String,
}

async fn store_audit_event() -> Result<(), Box<dyn std::error::Error>> {
let store = MongoDbStore::<AuditEvent>::connect_or_mock(
    std::env::var("MONGODB_URL").unwrap_or_default(),
    "my_application",
).await?;

store.create(
    &CollectionName::new("audit_events")?,
    &DocumentId::new("event-1")?,
    &AuditEvent { action: "login".into() },
).await?;
Ok(())
}
}

An empty URL or one beginning with mock_/mock:// selects an in-process, deterministic BTreeMap store. A non-mock URL uses the official MongoDB Rust driver. The release contract includes an optional Testcontainers CRUD suite; availability, backups, indexes, topology and authorization remain deployment responsibilities.

SurrealDB documents and graph reads

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    GraphQuery, GraphRepository, SurrealAuth, SurrealConfig, SurrealDbStore,
};

async fn read_graph() -> Result<(), Box<dyn std::error::Error>> {
let config = SurrealConfig::new(
    std::env::var("SURREALDB_URL").unwrap_or_default(),
    "main",
    "application",
    SurrealAuth::bearer(
        std::env::var("SURREALDB_TOKEN").unwrap_or_default(),
    ),
);
let store = SurrealDbStore::<serde_json::Value>::connect_or_mock(config)?;
let query = GraphQuery::read_only(
    "MATCH (person:person)-[knows:knows]->(friend:person) RETURN friend",
    100,
)?;
let rows = store.query_graph(&query).await?;
let _ = rows;
Ok(())
}
}

The adapter uses SurrealDB’s documented HTTP /key, /sql, and /gql protocol instead of embedding its BSL-licensed SDK. It disables redirects, requires HTTPS outside loopback unless cleartext is explicitly enabled, redacts authentication in Debug, streams through a configurable 1 KiB–8 MiB memory ceiling, and sends namespace/database headers on every scoped request.

Graph queries must start with MATCH; semicolons, caller-provided LIMIT, and the INSERT, SET, REMOVE, and DELETE tokens are rejected. The adapter then appends its own 1–1,000 row limit. This is a conservative read boundary, not arbitrary SurrealQL execution or a graph mutation API. The /gql endpoint requires SurrealDB 3.2 or newer and explicit experimental enablement on the 3.2 release line; the live contract pins 3.2.4 and enables that capability.

DuckDB analytics

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    AnalyticsRepository, AnalyticsValue, DuckDbStore, QueryLimit,
};

async fn analyze_events() -> Result<(), Box<dyn std::error::Error>> {
let analytics = DuckDbStore::in_memory().await?;
analytics.execute(
    "CREATE TABLE events (sequence BIGINT, label VARCHAR)",
    vec![],
).await?;
analytics.execute(
    "INSERT INTO events VALUES (?, ?)",
    vec![
        AnalyticsValue::Signed(1),
        AnalyticsValue::Text("started".into()),
    ],
).await?;
let rows = analytics.query(
    "SELECT sequence, label FROM events WHERE sequence >= ?",
    vec![AnalyticsValue::Signed(1)],
    QueryLimit::new(500)?,
).await?;
let _ = rows;
Ok(())
}
}

DuckDB is bundled for a predictable optional build. Its connection is guarded and every native operation runs through Tokio’s blocking worker pool. Dynamic values are prepared parameters; SQL text remains trusted application structure. Results must declare a 1–10,000 row materialization limit. Scalar, decimal, temporal, interval, geometry and binary values are preserved; unsupported complex result types fail with a typed error instead of being guessed.

Specialized Qdrant and Redis stores

Qdrant has a separate dense-vector contract rather than a document or Active Record facade. See RAG Systems & Vector Search for its bounded collection, upsert, delete and cosine-query API. The project wizard and deterministic CLI expose it as the additive --qdrant choice.

Redis native structures are also explicit and namespaced:

#![allow(unused)]
fn main() {
use rullst_orm::{
    RedisDataConfig, RedisDataKey, RedisDataStore, RedisField, RedisMember,
    RedisScanLimit, RedisStructuresRepository, RedisValue,
};

async fn redis_example() -> Result<(), Box<dyn std::error::Error>> {
let config = RedisDataConfig::new(
    std::env::var("REDIS_URL").unwrap_or_default(),
    "my-application",
    std::env::var("REDIS_USERNAME").unwrap_or_default(),
    std::env::var("REDIS_PASSWORD").unwrap_or_default(),
);
let data = RedisDataStore::connect_or_mock(config).await?;
let account = RedisDataKey::new("account:42")?;
data.hash_set(
    &account,
    &RedisField::new("display_name")?,
    &RedisValue::new("Ada")?,
).await?;
data.set_add(&account, &RedisMember::new("reader")?).await?;
let roles = data
    .set_scan(&account, RedisScanLimit::new(100)?)
    .await?;
let _ = roles;
Ok(())
}
}

The adapter also supplies atomic signed hash increments, exact membership, Sorted Set add/top ranking and exact per-structure deletion. Empty or mock_* endpoint/ACL credentials choose the deterministic fallback. Live remote Redis requires rediss://; intentionally unauthenticated development uses the loopback-only constructor. Hash values are capped at 1 MiB, members at 4 KiB, and scans/ranges at 1–1,000 accepted rows. Redis may still allocate a protocol value before client-side validation, so untrusted writers require server ACLs, quotas and isolation. Lists, Streams, cluster/failover, eviction and durable Pub/Sub are not part of this datastore contract.

What this feature does not promise

• no cross-backend transaction, replication, migration, or consistency layer;
• no claim that document databases implement SQL joins or Active Record;
• no automatic choice of a datastore based on a model;
• no managed backups, production credentials, provider homologation, indexes, cluster failover, or performance guarantee;
• no universal “support for every database”.

Run the application’s exact feature set in addition to the full workspace gates. Remote production readiness still requires a disposable live environment, negative authorization tests, backup/restore rehearsal, and operational review.

38. Transactional Outbox & Durable Effects

Use a transactional outbox when a committed database change must eventually produce an external effect even if the application process stops between the two operations. Typical examples are a webhook, an e-mail request, a search projection or a message published to another service.

after_commit is the simpler choice for a best-effort, process-local effect. Outbox is the durable choice. It stores an event in the same relational transaction as the domain mutation, then lets an independent worker claim and deliver it later.

1. Register the schema as a migration

Applications using the built-in SQLx migration runner can register the versioned migration supplied by the ORM:

#![allow(unused)]
fn main() {
use rullst_orm::OutboxMigration;
use rullst_orm::schema::migration::Migration;

fn migrations() -> Vec<Box<dyn Migration>> {
    vec![Box::new(OutboxMigration)]
}
}

Outbox::install() applies the same idempotent DDL directly and is useful in tests or explicit local setup. It never runs automatically. A production team should review and track the migration through the same deployment process as its domain schema; do not create tables opportunistically while serving a request.

The built-in contract supports the SQLx relational backends: SQLite, PostgreSQL, MySQL and MariaDB. It does not span MongoDB, DuckDB, Turso or SurrealDB transactions.

2. Commit domain state and event together

Choose a stable stream boundary and a deterministic event key. A stream can represent an application or tenant, but it is only a namespace: the framework does not infer authorization from it.

#![allow(unused)]
fn main() {
use rullst_orm::{Error, Orm, Outbox};
use serde_json::json;

async fn create_invoice() -> Result<(), Error> {
Orm::transaction(|_| Box::pin(async move {
    let insert = sqlx::query(
        "INSERT INTO invoices (id, status) VALUES (?, ?)"
    )
    .bind(123_i64)
    .bind("issued");
    rullst_orm::execute_query!(insert, execute, pool)?;

    Outbox::enqueue(
        "tenant-42",
        "invoice:123:issued:v1",
        "invoice.issued",
        &json!({"invoice_id": 123}),
    ).await?;

    Ok::<(), Error>(())
})).await?;
Ok(())
}
}

If the transaction rolls back, neither row survives. Calling enqueue outside Orm::transaction fails instead of silently opening an unrelated transaction. When the application already owns a raw SQLx transaction, use enqueue_with_tx(&mut transaction, ...).

(stream, event_key) is unique. Repeating the same kind and serialized JSON payload returns the existing event ID with inserted == false. Reusing that key for different content is an error; it does not overwrite the original event.

3. Claim, deliver and acknowledge

Each worker supplies a stable identifier, lease duration and maximum number of claims:

#![allow(unused)]
fn main() {
use rullst_orm::{Error, Outbox};

async fn deliver() -> Result<(), Error> {
if let Some(event) = Outbox::claim_next(
    "tenant-42",
    "webhook-worker-1",
    30, // lease seconds
    8,  // maximum claims
).await? {
    let payload = event.payload()?;

    // Perform the external effect. Pass event.event_key to a provider that
    // supports idempotency, or deduplicate it in the receiving service.
    let delivered = payload.get("invoice_id").is_some();

    if delivered {
        let owned = Outbox::acknowledge(event.id, event.claim_key).await?;
        if !owned {
            // The lease expired or another worker reclaimed the event.
            // Do not assume ownership or mutate the newer claim.
        }
    } else {
        Outbox::fail(
            event.id,
            event.claim_key,
            "provider temporarily unavailable",
            8,
            15,
        ).await?;
    }
}
Ok(())
}
}

An ACK or failure transition succeeds only for the exact, unexpired random claim token. A failed delivery becomes pending after the bounded delay, or dead_letter when its attempt limit is reached. If a worker dies during its final claim, the next claim sweep moves that expired event to dead-letter instead of retrying forever.

4. Understand the guarantee

The delivery guarantee is at least once:

1. the worker claims an event;
2. the external provider accepts the effect;
3. the process stops before the database ACK;
4. the lease expires and the event is delivered again.

No local database design can atomically commit an arbitrary remote HTTP side effect. Make the consumer idempotent using the stable stream/event key. Do not use a random key on every retry.

Other explicit limits:

• key fields are 1–128 characters from a bounded ASCII grammar;
• JSON payloads are at most one MiB;
• leases are 1–3,600 seconds and attempts are 1–100;
• ordering is not guaranteed across retries or concurrent workers;
• generated observers are not automatically converted into outbox events;
• cleanup, retention, tenant authorization and the worker supervision loop belong to the application;
• monitor retry and dead-letter state through your normal database operations.

This separation keeps model saves predictable while giving applications a durable primitive where the event schema and operational policy are explicit.

5. Relay into rullst-messaging

With the umbrella messaging-orm-outbox feature, OrmOutboxRelay<B> maps one exact outbox stream to one topic on any static MessageBroker. It validates the claimed JSON, uses event_key as the broker idempotency key, publishes and then acknowledges the exact ORM claim. Its executable crash-window test stops after the first publish, reclaims the expired event and observes an exact broker replay with only one retained message.

That bridge improves composition; it does not change the guarantee. ORM commit, broker publish and ORM ACK are not one distributed atomic transaction. Operate the claim loop, retry/dead-letter policy, cleanup, authorization and final consumer deduplication explicitly. See Bounded Brokered Messaging for the relay code.

39. Scout Search Providers

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Scout connects a #[orm(searchable)] SQLx model to one search backend. The model database remains authoritative; the search index is a projection updated only after a successful managed commit.

Enable the provider adapters

With the umbrella crate:

[dependencies]
rullst = { version = "12.0.0-rc.1", features = ["orm-scout"] }

Or enable scout-http directly on rullst-orm. The feature supplies bounded HTTP adapters for Meilisearch, Elasticsearch and Algolia. The in-memory MockSearchEngine is available without the HTTP feature.

Configure one engine

Configuration is process-wide and fail-closed if code tries to replace an already installed engine:

#![allow(unused)]
fn main() {
use rullst_orm::{MeilisearchEngine, set_search_engine};

fn configure() -> Result<(), rullst_orm::Error> {
let engine = MeilisearchEngine::new(
    std::env::var("MEILI_URL").unwrap_or_default(),
    std::env::var("MEILI_API_KEY").unwrap_or_default(),
)?;
set_search_engine(engine)?;
Ok(())
}
}

Empty or mock_* credentials deliberately select the deterministic offline store. That makes local/test behavior explicit and prevents an accidental live call with missing secrets. A keyless Meilisearch or Elasticsearch development server must be selected with MeilisearchEngine::local(...) or ElasticsearchEngine::local(...); those constructors accept only loopback HTTP. Normal custom endpoints require HTTPS, contain no URL credentials/path, and disable redirects.

Algolia normally derives its official API origin from the application ID:

#![allow(unused)]
fn main() {
use rullst_orm::AlgoliaEngine;

fn engine() -> Result<AlgoliaEngine, rullst_orm::Error> {
AlgoliaEngine::new("APPLICATION_ID", "ADMIN_API_KEY")
}
}

AlgoliaEngine::with_endpoint exists for an explicitly configured compatible proxy and applies the same HTTPS/loopback URL policy. Never expose an indexing or admin key to browser code.

Mark and query the model

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Clone, Debug, FromRow, Orm)]
#[orm(table = "articles", searchable)]
struct Article {
    id: i32,
    title: String,
    body: String,
}

async fn find() -> Result<Vec<Article>, rullst_orm::Error> {
let results = Article::search("transactional outbox").await.get().await?;
Ok(results)
}
}

Generated save/update/delete operations project only after the relational commit. Rollback produces no search write. Provider or search errors remain typed errors; they are not silently converted into an empty result.

The shared adapter boundary enforces:

• lowercase index names of at most 128 bytes;
• positive i32 document IDs;
• object-shaped JSON documents no larger than one MiB;
• queries no larger than 1,024 bytes and without control characters;
• at most 1,000 parsed hits and a four-MiB response body;
• five-second connect and twenty-second request deadlines;
• disabled redirects and no secret-bearing error bodies.

Meilisearch and Algolia asynchronous indexing tasks are awaited with a bounded poll loop. Elasticsearch uses refresh=wait_for for the adapter operations.

Choose the durability level

The generated Scout hook is process-local after commit. A provider outage is reported as PostCommit: the model row is already durable and must not be blindly inserted again. This path is suitable when the application can rebuild the index or explicitly retry.

If every projection must survive a process crash, write a versioned search event through Outbox::enqueue in the domain transaction and run the selected engine from an idempotent outbox worker. Rullst does not invent a stable event key or serialize every model hook automatically. See Transactional Outbox & Durable Effects.

Evidence boundaries

The repository runs a real update/search/delete lifecycle against a digest-pinned Meilisearch container. Elasticsearch and Algolia run deterministic offline tests plus local HTTP protocol fixtures that verify paths, headers, payloads, response bounds and ID parsing. Those fixtures do not prove a hosted Algolia account, every Elasticsearch version, cluster failover, ranking quality or production capacity.

Preparing a National NFS-e 1.01 homologation candidate

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

This guide exercises the part of the Brazilian National NFS-e pipeline that can be proved safely without sending a fiscal document. It builds a bounded DPS, checks checksum-pinned government schema sources, signs the document with an application-supplied A1 PKCS#12 certificate, and validates the signed result again.

It does not authorize a note. Rullst keeps homologation and production transmission disabled until the remaining protocol and external-evidence gates listed below are complete.

Enable the isolated dependency boundary before following the signing steps:

[dependencies]
rullst-capital = { version = "12.0.0-rc.1", features = ["nfse"] }

Umbrella applications can select rullst = { version = "12.0.0-rc.1", features = ["capital-nfse"] }. The feature adds local schema/signature/codec dependencies; it does not enable a live network path.

1. Know the pinned contracts

This source revision recognizes only these immutable artifact profiles:

Download production artifacts from the official current technical documentation page and restricted artifacts from the official restricted-production documentation page. Do not copy an archive from an unofficial mirror.

Verify the archive before extraction:

sha256sum NFSe-ESQUEMAS_XSD-v1.01-20260209.zip

NfseDpsSchemaValidator also verifies every expected XSD file. It rejects an unknown profile, a missing/modified file, a file larger than 256 KiB, traversal, and any import outside its closed in-memory catalogue. The XML instance cannot make it download a schema or follow a filesystem hint.

There is one intentionally visible compatibility rule. The pinned production simple-types file contains the DPS-series pattern ^0{0,4}\d{1,5}$, authored with .NET anchors even though ^ and $ are literals in XSD regex grammar. Only after the file hash matches, Rullst removes those two anchors in memory. The rewrite is tied to that exact file hash and exact one occurrence; any upstream change fails closed. Restricted production currently needs no rewrite.

2. Exercise the unsigned builder and official XSD

Point the example at the directory that directly contains DPS_v1.01.xsd:

RULLST_NFSE_XSD_DIR=/path/to/extracted/Schemas/1.01 \
  cargo run -p rullst-capital --example nfse_v101_preview

The example uses NfseDpsV101, not the legacy floating-point preview. Its bounded subset is an ordinary domestic service with:

• integer BRL cents and ISS basis points;
• explicit taxation and retention enums;
• checked CPF/CNPJ digits, IBGE codes, DPS ID, series, service code, text, and XML size;
• no automatic guess about municipal parameters or tax treatment.

Passing XSD validation proves document structure and scalar constraints only. SEFIN business rules still depend on the emitter, municipality, contributor registration, Simples Nacional state, service classification, and current official parameters.

3. Load and sign with an A1 certificate

Never commit a .pfx/.p12 file or its passphrase. Load them from the deployment secret boundary and keep the passphrase out of logs:

#![allow(unused)]
fn main() {
use rullst_capital::fiscal::{
    FiscalCertificate, NFSE_RESTRICTED_V1_01_20260727,
    NfseDpsSchemaValidator, sign_dps_xml,
};

fn prepare_signed_candidate(
    unsigned_xml: &str,
    schema_directory: &std::path::Path,
    pkcs12_path: &std::path::Path,
    passphrase: String,
) -> Result<String, Box<dyn std::error::Error>> {
    let pkcs12 = std::fs::read(pkcs12_path)?;
    let certificate = FiscalCertificate::from_bytes(&pkcs12, passphrase)?;
    let validator = NfseDpsSchemaValidator::from_pinned_directory(
        schema_directory,
        &NFSE_RESTRICTED_V1_01_20260727,
    )?;

    validator.validate(unsigned_xml)?;
    let signed_xml = sign_dps_xml(unsigned_xml, &certificate)?;
    validator.validate(&signed_xml)?;
    Ok(signed_xml)
}
}

sign_dps_xml accepts exactly one unsigned DPS 1.01 envelope with a unique 45-character infDPS/@Id. It extracts the matching key/certificate chain from PKCS#12, requires an RSA PKCS#8 key, emits an enveloped RSA-SHA256 signature using SHA-256 and inclusive C14N 1.0, and refuses to return partially signed XML. The signing path verifies the result against its embedded certificate before returning it; separate tests also verify the generated XMLDSig and validate a signed builder fixture with the pinned official schema.

Rullst redacts the certificate container in Debug and zeroizes certificate bytes, passphrases, decoded base64, and derived PEM buffers it owns. The application still owns secret-file permissions, secret-manager integration, rotation, process/core-dump policy, and access auditing.

4. Run the opt-in official-artifact regression

The repository does not redistribute mutable government packages. After downloading and verifying the pinned production archive, run the ignored test:

RULLST_NFSE_XSD_DIR=/path/to/extracted/Schemas/1.01 \
  cargo test -p rullst-capital \
  fiscal::signer::tests::signed_builder_output_matches_the_official_xsd_when_supplied \
  -- --ignored

The test generates an ephemeral RSA key and certificate at runtime. It is a schema/cryptographic interoperability fixture, not an ICP-Brasil certificate or an official homologation result.

The corresponding restricted-production package has a separate immutable manifest and regression:

RULLST_NFSE_RESTRICTED_XSD_DIR=/path/to/extracted/restricted/schemas \
  cargo test -p rullst-capital \
  fiscal::signer::tests::signed_builder_output_matches_the_official_restricted_xsd_when_supplied \
  -- --ignored

5. Exercise the offline protocol boundary

After producing the signed DPS, build the exact request body without sending it:

#![allow(unused)]
fn main() {
use rullst_capital::fiscal::NfseIssueRequest;

fn prepare(signed_dps: &str) -> Result<Vec<u8>, rullst_capital::fiscal::FiscalError> {
let request = NfseIssueRequest::try_from_signed_dps(signed_dps)?;
let body = request.to_json()?;
Ok(body)
}
}

Construction verifies that the document has one unique official DPS ID, one direct signed infDPS/tpAmb, one direct XMLDSig reference to that ID and a cryptographically valid embedded signature. GZip output fixes its timestamp to zero, so the JSON is deterministic for a given signed document. The environment passed to parse_response must equal that signed tpAmb.

For retained protocol fixtures, call request.parse_response(status, environment, body). HTTP 201 is represented only as NfseIssueResponse::Authorized; HTTP 400, 403 and 500 are represented as Rejected. The parser rejects unknown fields, wrong environments or DPS IDs, invalid access keys, malformed JSON/Base64/GZip/XML, unsigned or tampered NFS-e XML and decompressed material above four MiB. Embedded-signature verification proves document integrity against its declared certificate, not ICP-Brasil trust or emitter ownership.

6. Journal a caller-owned command before transport

The nfse feature provides bounded local evidence for a future reviewed transport workflow. Load exactly 32 random bytes from a secret manager; never derive this key directly from a password or commit it to the repository.

#![allow(unused)]
fn main() {
use rullst_capital::fiscal::{
    FiscalCommandJournal, FiscalJournalDisposition, FiscalJournalKey,
    NfseEnvironment, NfseIssueRequest, NfseIssueResponse,
};
use std::path::Path;

fn stage(
    path: &Path,
    key_bytes: &[u8],
    request: &NfseIssueRequest,
    parsed_response: Option<&NfseIssueResponse>,
) -> Result<(), Box<dyn std::error::Error>> {
let key = FiscalJournalKey::try_new("fiscal-2026-01", key_bytes)?;
let journal = FiscalCommandJournal::try_open(path, key)?;

// Use an opaque, stable, non-PII ID from the application's authoritative outbox.
let prepared = journal.prepare(
    "nfse-command:01J8YQ2V5M",
    NfseEnvironment::Homologation,
    request,
)?;
if prepared.disposition() == FiscalJournalDisposition::Recorded {
    // A future reviewed transport may run only after this synchronized record.
}

if let Some(response) = parsed_response {
    journal.record_response("nfse-command:01J8YQ2V5M", request, response)?;
}

for unresolved in journal.pending()? {
    // Locate the real request in the application's protected outbox, compare
    // request_digest(), and reconcile with SEFIN before deciding whether to retry.
    let _command_id = unresolved.command_id();
}

// Persist this separately if valid-prefix truncation must be detected on restart.
let _checkpoint = journal.checkpoint()?;
Ok(())
}
}

The HMAC-chained file accepts one active writer and at most 4,096 events/16 MiB. It stores no DPS/NFS-e XML, access key, processing message, response body, or certificate material. An exact command/request/result replay does not append; conflicts, corrupted/reordered frames, wrong keys, symlinks, external growth, quota exhaustion, and uncertain synchronization fail closed. pending() is a recovery index, not the protected request store itself. The host owns key rotation, directory permissions, exclusive-writer enforcement, the real request/outbox, independent checkpoint retention, backup/retention, retry policy, and authority reconciliation. The journal does not perform network I/O or establish exactly-once behavior across systems.

7. Do not enable live transmission yet

The official endpoints are immutable in NfseEnvironment, and the live path can already build an HTTPS-only rustls mTLS client with redirects disabled and bounded connect/request timeouts. It deliberately performs no request.

The exact request envelope and bounded response/rejection codec are now local, fixture-testable prerequisites. Before Rullst can enable restricted-production transmission, the exact source revision must still have:

1. retained fixtures from the current official restricted-production contract, including every supported success/rejection shape;
2. certificate validity, key-usage, emitter CPF/CNPJ, and ICP-Brasil chain policy reviewed against the current national rules;
3. deployment of the local journal with protected authoritative request/outbox storage, exclusive-writer/key/checkpoint operations, retry policy, and explicit authority reconciliation;
4. positive and negative tests in the restricted environment using an authorized real A1 certificate and valid contributor/municipality data;
5. independent fiscal/security review and retained evidence tied to an immutable commit;
6. successful official homologation before production can be considered.

Until those gates pass, NfseEnvironment::Homologation and NfseEnvironment::Production return FiscalError::Unsupported, while NfseEnvironment::Mock remains unmistakably MOCK_NOT_AUTHORIZED.

41. Tenant-Bound RAG in One Typed Operation

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Rullst’s bounded RAG pipeline turns one authenticated question into a guarded embedding, authorized retrieval request, budgeted context, grounded model call, source metadata, and a terminal audit event.

It deliberately does not hide the datastore or invent authorization. The host application still decides who may ask, which records that identity may read, how documents are ingested and deleted, and which embedding model and vector dimensions define an index.

Add the feature

[dependencies]
rullst = { version = "12.0.0-rc.1", default-features = false, features = ["ai"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Run the complete offline contract

An empty or mock_* OpenAI key selects Rullst’s deterministic offline provider. Its fixture embeddings have 16 dimensions, so the local index below uses the same exact dimension.

use rullst::ai::rag::{
    InMemoryRagAuditTrail, InMemoryRagRetriever, RagDocument, RagPipeline,
};
use rullst::ai::{providers::openai::OpenAiProvider, AiClient};
use rullst::security::TenantContext;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build this only from verified authentication and membership claims.
    let tenant = TenantContext::try_new("tenant:acme")?;
    let client = AiClient::new(OpenAiProvider::new("mock_rag"));
    let retriever = InMemoryRagRetriever::try_new(1_000, 16)?;

    let content = "Rullst upgrades start with cargo rullst upgrade --dry-run.";
    let vector = client.embed(content).await?;
    let document = RagDocument::try_new(
        &tenant,
        "upgrade-guide",
        content,
        0.0, // The retriever replaces this with cosine similarity.
    )?;
    retriever.upsert(&tenant, document, vector)?;

    let audit = Arc::new(InMemoryRagAuditTrail::new(1_000)?);
    let pipeline = RagPipeline::new(client, retriever, Arc::clone(&audit));
    let response = pipeline
        .answer(&tenant, "How do I preview a framework upgrade?")
        .await?;

    println!("{}", response.answer());
    for source in response.sources() {
        println!(
            "source={} score={} chars={} truncated={}",
            source.document_id(),
            source.score(),
            source.included_chars(),
            source.truncated()
        );
    }

    let events = audit.entries()?;
    println!("recorded {} terminal RAG event(s)", events.len());
    Ok(())
}

The offline provider is a deterministic test fixture, not evidence of live model quality. In a real application, select a live provider explicitly and evaluate its configured model against a versioned domain corpus.

What the pipeline enforces

For each call, RagPipeline:

1. validates the bounded question and runs guarded embedding;
2. passes the trusted TenantContext, query vector, and bounded limit to the application retriever;
3. rejects over-returned or differently tagged documents;
4. runs prompt-injection checks and outbound PII masking on every passage;
5. truncates by per-document and total Unicode-scalar budgets;
6. refuses to generate when no safe context remains;
7. returns only source identifiers, scores, included character counts, and truncation state alongside the answer;
8. records exactly one terminal, secret-minimized audit event, or fails the operation if the required audit sink is unavailable.

Tune budgets with RagConfig::try_new(max_documents, max_document_chars, max_context_chars). The constructor rejects zero or unbounded values; RagPipeline::with_config accepts only an already validated configuration.

Use an authoritative production retriever

InMemoryRagRetriever is bounded and tenant-partitioned, but it is process local, nondurable, and uses an exact linear cosine scan. It is appropriate for tests, development, and small ephemeral datasets.

Production applications implement the public async RagRetriever trait over their chosen store. A PostgreSQL implementation should put the tenant predicate inside the same parameterized pgvector query that performs similarity ordering. A Qdrant implementation should apply the deployment’s reviewed tenant filter or separate-collection policy. It then creates each RagDocument from the same trusted context passed to retrieve.

The essential shape is:

async fn retrieve(
    &self,
    tenant: &TenantContext,
    query_embedding: &[f32],
    limit: usize,
) -> Result<Vec<RagDocument>, RagRetrievalError> {
    let rows = self.store
        .similar_chunks_for_tenant(&tenant.tenant_id, query_embedding, limit)
        .await
        .map_err(redacted_retrieval_error)?;

    rows.into_iter()
        .map(|row| RagDocument::try_new(tenant, row.id, row.content, row.score))
        .collect()
}

The pipeline verifies the returned tenant tag as defense in depth. That check cannot detect a datastore adapter that incorrectly read another tenant’s row and then falsely relabeled it. Authoritative tenant and ownership filtering must therefore happen in the datastore query itself.

Supply durable, minimized audit evidence

InMemoryRagAuditTrail is useful for local assertions. A single-process service can use the bounded built-in local file:

#![allow(unused)]
fn main() {
use rullst::ai::rag::DurableRagAuditTrail;
use std::sync::Arc;

let audit = Arc::new(DurableRagAuditTrail::try_open(
    "storage/audit/rag.log",
)?);
Ok::<(), Box<dyn std::error::Error>>(())
}

The trail synchronously appends a distinct versioned stream, validates every event/frame on restart and fails closed on corruption, unsafe file types, external length changes and quota exhaustion. The default ceilings are 16 MiB and 4,096 events; try_open_with_max_bytes may select a smaller byte quota. Its SHA-256 frame digest detects corruption but does not authenticate the writer. The host owns trusted directory permissions, exclusive writer access, rotation, retention, backup and export. Multi-instance deployments should implement RagAuditSink over an append-only, access-controlled destination.

The built-in event contains the tenant ID, a SHA-256 digest of the original question, document counts, included context characters, and the terminal outcome. It omits raw questions, passages, vectors, model answers, and provider error bodies. A digest is not encryption and low-entropy questions may be guessable, so do not expose the audit stream as public data.

Security and quality boundaries

• Prompt-injection filtering is heuristic defense in depth, not proof that a passage or answer is safe.
• Source metadata proves which identifiers entered the prompt; it does not prove that the model cited them faithfully or that their contents were true.
• Apply normal output encoding, domain validation, and tool authorization after generation. Never treat model text as an authorized command.
• Keep ingestion, updates, deletions, retention, embedding-model migrations, ANN tuning, backups, and disaster recovery explicit.
• Test cross-tenant denial, empty retrieval, hostile passages, provider failure, datastore failure, audit failure, and context truncation in the host application.

For the lower-level vector-store contracts, see RAG Systems & Vector Search. For the framework’s broader claims and limits, see the capability ledger.

42. Server-Bound OAuth/OIDC Sessions

Rullst Connect can manage the browser-to-provider callback challenge for an Axum application. The bounded flow generates state and PKCE for OAuth 2.0, adds nonce for OpenID Connect, stores the private values in tower-sessions, and consumes them before validating the callback.

This removes security-sensitive plumbing from ordinary handlers. It does not configure the application’s session store, cookie, TLS, account-linking, or authorization policy.

Enable the session feature

For the unreleased workspace:

[dependencies]
rullst-connect = { path = "../Rullst/rullst-connect", features = ["axum-session"] }
tower-sessions = "0.15"

Published applications should replace the path with one immutable compatible version. Add a SessionManagerLayer to the Axum router. MemoryStore is useful for local examples and tests, but it is process-local and is not a production durability or horizontal-scaling strategy.

use tower_sessions::{cookie::SameSite, MemoryStore, SessionManagerLayer};

let sessions = SessionManagerLayer::new(MemoryStore::default())
    .with_http_only(true)
    .with_same_site(SameSite::Lax)
    .with_secure(true);

let app = app.layer(sessions);

SameSite::Lax permits the ordinary top-level OAuth callback while reducing cross-site cookie exposure. Production still requires HTTPS, a durable shared store where multiple instances are used, bounded store retention, protected keys and an explicit reverse-proxy policy.

Start OAuth 2.0 with state and PKCE

Use this path for providers such as GitHub where the application is using an OAuth authorization-code flow without an ID token:

#![allow(unused)]
fn main() {
use axum::response::Redirect;
use rullst_connect::prelude::*;
use tower_sessions::Session;

async fn start_github(
    session: Session,
    github: &GithubProvider,
) -> Result<Redirect, ConnectError> {
    let authorization = begin_oauth_session(&session, github).await?;
    Ok(Redirect::temporary(authorization.url()))
}
}

The returned URL contains the random state and the SHA-256 PKCE challenge. The 64-character verifier is serialized only in the server-side session record. OAuthAuthorization deliberately redacts its URL from Debug output.

Start OpenID Connect with nonce

Use the OIDC variant for Google, Apple, or a discovered custom OIDC provider:

let authorization = begin_oidc_session(&session, &oidc_provider).await?;
Ok(Redirect::temporary(authorization.url()))

This stores another random value and sends it as nonce. The provider adapter receives that same expected nonce later and validates it against the signed ID token in the adapters whose documented contract includes ID-token validation.

Consume the callback

Mount AuthSession directly as an Axum extractor. Extraction parses the real query, removes and immediately saves the stored challenge, rejects expiry or a constant-time state mismatch, and makes a later sequential replay fail:

#![allow(unused)]
fn main() {
use rullst_connect::prelude::*;
use tower_sessions::Session;

async fn github_callback(
    session: Session,
    callback: AuthSession,
    github: &GithubProvider,
) -> Result<UniversalProfile, ConnectError> {
    let user = github.get_user(callback.exchange_params()?).await?;

    // Rotate the browser session before establishing authenticated identity.
    session
        .cycle_id()
        .await
        .map_err(|error| ConnectError::Session(error.to_string()))?;
    session
        .insert("authenticated_user_id", &user.id)
        .await
        .map_err(|error| ConnectError::Session(error.to_string()))?;

    Ok(user.universal_profile())
}
}

Do not serialize ConnectUser as a credential store. Its public serialization already omits provider tokens, while UniversalProfile is the narrower credential-free identity projection. If an application needs provider refresh tokens, place them in a dedicated encrypted store with explicit rotation and revocation policy.

For a provider that returned both a refresh token and expires_in, construct a bounded process-local coordinator at the trusted time the token response was received:

#![allow(unused)]
fn main() {
use rullst_connect::{AutoRefreshingSession, ConnectError, ConnectUser};
use rullst_connect::prelude::ExposeSecret as _;

async fn call_authorized_endpoint(_: &str) -> Result<(), ConnectError> {
    Ok(())
}

async fn provider_request(
    github: &rullst_connect::providers::GithubProvider,
    user: &ConnectUser,
    token_received_at: u64,
) -> Result<(), ConnectError> {
    let tokens = AutoRefreshingSession::from_user_at(
        github,
        user,
        token_received_at,
    )?;
    let lease = tokens.access_token().await?;
    call_authorized_endpoint(lease.access_token().expose_secret()).await?;
    Ok(())
}
}

AutoRefreshingSession<P> checks a bounded early-expiration window and holds one async process-local refresh gate, so provider refresh calls cannot overlap and waiters reuse the first valid result. It keeps the old refresh credential if the provider does not rotate, adopts a valid rotation, requires the same provider user ID and changes state only after full validation.

Persist refresh state without storing plaintext tokens

Rullst supplies a storage-neutral authenticated envelope. The application still chooses its database/file/secret manager, but the stored token record need not invent its own cryptographic format:

#![allow(unused)]
fn main() {
use rullst_connect::{
    AutoRefreshingSession, EncryptedTokenSnapshot, Provider,
    TokenSnapshotBinding, TokenSnapshotError, TokenSnapshotKey,
};

async fn seal_current_state<P: Provider + ?Sized>(
    session: &AutoRefreshingSession<'_, P>,
    key_bytes: [u8; 32],
    local_account_id: &str,
) -> Result<EncryptedTokenSnapshot, TokenSnapshotError> {
    let state = session.state_snapshot().await;
    let binding = TokenSnapshotBinding::try_new("github", local_account_id)?;
    let key = TokenSnapshotKey::try_new("oauth-primary-2026", key_bytes)?;
    EncryptedTokenSnapshot::seal(&state, &key, &binding)
}
}

Write only EncryptedTokenSnapshot::as_str() to durable storage. On restart:

1. parse the stored string with EncryptedTokenSnapshot::try_from_envelope;
2. read its non-secret key_id() and select that 32-byte key in a secret manager;
3. rebuild the same binding from trusted provider and local-account state;
4. call open, then pass the restored state to AutoRefreshingSession::new.

The AES-256-GCM authentication tag covers the envelope version, key ID, provider and local account, so a copied record fails for another owner. The payload is bounded and revalidated after decryption. Debug output is redacted, and the envelope itself does not implement Display or Serde. The application must still commit each new generation transactionally, rotate/retain keys, authorize the account and revoke local state. Multi-process deployments also need a distributed compare-and-set/lease; retry/backoff, reauthentication and replay of the original API request are deliberately not inferred.

Lifecycle and failure semantics

The managed contract is intentionally small:

• a challenge expires ten minutes after it is created;
• there is one active challenge per browser session;
• starting a second flow replaces the first, so the older browser tab fails;
• authorization URLs must use HTTPS or exact loopback HTTP, contain no URL credentials/fragment, and preserve exactly one generated state and S256 PKCE tuple without a preconfigured nonce;
• the challenge is removed and saved before state, nonce or PKCE-dependent exchange;
• missing, mismatched, expired and later sequential callbacks fail closed;
• provider error text is bounded before it becomes a typed error;
• callback codes, state, nonce, verifier and authorization URLs are redacted from the managed types’ Debug output.

One active challenge makes replay and lifecycle behavior unambiguous, but it is not the best UX for applications that intentionally support concurrent login tabs. Such an application should build a bounded transaction store keyed by an opaque flow identifier and retain the same expiry, atomic consume, constant-time comparison and redaction properties.

The generic tower-sessions store interface does not expose a distributed compare-and-delete. Two requests that already loaded the same record can still race even though each removal is saved immediately. Provider authorization codes are themselves single-use, but account creation/linking and authenticated session establishment must still be idempotent. Deployments requiring a strict distributed callback claim should use an application-owned atomic challenge store.

What the application still must prove

Before release, test the exact deployed provider and browser path:

1. The registered redirect URI exactly matches the application route and uses HTTPS outside an exact loopback development host.
2. The session cookie remains Secure and HttpOnly, uses an intentional SameSite policy, and is rotated after successful authentication.
3. Every application instance sees the same durable session store, or routing is deliberately constrained without pretending failover works.
4. Issuer, audience, signature, expiry and nonce checks pass and fail against the provider’s real or restricted environment.
5. Account creation/linking cannot attach an attacker-controlled provider identity to an existing local account.
6. Denial, timeout, provider outage and abandoned-login recovery have bounded user-visible behavior without logging credentials.

The local Rullst regressions prove generation, round-trip, mismatch, missing state, expiry, replacement, replay, typed exchange parameters and redaction. They are not provider certification or deployment evidence.

Rullst Omni: Web-First, Platform-Enhanced Applications

Rullst Omni packages one canonical Rullst web application for desktop, Android and iOS with Tauri. It is deliberately a secure web-shell foundation, not a claim that a website automatically becomes a store-ready native product.

The architectural rule is simple:

1. the Rullst server owns domain rules, identity, authorization, persistence, realtime policy and security;
2. the web interface remains the universally reachable product;
3. platform shells reproduce that interface and add only narrowly scoped native capabilities that have a real product need and platform tests.

This keeps web, desktop and mobile behavior aligned without treating an untrusted client as the authority.

Generate a desktop development shell

From a Rullst application root:

cargo rullst make:omni --platform desktop
cargo rullst omni desktop

The product name and version inherit [package].name and [package].version. Desktop development derives a com.example.<package> identifier when none is provided. That namespace is a visible placeholder, not a distributable product identity.

The default http://localhost:3000 profile starts the parent Rullst server, waits for it and owns only the child process it created. It refuses to attach when port 3000 was already occupied, stops if the child exits before readiness and fails after a bounded timeout. This prevents the shell from silently connecting to an unrelated local process.

For an externally operated HTTPS application, set its public web URL:

cargo rullst make:omni \
  --platform desktop \
  --backend-url https://app.example.com \
  --identifier com.exampleowner.myapp \
  --product-name "My App" \
  --app-version 1.2.3

Use a reverse-DNS namespace that you or your organization actually control; the value above is illustrative.

Generate Android or iOS

Mobile requires both a reachable backend and an application-owned identifier:

cargo rullst make:omni \
  --platform android \
  --backend-url https://app.example.com \
  --identifier com.acme.myapp

cargo rullst make:omni \
  --platform ios \
  --backend-url https://app.example.com \
  --identifier com.acme.myapp

Android emulator development may use http://10.0.2.2:3000. Distributable applications should use HTTPS. Android requires the Android SDK/NDK and Java; iOS generation requires macOS and Xcode.

cargo rullst omni android
cargo rullst omni ios

The CLI initializes only platforms selected by the user. A requested toolchain or Tauri initialization failure fails the command instead of printing a false success.

Security model

The generated local bootstrap has an origin-specific CSP and no inline script. Remote content is not given a global Tauri object or privileged command capability. A Rust-side navigation policy admits only:

• the packaged Tauri bootstrap origin; and
• the exact scheme, host and effective port of --backend-url.

Paths and query strings on that same backend remain usable. A lookalike host, scheme downgrade, different port or third-party origin is rejected.

This secure default means cross-origin OAuth and ordinary external links do not yet work inside the webview. Do not weaken the allowlist to https: or expose a generic shell command. Add a reviewed system-browser opener plus an allowlisted, single-use deep-link callback when the application needs that flow.

All normal web protections still apply. The server must enforce sessions, CSRF, secure headers, ownership/RBAC, input validation and rate limits. A mobile package does not make server-side authorization optional.

Share one typed wire contract

rullst::client_contract is available to native server code and wasm32-unknown-unknown clients. Its rullst.client v1 envelope gives web and Omni code the same bounded JSON shape without inventing a second business API:

#![allow(unused)]
fn main() {
use rullst::client_contract::{
    ClientContractPolicy, ClientRequest, IdempotencyKey, RequestId,
    CURRENT_CLIENT_CONTRACT_VERSION,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct LessonAttempt {
    lesson_id: String,
    answer: String,
}

fn encode_attempt() -> Result<(), Box<dyn std::error::Error>> {
let request = ClientRequest::mutation(
    CURRENT_CLIENT_CONTRACT_VERSION,
    RequestId::new("req_01j8lesson")?,
    IdempotencyKey::new("attempt_01j8lesson")?,
    LessonAttempt {
        lesson_id: "lesson_1".into(),
        answer: "bonjour".into(),
    },
);
let encoded = ClientContractPolicy::default().encode_request(&request)?;
let _ = encoded;
Ok(())
}
}

The server decodes through ClientContractPolicy, derives the user and tenant from its authenticated session, requires the idempotency key before a mutation, and computes grading, points, streaks and server time itself. Do not put a role, user_id, trusted score or authorization decision in the client payload.

The generic codec has a configurable ceiling no larger than 2 MiB, rejects unknown outer fields and selects only a mutually supported positive version. Its key proves request shape, not exactly-once execution: the application still needs a durable unique key plus an atomic result/effect transaction. This contract is a prerequisite for future offline queues, not an offline queue.

Offline behavior

The packaged bootstrap can explain that the device is offline and retry before the first navigation. It still does not automatically cache application data or mount background synchronization.

The opt-in native offline-sync feature now supplies a bounded foundation: account-bound AES-256-GCM snapshots, FIFO idempotent mutations, authoritative server revisions/cursors, explicit conflicts, full resync, quotas, recovery and logical erasure. A bounded foreground coordinator can drive an application-owned authenticated transport with request budgets, timeout and cursor-stall protection. Follow the offline synchronization tutorial to use it without moving authority into the client.

Calling the generated shell itself “offline-first” remains inaccurate. A real application profile must still provide at least:

• reviewed platform persistence and Keychain/Keystore integration;
• concrete authenticated HTTP, retry/background scheduling and application conflict UX;
• concrete migrations beyond the current versioned fail-closed schema;
• complete deletion of snapshots, backups and platform keys;
• browser, Android and iOS tests for airplane mode and reconnection.

Adding native capabilities safely

Push notifications, biometrics, deep links, camera/file access, haptics and OS secure storage can make Omni feel native. Add them as opt-in capabilities, one at a time:

1. state the user-facing need and supported platforms;
2. grant the narrowest Tauri/platform permission;
3. keep device credentials in Keychain/Keystore-class storage, never in web local storage or generated source;
4. authenticate every server operation independently of the client signal;
5. add negative tests for denied/replayed/cross-account requests;
6. test a real device before documenting the capability as supported.

Biometrics may unlock a local credential; it must not manufacture server authorization. Push payloads should be minimized and treated as untrusted input.

What CI proves

Rullst maintains path-aware generation/compile workflows for three evidence classes:

• desktop crate checks on Linux, macOS and Windows;
• an Android debug APK build;
• an iOS simulator build on macOS.

A green run proves that a fresh generated shell compiled for that runner and commit. All three gates passed on 755fbd61933bed04369e0eb5de50b11275db5e3d. This does not prove physical-device behavior, accessibility, signing, privacy declarations, TestFlight/Play testing or store acceptance.

Before distribution

Review the generated omni-app/README.md, then complete application-owned work:

• production identity, icons, versioning and metadata;
• HTTPS endpoint, authentication and retention policy;
• accessibility and poor/offline-network behavior;
• platform privacy manifests and usage descriptions;
• signing/provisioning and secret handling;
• physical-device and beta-channel tests;
• store policy, screenshots, disclosure and review.

Tauri supplies legitimate packages and installers; stores decide whether the finished product meets their technical, functionality, privacy and content requirements.

Bounded Offline Synchronization for Omni

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Rullst’s opt-in offline-sync feature supplies the native state and encrypted snapshot boundary needed to build a resilient Omni client. It is not mounted automatically by make:omni: the generated shell remains a minimal web shell, and the application chooses which entities may exist offline.

The contract deliberately keeps the server authoritative. Local records are a cache; queued writes are proposals. Roles, tenant membership, scores, streaks, entitlements and trusted time must be recomputed or revalidated by the server.

Enable the native profile

[dependencies]
rullst = { version = "12.0.0-rc.1", features = ["offline-sync"] }

The encrypted snapshot codec is native-only. A browser offline implementation needs a separately reviewed IndexedDB/service-worker adapter and browser tests; the current feature does not silently substitute local storage.

Create an account-bound state

#![allow(unused)]
fn main() {
use rullst::offline_sync::{
    OfflineAccountId, OfflineSnapshotCipher, OfflineSyncPolicy, OfflineSyncState,
};

fn load_device_key() -> Result<[u8; 32], std::io::Error> {
    Err(std::io::Error::other("platform secure storage adapter omitted"))
}
fn create_state() -> Result<(), Box<dyn std::error::Error>> {
let account = OfflineAccountId::new("account_01j8student")?;
let policy = OfflineSyncPolicy::default();
let mut state = OfflineSyncState::new(account.clone());

// Load these 32 high-entropy bytes from Keychain/Keystore-class storage.
// Never embed a production key in source or store it next to the snapshot.
let device_key = load_device_key()?;
let cipher = OfflineSnapshotCipher::new("device-key-2026-01", device_key)?;
let _ = (cipher, policy, state);
Ok(())
}
}

The cipher uses randomized AES-256-GCM. Its authenticated data binds the envelope domain, key id and exact account id, so another account, key, modified nonce/tag or modified ciphertext fails closed. The owned key is redacted from Debug and zeroized on drop, but Rust cannot erase copies made beforehand.

Queue a lesson attempt

Use a unique event entity for an immutable attempt. Do not queue an authoritative score: the server grades the answer and returns its own revision and value.

#![allow(unused)]
fn main() {
use rullst::client_contract::IdempotencyKey;
use rullst::offline_sync::{
    OfflineAccountId, OfflineEntityKey, OfflineMutation, OfflineSyncPolicy,
    OfflineSyncState,
};
use serde_json::json;

fn queue_attempt() -> Result<(), Box<dyn std::error::Error>> {
let policy = OfflineSyncPolicy::default();
let account = OfflineAccountId::new("account_01j8student")?;
let mut state = OfflineSyncState::new(account);
let client_epoch_ms = 1_800_000_000_000;
let attempt = OfflineMutation::upsert(
    IdempotencyKey::new("attempt_01j8french7")?,
    OfflineEntityKey::new("lesson_attempts", "attempt_01j8french7")?,
    None,
    client_epoch_ms, // UX ordering only; never trusted by the server.
    json!({
        "lesson_id": "french-basics-7",
        "answer": "bonjour"
    }),
)?;
state.queue(policy, attempt)?;

let batch = state.push_batch(policy, 25)?;
let _ = batch;
Ok(())
}
}

Queue order is FIFO and replay keys are unique across pending and conflicted operations. Counts, payload bytes, snapshot bytes and push size all have configurable limits below hard framework ceilings.

Send SyncPushBatch inside the versioned rullst.client envelope. On the server, authenticate the session, derive account/tenant context, validate the entity and domain payload, and atomically persist both the replay key and its result/effect. A client key alone does not provide exactly-once behavior.

Apply authoritative results

The server returns a SyncPushResult whose outcomes are one of:

• Applied: durable result plus the current server record or tombstone;
• Conflict: current server record plus a stable bounded code;
• Rejected: stable code and an explicit retry hint.

Applying a response is transactional within the state value. Unknown or duplicated replay keys, mismatched entities, regressing revisions, reused revisions with different data and regressing server time leave the original state unchanged.

A retryable rejection stays in the FIFO queue. A conflict or permanent rejection moves the proposal out of automatic replay. The application must either accept server state or retry the original proposal against the latest server revision with a new idempotency key. There is no automatic client-wins mode.

Coordinate a bounded foreground sync

Implement OfflineSyncTransport on an application adapter that already owns its authenticated session, TLS policy and endpoint. The trait uses static dispatch: it does not box a provider or place credentials in offline state. The account_id argument is only a local binding/routing hint; the server must derive the real account, tenant, ownership and authorization from the authenticated request.

Map the response’s versioned client-contract envelope into AuthoritativePush or AuthoritativePull, including server-authored time, then run one bounded foreground attempt:

The following integration fragment intentionally depends on the application-owned OfflineSyncTransport implementation described above:

use rullst::offline_sync::{
    OfflineSyncCoordinator, OfflineSyncRunPolicy,
};

let run_policy = OfflineSyncRunPolicy::new(
    25,     // mutations per push
    4,      // push requests this run
    20,     // pull pages this run
    15_000, // timeout for every transport request
)?;

let report = OfflineSyncCoordinator::synchronize(
    &authenticated_transport,
    &mut state,
    policy,
    run_policy,
).await?;

The coordinator pushes before pulling, stops retrying a batch that produced no local progress, bounds page/request counts, times out every transport future and rejects has_more when the opaque cursor does not advance. It does not invent retry delays or silently start an OS background task. Successfully accepted pages remain in state if a later request fails, so seal and atomically persist the state after both success and error paths. The server must persist replay decisions atomically so a request accepted before a client crash can safely return the same result later.

Pull, reconnect and full resync

Apply incremental SyncPullPage values in order. If a newer server revision touches an entity with a divergent local proposal, Rullst preserves that proposal as an explicit conflict before caching server state.

When the server sets requires_full_resync, apply_pull changes nothing and returns FullResyncRequired. Fetch a complete authorized snapshot, then call replace_server_snapshot. New local entities whose base is still absent stay pending; stale proposals become conflicts instead of disappearing.

recover_server_cache clears derived records, cursor and accepted server time while preserving pending work and conflicts. It is useful after an application decides that its server cache is unusable; it is not a substitute for detecting corrupt encrypted bytes, which already fail authentication or schema checks.

Persist and erase

The persistence call below is also an application integration fragment: cipher, policy, state, and account come from the preceding steps, while platform_store_atomically is the reviewed platform adapter Rullst deliberately does not supply:

let encrypted = cipher.seal(policy, &state)?;
platform_store_atomically(&encrypted)?;

let restored = cipher.open(policy, &account, &encrypted)?;

Write the encrypted bytes atomically inside the platform’s application data directory. Store the key separately in Keychain/Keystore-class storage and apply OS backup/privacy policy intentionally. Rullst currently supplies neither that platform adapter nor background scheduling.

For logout/account deletion, call state.erase(), delete every persisted snapshot (including backups and temporary files), and remove the associated secure-storage key. The method performs logical state erasure; it cannot erase prior clones, filesystem snapshots, cloud backups or server data.

What remains before calling an app offline-first

• reviewed Keychain/Keystore and atomic file/SQLite adapters per platform;
• schema migration implementations beyond the current fail-closed v1 marker;
• a concrete authenticated HTTP adapter plus application retry/backoff, cancellation and OS background execution around the bounded coordinator;
• browser storage support where the web product needs offline data;
• airplane-mode, process-kill, quota, corrupt-state, account-switch and reconnection tests on physical Android/iOS devices;
• application-specific conflict UX, retention and erasure verification.

The module closes the protocol/state/cryptographic foundation, not those platform and product obligations.

45. Accessible Academy Media

Rullst’s LMS blueprint generates a bounded lesson-presentation foundation for video and audio. It belongs to the web-first Academy slice: authorization and progress remain server-owned, while the browser receives accessible media markup and an escaped transcript.

Generate the complete Academy starter

cargo rullst new language-academy --default --blueprint lms \
  --skip-initial-migration
cd language-academy
cargo test --offline --all-targets

The complete starter includes the integrated curriculum, assessment, gamification, automation and notification journey. A smaller learning foundation is available with --lms-modules auth,learning.

Lesson media contract

Generated lessons store these fields:

For production, prefer application-owned same-origin or signed media. Put a caption file at static/media/lesson.pt-BR.vtt and store the public source as /static/media/lesson.pt-BR.vtt; Server mounts the local static/ directory at /static.

WEBVTT

00:00.000 --> 00:04.000
Bem-vindo à primeira atividade.

The blueprint intentionally does not copy a media binary. Add your reviewed audio/video asset or application-specific object-storage delivery, then use a same-origin path such as /static/media/lesson.webm. If you choose a remote host, add only that reviewed origin to the application’s media-src CSP; do not weaken the policy to arbitrary HTTPS.

What the generated player enforces

• no autoplay;
• native video/audio controls;
• a caption track for every video;
• an always-available transcript for video and audio;
• visible keyboard focus and nonce-bound styles;
• escaped title and transcript values;
• fail-closed rendering for unknown kinds, insecure sources or invalid accessibility metadata.

The protected lesson controller still checks the authenticated learner’s school, enrollment, entitlement and release policy before rendering the player. Progress submissions use CSRF and idempotency data and remain authoritative in the database.

Evidence boundary

Repository tests materialize the generated SQLite project and exercise both successful renderers and negative source/metadata cases. They do not prove codec support, buffering behavior, screen-reader quality, subtitle accuracy, microphone or speech recognition, physical mobile devices, CDN delivery or app store behavior. Run browser accessibility tests with your real content and deployment before making those claims.

46. Server-Authoritative Learning Activities

Interactive learning clients must never decide their own points. The complete Academy starter generates a static-dispatch ActivityEvaluator boundary that turns an untrusted submission into a server-authored ActivityResult.

Evaluate a single-choice exercise

Load the correct option, maximum score and canonical SHA-256 digest from your trusted, versioned rules. Do not accept them from an HTTP form.

This block is compiled inside the generated Academy starter, whose application-local crate::services modules provide the two imported contracts:

use crate::services::activity_contract::{
    ActivityAttempt, ActivityKind, SingleChoiceEvaluator,
    SingleChoiceSubmission, ACTIVITY_SCHEMA_VERSION, evaluate_activity,
};
use crate::services::score_service::{ScoreReceipt, record_activity_result};
use rullst_security::UserContext;

async fn grade(
    context: &UserContext,
    selected_option_id: i32,
) -> Result<ScoreReceipt, Box<dyn std::error::Error>> {
    // These three values represent data loaded from trusted server state.
    let evaluator = SingleChoiceEvaluator::new(7, 100, "a".repeat(64))?;
    let attempt = ActivityAttempt {
        schema_version: ACTIVITY_SCHEMA_VERSION,
        attempt_key: "attempt-language-1".to_string(),
        activity_id: 42,
        subject_user_id: 9,
        kind: ActivityKind::Exercise,
        ruleset_version: "portuguese-a1-v3".to_string(),
        started_at_epoch_seconds: 1_800_000_000,
        state_json: r#"{"prompt_version":3}"#.to_string(),
    };
    let validated = evaluate_activity(
        context,
        attempt,
        &SingleChoiceSubmission { selected_option_id },
        1_800_000_030,
        &evaluator,
    )?;
    Ok(record_activity_result(context, validated).await?)
}

The submission contains an option ID but no score, maximum or answer key. The contract rejects cross-owner access, activity-kind mismatch, invalid identity, non-object or oversized state, reversed time, out-of-range results and non-canonical evidence digests.

Persist one authoritative transaction

In the complete Academy starter, pass the opaque ValidatedActivityResult directly to record_activity_result. Callers cannot construct that wrapper or replace its points. The bridge loads the persisted activity and rechecks its course, kind, maximum, ruleset, season, evidence digest and exact evaluator configuration before one transaction:

1. appends a deduplicated ScoreEvent v2;
2. updates the authoritative leaderboard projection; and
3. appends the strict score_recorded v2 outbox event before commit.

The configuration is checked again under the transaction’s policy lock. A concurrent answer-policy edit therefore cannot commit a result graded against stale rules.

The complete starter also persists the bounded attempt/result in that transaction. Identical retries are no-ops; changing the selected option under the same attempt key is a conflict. The database scopes that client key by learner and activity, while the score-event key is derived server-side, so keys chosen by different learners cannot reserve one another’s attempts.

Submit through the authenticated route

The generated owner-only route is POST /activities/{id}/attempts. After your normal authenticated session and CSRF ceremony, its JSON body contains only:

{
  "attempt_key": "attempt-language-1",
  "selected_option_id": 7
}

Do not add learner ID, ruleset, answer key, points, maximum, evidence or client time to this payload. The route and persisted activity supply them. The stored bounded state_json is hidden in Nexus but is still application data: include activity_attempts in retention, export and erasure policy where applicable.

For a bounded pair-matching activity, use POST /activities/{id}/attempts/matching:

{
  "attempt_key": "attempt-match-1",
  "pairs": [
    { "left_id": 1, "right_id": 11 },
    { "left_id": 2, "right_id": 12 }
  ]
}

The persisted policy owns the complete left/right ID sets and correct mapping. The request must be a complete permutation of two to eight pairs; unknown or duplicate IDs fail closed. Input order does not affect replay identity, partial credit uses integer server scoring, and no answer text crosses this endpoint.

For typed recall, configure a closed accepted_answers array and submit to POST /activities/{id}/attempts/typed:

{
  "attempt_key": "attempt-recall-1",
  "answer": "  Ownership  "
}

The built-in evaluator caps UTF-8 input at 512 bytes, rejects control characters and trims it. When case_sensitive is false it applies Unicode lowercase before exact comparison. It does not perform NFC/NFKC normalization, accent folding, stemming or fuzzy matching; add a reviewed domain evaluator when your pedagogy requires those semantics. The durable submission key is SHA-256 over the exact policy binding plus normalized input, so the raw answer is absent from activity_attempts. A digest is not encryption and may remain personal data; retain/erase it under the same lifecycle as the attempt.

The full Academy quiz service follows the same score-event invariants but is still a separate evaluator. Do not claim generic quiz or game integration until those paths are unified and their materialized tests pass.

Implement another ActivityEvaluator when spelling needs language-specific normalization or when a listening/game exercise needs different trusted rules. Keep the concrete evaluator type visible; do not use a runtime registry merely to hide domain differences.

47. Durable Spaced-Review Queue

The complete LMS blueprint can turn newly applied authoritative activity scores into a durable due-review queue. This is useful for vocabulary, facts, concept recall and other practice that benefits from repeated exposure.

Generate the complete Academy starter

cargo rullst new language-academy --default --blueprint lms \
  --skip-initial-migration
cd language-academy
cargo test --offline --all-targets

Review scheduling belongs to the complete starter because it composes activity evaluation, score persistence, school/course authorization and enrollment. The smaller detached LMS profiles do not include this vertical.

Enable a review policy

Each reviewable activity has one activity_review_policies row. Use the generated Nexus model or application-owned parameterized administration code to configure these fields:

Malformed policy or existing state fails the score transaction closed. A different algorithm version also requires an explicit application migration; it is never silently reinterpreted.

Submit an authoritative exercise

Use one of the authenticated activity routes described in the previous tutorial:

• POST /activities/{id}/attempts for single choice;
• POST /activities/{id}/attempts/matching for bounded matching;
• POST /activities/{id}/attempts/typed for typed recall.

The route obtains identity, answer policy, points and time from server state. When the score is new, the same database transaction updates activity_review_states before it commits the score and outbox event. An exact retry is a no-op and cannot make the interval grow twice.

rullst-box-v1 applies a deliberately small inspectable transition:

• a passing result increments repetitions and schedules at least the configured first interval;
• a perfect result also raises the bounded ease value;
• later passes multiply the prior interval by that ease, capped by the policy;
• a lapse resets repetitions, increments lapses, lowers bounded ease and uses the configured lapse interval.

Read the learner’s due queue

After the normal authenticated session, request:

GET /reviews/due?limit=20

The handler derives the learner and current time from server extensions; there is no learner ID in the query. It accepts a limit from 1 through 50, checks the active school membership and returns only activities whose course scope and active enrollment still authorize the learner. Results are ordered by due time and then activity ID.

[
  {
    "activity_id": 42,
    "course_id": 3,
    "title": "Recall: ownership",
    "due_at_epoch": 1800086400,
    "repetitions": 1,
    "lapses": 0
  }
]

Render this response in the web application as the source of truth. An Omni shell can present the same web-first route, but offline proposals must still be reconciled with the server before the schedule is considered authoritative.

Product and evidence boundary

The state includes learner/activity history and must participate in retention, export and erasure policy. The generated foundation does not prove that its intervals improve learning and does not implement FSRS, SM-2, speech recognition, language-specific answer normalization, AI personalization, streaks or a polished review UI. Tune policy only with reviewed product rules and measured outcomes; use an explicit version plus migration for any new algorithm.

Repository evidence covers deterministic pass/lapse transitions and a materialized SQLite journey across single-choice, matching and typed recall, including exact replay and cross-user denial. PostgreSQL/MySQL contention, real-user efficacy, browser UX and physical Omni devices remain separate gates.

48. Signed Local OIDC Testing

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

Rullst Connect includes an explicitly mounted local identity-provider fixture so an application can exercise a cryptographically verified OIDC flow without a third-party account. Unlike an in-process provider stub, this path traverses HTTP discovery, authorization, token exchange, JWKS retrieval and ID-token verification through the ordinary OidcProvider implementation.

Enable and bind the fixture

Enable the Axum feature in development:

[dev-dependencies]
rullst-connect = { version = "12.0.0-rc.1", features = ["axum"] }

Mount the router only on an exact loopback listener:

#![allow(unused)]
fn main() {
use rullst_connect::mock_idp::{MockIdpConfig, mock_router_with_config};

async fn run() -> Result<(), Box<dyn std::error::Error>> {
let issuer = "http://127.0.0.1:8080";
let callback = "http://127.0.0.1:3000/auth/callback";
let config = MockIdpConfig::try_new(
    issuer,
    "academy-local-client",
    "academy-local-secret",
    callback,
)?;
let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
axum::serve(listener, mock_router_with_config(config)).await?;
Ok(())
}
}

MockIdpConfig rejects non-HTTP or non-loopback issuers and callbacks, issuer paths, empty/oversized identifiers and control characters. The application must still bind the actual listener to loopback; possession of a router does not control how the host serves it.

Configure the ordinary OIDC client

Use non-placeholder local credentials so OidcProvider traverses the HTTP fixture instead of selecting the separate network-free credential fallback:

#![allow(unused)]
fn main() {
use rullst_connect::providers::OidcProvider;

async fn provider() -> Result<OidcProvider, rullst_connect::ConnectError> {
OidcProvider::discover(
    "http://127.0.0.1:8080",
    "academy-local-client",
    "academy-local-secret",
    "http://127.0.0.1:3000/auth/callback",
).await
}
}

Compose this provider with the server-bound session ceremony from Tutorial 42. That ceremony generates and stores state, PKCE verifier and OIDC nonce; the fixture binds the challenge and nonce to its one-shot authorization grant. The callback then supplies the consumed values to OidcProvider::get_user.

What the test proves

The checked-in loopback regression proves that the current client can:

• validate discovery metadata on the exact issuer origin;
• preserve an exact registered client and callback;
• exchange one expiring authorization code only once;
• reject a missing, malformed or mismatched S256 PKCE verifier;
• bind the requested nonce into a signed ID token;
• select the Ed25519 public key by kid from JWKS;
• validate EdDSA signature, issuer, audience, expiry and nonce; and
• accept only an issued, unexpired bearer token at userinfo.

Authorization grants and access-token digests are process-local and capped at 64 records. A restart erases them. This is intentional test behavior, not a durable identity service.

Non-production boundary

The signing seed, client credentials and identity are deterministic public fixtures. The router has no interactive login, consent, refresh-token, device, federation, account-management, key-rotation or administrative lifecycle. It has not passed an OIDC conformance suite. Never expose it publicly, reuse its key or credentials, or use a successful fixture test as evidence that a live provider/deployment is correctly configured.

49. Bounded Brokered Messaging

Important

Dependency examples use 12.0.0-rc.1, the planned first v12 RC. Do not request it from crates.io before it is published; use path dependencies from this source checkout during development.

This tutorial starts with rullst-messaging’s deterministic in-memory broker and then switches the same trait contract to the durable local SQLite adapter. Remote broker protocols remain separate adapters.

1. Enable the umbrella feature

[dependencies]
rullst = { version = "12.0.0-rc.1", features = ["messaging"] }

Use messaging-sqlite instead of messaging for durable local state. A direct dependency uses rullst-messaging = { version = "12.0.0-rc.1", features = ["sqlite"] }.

2. Create a bounded broker

#![allow(unused)]
fn main() {
use rullst::messaging::{BrokerConfig, InMemoryBroker};

fn create_broker() -> Result<(), rullst::messaging::MessagingError> {
let config = BrokerConfig::try_new("billing")?
    .with_limits(
        10_000,        // retained messages
        128,           // consumer-group subscriptions
        5,             // delivery attempts
        1024 * 1024,   // payload bytes
    )?;
let broker = InMemoryBroker::new(config);
let _ = broker;
Ok(())
}
}

The hard ceilings prevent an accidental configuration from turning the local broker into unbounded memory state. Capacity exhaustion fails closed until terminal messages are explicitly purged.

Persist the same contract locally

#![allow(unused)]
fn main() {
use rullst::messaging::{BrokerConfig, SqliteBroker};

async fn open() -> Result<(), rullst::messaging::MessagingError> {
let config = BrokerConfig::try_new("billing")?
    .with_limits(10_000, 128, 5, 1024 * 1024)?;
let broker = SqliteBroker::connect("sqlite://storage/messages.sqlite", config).await?;
let _ = broker;
Ok(())
}
}

All mutations use serialized SQLite write transactions. A committed publish or ACK survives restart, while an uncommitted operation rolls back. In-flight leases also survive; after expiry the next broker operation requeues or dead-letters them. Multiple processes may share one file and namespace, but reopening it with different limits is rejected. This is local durability, not network replication, automatic failover or exactly-once side effects.

Protect header values and payloads

SqliteBroker::connect deliberately retains the compatible plaintext profile. For a new namespace/database, load a 32-byte high-entropy key from a secret manager and select the encrypted profile explicitly:

#![allow(unused)]
fn main() {
use rullst::messaging::{
    BrokerConfig, MessagingKeyring, MessagingStorageKey, SqliteBroker,
};

async fn open_encrypted(
    secret_manager_key: [u8; 32],
) -> Result<(), rullst::messaging::MessagingError> {
let primary = MessagingStorageKey::try_new("messages-2026-09", secret_manager_key)?;
let keyring = MessagingKeyring::new(primary);
let broker = SqliteBroker::connect_encrypted(
    "sqlite://storage/messages.sqlite",
    BrokerConfig::try_new("billing")?,
    keyring,
).await?;
let _ = broker;
Ok(())
}
}

To rotate, put the new primary first and append the old decryption key:

#![allow(unused)]
fn main() {
use rullst::messaging::{MessagingKeyring, MessagingStorageKey};

fn rotate(new_key: [u8; 32], old_key: [u8; 32])
    -> Result<MessagingKeyring, rullst::messaging::MessagingError> {
let keys = MessagingKeyring::new(MessagingStorageKey::try_new(
    "messages-2026-10",
    new_key,
)?)
.with_decryption_key(MessagingStorageKey::try_new(
    "messages-2026-09",
    old_key,
)?)?;
Ok(keys)
}
}

New publications use the primary. Old records are not silently rewritten and their keys remain mandatory until those messages become terminal and are purged. Plaintext/encrypted profiles cannot be mixed or changed in place; move through a new namespace/database with an application-reviewed republish procedure. Passwords are not AES keys, and source literals are unsuitable for production key custody.

The encrypted profile protects header values and payloads. Topic, event and content type, message/key IDs, timestamps, idempotency key, fingerprint and delivery state remain visible metadata. Protect the database file and backups, control rollback, rehearse key recovery and authorize topic access separately.

3. Register a consumer group and publish

#![allow(unused)]
fn main() {
use rullst::messaging::{
    MessageBroker, PublishRequest, StartPosition, SubscriptionRequest, TraceContext,
};

async fn example(
    broker: &rullst::messaging::InMemoryBroker,
) -> Result<(), rullst::messaging::MessagingError> {
broker
    .subscribe(SubscriptionRequest::try_new(
        "invoices",
        "receipt-mailers",
        StartPosition::Earliest,
    )?)
    .await?;

let trace = TraceContext::try_with_state(
    "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "vendor=value",
)?;
let request = PublishRequest::try_new(
    "invoices",
    "invoice.paid",
    "invoice/2026-0042/paid/v1",
    br#"{"invoice_id":"2026-0042"}"#.to_vec(),
)?
.with_content_type("application/json")?
.with_trace_context(&trace)?;

let first = broker.publish(request.clone()).await?;
let replay = broker.publish(request).await?;
assert_eq!(first.id(), replay.id());
assert!(replay.is_duplicate());
Ok(())
}
}

Idempotency is scoped to the topic. The same topic/key with different content returns MessagingError::IdempotencyConflict; it never silently overwrites the original publication.

Only validated W3C version-00 traceparent and a conservative tracestate subset are copied. baggage is deliberately excluded because arbitrary application metadata may contain credentials or personal data. Sampling, export, retention and tenant-aware correlation remain host responsibilities.

4. Receive, acknowledge, retry, or dead-letter

#![allow(unused)]
fn main() {
use rullst::messaging::{
    FailureCode, MessageBroker, ReceiveRequest, RetryDisposition,
};
use std::time::Duration;

async fn consume(
    broker: &rullst::messaging::InMemoryBroker,
) -> Result<(), rullst::messaging::MessagingError> {
let request = ReceiveRequest::try_new(
    "invoices",
    "receipt-mailers",
    "worker-1",
    10,
    Duration::from_secs(30),
)?;

for delivery in broker.receive(request).await? {
    let effect_succeeded = true;
    if effect_succeeded {
        broker.ack(delivery.ack_token()).await?;
    } else {
        let disposition = broker
            .retry(
                delivery.ack_token(),
                Duration::from_secs(15),
                FailureCode::try_new("mail.transient")?,
            )
            .await?;
        if disposition == RetryDisposition::DeadLettered {
            // Alert through an application-owned operational channel.
        }
    }
}
Ok(())
}
}

If an adapter needs a stable broker-neutral representation, encode the received envelope explicitly:

#![allow(unused)]
fn main() {
use rullst::messaging::{BrokerConfig, MessageEnvelope, WireEnvelopeCodec};

fn frame(
    envelope: &MessageEnvelope,
) -> Result<(), rullst::messaging::MessagingError> {
let config = BrokerConfig::try_new("billing")?;
let bytes = WireEnvelopeCodec::encode(envelope, &config)?;
let decoded = WireEnvelopeCodec::decode(&bytes, &config)?;
assert_eq!(&decoded, envelope);
Ok(())
}
}

The v1 frame is canonical, bounded by BrokerConfig, namespace-bound and rejects unknown versions, truncation, trailing bytes and non-canonical fields. It carries an accepted envelope only. It does not retain the caller’s publish idempotency key, connect to a broker, or map remote ACK/retention semantics, so it cannot be presented as a Kafka/NATS/RabbitMQ adapter by itself.

An ACK token is an opaque, single-use capability bound to one group and one lease. Once it expires, the message is requeued or dead-lettered at the attempt ceiling. Do not serialize tokens into logs or application records.

5. Design for at-least-once delivery

The consumer may complete the mail/payment/webhook effect and stop before the ACK reaches the broker. Therefore:

1. use delivery.envelope().id() as a stable deduplication key;
2. claim that key transactionally in the side-effect system where possible;
3. ACK only after the effect is durably accepted;
4. treat retries and dead letters as normal operational states;
5. authorize topics and tenant scope in the host application.

The in-memory broker loses state on process exit. The SQLite adapter retains state; its default profile is plaintext, while the explicit encrypted profile protects header values and payloads but not routing/idempotency metadata. The host owns key custody, file permissions, protected backup/restore, rollback detection, retention, disk monitoring and topic/tenant authorization. A future remote adapter is supported only after it passes the shared contract plus its own protocol, restart, and fault matrix; an adapter name alone is not durability evidence.

6. Relay a relational outbox after commit

Enable messaging-orm-outbox on the umbrella crate. Commit the domain mutation and rullst_orm::Outbox::enqueue together as described in the transactional outbox tutorial. Then bind one exact outbox stream to one broker topic:

#![allow(unused)]
fn main() {
use rullst::messaging::{
    InMemoryBroker, MessagingError, OrmOutboxRelay,
};

fn configure_relay(
    broker: InMemoryBroker,
) -> Result<OrmOutboxRelay<InMemoryBroker>, MessagingError> {
    OrmOutboxRelay::try_new("tenant-a", "domain-events", broker)
}
}

A supervised worker claims and relays one event:

#![allow(unused)]
fn main() {
use rullst::messaging::{InMemoryBroker, OrmOutboxRelay};
use rullst_orm::Outbox;

async fn relay_one(relay: &OrmOutboxRelay<InMemoryBroker>) {
    let claim = match Outbox::claim_next("tenant-a", "worker-a", 30, 8).await {
        Ok(Some(claim)) => claim,
        Ok(None) | Err(_) => return,
    };
    match relay.relay_and_ack(claim).await {
        Ok(receipt) if !receipt.outbox_acknowledged() => {
            // The lease expired; a later claim will replay the same event key.
        }
        Ok(_) => {}
        Err(error) => {
            // Record a secret-free operational failure and let the lease expire.
            let _accepted_before_ack_failure = error.accepted_publication();
        }
    }
}
}

The ordering is intentionally publish then ACK. A stop in between causes a new ORM claim to publish the same event key and content; the broker returns its original ID as a duplicate. This is at-least-once relay with bounded idempotency, not an atomic transaction across two systems. Keep the worker supervised and make the final consumer idempotent too.

Auditable Revisions

Rullst SQLx models can bind each instance mutation to a validated principal and restore eligible update revisions as a new compensating mutation. The audit row and model write share a transaction; an audit failure rejects the write.

This contract is opt-in and does not infer identity from request data. Install the principal and tenant contexts only after your authentication and authorization boundary has validated them.

1. Mark the model and install the table

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Debug, Clone, FromRow, rullst_orm::Orm)]
#[orm(table = "projects", auditable, tenant_column = "account_id")]
struct Project {
    id: i32,
    account_id: String,
    name: String,
    #[orm(masked)]
    api_token: String,
}

async fn install() -> Result<(), rullst_orm::Error> {
rullst_orm::audit::create_audit_table().await?;
Ok(())
}
}

create_audit_table also adds the v2 columns to the legacy audit table. Legacy records retain version 1 and cannot be restored.

Fields whose names contain password, token, secret, API key, credential, cookie or similar markers must use #[orm(masked)] on auditable models. Their values are never retained in audit payloads or reverse patches.

2. Bind a mutation to trusted context

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, rullst_orm::Orm)]
#[orm(table = "projects", auditable, tenant_column = "account_id")]
struct Project { id: i32, account_id: String, name: String, #[orm(masked)] api_token: String }
use rullst_orm::audit::{AuditContext, with_audit_context};
use rullst_orm::with_tenant;

async fn update(mut project: Project) -> Result<(), rullst_orm::Error> {
let audit = AuditContext::user("user-42")?
    .with_correlation_id("request-01J...")?;

with_tenant("account-a", with_audit_context(audit, async move {
    project.name = "New name".to_string();
    project.save().await
}))
.await?;
Ok(())
}
}

Background work can use AuditContext::service("billing-worker"); reviewed maintenance can use AuditContext::system("migration-2026-08"). Empty, padded, control-character, and oversized identifiers fail validation. An auditable mutation without an active context also fails closed.

3. Restore an eligible update

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};
#[derive(Debug, Clone, FromRow, rullst_orm::Orm)]
#[orm(table = "projects", auditable, tenant_column = "account_id")]
struct Project { id: i32, account_id: String, name: String, #[orm(masked)] api_token: String }
use rullst_orm::audit::{AuditContext, with_audit_context};
use rullst_orm::with_tenant;
async fn restore(project: Project, audit_id: i32) -> Result<Project, rullst_orm::Error> {
let actor = AuditContext::user("admin-7")?
    .with_correlation_id("support-case-1042")?;

let restored = with_tenant("account-a", with_audit_context(actor, async move {
    project
        .restore_revision(audit_id, "approved support rollback")
        .await
}))
.await?;
Ok(restored)
}
}

The returned model contains the restored state. Rullst verifies the exact model, ID, active tenant, patch version and current post-state before writing. PostgreSQL and MySQL/MariaDB lock the row during this check. Success creates a new updated audit entry with reverted_audit_id and the bounded reason; audit history is not rewritten or deleted.

Use restore_revision_with_tx when a caller-owned SQLx transaction must include other relational writes. Prefer Orm::transaction when generated post-commit observers must wait for the final commit decision.

Deliberate refusal cases

Restoration fails for:

• legacy v1, create, or delete entries;
• a revision from another model, record, or tenant;
• a row changed again after the selected revision;
• a patch containing a redacted/sensitive change;
• malformed, empty, too deep, too large, or excessively wide patches.

Those refusals prevent audit history from becoming an unsafe generic backup mechanism. Use reviewed database backups and restore drills for disaster recovery. Bulk update/delete builders do not invent per-row audit history, and cross-process export or notification should use the transactional outbox.

Supervised Development Auto-Reload

Release-audit follow-up: the implementation and final workspace validation are still in progress. See the audit evidence; this tutorial is not a claim that the current branch is already release-ready.

Rullst v12’s development command rebuilds and restarts a directly linked application. This keeps Tokio, ORM pools, sessions and other process globals in one runtime. It replaces the advertised DLL-swap profile after Windows/LMS testing exposed an uninitialized ORM in the loaded library.

Run the development loop

Generate a normal application and use either development command:

cargo rullst new learning-app --default --blueprint blank \
  --database sqlite --skip-initial-migration
cd learning-app
cargo rullst dev
# Or, in an interactive terminal:
cargo rullst dash

There is no hot-reload question in the v12 wizard. Both commands supervise reloads automatically; use cargo run for ordinary execution.

What a save does

flowchart LR
    A[Save source or assets] --> B[Coalesce changes]
    B --> C[Compile executable]
    C -->|Failure| D[Keep current application and show diagnostic]
    C -->|Success| E[Snapshot new executable]
    E -->|Failure| D
    E -->|Success| F[Stop owned child and start replacement]
    F --> G[Verify process generation over HTTP]
    G --> H[Browser refresh]

The watcher observes source, static assets, templates and manifest/configuration files, including atomic editor renames. It excludes build outputs, Git data and runtime database/log files. Events while a build is running remain pending for a later rebuild. Saving CSS also triggers this conservative rebuild/restart path; no compilation-free claim is made.

Initial migrations run before the first start when the generated migration directory exists. Later migrations are explicit: use the dashboard migration action or cargo rullst db:migrate. The dashboard queues migrations through the supervisor, using its current executable snapshot with bounded output and cancellation cleanup; the action is serialized with rebuilds. It does not compile an unsaved or unbuilt migration into that snapshot. Restarting a process does not apply arbitrary database-schema changes safely.

Failure and state boundaries

The old binary is copied before execution so Windows does not lock Cargo’s output during the next build. Cleanup targets only the snapshot created by this supervisor. On Unix the child receives a two-second shutdown interval, followed by termination of its owned process group if needed; group cleanup precedes reaping the leader. Windows uses best-effort tree termination: without Job Objects it cannot guarantee cleanup of orphan descendants after their parent has exited, and it does not promise graceful request drain.

All process-local state resets, including in-memory sessions/queues/caches. Persist important state explicitly. In-flight requests may be interrupted. This is a local development loop, not zero-downtime production deployment.

Browser and security boundary

The debug/development server serves a local reload script and an opaque generation marker under /_rullst/dev-*. The script polls the same origin and refreshes only after a different valid generation responds. Readiness checks match the child generation rather than trusting any service on the port. The marker is not a secret or an authentication credential. These endpoints cannot instruct the server to compile, launch a process, or swap a library.

Eligible full-document, known-size, uncompressed HTML up to 10 MiB receives the script and a nonce seeded before inner header middleware. HTMX partial requests, streaming/larger/compressed responses pass through without injection. A browser singleton prevents duplicate pollers, and changed HTML is marked no-store. Polling has a request timeout and bounded retry delay. Browser refresh loses unsaved DOM-only state. Custom routers that do not use the Rullst Server development composition may need manual browser refresh.

Production/release builds do not mount this browser surface. Keep development servers on loopback and do not override their host for an untrusted network. The current supervisor probes 127.0.0.1 and the configured port; custom HOST or RULLST_HOST bindings, including IPv6-only loopback, are not equivalent verified-readiness configurations. Keep the default host and restart the CLI after changing its port configuration.

Existing DLL scaffolds and the v13 decision

The v12 CLI rejects the old --hot-reload generation flag and removes HOT_RELOAD when it launches a child, so old generated projects use their directly linked router unless their application reloads that variable itself. Remove legacy HOT_RELOAD entries from .env as well: application-owned dotenv loading can otherwise restore them. Regenerate fresh projects for release acceptance; already edited application code may need application-specific migration.

The existing library loader is retained only as a legacy experimental boundary. Passing Rust, Axum, Tokio or SQLx objects across a library ABI does not provide a stable interoperability contract. Do not reintroduce cross-library ORM pools.

For v13, compare supervised restart with any proposed replacement using real blueprints and databases on Windows, Linux and macOS. Measure cold/warm reload time, failed-build recovery, cancellation, memory growth, process cleanup and state ownership. Restore DLL swapping only if its safety requirements can be established and it offers a measured practical benefit; keeping supervised restart remains a valid v13 outcome.

Terminal accessibility

Use RULLST_REDUCED_MOTION=1 cargo rullst dash for static rendering with colors, or NO_COLOR=1 cargo rullst dash for static color-free output. Use cargo rullst dev with redirected/non-interactive output.

Tutorial 52: Typed Server Functions

#[server_function] lets one concrete async Rust signature describe both the native server implementation and its Wasm caller. The transport is explicit: the macro also creates a <function>_rpc_router() that you mount in the server. It does not discover routes through runtime reflection.

use rullst::{Router, server_function};
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize)]
pub struct SumResponse {
    pub value: u32,
}

#[server_function(path = "/api/rpc/math/add")]
pub async fn add(left: u32, right: u32) -> rullst::rpc::RpcResult<SumResponse> {
    Ok(SumResponse {
        value: left.saturating_add(right),
    })
}

pub fn rpc_routes() -> Router {
    add_rpc_router()
}

fn main() {
    let _router = rpc_routes();
}

When this function is compiled for the native server, its written body runs. When compiled for wasm32, calling add(20, 22).await serializes (20, 22) and returns the decoded RpcResult<SumResponse>. Transport failures are machine-readable RpcFailure values; they never become a fabricated default application value.

Mount the generated route inside server policy

Merge the generated router before applying the standard security baseline and your domain layers:

use rullst::{Router, server_function};
use serde::{Deserialize, Serialize};
#[derive(Deserialize, Serialize)]
pub struct SumResponse { pub value: u32 }
#[server_function(path = "/api/rpc/math/add")]
pub async fn add(left: u32, right: u32) -> rullst::rpc::RpcResult<SumResponse> {
    Ok(SumResponse { value: left.saturating_add(right) })
}
fn secured_transport() -> Result<axum::Router, rullst::SecurityBaselineError> {
    let app = Router::new()
        .merge_axum(add_rpc_router().into_axum())
        .into_axum();

    rullst::apply_security_baseline(
        app,
        rullst::SecurityConfig::default(),
        rullst::config::Environment::Production,
    )
}

fn main() -> Result<(), rullst::SecurityBaselineError> {
    let _app = secured_transport()?;
    Ok(())
}

The production baseline verifies the double-submit CSRF cookie/header pair. The Wasm caller reads the bounded rullst_csrf cookie and forwards it as X-CSRF-Token. The application must still add session/authentication, trusted tenant resolution, object/role authorization and rate limiting in the order documented by ProductionPreset. Never accept role, owner or tenant authority from a function argument.

Failure codes

Application failures use the same lowercase dotted-code grammar as the shared client contract:

#![allow(unused)]
fn main() {
fn capacity_failure() -> Result<rullst::rpc::RpcFailure, rullst::client_contract::ClientContractError> {
    rullst::rpc::RpcFailure::application("course.capacity_reached", false)
}

let failure = capacity_failure()?;
assert_eq!(failure.code(), "course.capacity_reached");
Ok::<(), rullst::client_contract::ClientContractError>(())
}

Do not place provider bodies, database errors, PII, tokens or debug text in a failure code. Log sensitive diagnostics only through an approved server-side telemetry policy.

Exact v12 limits

• zero to 16 simple identifier parameters;
• owned parameter types and one owned output type implementing the needed Serde traits;
• a concrete async free function with no generics, receiver, unsafe, extern ABI or variadic arguments;
• rullst::rpc::RpcResult<T> as the return type;
• an optional same-origin path below /api/rpc/, using at most 128 ASCII bytes;
• 256 KiB encoded request and response policy;
• JSON POST transport with a versioned envelope and request-ID correlation.

These bounds do not make a mutation exactly once. Put a stable idempotency key in the domain payload and enforce it transactionally on the server when replay would be harmful. Actual browser-engine compatibility, network availability and deployed identity policy must be tested by the application.

Rullst Specification 📄

“The Single Source of Truth (SST) for Framework Architecture & Conventions”

This document is the Single Source of Truth (SST) for the Rullst Framework. It specifies the exact conventions, API structures, naming rules, directory standards, and subsystem maturity lifecycles across all monorepo crates.

Important

AI & Human Alignment Directive: Whenever updating, refactoring, or generating code/documentation for Rullst, always refer to this specification as the baseline. Every capability in the framework is strictly tagged with its implementation lifecycle status:

• 🟢 [Implemented / Bounded]: A defined implementation exists with automated tests for the stated scope. This is not a deployment, provider-homologation, or certification claim.
• 🟠 [Partial]: Useful foundations exist, but a named interoperability, architecture, or conformance boundary is still incomplete.
• 🟡 [Offline Test Mock / Simulador Dev]: Deterministic offline sandbox fixtures for local development and offline CI without external API dependencies.
• 🔵 [Roadmap / Em Construção]: Architectural design, public traits, and domain models specified in full, with production drivers in active engineering.

📂 1. Directory Structure Conventions

A standard Rullst application scaffold strictly adheres to this folder hierarchy:

my-app/
├── src/
│   ├── controllers/      # Route controllers (async request handlers)
│   │   └── mod.rs
│   ├── models/           # Active Record & Repository Models (rullst-orm entities)
│   │   └── mod.rs
│   ├── pages/            # Shared HTML views, templates, and layouts
│   │   └── mod.rs
│   ├── middlewares/      # Custom application middleware layers
│   │   └── mod.rs
│   └── main.rs           # Application entrypoint, server bootstrap & central routing
├── Cargo.toml            # Project cargo dependencies
└── Rullst.toml           # Framework configuration (database, environment, secrets)

🛠️ 2. Naming Conventions

To guarantee consistency, both humans and AI coders must adhere to the following naming normalization rules:

• File Names: Standard Rust snake_case (e.g. users_controller.rs, post_model.rs, billing_service.rs).
• Struct / Model / Trait Names: Standard PascalCase (e.g. UsersController, PostModel, PaymentProvider).
• URL Paths: Lowercase kebab-case (e.g. /users, /user-profiles, /billing/webhooks).
• Database Identifiers: Snake case (e.g. user_id, created_at, billing_accounts).

⚡ 3. Framework Crates & Capability Matrix

v12 audit correction invariants

The current release audit reopens earlier readiness claims. A historical score, checked roadmap item or green mainline run is not evidence that the current revision satisfies these contracts.

• Generated safe ORM projections validate column identifiers. Empty membership predicates match nothing. Mandatory tenant, global and soft-delete scopes remain grouped outside application OR expressions; nested queries preserve validation errors. Bulk mutation must not bypass model authorization.
• Queries inside a managed transaction use its executor. Callbacks that already borrow a mutation executor must fail explicitly on unsupported reentrant ORM access rather than deadlock or silently use an unrelated connection.
• Local durable stores use SQLx-owned transactions so dropping a cancelled operation schedules rollback. A cancellation racing an already dispatched commit can still have an uncertain outcome and requires reconciliation.
• Authentication validates expiry independently of clock-skew allowances; provider-specific identity claims, nonce and refresh semantics cannot be replaced by successful offline fixtures.
• Payment adapters must not fabricate live checkout prices, portal URLs or mutation success. Unsupported provider operations fail explicitly. Signed webhook bytes still require provider-specific schema and lifecycle validation.
• Development restart owns builds, application snapshots and migrations. It is not a stable Rust DLL ABI or production rolling-deployment mechanism. Windows descendant cleanup remains best effort without a Job Object implementation.

These describe required behavior, not a declaration that every final release gate has passed. The audit records the current evidence and remaining work.

Pre-release scaffold source invariant

An unpublished pre-release cargo-rullst may reuse only local framework crates whose package names and versions exactly match that CLI. The invocation directory is preferred; otherwise the exact still-present checkout from which the CLI was compiled is used. Stable or version-mismatched packages fall back to crates.io. This permits evaluation outside the repository without silently mixing release trains, but generated absolute path dependencies remain non-portable until the matching immutable release is published.

Shared-local facade composition invariant

The umbrella features auth-sqlite, capital-quota-sql, oauth-sqlite, mail-sqlite, messaging-sqlite, and queue-sqlite may deliberately share one file-backed SQLite database for a bounded single-host deployment. Each subsystem owns a fixed, distinct table namespace. The host prepares and checks every store sequentially and keeps ApplicationLifecycle unready until all required components have succeeded. Restart must reuse the same validated database URL, quotas, namespaces, and encryption keys; all handles must close before a host copies, restores, or replaces the file.

The executable facade contract proves persistence and idempotent replay across restart, encrypted token/message plaintext absence from the database/WAL/SHM, queue recovery, aggregate readiness, and fail-closed token corruption without breaking an unrelated mail read. It does not create a cross-subsystem transaction, consistent online backup, key manager, distributed database, or multi-host coordination. Whole-file snapshot consistency, filesystem trust, permissions, key/backup operations, contention policy, and recovery drills are host responsibilities. Separate databases remain preferable where failure isolation or write throughput matters.

Native relational enum invariant

rullst-orm has one bounded native-enum contract. #[derive(Enum)] generates a closed label set shared by Display, parsing, Serde, RullstValue and SQLx codecs. A database enum has 1–64 unique labels; its type identifier and labels use the documented bounded ASCII allowlists. Blueprint::native_enum emits:

• a named PostgreSQL enum with exact existing-label drift detection only under strict-postgres;
• an inline ENUM for MySQL/MariaDB; and
• a TEXT CHECK constraint for SQLite.

PostgreSQL through SQLx Any must fail before DDL because that driver cannot decode custom PostgreSQL types. Adding, removing or reordering variants, deployment order, dependent-object removal and rollback remain explicit, reviewed migration work. The schema helper does not auto-migrate an existing type or infer application compatibility.

The Capital row also includes one implemented, feature-gated quota boundary: BillingSubject binds a shared team/workspace counter to trusted tenant state, Billable::quota_request derives the limit from the subscription owner, and QuotaStore atomically reserves idempotent units before resource creation. The deterministic local store is always available; quota-sql uses fixed-schema SQLx transactions on SQLite/PostgreSQL/MySQL/MariaDB, with exact replay/release and a caller-owned transaction path for atomic domain writes. Live container contracts exercise all four protocols. Membership establishment, plan state, migrations, reconciliation and non-relational adapters remain application boundaries.

3.1. Generated Academy activity boundary

The generated ActivityEvaluator boundary uses static dispatch and accepts an untrusted submission, never client-supplied points. It validates authenticated ownership, activity/ruleset identity, bounded object-shaped state, server-time ordering and a canonical evidence digest, then constructs ActivityResult from the evaluator’s outcome. Built-in bounded evaluators cover single-choice, a complete permutation of at most eight matching pairs and typed recall with a closed answer set, 512-byte/control-character boundary, trim and optional Unicode lowercase comparison. Typed replay persists a policy-bound SHA-256 digest rather than raw input; it does not perform Unicode normalization, accent/fuzzy matching or make the digest non-personal data. The complete Academy starter’s record_activity_result rechecks the authenticated actor, loads course/kind/maximum/ruleset/season and the canonical evidence digest and exact evaluator configuration from persisted activity state, rejects any divergence, then atomically appends an exact-replay activity-attempt record, ScoreEvent v2, the leaderboard update and score_recorded. The generated owner-only POST /activities/{id}/attempts accepts only an idempotency key and selected option. POST /activities/{id}/attempts/matching accepts only an idempotency key and bounded pair IDs, while POST /activities/{id}/attempts/typed accepts the key and bounded learner text. All derive learner/activity identity, policy, answers, points, evidence and time from authenticated/server state. Durable attempt identity is scoped by learner and activity, and the event idempotency key is derived by the server rather than trusted as a global client namespace. The application must keep evaluator answer rules in trusted state and include retained attempt state in its privacy lifecycle. Listening/game evaluators and unification with the separately persisted quiz evaluator remain roadmap work.

Activities may opt into the exact rullst-box-v1 review policy. For a newly applied score, the score transaction locks and validates that versioned policy, loads the learner/activity review state, applies a deterministic bounded pass/lapse transition and upserts the next due time before commit. An exact activity replay exits before this transition and therefore cannot advance the schedule. The owner-only GET /reviews/due derives the learner and current time from server state and returns at most 50 due activities after rechecking active school membership, course scope and enrollment. Invalid policy/state or a changed algorithm version fails the score transaction closed. This is a simple inspectable scheduling foundation, not FSRS/SM-2 compatibility, efficacy proof, AI personalization, generated pedagogy or a complete adaptive-learning system; PostgreSQL/MySQL contention evidence also remains open.

⚡ 4. Core API Specifications (rullst-core)

rullst-core provides the runtime kernel. Database and queue drivers are modular and feature-gated.

4.1. Server & Routing (rullst::routing)

• Routing Macro: Central declarative routing declared via the routes! macro wrapping Axum routing handlers:

  #![allow(unused)]
  fn main() {
  use rullst::{response::Html, routes};
  
  async fn home() -> Html<&'static str> {
      Html("Home")
  }
  
  async fn posts_index() -> Html<&'static str> {
      Html("Posts")
  }
  
  let router = routes![
      get("/" => home),
      get("/posts" => posts_index),
  ];
  }

• Server Lifecycle & Graceful Shutdown:

  #![allow(unused)]
  fn main() {
  use rullst::{Server, routes};
  
  async fn serve() -> Result<(), rullst::server::ServerError> {
      let router = routes![get("/" => || async { "OK" })];
      Server::new(router).run(3000).await
  }
  }

  ApplicationLifecycle is the opt-in orchestration contract behind a lifecycle-aware server. Its phase is monotonic, its immutable registry has at most 32 validated required-component labels, and request admission requires both Ready and every component bit. Exact GET/HEAD health probes bypass admission so /ready can return a bounded 503 during startup, dependency failure or drain while /health stays process-only. The JSON reports counts, not labels or dependency errors. Server::run_with_shutdown accepts a caller-owned future; when it resolves, the lifecycle changes to draining before Axum waits for accepted requests and then becomes stopped. Dependency checks/timeouts, component updates, replica consensus, load-balancer timing, authorization and the deployment termination deadline remain host contracts.
• Default Dynamic Cache Boundary: headers_middleware supplies Cache-Control: no-store only when the handler has not already selected an explicit cache policy. Versioned public/static responses can therefore opt into reviewed caching without weakening the default for dynamic data.
• Double-Submit Form Contract: csrf_middleware installs the exact request-scoped CsrfToken used by the CSRF cookie on eligible safe requests and preserves it after a valid state-changing request. Server-rendered forms must echo that value in _token; HTMX/JavaScript may instead send it through X-CSRF-Token. The cookie intentionally remains script-readable and must not be confused with an authentication or session cookie.

4.2. Server-Side Rendering (rullst::macros)

• Macro: html! expands supported HTML trees into ordinary Rust String construction at compile time.
• XSS Protection: Dynamic display values in the supported {expr} syntax are HTML-escaped by the generated code.
• Raw Unescaped HTML: Explicitly bypassed using the wrapper rullst::html::RawHtml(String).
• Example:

  #![allow(unused)]
  fn main() {
  use rullst::html;
  
  let username = "<script>alert('xss')</script>";
  let rendered = html! {
      <div class="user-badge">
          <span>"User: "{username}</span>
      </div>
  };
  // Automatically escapes to: &lt;script&gt;alert('xss')&lt;/script&gt;
  }

4.3. Durable Queue Timing and Completion History

• SQLite and Redis persist dispatch_at for at most 366 days and never claim a job before its stored millisecond due time. Execution remains poll-dependent and at-least-once.
• Successful SQLite jobs are deleted by default. The explicit Queue::sqlite_with_completed_history constructor validates a 1–100,000 row limit, changes a processing row to completed, and prunes excess history in the same transaction.
• Queue::purge_completed_history removes those opt-in retained successes. Rows contain the original payload, so Studio access, data minimization and retention policy remain host responsibilities. Redis/custom drivers expose inspection or history only when their capability implements it.

🗄️ 5. Active Record ORM & Schema Engine (rullst-orm)

5.1. Model Definition & CRUD

#![allow(unused)]
fn main() {
use rullst_orm::{FromRow, Orm};

#[derive(Debug, Clone, FromRow, Orm)]
#[orm(table = "users")]
pub struct User {
    pub id: i32,
    pub name: String,
    pub email: String,
    #[orm(encrypted)]
    pub secret_token: Option<String>,
}

async fn use_users() -> Result<(), rullst_orm::Error> {
// Queries (after `Orm::init(...)` and schema migration at startup).
let all_users: Vec<User> = User::all().await?;
let user: Option<User> = User::find(1).await?;

// Mutations
let mut new_user = User { id: 0, name: "Alice".into(), email: "alice@example.com".into(), secret_token: None };
new_user.save().await?; // Auto-executes parameterized INSERT or UPDATE
new_user.delete().await?;
let _ = (all_users, user);
Ok(())
}
}

The Orm derive grammar is fail-closed. Model and field attributes are parsed as structured nested metadata; unknown or duplicate options are compile errors. Every SQLx model requires a persisted named id field. Explicit table/column/relation identifiers use the 1–64 byte portable ASCII identifier grammar, and declared hook, scope, policy, relation-model, tenant, soft-delete, and embedding references are validated before code generation. A relation field accepts exactly one relation declaration; options that do not apply to that relation fail compilation. belongs_to_many requires pivot_table and defaults omitted owner/related pivot keys from the two model names.

Only skip, default, json, and json(nullable) from SQLx field metadata are compatible with generated ORM persistence in v12. rename, try_from, flatten, and unknown SQLx options fail compilation instead of letting the decoded shape drift from generated SQL. Soft-delete sentinel expressions are bounded compile-time SQL fragments, not parameterized runtime values: they are capped at 128 bytes and reject statement separators, NUL, and SQL comments, while portability and semantic review remain the model author’s responsibility.

5.2. Parameterized Queries & Privacy

• Values accepted by non-raw query APIs use SQLx parameterization. Structural identifiers use the bounded ASCII grammar. pgvector helpers bind canonical vector/distance strings after rejecting empty/non-finite vectors and invalid distances; they do not interpolate those runtime values. Methods explicitly suffixed/named raw remain caller-owned escape hatches rather than an injection-safety claim.
• Generated builders assemble bindings by emitted clause position (CTE, JOIN, WHERE/HAVING, ORDER BY), not by the order in which fluent methods were called. Nested typed subqueries export that ordered binding sequence.
• Generated magic filters bind supported primitive fields to their Rust type at compile time (String, i32, f64, and bool), and generated column enums make unknown columns unrepresentable on typed paths. String-column builders, custom RullstValue conversions and raw SQL are explicit runtime-checked or caller-owned alternatives, not compile-time schema verification.
• String and Option<String> fields annotated with #[orm(encrypted)] are encrypted before generated ORM writes and decrypted after generated model reads using AES-256-GCM. Randomized ciphertext cannot be filtered, ordered, grouped, or explicitly selected by generated query-builder methods; use a separately reviewed blind index when equality lookup is required. Raw SQL remains an explicit, non-transparent escape hatch.

5.3. Generated Relationship Contract

• SQLx models may declare morph_many, morph_one, and one or more explicit typed morph_to targets. A polymorphic relation requires morph_name = "..." (name remains a legacy alias).
• morph_to fails macro expansion unless the source has a persisted bindable <morph_name>_id field and a persisted String discriminator named <morph_name>_type. foreign_key may override the ID field and related_key may override the target key.
• The discriminator stores the Rust target model name. Lazy loading returns None for a different target; eager loading batches each declared target and never guesses an undeclared runtime type. Target models used in eager inverse loading must implement Clone.

5.4. Tenant Scope Contract

• A SQLx model declaring #[orm(tenant_column = "tenant_id")] must have a persisted String, i32, f64, or bool tenant field. The derive rejects a missing or unsupported field type.
• Generated queries fail closed when called outside with_tenant(...) and bind the active tenant inside the scope. Generated full/partial updates and instance delete/restore paths reject a model from another tenant.
• Model::unscoped() is the explicit global escape hatch. Deciding who may use it, deriving tenant identity from authenticated state, and database-level RLS remain host responsibilities.
• SQLx builders keep offset-based chunk(...) for compatibility and expose fallible chunk_by_id(...)/chunk_by_id_with_tx(...) for stable ascending keyset traversal over the generated i32 primary key. This prevents deletes of processed rows from shifting later rows behind an offset; it is not a database-server cursor or a universal cross-shard snapshot.
• A model delete with marked cascade_soft_delete has-one/has-many relations runs parent and direct-child mutations in one transaction. An existing explicit or task-scoped transaction is reused; otherwise delete() opens, commits, or rolls back its own transaction. Recursive descendant/cycle traversal remains a separate contract.
• Generated #[orm(auditable)] instance save()/delete() operations write their bounded audit entry through the same explicit, implicit, or task-scoped transaction as the model mutation. Audit write errors fail the mutation and roll its savepoint back; direct log_audit calls also honor a task-scoped transaction. Every recorded mutation requires an AuditContext naming a validated user, service, or system principal; the record also carries the optional correlation identifier and derives its typed tenant key from the active with_tenant(...) scope. The host remains responsible for deriving both contexts from authenticated authority rather than client assertions.
• create_audit_table creates the v2 schema and adds its columns to a legacy table without presenting legacy rows as v2 evidence. JSON payloads are bounded and recursively mask sensitive names for create, update, and delete; audit/debug output does not expose principal, tenant, correlation, reason, or payload values.
• An auditable model exposes restore_revision(audit_id, reason) and its caller-owned transaction variant. Only a bounded v2 update patch for the exact model, ID, and active tenant is eligible. The current row must still match the revision’s recorded post-state; PostgreSQL and MySQL/MariaDB also lock that row during restoration. A successful restore is a compensating audited update referencing the restored audit ID and reason. Legacy, create/delete, oversized, stale, malformed, cross-tenant, or redacted-field revisions fail closed. Bulk builders still do not synthesize per-row history, and durable external export remains an explicit outbox/application contract.

5.5. Process-Local Post-Commit Contract

• Orm::transaction and direct generated model save()/delete() operations own a post-commit callback scope. after_commit callbacks registered within it run only after SQLx confirms commit and are discarded on rollback. When no managed transaction is active, after_commit executes immediately for an already committed/autocommit operation.
• Generated observers retain synchronous lifecycle callbacks such as creating, created, and saved for mutation validation. The separate committed(ModelCommittedEvent) callback receives an owned, hidden-field- aware snapshot after the managed commit. Generated Redis invalidation/pub-sub and Scout projections use this same post-commit boundary.
• Savepoint-scoped generated saves/deletes and revision restores collect their callbacks in a nested scope. The callbacks are promoted to the enclosing commit boundary only after that savepoint succeeds, so catching a failed auditable mutation cannot leak a later committed effect.
• Every queued callback is attempted. A failure is returned as PostCommit, whose contract explicitly means the database mutation is already durable. Applications must not retry the database mutation blindly from this error.
• A caller-owned raw SQLx transaction passed to save_with_tx or delete_with_tx does not expose its later commit/rollback decision to the ORM. Use Orm::transaction for the strict process-local boundary.
• These callbacks do not survive process failure and provide no retry, idempotency or cross-node delivery. Use the explicit durable outbox below for an irreversible or externally delivered effect; it is not enabled automatically by a generated observer.

5.6. Durable Transactional Outbox Contract

• Outbox::enqueue accepts only a currently managed Orm::transaction and writes rullst_outbox through that same transaction. A domain rollback also removes the event. enqueue_with_tx provides the equivalent explicit path for a caller-owned SQLx transaction. No implicit independent commit is permitted.
• (stream, event_key) is the database uniqueness boundary. Replaying the same key and exact event kind/payload returns the existing i64 identifier; reusing the key with different content fails closed. stream, event key, event kind and worker identifiers use a bounded ASCII grammar, and serialized payloads are limited to one MiB.
• PostgreSQL, MySQL/MariaDB and SQLite share the outbox state machine. A claim increments attempts and receives a random token plus a bounded lease. Only that token may acknowledge or fail the event; expiration permits another worker to reclaim it. Failure schedules a bounded retry or moves the event to dead_letter at the configured attempt limit, including a worker that dies while holding its final lease.
• Delivery is at least once, not exactly once. A worker may perform its external effect and crash before acknowledgement, so consumers must use the stable stream/event key as their own idempotency key. Ordering across retries or concurrent workers is not guaranteed.
• Outbox::install is an explicit setup/test convenience and never runs at startup. OutboxMigration puts the same schema under the built-in reviewed migration lifecycle. The ORM does not infer tenant authorization from stream, automatically serialize model observers, dispatch HTTP webhooks, purge delivered rows or promise cross-database transactions.

5.7. Generated Redis Query Cache Contract

• The optional redis feature enables .remember(seconds) for generated SQLx reads. Orm::init_redis_with_namespace(url, application_namespace) is the recommended initializer when a Redis database is shared; the compatibility init_redis(url) initializer uses the literal namespace default.
• Versioned SHA-256 cache keys bind the validated application namespace, an opaque digest of the active tenant scope when present, table, generated SQL, and typed bindings. Raw tenant identifiers are not emitted in keys.
• Generated reads always bypass Redis inside explicit and task-scoped database transactions, so cached state cannot replace the transaction’s own view. remember(0) is invalid. Outside transactions, explicitly requesting cache without initializing Redis fails closed as a configuration error; transport failures and corrupt cached JSON fail open to the authoritative database.
• Cache writes occur only after a successful database read and retain encrypted model fields as ciphertext. Generated model save()/delete() operations invalidate the active tenant/table’s versioned keys only after commit through a bounded Redis SCAN plus asynchronous UNLINK; rollback preserves existing entries. Raw SQL, bulk builders, caller-owned raw transactions and writes from other processes cannot be inferred. Callers must retain a defensive TTL and treat Redis cluster/failover and durable invalidation delivery as separate application contracts.

5.8. Polyglot Persistence Boundary

• Optional persistence adapters are disabled by default and selected with mongodb, duckdb, turso, surrealdb, qdrant, or the polyglot convenience feature. The umbrella crate exposes matching orm-* features.
• DocumentRepository<T> provides create, find, replace, delete, and deterministic bounded listing. Collection names, document IDs, offsets and limits are validated before reaching a driver.
• DocumentInventory<T> is the separate identifier-preserving extension used by recovery tooling. Its stable ascending pages avoid breaking existing third-party DocumentRepository implementations.
• export_document_snapshot performs two matching bounded observations before sealing a versioned payload with AES-256-GCM. The authentication data binds the key-rotation ID, trusted application namespace and exact collection; decoding is capped at 64 MiB and 100,000 documents. Restoration accepts only an empty destination or an exact matching subset, never replaces or deletes, tolerates only an exact raced duplicate and verifies the complete final inventory. Applications must quiesce source/destination writers and durably store, rotate and protect keys/snapshots. Required destination schema must be provisioned first; driver/schema errors never become an implicit empty collection. The API is crash-resumable, not a cross-store transaction or managed backup service.
• MongoDbStore<T> uses the official MongoDB Rust driver and stores the portable DocumentId as _id; portable models must not define _id.
• DuckDbStore serializes access to its native connection and delegates every database operation to spawn_blocking. Dynamic values use prepared parameters, and callers must supply a QueryLimit before rows are materialized. Application-provided SQL text remains a trusted structural input.
• TursoStore speaks the official Hrana HTTP v3 protocol directly for remote edge SQL. It uses positional typed parameters, conditional atomic batches, a 30-second request deadline, no redirects, a 16-MiB response bound, bounded row materialization, and ordered checksummed migrations. This avoids an unnecessary embedded/native SDK dependency while retaining conformance against the official libSQL server. Empty or mock_* endpoints use a one-connection SQLite fallback that exercises real SQL without pretending to be a remote replica. HTTPS/libsql:// is required outside explicitly enabled loopback development.
• SurrealDbStore<T> uses the documented /key, /sql, and /gql HTTP endpoints with namespace/database headers, no redirects, bounded streaming responses, HTTPS by default, and redacted authentication configuration. GraphQuery::read_only accepts one MATCH query, rejects mutation tokens and caller-supplied limits, then appends a bounded limit.
• This boundary does not turn every backend into SQL Active Record, perform cross-database transactions, provide an online-consistent snapshot, synchronize records between engines, or prove a third-party deployment. See the Polyglot Persistence guide.

5.9. Scout Search Projection Contract

• #[orm(searchable)] projects generated save/delete operations only after a managed relational commit. Search adapter failures remain visible; a failed query is not silently treated as an empty result, and PostCommit means a projection failed after the database mutation became durable.
• MockSearchEngine is deterministic and always available. The optional scout-http feature adds Meilisearch, Elasticsearch and Algolia. Empty or mock_* credentials select the mock; keyless live constructors accept only loopback HTTP, while remote/custom origins require HTTPS without URL credentials, redirects, paths, queries or fragments.
• Index names, positive IDs, object payloads, queries, response bytes and hit counts are bounded. Meilisearch/Algolia tasks use bounded polling; Elasticsearch requests use refresh=wait_for. Provider response bodies and credentials are not copied into transport errors.
• The repository proves a real Meilisearch lifecycle in a digest-pinned container. Elasticsearch and Algolia protocol fixtures prove the documented HTTP shape and bounds, not hosted service operation, version-wide compatibility, ranking quality or cluster failover.
• The generated hook remains process-local. Guaranteed crash recovery requires an application-versioned event in the transactional Outbox and an idempotent worker; the ORM cannot infer a safe event key or external retry policy from an arbitrary model save.

5.10. PostgreSQL pgvector Contract

• The optional pgvector feature re-exports the SQLx-compatible Vector type. The supported execution profile combines it with strict-postgres; other SQLx backends do not pretend to implement PostgreSQL vector operators.
• where_similar, L2, cosine and inner-product ordering validate column names, reject empty/non-finite vectors and invalid distances, and bind vector and distance values. ORDER BY bindings are assembled after WHERE bindings regardless of builder call order.
• A digest-pinned PostgreSQL + pgvector container installs the extension, uses a typed vector model and proves L2 threshold/cosine ordering queries. The application still owns reviewed migrations, vector dimensions, embedding model compatibility, HNSW/IVFFlat index selection/tuning, tenant policy, context budgets, citations, ingestion/deletion and RAG evaluation.

5.11. Qdrant and Redis Specialized Store Contract

• The optional qdrant feature exposes a separate VectorRepository rather than pretending Qdrant is SQL Active Record. Collection names, dimensions, vectors, cosine norm, point payloads, query limits and response bytes are bounded. The HTTP client rejects redirects and URL credentials, uses short connect/request deadlines, requires HTTPS outside loopback, redacts API keys, and never copies provider response bodies into errors.
• QdrantConfig::new selects a deterministic in-process fallback for empty or mock_* endpoint/API-key values. unauthenticated_local is an explicit loopback-only path for self-hosted development. The supported live API is one unnamed dense cosine vector per numeric point with create, single-point upsert/delete and bounded nearest-neighbor query; named/sparse/multivectors, arbitrary filters, collection tuning and distributed topology are outside it.
• The optional redis feature exposes RedisDataStore for explicitly namespaced Hash, Set and Sorted Set operations in addition to the generated query cache. Keys, fields, UTF-8 values/members, finite scores and scan/range materialization are bounded. Remote endpoints require rediss://; URL credentials are rejected, ACL credentials are redacted, operations have connection/response deadlines, and empty/mock_* credentials select a deterministic in-process fallback.
• Digest-pinned Qdrant and Redis matrices prove their respective live lifecycles, including Redis namespace/structure separation. They do not prove hosted-provider availability, backups, cluster failover, tenant authorization, eviction policy, ANN quality, or cross-store transactions.

5.12. ORM Telemetry Contract

• Generated model/query entrypoints, transaction-aware variants, raw ORM queries and generated streams emit rullst.orm.query spans with only a static model, validated table and bounded operation name. SQL text, bindings, model values, DSNs and error strings are not fields of these Rullst-owned spans. The explicit debug query logger remains a separate opt-in surface.
• Managed transactions emit begin and lifecycle spans. Their final outcome is one of the bounded commit/rollback states; transaction errors are returned to the caller rather than copied into telemetry. Generated stream spans are entered only while the stream is polled, so a tracing guard is never held across suspension.
• Every pool constructed through Orm::init* emits SQLx pool-acquire timing at info level and promotes acquisitions slower than 500 ms to warnings. Primary and replica pools share this configuration. Direct pools constructed by the application are outside the contract.
• These standard tracing spans/events are exported when the host enables the umbrella telemetry feature and initializes Core’s OpenTelemetry subscriber. The host still owns OTLP endpoint security, filters, sampling, retention and collector availability. SQLx or application logging configured separately may have its own statement-data policy.

💳 6. Billing, Payments & Fiscal Engine (rullst-capital)

rullst-capital exposes bounded billing-provider and payout-provider adapters, plus a bounded Brazilian digital-invoicing preparation pipeline (NFS-e Nacional). Local cryptographic/schema validity is not tax authorization.

Every reviewed live adapter uses the same fail-closed outbound HTTP boundary: redirects and ambient proxy environment variables are disabled, connection and whole-request timeouts are finite, and a successful provider response is read only up to one MiB before JSON decoding. Failures expose a redacted typed ProviderFailure contract with permanent, transient, and rate-limited classes; only a bounded numeric Retry-After delta is retained. Raw response bodies, request URLs, credentials, and transport diagnostics are not included in the public error. Rullst deliberately does not retry billing mutations: callers may retry a transient or rate-limited result only when that exact operation has a persisted provider-forwarded idempotency key and a reconciliation policy. Returned checkout locations are accepted only as bounded, absolute, credential-free HTTPS URLs without fragments; provider/account sandbox acceptance remains external evidence.

6.1. Multi-Gateway Payment Architecture

Billing adapters implement BillingProvider; the Wise payout adapter implements the separate PayoutProvider contract. Individual billing operations may still return Unsupported when a provider adapter has no reviewed implementation:

#![allow(unused)]
fn main() {
use rullst_capital::providers::stripe::StripeProvider;
use rullst_capital::providers::BillingProvider;

async fn create_checkout() -> Result<(), rullst_capital::CapitalError> {
let provider = StripeProvider::new("mock_api_key", "mock_webhook_secret");
let session = provider
    .create_checkout_session(
        "customer@example.com",
        "price_monthly",
        "https://example.com/billing/complete",
    )
    .await?;
let _ = session;
Ok(())
}
}

#[derive(rullst::Billable)] is the umbrella convenience for named structs with an email: String field. It preserves generics; optional subscription_id: Option<String> and tier: Option<String> fields expose the corresponding helpers. An all-or-none grace_period_starts_at: Option<i64>/grace_period_ends_at: Option<i64> pair exposes a validated half-open window of at most 366 days. A provider-bound SubscriptionHandle<P> delegates cancellation and pausing; the explicit subscription_with path keeps static dispatch. These values do not infer or persist ownership, team membership, entitlement, currency, payment methods, usage or provider scheduling. Shared quota accounting is a separate explicit boundary described below.

The same derive inherits the bounded charge_with/charge helpers for an immediate off-session charge. A charge requires a positive integer amount in currency minor units (maximum eight digits), a three-letter currency, explicit provider customer and tokenized payment-method IDs, the model e-mail and an application-owned idempotency key of at most 255 bytes. BillingProvider::charge defaults to UnsupportedOperation; the reviewed live implementation is Stripe Payment Intents, which forwards the idempotency key, confirms off-session and fails closed on an amount/currency mismatch or a status other than succeeded or processing. Empty/mock_* Stripe credentials return a deterministic local receipt with the distinct non-success Mock status for exact retries. Rullst does not model raw payment credentials, prove that a stored method has a valid mandate, persist idempotency, grant an entitlement, reconcile webhooks or imply direct-charge parity across adapters.

Provider-Specific Metered Usage

MeteredBillingProvider deliberately uses an associated request type rather than pretending provider identities and retry semantics are interchangeable. StripeMeterEvent targets the current /v1/billing/meter_events API with the default stripe_customer_id and value payload mapping. It validates positive integer usage, the meter event name, customer, timestamp window and a forwarded identifier; the Stripe adapter sends that identifier as both event identity and HTTP idempotency key. LemonSqueezyUsageRecord targets /v1/usage-records, requires the numeric subscription-item relationship and an explicit increment or set action that must match the configured aggregation.

Both adapters limit response JSON to one MiB, bind identity/quantity/action fields before returning UsageStatus::Accepted, redact request/receipt identities from Debug, and return deterministic Mock receipts for empty or mock_* API keys. Stripe documents only a rolling provider deduplication window. Lemon Squeezy’s reviewed request has no equivalent event-key field, so its receipt reports ApplicationOutboxRequired; the application must claim event_key durably before submission. Provider-account acceptance, durable outbox storage, retries, reconciliation and entitlement/quota policy remain application/release evidence. The legacy uniform BillingProvider::report_usage is compatibility-only and fails closed for live Stripe/Lemon Squeezy rather than guessing the required provider-specific identity.

Coupons and Relative Trial Extensions

CouponCode accepts at most 256 ASCII identifier bytes and redacts its value from Debug. The Stripe adapter uses discounts[0][coupon], requests expanded discount evidence and accepts only a response bound to both the subscription and requested coupon. Lemon Squeezy documents discount codes for checkout, not post-checkout subscription mutation; it and every adapter without a reviewed live contract return UnsupportedOperation rather than a false success. Empty or mock_* credentials retain the deterministic offline no-op required for local applications and tests.

TrialExtension resolves 1 to 730 whole days against a trusted clock. Billable and SubscriptionHandle expose the historical ergonomic extend_trial(15) meaning plus extend_trial_days_at for a stable persisted command clock and set_trial_end for explicit reconciliation. Stripe sends trial_end; Lemon Squeezy sends trial_ends_at through its JSON:API PATCH. Both cap provider responses and bind the returned subscription and expiration. The host must authorize the subscription owner, persist a stable command time before retry, serialize conflicting changes, reconcile signed webhooks and evaluate provider-specific billing-cycle effects. Live-account acceptance is release evidence, not inferred from protocol fixtures.

Shared Team and Workspace Quotas

BillingSubject identifies one authoritative user, team, workspace or trusted tenant as the owner of both the subscription and its shared counters. Billable::quota_request derives the limit from that owner’s tier policy instead of accepting it from an HTTP payload. A QuotaStore then performs an atomic, idempotent reservation before the application creates the resource.

InMemoryQuotaStore is the deterministic offline/process-local contract. The opt-in quota-sql feature supplies SqlQuotaStore for SQLite, PostgreSQL, MySQL and MariaDB. Its conditional counter update and unique event claim prevent concurrent members from exceeding the same limit. Exact retries return a replay grant without consuming or executing again; a key reused with different units or limit fails closed. QuotaGate::execute blocks the callback before an over-limit creation and compensates an ordinary callback error.

The convenience gate cannot make two unrelated storage systems atomic. A relational application that needs exact quota/resource atomicity must open a transaction from SqlQuotaStore::pool, call reserve_with_transaction, perform the domain insert through that transaction and commit once. Trusted middleware must establish membership and active tenant before constructing the subject. Plan/webhook reconciliation, migrations and custom/non-relational stores remain explicit application work.

6.2. Invoice Rendering

Invoice::generate_html remains the source-compatible escaped HTML renderer. Trusted paths use validate/try_generate_html: the legacy public f64 model accepts only bounded finite positive values with at most two decimal places, converts them to integer minor units, and requires the exact item sum.

The opt-in invoice-pdf feature adds bounded paginated A4 rendering. Its embedded Helvetica subset supports WinAnsi text; other scripts require a caller-supplied TTF/OTF of at most eight MiB containing every used glyph. PDF output is capped at sixteen MiB. Invoice::bind_succeeded_charge creates an immutable PaidInvoice only when a final, non-mock receipt exactly matches the recipient, minor-unit amount and currency. It derives a stable non-secret key from the invoice and provider evidence for use by an application outbox.

The downstream rullst-mail/capital-invoice feature converts that value into a pipeline-validated HTML message with the PDF attached and exposes one-call facade, tenant-aware or static-driver delivery. It does not infer a webhook event, atomically claim the delivery key, guarantee provider acceptance or promise exactly-once delivery. Applications processing retries or multiple instances must persist/claim the key and reconcile payment state durably before sending.

6.3. Webhook Signature Verification

• The Axum and opt-in Actix middleware adapters call one canonical bounded verifier before dispatch. Built-in provider adapters use provider-appropriate cryptographic verification; equality checks for derived signatures are constant-time where applicable.
• Timestamped protocols enforce a bounded freshness window. The default replay store is bounded and process-local and fails closed instead of evicting an unexpired proof when full.
• The opt-in webhook-sql store shares bounded payload-digest or semantic-event claims across processes on SQLite, PostgreSQL, MySQL, and MariaDB. Its schema profile is immutable, claims serialize through one configuration lock, expiry uses the database transaction clock, and storage/configuration/capacity failures reject the request.
• SQL-backed middleware admission claims a payload before handler dispatch; it is replay protection, not an exactly-once delivery protocol. When billing correctness requires atomic domain mutation, the application must verify the provider payload, select the provider’s stable event ID, and call check_and_record_event_key_with_transaction through the same relational transaction as the mutation. Cross-system effects still require an outbox, idempotent consumers, and reconciliation.

6.4. NFS-e Nacional Specification (FiscalEngine)

• 🟢 [Implemented / Bounded] DPS 1.01 Builder: NfseDpsV101 models an ordinary domestic-service subset, validates CPF/CNPJ/IBGE/identifier/text limits, keeps BRL values in integer cents and ISS rates in basis points, and emits an unsigned DPS in the official namespace. The legacy floating-point preview remains compatibility-only.
• 🟢 [Implemented / Bounded] Pinned Schema Validation: Production profile v1.01-20260209 and restricted profile v1.01-20260727 carry immutable archive/file SHA-256 values. NfseDpsSchemaValidator reads only the expected bounded files and resolves imports from an in-memory catalogue; it never downloads schemas or follows instance hints.
• 🟢 [Implemented / Bounded] Local XMLDSig and mTLS Preparation: sign_dps_xml parses a protected PKCS#12 A1 container, rejects malformed/duplicate/already-signed envelopes and emits an enveloped inclusive-C14N 1.0 RSA-SHA256 signature over the unique infDPS/@Id. The matching certificate chain is embedded and tested with independent local verification. The same container can construct a rustls mTLS identity/client with HTTPS-only, no redirects, and bounded timeouts.
• 🟢 [Implemented / Bounded] Offline SEFIN Issuance Codec: NfseIssueRequest accepts only one structurally bound and cryptographically valid embedded DPS XMLDSig, emits deterministic GZip/Base64 inside the exact dpsXmlGZipB64 JSON object, and parses at most four MiB. HTTP 201 can become Authorized only when environment, submitted DPS ID, 50-digit access key, infNFSe/@Id and the embedded NFS-e XMLDSig agree; HTTP 400/403/500 become a separate bounded Rejected variant. Unknown fields, malformed JSON/XML/Base64/GZip, duplicate/confused IDs, invalid signatures and decompression amplification fail closed. Embedded-signature validity does not establish ICP-Brasil trust or emitter ownership.
• 🟢 [Implemented / Bounded] Local Fiscal Command Journal: The nfse feature exposes a single-active-writer FiscalCommandJournal that accepts only a homologation/production command whose selected environment equals the signed infDPS/tpAmb. It synchronously records a prepared command before any caller-owned transport and then one bound authorized or rejected terminal result. Exact command/request/result replays do not append; key reuse with different material, invalid transitions, external file growth, quota exhaustion, wrong keys, symlinks, corruption and durability uncertainty fail closed. The append-only v1 file is bounded to 16 MiB and 4,096 events, uses a named 256-bit HMAC key and chains every frame to the prior tag. It stores the caller’s opaque command ID, request/result digests, environment, state and bounded times, never the DPS/NFS-e XML, access key, certificate, response body or processing messages. pending() recovers minimized unresolved descriptors after restart. A serializable exact-tip checkpoint can detect valid-prefix truncation only when retained independently. The host owns a non-PII command namespace, key custody/rotation, a trusted directory, one active writer, secure storage of the actual request, checkpoint persistence, backup/retention, authority reconciliation and retry policy; this journal does not transmit, retry, prove cross-system exactly-once or establish tax authorization.
• 🟡 [Simulado] Offline Mock Environment: NfseEnvironment::Mock produces deterministic test fixtures for local sandboxing.
• 🔵 [Roadmap / External Evidence] Official SEFIN Homologation & Production: Homologation and Production validate credentials and then return FiscalError::Unsupported without network I/O. Enabling transmission requires emitter-certificate/ICP-Brasil lifecycle checks, deployment of the local journal plus authoritative request/outbox and reconciliation storage, retained protocol fixtures, real restricted-environment tests with an authorized contributor and municipality, independent review, and successful official homologation.

🛡️ 7. Enterprise Security, RASP & Vault (rullst-security)

7.1. Rullst Vault (Authenticated Field Encryption)

• Algorithm: AES-256-GCM with authenticated 96-bit random nonces and 128-bit authentication tags.
• Envelope Format: RULLST:v2:<key_id>:<base64_nonce>:<base64_ciphertext_and_tag>.
• Key Rotation: Built-in keyring support (decrypt_with_keyring) can read prior keys while new writes use the active key. Deployment coordination, re-encryption, key custody and retirement remain operator responsibilities.
• ORM Configuration: RULLST_ENCRYPTION_KEY, RULLST_ENCRYPTION_KEY_ID, and RULLST_ENCRYPTION_KEYRING select the current and still-readable prior keys. Rullst does not provide key custody or automatic retirement.

7.2. Runtime Application Self-Protection (RASP)

• Bounded Heuristic Inspector: ASCII case-insensitive signature matching covers selected SQL injection, traversal, SSRF, shell/JNDI patterns across URI, non-secret headers, and supported bounded textual/JSON bodies. Percent decoding and body/JSON inspection allocate; this control does not replace typed parsing, SQL binds, validation, authorization, or SSRF allowlists.
• Login Guard Tarpit: record_login_failure returns progressive delay decisions and record_login_failure_and_wait applies them asynchronously; both share bounded, temporary in-memory jails keyed by a hashed identity.

7.3. MFA and Security Evidence Boundaries

• TOTP enrollment: Secrets contain 160 bits derived from the OS RNG, verification accepts exactly six ASCII digits with constant-time comparison, and enrollment can emit an otpauth:// URI or bounded SVG QR. Secret custody, recovery workflow and durable rate limiting belong to the application.
• Security CLI: CycloneDX generation, MSRV/tool diagnostics, unsafe/IDOR source heuristics, network observations and compliance evidence are bounded checks. They do not certify a deployment, prove absence of vulnerabilities or replace provider/CI evidence tied to an immutable SHA.

7.4. Bounded JSON Schema Enforcement

• JsonSchemaPolicy::from_schema compiles an application-supplied JSON Schema 2020-12 document once; from_openapi_component selects one explicit components.schemas entry from OpenAPI 3.1. OpenAPI 3.0 is rejected because it is not the same schema dialect.
• Construction caps serialized bytes, node count and depth, rejects non-local $ref/$dynamicRef, disables network/filesystem retrieval and selects the linear-time regex engine. The route-scoped Axum middleware first enforces the existing exact media-type, syntax, duplicate-key, payload-size and depth boundary, then returns 422 for schema mismatch without echoing values.
• The policy validates JSON bodies only. Authentication, authorization, ownership, business invariants and query/header/form parameters remain separate application boundaries.

7.5. Deterministic Threat Sentinel and Proof of Work

• ThreatClassifier assesses a bounded aggregate window supplied by the host against transparent thresholds for credential stuffing, API scraping and distributed automation. It does not collect traffic, infer identity, use a model or attribute a botnet.
• ProofOfWorkGate issues OS-random, HMAC-authenticated challenges bound to one canonical application subject. Tokens have bounded difficulty, TTL and cardinality; successful verification atomically consumes local state so only one concurrent verifier succeeds in the process.
• Classification is evidence, not authorization. The host chooses whether and where to challenge, provides an accessible fallback, rate-limits issuance and owns trusted proxy/device policy. Replay state is process-local; distributed enforcement, durable telemetry and cross-process one-shot consumption require an application adapter.

7.6. Authenticated Local SIEM Journal

• AuthenticatedSiemSpool is the opt-in authenticated counterpart to the compatible unsigned DurableSiemSpool. It normalizes each local v1 event, writes it synchronously under 16 MiB/4,096-record ceilings and authenticates sequence, key identifier, predecessor tag, payload length and exact payload with a domain-separated HMAC-SHA256 chain.
• SiemKeyRing accepts one active write key and at most seven historical verification keys. Key identifiers are bounded, key material is consumed into zeroizing storage, and secret-bearing Debug output is redacted. A rotation reopens the spool with the new active key plus every still-needed historical key; silently missing or wrong keys fail closed.
• This journal detects forged records, interior deletion/reordering and external length changes. Removal of a complete valid tail is indistinguishable from an earlier valid file unless the operator retains a trusted external checkpoint. Path/key custody, permissions, single-writer enforcement, rotation retirement, compaction, retention, backup, transport, retry, acknowledgement and dead-letter handling remain operator/application work.

📡 8. IoT, Firmware Security & Protocol Frames (rullst-iot)

8.1. Ed25519 OTA Firmware Gate

• Firmware Verification: Strict Ed25519 signature validation over a cryptographic manifest [target, version, rollback_counter, firmware_len, firmware_sha256].
• Anti-Rollback Protection: Verification rejects any counter lower than or equal to the state loaded into the manager. The recommended RollbackCounterStore path additionally performs an exact compare-and-set and may report success only after a strictly increasing value is durably committed across reset. Atomicity, integrity, wear-leveling and power-loss behavior are obligations of the caller’s platform adapter and require hardware-specific evidence.
• Commit Invariant: In-memory partition selection and store-backed counter commit are blocked until full cryptographic verification succeeds. verified_target_partition exposes the inactive bank for platform flash/read-back before commit. The compatibility commit_verified_update path is process-local and does not claim persistence, flash or bootloader control.

8.2. Embedded Sensor Frames (#![no_std])

• rullst-iot core models compile under bare-metal #![no_std] targets (STM32, ESP32-C3, Cortex-M).
• cargo rullst make:iot <DeviceName> generates and registers a local telemetry module, enables the umbrella iot feature and refuses unsafe names or collisions. It does not install firmware, a HAL, MQTT or CoAP.
• IotDashboard renders an escaped HTML snapshot. It does not infer online state or provide a live device connection.
• MqttPublish encodes one bounded MQTT 5 PUBLISH packet with validated topic, minimal Remaining Length, QoS/packet-identifier invariants and an empty property section. CoapRequest encodes bounded RFC 7252 base requests with a token, ordered URI-Path/Content-Format options and a non-empty payload marker. Both compile under no_std; neither opens a socket or owns protocol session state.
• 🔵 [Roadmap] MQTT/CoAP Transport: Async connections, TLS/DTLS, broker negotiation, acknowledgements, retransmission/congestion control, block-wise transfer and interoperability matrices remain separate integration work.

🤖 9. AI Agent & LLM Orchestration (rullst-ai)

9.1. Guarded AI Client

• Provider-agnostic interface for Google Gemini, OpenAI, Anthropic Claude, DeepSeek, Ollama, and explicit OpenAI-compatible endpoints. The compatible adapter is chat-only by default; applications declare optional request shapes for one exact model. Loopback may be unauthenticated, cloud requires HTTPS/Bearer, and unrelated protocols implement the public AiProvider boundary rather than passing through arbitrary HTTP.
• Prompt Injection Firewall: Real-time token heuristics intercepting prompt exfiltration, instruction overrides (DAN mode), and delimiter injection attacks.
• Automated PII Masking: Scrubs sensitive data (CPF/CNPJ, credit cards, emails) prior to outbound LLM dispatch.

9.2. Bounded Streaming and Cancellation

• StreamingAiClient<P> preserves static dispatch, reapplies the mandatory input guardrails and enforces at most 4,096 non-empty chunks, 64 KiB per chunk and 2 MiB aggregate output independently of the provider.
• An OpenAI-compatible configuration may explicitly declare SSE streaming. The transport requires text/event-stream, bounded raw bytes, supported chat deltas and [DONE]; malformed, truncated or oversized streams fail closed.
• AiCancellation races the initial request and every streamed body read. It drops local transport work but does not prove upstream cancellation or stop provider billing. Non-compatible protocols and ordinary non-streaming calls retain deadline/drop semantics.

9.3. Bounded Tenant-Aware RAG

• RagPipeline::answer requires a trusted Core TenantContext and composes guarded embedding, a static-dispatch application RagRetriever, bounded context selection, guarded generation, source metadata, and one required terminal RagAuditSink event.
• Retrieved documents carry the trusted tenant tag. The pipeline rejects mismatches, over-return, injection heuristics, empty context, non-finite embeddings, and unavailable mandatory audit evidence rather than silently generating an ungrounded response.
• Context limits count Unicode scalar values per document and in total. The audit event omits raw question, context, embeddings, provider bodies, and answer; its SHA-256 query digest is correlation metadata, not encryption.
• InMemoryRagRetriever and InMemoryRagAuditTrail are bounded process-local development/test implementations. DurableRagAuditTrail and DurableToolAuditTrail add bounded, synchronously persisted, versioned local evidence with restart validation and fail-closed corruption/quota handling. They are single-process writers; their SHA-256 frames detect corruption but do not authenticate events. Production hosts own authoritative tenant and ownership predicates, durable/external vector adapters, ingestion/deletion, model/vector compatibility, output policy, directory permissions, rotation/retention/backup, external audit delivery, tuning, evaluation and recovery.

9.4. Bounded Conversational Memory

• StatefulChat<M> uses static dispatch over ChatMemory, requires a trusted TenantContext and validated ConversationId, loads only the configured even number of recent messages, applies the guarded AiClient, and persists the user/assistant exchange only after generation succeeds.
• InMemoryChatMemory is deterministic, tenant-partitioned, cardinality-bound, and intended for tests/local use. The opt-in sql-memory adapter supports SQLite, PostgreSQL, MySQL, and MariaDB through a dedicated SQLx Any pool.
• The SQL adapter advances an even conversation revision and inserts both messages in the same transaction. A compare-and-swap predicate rejects stale cross-process writers; Rullst deliberately does not retry the provider call. History reads bind the tenant/conversation and never include rows newer than the revision observed by that read.
• Message text is not encrypted by this adapter. Authenticated conversation ownership within a tenant, retention/erasure, provider audit, backups, migration governance, and user-facing conflict retry remain host policy. The generated Turso/custom-model scaffold is a separate application-owned path.

9.5. Authenticated Audit Export

• AuditDeliveryClient exports an application-minimized serializable event in a versioned JSON envelope of at most 16 KiB. Cloud endpoints require HTTPS; local HTTP(S) requires a literal loopback IP. Redirects and ambient proxies are disabled.
• HMAC-SHA256 covers a domain separator, key ID, Unix-millisecond timestamp and the exact body. A caller-supplied event ID remains unchanged across one to five attempts. Only transport/deadline errors, HTTP 429 and HTTP 5xx are retryable, and a closed acknowledgement of at most 8 KiB must bind that ID. AiCancellation races request, body and retry waits. Empty or mock_* keys select deterministic offline behavior.
• A timeout may follow remote acceptance. The receiver therefore owns signature and freshness verification, event-ID deduplication, authorization, persistence, retention, key distribution/rotation and operational availability. The client does not minimize arbitrary event values or provide a durable outbox/SIEM service.

9.6. Bounded Adaptive Evaluation

• AdaptiveAiEvaluator<P> keeps static provider dispatch and reapplies the mandatory prompt guardrail on every strategy-generated prompt. A scenario is capped at 32 turns, 16 KiB per prompt and 2 MiB per response, with an independent per-turn deadline and AiCancellation raced against each call.
• AiEvaluationStrategy temporarily receives the bounded response or a low-cardinality guardrail/provider/deadline outcome and explicitly chooses pass, fail, inconclusive or a next prompt. The synchronous strategy is application code and must not persist/log model text without policy.
• The version-1 JSON report records caller-supplied suite and exact model/configuration subject labels, provider name, terminal code and only per-turn byte counts/outcomes. It retains no prompt, response or provider error. Subject labels are assertions, not automatic model discovery.
• Deterministic repository fixtures prove bounds, feedback, redaction, cancellation and status semantics. Operators still version domain corpora, run them against every exact live model/configuration and review results; a pass is not universal safety, groundedness or jailbreak-resistance evidence.

📊 10. Control Center & Admin Interfaces (rullst-studio & rullst-nexus)

10.1. Rullst Studio (http://127.0.0.1:5555)

• Local-first developer dashboard with a server-rendered dark interface; browser assets and final page policy remain deployment concerns.
• Process observations sourced from RadarSnapshot::collect() and explicitly supplied local collectors; unsupported values remain unavailable.
• Generated applications start the standalone Studio only in debug builds and bind it to loopback. Its local capability verifies the direct loopback peer, accepts only a local Host authority, requires same-origin Origin on unsafe methods, and rejects missing origins on mutations. This is a local DNS-rebinding/CSRF boundary, not production authentication.
• Queue, revenue, security and telemetry pages report only values supplied by their configured process-local source. Unsupported driver operations and disconnected integrations remain errors or Unavailable. The standalone migration surface provides CLI guidance and returns 501 from legacy mutation handlers because no migration/seeder registry is installed.
• The database browser accepts a deliberately narrow ASCII SQL-identifier boundary. Reads are bounded; writes require the crate-private proof inserted by the verified local middleware, database-inspected table/column/complete-PK metadata, a 64 KiB request limit, primitive typed binds and exactly one affected row. Primary keys/backend-specific values are read-only, while delete requires DELETE <table>. SQLite, PostgreSQL, MySQL and MariaDB run separate mutation contracts. This is not application authorization, tenant scoping, audit, rollback or shared-production administration. The ER diagram inspects the same relational backends with bound lookup values and strict normalized Mermaid identifiers. Swagger requires an application-supplied OpenApi.
• Request SSE records method, URI, status, and latency without bodies or headers. Environment values are redacted by default and the typed config projection never renders connection URLs, filesystem paths, cookies, tokens, or credentials. A successful Studio database-flag mutation invalidates warm DbFeatureDriver caches in the same process; direct writers and other processes remain subject to TTL unless the host distributes invalidation. SQLite removes completed jobs by default. An explicit 1–100,000-row history policy retains and atomically prunes real completion records for Studio, with a separate purge; retained payload access and lifecycle belong to the host. Redis/custom queue inspection remains capability-specific.
• Studio::with_cache is an explicit metadata-only diagnostic capability. The memory and Redis cache drivers return at most 200 sorted entries containing logical key, UTF-8 value byte length and remaining TTL; custom drivers return InspectionUnsupported by default. Studio displays at most 100 keyed opaque identifiers and never cache values or exact logical keys. Individual invalidation requires its unforgeable verified-local marker and a fresh process-bound HMAC token. The page has no bulk flush operation.
• Distributed trace producers use separately mounted, push-only routers; each endpoint binds one exact producer name to one key and multiple producers use separate endpoints/keys over the same shared store. A v1 batch is at most 128 KiB and 128 spans, carries W3C-compatible IDs, a bounded source/operation/kind/timing/status set, and accepts no attributes, SQL, bindings, headers, bodies or error strings. HMAC-SHA256 authenticates the exact body and source/timestamp/nonce headers; a 60-second window and bounded atomic nonce cache reject replay, while the shared in-process store is capacity-bound and idempotent by trace/span ID. The local viewer reports a fixed 100 ms slow-query signal and a three-equal-label possible-N+1 heuristic. This is not an OTLP collector, durable backend, secret manager, remote viewer/login, or proof that a repeated operation is defective. TLS, network policy, key distribution/rotation, clock synchronization, producer label redaction, retention and availability belong to the deployment.
• Exposing Studio beyond the developer machine requires an explicit authenticated network boundary owned by the application; no environment variable silently converts the local server into a production admin surface.

10.2. Rullst Nexus (/nexus)

• Auto-generated CMS with dynamic CRUD operations and AI Admin Assistant.
• Security Default: Fail-closed by design; requires explicit authentication middleware and RBAC role validation (admin) on all mutating endpoints.
• Generated applications may use NexusAuthPolicy::local_development_or_basic_from_env(): debug builds accept only a peer address verified as loopback through ConnectInfo, while release builds require validated Basic Auth credentials from the environment. Missing peer metadata is denied, and an environment mode flag cannot enable unauthenticated release access.
• A model may explicitly declare one text tenant column. Nexus then obtains the scope only from a trusted Core TenantContext, injects it on create, includes it in every built-in read/mutation/batch predicate, and denies a missing context. Models without that metadata remain global administrator models. Authentication and tenant-membership resolution remain host contracts.
• with_required_audit requires the fixed rullst_nexus_audits schema and appends one minimized committed-mutation row in the same transaction. Audit unavailability rolls the data change back. This is not append-only, tamper-evident, denied-attempt, retention, backup, replication or external-SIEM evidence; those properties remain host responsibilities.

🛡️ 11. Architectural Guidelines for Backward Compatibility

1. #[non_exhaustive] on Public Structs: All configuration structs and enums must use #[non_exhaustive] to ensure minor versions can add fields without breaking downstream code.
2. Deprecation Policy (#[deprecated]): Public APIs will never be removed without at least one minor release cycle marked with #[deprecated].
3. Ergonomic String Constructors: Public constructors accept impl Into<String> to support both &str literals and owned String parameters without boilerplate.
4. Zero-Panic Invariant: Production paths must never call panic!(), unwrap(), or expect(); domain errors must return typed Result<T, AppError>.

🔄 12. Assisted Framework Upgrade Contract

cargo rullst upgrade is the canonical application-upgrade boundary. It is an assistant, not a claim that compilation proves production compatibility.

• 🟢 [Implemented / Bounded] Planning: --dry-run enumerates only Cargo workspace manifests, preserves TOML comments/order, understands normal, inline-table, workspace, target-specific and renamed Rullst dependencies, and reports path/git dependencies that have no version instead of guessing. --dry-run --json emits the versioned rullst.upgrade-plan.v1 envelope.
• 🟢 [Implemented / Bounded] Versioned Rules: source findings are selected from a versioned rule catalog using detected source majors and the exact target major. Every future major release must extend that catalog, migration documentation, negative tests and process-level fixtures for its supported upgrade paths.
• 🟢 [Implemented / Bounded] Transaction: the default target is the exact installed cargo-rullst version; --to accepts only the same major train as that CLI. Before writes, the command snapshots workspace manifests, the root lockfile and Rust sources under target/rullst-upgrades. It applies only dependency edits and compiler-provided cargo fix changes, then requires cargo check --workspace --all-targets to pass. A failed gate restores the snapshot by default; --keep-on-failure is explicit, and --restore can recover a persisted, path-validated snapshot after an interruption. Process fixtures independently select the v5, v6 and v11 rule sets, prove atomic restoration across multiple workspace members, preserve a failed edit only when explicitly requested, restore that persisted review state, and reject symlinked Rust sources before starting the transaction.
• 🟠 [Manual Application Boundary] the command never installs a CLI, changes secrets, executes database migrations, invents authorization or tenant policy, exposes Nexus/Studio, validates providers, or declares an application production-ready. Database restore/migration/rollback, the full test suite, authorization negatives and deployment smoke tests remain mandatory human-owned gates.

📱 13. Omni Packaging Contract

cargo rullst make:omni generates an application-owned Tauri packaging shell; it is not a native-runtime abstraction or store-publication service.

The canonical product is the Rullst web application. Server-side domain rules, authentication, authorization, persistence, realtime policy and security controls remain authoritative and must work without trusting the platform shell. Omni is web-first, platform-enhanced: it may add narrowly scoped native capabilities, but it must not fork the business/security model or move authoritative secrets into JavaScript or an untrusted client.

• 🟢 [Implemented / Bounded] Deterministic Scaffold: --platform accepts desktop, Android and iOS selections without a prompt. Mobile selections require --backend-url; HTTPS is required except for explicitly bounded loopback/emulator development hosts, and embedded credentials are rejected. Product name and application version default to validated Cargo package metadata. --product-name, --app-version and --identifier provide deterministic overrides. Android/iOS require an application-owned lowercase reverse-DNS identifier and reject framework/reserved example placeholders; desktop-only development may use a clearly documented com.example value.
• 🟢 [Implemented / Bounded] Reproducible Tooling: the generated manifest pins the Tauri CLI and Rust dependencies, emits a restrictive local CSP and real source-derived platform icons, and treats npm, icon generation or explicitly requested mobile initialization failures as command failures. Explicit iOS initialization requires macOS/Xcode.
• 🟢 [Implemented / Bounded] Remote-content Boundary: the generated local bootstrap exposes no Tauri IPC API to the remote application. A native navigation callback permits only Tauri’s packaged origin and the exact scheme/host/effective-port tuple of the configured backend; cross-origin links and OAuth must use a separately reviewed system-browser/deep-link flow. The bootstrap provides an accessible initial offline/retry state, but this is not offline application data or synchronization.
• 🟢 [Implemented / Bounded] Desktop Lifecycle: the one-command local http://localhost:3000 development profile owns its child process, refuses a pre-existing port rather than attaching to an unknown process, stops on early child exit or timeout, and terminates only the child it spawned. HTTPS and other configured origins are treated as externally operated backends.
• 🟢 [Implemented / Bounded] Shared Wire Contract: rullst::client_contract provides the strict rullst.client v1 JSON marker, positive version negotiation, private typed request/success/failure envelopes, bounded log-safe correlation and idempotency tokens, server time, message-free dotted failure codes and a codec capped at 2 MiB. Unknown outer fields, unsupported versions and oversized bodies fail closed. The same code compiles natively and for wasm32-unknown-unknown. The envelope carries no role, tenant or authorization claim; the server must derive those from its authenticated context and persist idempotency atomically.
• 🟢 [Implemented / Feature-gated Foundation] Offline State Contract: the native offline-sync feature supplies one account-bound, versioned state with bounded cached records, FIFO idempotent mutations, server revisions and cursors, atomic response application, explicit conflict isolation, full resync, quotas, cache recovery and logical erasure. OfflineSnapshotCipher authenticates and encrypts the closed snapshot with randomized AES-256-GCM, binds it to the exact account and rotation-key id, revalidates every bound after decryption, redacts state payloads from aggregate Debug, and zeroizes its owned key/plaintext buffers where possible. It never treats client time, cached identity/role/tenant, score or local revision as authority. A static-dispatch coordinator bounds foreground push/pull requests, mandates per-request timeout, stops on retryable no-progress and rejects a continuing page whose cursor did not advance. Keychain/Keystore, atomic platform persistence, browser storage, concrete authenticated HTTP, retry/background orchestration, concrete future-schema migrations, physical-device recovery/erasure evidence and application conflict UX remain explicit platform/application work; therefore the generated shell alone is not an offline-first application.
• 🟢 [Implemented / Hosted Compile Evidence] Compile Evidence: on commit 755fbd61933bed04369e0eb5de50b11275db5e3d, path-aware workflows created disposable hosts and passed fresh desktop shell checks on Linux, macOS and Windows, an Android aarch64 debug APK build, and an iOS simulator build. These are compile gates for that SHA, not physical-device or store evidence.
• 🟠 [Application / Platform Boundary] bundle identity, signing and provisioning, privacy manifest and usage declarations, native capabilities, production endpoint/auth policy, physical-device testing, TestFlight, Play testing, metadata and store review belong to the generated application. Offline sync, push, biometrics, OS secure storage, deep links and signed updates are not implied by the web shell and require opt-in capability scopes plus platform tests. Simulator/APK compilation must never be described as store acceptance or universal iPhone/Android compatibility.

Capability status and vision decisions

Rullst’s ambitious ideas are not deleted when an implementation is incomplete. They are kept here with an explicit status and an engineering recommendation. User-facing guides describe what can be used today; this ledger preserves the larger vision without presenting roadmap work as a production capability.

Status is evaluated against the current version 12 source tree, not against an old changelog entry or marketing description:

• Implemented: a real implementation and focused tests exist; deployment responsibilities may still apply.
• Partial: useful foundations exist, but the advertised end-to-end contract is not complete.
• Experimental: available only behind an explicit experimental/simulator boundary and carries no production guarantee.
• Not implemented: absent or intentionally returns a typed Unsupported error instead of simulating success.
• Do not promise: the absolute claim is not a technically honest product contract; a narrower engineering goal may still be worthwhile.

The recommendation column is intentionally opinionated. “Worth implementing” does not mean “put it in Core”: several excellent ideas belong in optional, independently tested crates. Ideas that additionally need continuous operations, homologation, or hardware can follow the Maybe SaaS incubation strategy.

Architecture and framework contract

ORM and persistence

Capital, billing, and fiscal vision

IoT, edge, and cryptography vision

Connect, real-time, queues, storage, and data

Security, authentication, Studio, and Nexus