Genarrative/.codex/skills/spacetimedb-rust/SKILL.md

name, description

name	description
spacetimedb-rust	Develop SpacetimeDB 2.5 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.

SpacetimeDB Rust Module Development

Use this skill for Rust code in server-rs/crates/spacetime-module and related Genarrative schema/migration work.

Genarrative Rules

• Keep domain rules in module-*; keep SpacetimeDB tables, reducers, procedures, views, mappers, and transaction adapters in spacetime-module.
• Existing table fields must be appended at the end with explicit defaults. Do not rename, remove, reorder, or change field types without a user-confirmed migration plan.
• After schema changes, update migration.rs, table catalog/docs, generated bindings, and run npm run spacetime:generate plus npm run check:spacetime-schema.
• Private tables are backend facts. Expose user-visible state through BFF endpoints/read models rather than direct client SQL.

Hallucinated APIs: Do Not Use

#[derive(Table)]                // Tables use #[table], not derive
#[derive(Reducer)]              // Reducers use #[reducer], not derive
#[derive(SpacetimeType)]        // Do not derive this on #[table] structs

pub fn reducer(ctx: &mut ReducerContext) {} // Use &ReducerContext

ctx.db.player                   // Use ctx.db.player()
ctx.db.player.find(id)          // Use ctx.db.player().id().find(&id)
ctx.sender                      // Use ctx.sender()
ctx.db.user().name().update(..) // Update by primary key only

spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures in 2.5

Required Patterns

use spacetimedb::{reducer, table, Identity, ReducerContext, Table, Timestamp};
use spacetimedb::SpacetimeType; // Custom types only, not tables

#[table(accessor = player, public)]
pub struct Player {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub owner: Identity,
    pub name: String,
    pub created_at: Timestamp,
}

#[reducer]
pub fn create_player(ctx: &ReducerContext, name: String) -> Result<(), String> {
    if name.trim().is_empty() {
        return Err("name required".to_string());
    }
    ctx.db.player().try_insert(Player {
        id: 0,
        owner: ctx.sender(),
        name,
        created_at: ctx.timestamp,
    })?;
    Ok(())
}

Hard requirements:

• Import Table for table operations.
• Use accessor = identifier, not string literals.
• Use ctx.sender() for authorization.
• Use ctx.rng() / ctx.random() / ctx.new_uuid_*() for deterministic randomness and UUIDs.
• Use Result<(), String> for expected sender errors; avoid panics except impossible states.
• Use try_insert() in Result reducers when constraint violations should be reported cleanly.

Tables

#[spacetimedb::table(accessor = game_tick_schedule, scheduled(game_tick))]
pub struct GameTickSchedule {
    #[primary_key]
    #[auto_inc]
    pub scheduled_id: u64,
    pub scheduled_at: ScheduleAt,
}

Table attributes:

Attribute	Description
accessor = identifier	API name used in ctx.db.{accessor}()
public	Visible to clients via subscriptions
event	Transient event table
scheduled(function_name)	Schedule table that triggers a reducer/procedure
index(accessor = idx, btree(columns = [a, b]))	Multi-column index

Column attributes:

Attribute	Description
#[primary_key]	One primary key per table
#[auto_inc]	Auto-generates integer values when inserting 0
#[unique]	Unique constraint and find() accessor
#[index(btree)]	B-tree index and filter() accessor
#[default(...)]	Required for new fields on existing Genarrative tables

Genarrative Schema Change Pattern

#[spacetimedb::table(accessor = creation_entry_config, public)]
pub struct CreationEntryConfig {
    #[primary_key]
    pub id: u64,
    pub existing_field: String,

    // Append new fields at the end and provide a default.
    #[default(false)]
    pub new_flag: bool,
}

Then update migration.rs, table catalog/docs, generated bindings, and run:

npm run spacetime:generate
npm run check:spacetime-schema

Table Operations

let row = ctx.db.player().insert(Player { id: 0, owner, name, created_at });
ctx.db.player().try_insert(row)?;

let by_id = ctx.db.player().id().find(&123u64);
for player in ctx.db.player().owner().filter(&ctx.sender()) {}
for player in ctx.db.player().level().filter(&(18u32..=65u32)) {}
for player in ctx.db.player().iter() {}
let count = ctx.db.player().count();

if let Some(player) = ctx.db.player().id().find(&id) {
    ctx.db.player().id().update(Player { name: new_name, ..player });
}

ctx.db.player().id().delete(&id);

For delete/update based on non-PK filters, collect keys first to avoid iterator invalidation.

Indexes

#[spacetimedb::table(
    accessor = score,
    public,
    index(accessor = by_player_level, btree(columns = [player_id, level]))
)]
pub struct Score {
    pub player_id: u32,
    pub level: u32,
    pub points: i64,
}

for row in ctx.db.score().by_player_level().filter(&(42,)) {}
for row in ctx.db.score().by_player_level().filter(&(42, 5)) {}

Event Tables

#[table(accessor = damage_event, public, event)]
pub struct DamageEvent {
    pub target: Identity,
    pub amount: u32,
}

#[reducer]
fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) {
    ctx.db.damage_event().insert(DamageEvent { target, amount });
}

Event tables must be subscribed explicitly and are excluded from subscribe_to_all_tables().

In 2.5, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.

Event-table primary keys and constraints are enforced only within the current transaction. They do not make event rows persistent, and client SDKs expose event tables as insert-only event streams. Do not rely on OnUpdate / on_update / onUpdate for event tables; use a persistent table or a primary-keyed procedural view when update callbacks are required.

Official 2.4.1/2.5 release notes tie primary-key-backed update callbacks to procedural views, not event tables.

Views

#[spacetimedb::view(accessor = my_players, public, primary_key = id)]
pub fn my_players(ctx: &spacetimedb::ViewContext) -> Vec<Player> {
    ctx.db.player().owner().filter(&ctx.sender()).collect()
}

Rust and TypeScript gained primary key support for procedural views in 2.4.1. With primary keys, clients can receive update events when subscribed to such views. Avoid duplicate primary keys in view results.

Lifecycle & Scheduled Reducers

#[spacetimedb::reducer(init)]
pub fn init(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }

#[spacetimedb::reducer(client_connected)]
pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }

#[spacetimedb::reducer(client_disconnected)]
pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }

use spacetimedb::{ScheduleAt, TimeDuration};

ctx.db.game_tick_schedule().insert(GameTickSchedule {
    scheduled_id: 0,
    scheduled_at: ScheduleAt::Interval(std::time::Duration::from_millis(100).into()),
});

let run_at = ctx.timestamp + std::time::Duration::from_secs(60);
ctx.db.game_tick_schedule().insert(GameTickSchedule {
    scheduled_id: 0,
    scheduled_at: ScheduleAt::Time(run_at),
});

For scheduled reducers, check ctx.sender_auth().is_internal() when the reducer should only be system-triggered.

Procedures

Procedures are stable in 2.5 and no longer require the unstable feature.

use spacetimedb::{procedure, ProcedureContext};

#[procedure]
fn save_external_data(ctx: &mut ProcedureContext, url: String) -> Result<(), String> {
    let body = ctx.http.get(url).send()?.text()?;
    ctx.try_with_tx(|tx| {
        tx.db.external_data().insert(ExternalData { id: 0, content: body });
        Ok(())
    })?;
    Ok(())
}

Reducers	Procedures
&ReducerContext	&mut ProcedureContext
Direct ctx.db access	Use with_tx() / try_with_tx()
No HTTP/network	Outgoing HTTP via ctx.http
Deterministic transaction path	Side-effect-capable workflow path

In Genarrative, keep external provider protocols in platform-* by default unless the architecture explicitly moves that workflow into the module.

Identity & Auth

fn require_owner(ctx: &ReducerContext, owner: &Identity) -> Result<(), String> {
    if ctx.sender() != *owner {
        return Err("Not authorized".to_string());
    }
    Ok(())
}

ReducerContext::identity is deprecated since 2.3; use the current database/module identity API when needed, and use ctx.sender() for caller identity.

Commands

spacetime build
spacetime publish my_database --server http://127.0.0.1:3101 --module-path . --yes=migrate
spacetime publish my_database --server http://127.0.0.1:3101 --delete-data=on-conflict --module-path . --yes=migrate
spacetime logs my_database --server http://127.0.0.1:3101
spacetime call --server http://127.0.0.1:3101 my_database create_player '"Alice"'
spacetime sql my_database --server http://127.0.0.1:3101 "SELECT * FROM player"
npm run spacetime:generate
npm run check:spacetime-schema