Bradley/stackbench test

.gitattributes

@@ -2,3 +2,5 @@
 **/ModuleBindings/** linguist-generated=true eol=lf
 /docs/llms/** linguist-generated=true
 /docs/llms/*-details.json linguist-generated=false
+/tools/stack-bench/** text eol=lf
+/tools/stack-bench/**/*.woff2 -text -diff

.gitignore

@@ -267,3 +267,6 @@ nul
 
 # Any local file
 *.local
+
+# Local working notes and temporary builds
+/local-notes/

codex-plugin/plugins/spacetimedb/skills/cli/SKILL.md

@@ -43,13 +43,15 @@ spacetime build --debug            # faster iteration, slower runtime
 
 # Dev mode (auto-rebuild, auto-publish, generates bindings)
 spacetime dev
-spacetime dev --client-lang typescript --module-bindings-path ./client/src/module_bindings
+spacetime dev my-database --server local --yes --delete-data=never --client-lang typescript --module-bindings-path ./client/src/module_bindings
 
 # Generate client bindings
 spacetime generate --lang typescript|csharp|rust --out-dir ./bindings --module-path ./server
 spacetime generate --lang unrealcpp --uproject-dir ./MyGame --module-path ./server --unreal-module-name MyGame
 ```
 
+`dev` stays running and watches module changes. `--run "npm run dev"` starts a client command; `--server-only` omits it. `--module-path` selects the module directory when no publish targets exist in `spacetime.json`. Once targets exist, use their configured paths and omit that flag. Separate build/publish/generate commands remain useful for one-shot deployment.
+
 ### Publishing & Deployment
 
 ```bash
@@ -112,7 +114,7 @@ spacetime server add myserver --url https://my-spacetime.example.com
 # Set default server
 spacetime server set-default local
 
-# Test connectivity
+# Check connectivity
 spacetime server ping local
 
 # Start local instance
@@ -169,10 +171,7 @@ spacetime server ping <server>
 ```
 
 ### "Schema conflict"
-```bash
-# Clear data and republish
-spacetime publish my-db --delete-data=always --yes
-```
+`--delete-data=never` rejects incompatible schema updates without clearing data. A compatible migration preserves existing data; `--delete-data=always` destroys it and is only appropriate for an intentional reset.
 
 ### "Build failed"
 ```bash

codex-plugin/plugins/spacetimedb/skills/concepts/SKILL.md

@@ -101,8 +101,8 @@ Lifecycle: Write → Compile → Publish (`spacetime publish`) → Hot-swap (rep
 
 ## Identity
 
-- **Identity**: A long-lived, globally unique identifier for a user.
-- **ConnectionId**: Identifies a specific client connection.
+- **Identity**: A long-lived, globally unique identifier for a user, derived from the token's issuer and subject claims. The same token yields the same identity on every connection.
+- **ConnectionId**: Identifies one client connection. A new connection gets a new connection ID; a disconnect ends the connection, not the identity.
 - Always use `ctx.sender` / `ctx.Sender` / `ctx.sender()` for authorization.
 
 SpacetimeDB works with many OIDC providers, including SpacetimeAuth (built-in), Auth0, Clerk, Keycloak, Google, and GitHub.

codex-plugin/plugins/spacetimedb/skills/cpp-server/SKILL.md

@@ -138,6 +138,8 @@ SPACETIMEDB_CLIENT_DISCONNECTED(on_disconnect, ReducerContext ctx) {
 }
 ```
 
+Connection hooks run once per connection. The same authenticated principal keeps the same identity (`ctx.sender()`) across connections, while each connection has its own connection ID (`ctx.connection_id()`). A disconnect ends one connection; it does not end the identity, which returns unchanged on the next connection with the same token. Use connection IDs for presence and other connection-scoped state.
+
 ## Authentication & Timestamps
 
 ```cpp

codex-plugin/plugins/spacetimedb/skills/csharp-server/SKILL.md

@@ -162,7 +162,9 @@ public static void OnConnect(ReducerContext ctx) { ... }
 public static void OnDisconnect(ReducerContext ctx) { ... }
 ```
 
-`ctx.ConnectionId` is `ConnectionId?`, including in connection lifecycle reducers. Check or unwrap it before storing it in a non-nullable column or passing it to an index accessor.
+Connection hooks run once per connection. The same authenticated principal keeps the same identity (`ctx.Sender`) across connections, while each connection has its own connection ID (`ctx.ConnectionId`). A disconnect ends one connection; it does not end the identity, which returns unchanged on the next connection with the same token. Use connection IDs for presence and other connection-scoped state.
+
+`ctx.ConnectionId` is typed `ConnectionId?`. It is present inside connection lifecycle reducers and reducers invoked over a connection, and null in `Init` and scheduled reducers. Check or unwrap it before storing it in a non-nullable column or passing it to an index accessor.
 
 ## Views
 

codex-plugin/plugins/spacetimedb/skills/rust-server/SKILL.md

@@ -150,6 +150,8 @@ pub fn on_connect(ctx: &ReducerContext) { ... }
 pub fn on_disconnect(ctx: &ReducerContext) { ... }
 ```
 
+Connection hooks run once per connection. The same authenticated principal keeps the same identity (`ctx.sender()`) across connections, while each connection has its own connection ID (`ctx.connection_id()`). A disconnect ends one connection; it does not end the identity, which returns unchanged on the next connection with the same token. Use connection IDs for presence and other connection-scoped state.
+
 The current connection ID is available through `ctx.connection_id()` (not a public field) and may be absent outside connection-scoped calls.
 
 ## Views

codex-plugin/plugins/spacetimedb/skills/typescript-client/SKILL.md

@@ -18,7 +18,7 @@ Generated bindings convert snake_case names to camelCase, including row fields:
 ## React: main.tsx
 
 ```typescript
-import React, { useEffect, useMemo } from 'react';
+import React, { useMemo } from 'react';
 import ReactDOM from 'react-dom/client';
 import { SpacetimeDBProvider } from 'spacetimedb/react';
 import { DbConnection } from './module_bindings';
@@ -30,6 +30,7 @@ function Root() {
     DbConnection.builder()
       .withUri(SPACETIMEDB_URI)
       .withDatabaseName(MODULE_NAME)
+      // Reuse the token issued on the previous connection.
       .withToken(localStorage.getItem('auth_token') || undefined),
     []
   );
@@ -46,27 +47,18 @@ ReactDOM.createRoot(document.getElementById('root')!).render(<Root />);
 ## React: App.tsx
 
 ```typescript
+import { useEffect } from 'react';
 import { useTable, useSpacetimeDB } from 'spacetimedb/react';
 import { DbConnection, tables } from './module_bindings';
 
 function App() {
-  const { isActive, identity: myIdentity, token, getConnection } = useSpacetimeDB();
+  const { identity: myIdentity, token, getConnection } = useSpacetimeDB();
   const conn = getConnection() as DbConnection | null;
 
-  // Save auth token
+  // Persist the issued token for the next page load.
   useEffect(() => { if (token) localStorage.setItem('auth_token', token); }, [token]);
 
-  // Subscribe when connected. Prefer typed query builders over raw SQL
-  useEffect(() => {
-    if (!conn || !isActive) return;
-    conn.subscriptionBuilder()
-      .onApplied(() => setSubscribed(true))
-      .subscribe([tables.entity, tables.record]);
-      // Or with filters: tables.entity.where(r => r.active.eq(true))
-      // Or raw SQL:      'SELECT * FROM entity'
-  }, [conn, isActive]);
-
-  // Reactive data. Returns [rows, isReady]
+  // useTable owns the subscription and cleanup. Returns [rows, isReady].
   const [entities, entitiesReady] = useTable(tables.entity);
   const [records, recordsReady] = useTable(tables.record);
 
@@ -80,8 +72,8 @@ function App() {
     }
   );
 
-  // Call reducers with object syntax
-  conn?.reducers.addRecord({ data }).catch(console.error);
+  // A callback for a UI event; defining it does not call the reducer during render.
+  const addRecord = (data: string) => conn?.reducers.addRecord({ data }).catch(console.error);
 
   // Compare identities
   const isMe = row.owner.toHexString() === myIdentity?.toHexString();
@@ -111,7 +103,9 @@ conn.db.user.onUpdate((ctx, oldUser, newUser) => console.log('Updated:', newUser
 
 ## Gotchas
 
-- **`useTable` rows are `readonly`.** Copy before sorting/mutating, or it fails to type-check:
+- **Subscription rows have no presentation order.** A server view's array order does not
+  define client cache iteration order. `useTable` rows are `readonly`; a sorted copy can
+  express the application's display order:
   `const [rows] = useTable(tables.message); const sorted = [...rows].sort(...)`.
-- **bigint in JSX.** ids/counts from `t.u64()`/`t.i64()` columns are `bigint`, which React
-  cannot render. Wrap it: `{Number(row.id)}` or `{String(count)}`.
+- **64-bit display values.** `{String(row.id)}` preserves the full `bigint` value.
+  Conversion to `Number` can lose precision outside JavaScript's safe integer range.

codex-plugin/plugins/spacetimedb/skills/typescript-server/SKILL.md

@@ -98,6 +98,11 @@ Every column is a `t` builder value:
 
 Modifiers: `.primaryKey()`, `.autoInc()`, `.unique()`, `.index('btree')`, `.default(value)`.
 
+`.primaryKey()` and `.unique()` apply to one column. For uniqueness across
+multiple columns, use a surrogate key, the multi-column index below, and a
+reducer that rejects an existing index match before inserting. An index alone
+does not enforce uniqueness.
+
 Use `.default(value)` only for a newly appended migration-safe field. Do not put defaults on primary-key, unique, or auto-increment columns.
 
 Optional columns: `nickname: t.option(t.string())`
@@ -130,7 +135,9 @@ export { default } from './schema';   // re-export the schema for the module ent
 
 ## Reducers
 
-Reducers are created with `spacetimedb.reducer(...)`; the export name becomes the reducer name:
+Reducers are created with `spacetimedb.reducer(...)`. An exported `signUp`
+becomes `signUp` in generated clients and `sign_up` in `spacetime call` and
+`describe`:
 
 ```typescript
 export const createEntity = spacetimedb.reducer(
@@ -178,10 +185,17 @@ export const onConnect = spacetimedb.clientConnected((ctx) => { ... });
 export const onDisconnect = spacetimedb.clientDisconnected((ctx) => { ... });
 ```
 
-`ctx.connectionId` is `ConnectionId | null`, including in lifecycle contexts. Guard it before passing it to a helper or using it as a table key.
+Connection hooks run once per connection. The same authenticated principal keeps the same identity (`ctx.sender`) across connections, while each connection has its own connection ID (`ctx.connectionId`). A disconnect ends one connection; it does not end the identity, which returns unchanged on the next connection with the same token. Use connection IDs for presence and other connection-scoped state. Reloads and temporary network loss also disconnect clients; application login expiry and explicit sign-out are separate from connection cleanup.
+
+`ctx.connectionId` is typed `ConnectionId | null`. It is present inside connection lifecycle hooks and reducers invoked over a connection, and `null` in `init` and scheduled reducers. Guard it before passing it to a helper or using it as a table key.
 
 ## Reducer Context API
 
+Each reducer call runs in one database transaction. An error that escapes the
+reducer rolls back its database changes. `ctx.sender` identifies the caller;
+application roles and permissions are not inferred from that identity. Table
+visibility and view filters control reads, not authorization to call reducers.
+
 `ctx` is the only source of sender identity, time, and randomness; stdlib clocks and RNG are unavailable in modules. Let exported callbacks infer their context type. In helpers, use `ReducerCtx<InferSchema<typeof spacetimedb>>`; do not annotate a context as `any`, because that erases table row types and can make `bigint` expressions infer as `number`.
 
 ```typescript
@@ -278,17 +292,30 @@ const Shape = t.enum('Shape', {
 A client subscribing to a view receives only the rows it returns. Use a per-user view
 (keyed on `ctx.sender`) for per-viewer access control: deleting a row it depends on
 (e.g. a membership row) automatically drops the rows it was exposing from that client.
+Use index accessors in views. Do not scan a whole table with `.iter()` when an
+indexed lookup can select the required rows.
 
 `t.row(...)` and `t.object(...)` return schema builders, not TypeScript runtime row types. Let a view callback infer its result, or annotate a separately declared structural type such as `Array<{ sku: bigint; label: string }>`. A named output type must not reuse the generated PascalCase name of its view accessor (for example, reserve `DiscountedProduct` for a `discounted_product` view).
 
+A view context is `ViewCtx<S>` (and `AnonymousViewCtx<S>`), both exported from
+`spacetimedb/server`. It carries `sender`, a read-only `db`, and `from`; it is
+not a `ReducerCtx`, so a helper shared between a reducer and a view must accept
+either:
+
+```typescript
+import type { ReducerCtx, ViewCtx, InferSchema } from 'spacetimedb/server';
+type S = InferSchema<typeof spacetimedb>;
+function stockOf(ctx: ReducerCtx<S> | ViewCtx<S>, itemId: bigint) { ... }
+```
+
 Both `spacetimedb.view(...)` and `spacetimedb.anonymousView(...)` take three arguments: view options, the declared return schema, and the callback.
 
 ```typescript
 // Anonymous view (same for all clients):
 export const activeUsers = spacetimedb.anonymousView(
   { name: 'active_users', public: true },
   t.array(entity.rowType),
-  (ctx) => [...ctx.db.entity.iter()].filter(e => e.active)
+  (ctx) => [...ctx.db.entity.active.filter(true)]        // active: t.bool().index('btree')
 );
 
 // Per-user view (varies by ctx.sender):

crates/bindings-typescript/src/lib/query.ts

@@ -248,19 +248,21 @@ export type NamespacedQueryBuilder<SchemaDef extends UntypedSchemaDef> =
  * A runtime reference to a table. This materializes the RowExpr for us.
  * TODO: Maybe add the full SchemaDef to the type signature depending on how joins will work.
  */
-export type TableRef<TableDef extends TypedTableDef> = Readonly<{
-  type: 'table';
-  sourceName: TableDef['sourceName'];
-  accessorName: string;
-  cols: RowExpr<TableDef>;
-  indexedCols: IndexedRowExpr<TableDef>;
-  tableDef: TableDef;
+// Keep this named so TypeScript diagnostics show `TableRef` instead of its
+// expanded structure.
+export interface TableRef<TableDef extends TypedTableDef> {
+  readonly type: 'table';
+  readonly sourceName: TableDef['sourceName'];
+  readonly accessorName: string;
+  readonly cols: RowExpr<TableDef>;
+  readonly indexedCols: IndexedRowExpr<TableDef>;
+  readonly tableDef: TableDef;
   // Delegated UntypedTableDef properties for compatibility.
-  columns: TableDef['columns'];
-  indexes: TableDef['indexes'];
-  rowType: TableDef['rowType'];
-  constraints: any;
-}>;
+  readonly columns: TableDef['columns'];
+  readonly indexes: TableDef['indexes'];
+  readonly rowType: TableDef['rowType'];
+  readonly constraints: any;
+}
 
 class TableRefImpl<TableDef extends TypedTableDef>
   implements TableRef<TableDef>, From<TableDef>

crates/bindings-typescript/tests/table_ref_error_message.test.ts

@@ -0,0 +1,79 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+const bindingsRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..'
+);
+
+function runTypecheck(source: string) {
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'stdb-tableref-diag-'));
+  const reproPath = path.join(tmpDir, 'repro.ts');
+  writeFileSync(reproPath, source);
+
+  try {
+    const options: ts.CompilerOptions = {
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.ESNext,
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      allowImportingTsExtensions: true,
+      noImplicitAny: true,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      useDefineForClassFields: true,
+      verbatimModuleSyntax: true,
+      isolatedModules: true,
+    };
+
+    const host = ts.createCompilerHost(options);
+    const program = ts.createProgram(
+      [reproPath, path.join(bindingsRoot, 'src/server/sys.d.ts')],
+      options,
+      host
+    );
+    const diagnostics = ts.getPreEmitDiagnostics(program);
+    return diagnostics.map(d =>
+      ts.flattenDiagnosticMessageText(d.messageText, '\n')
+    );
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+describe('TableRef diagnostics', () => {
+  const source = `
+import { t } from ${JSON.stringify(path.join(bindingsRoot, 'src/server/index.ts'))};
+import { table } from ${JSON.stringify(path.join(bindingsRoot, 'src/lib/table.ts'))};
+import { createTableRefFromDef } from ${JSON.stringify(path.join(bindingsRoot, 'src/lib/query.ts'))};
+import type { AllUnique } from ${JSON.stringify(path.join(bindingsRoot, 'src/lib/constraints.ts'))};
+
+const cartItem = table(
+  { name: 'cart_item' },
+  { id: t.u64().primaryKey().autoInc(), accountId: t.u64(), quantity: t.u32() }
+);
+
+const ref = createTableRefFromDef(cartItem as any, 'cartItem');
+type Boom = AllUnique<typeof ref, ['accountId']>;
+declare const b: Boom;
+`;
+
+  it('names the type instead of dumping its structure', () => {
+    const messages = runTypecheck(source);
+    const constraintError = messages.find(m =>
+      m.includes("does not satisfy the constraint 'UntypedTableDef'")
+    );
+
+    expect(constraintError).toBeDefined();
+    // The name, not the shape.
+    expect(constraintError).toContain('TableRef<');
+    expect(constraintError).not.toContain('type: "table"');
+    expect(constraintError).not.toContain('accessorName');
+    expect(constraintError.length).toBeLessThan(250);
+  }, 15000);
+});

crates/cli/build.rs

@@ -6,6 +6,7 @@ use std::process::Command;
 use toml::Value;
 
 fn main() {
+    println!("cargo:rerun-if-env-changed=SPACETIMEDB_NIX_BUILD_GIT_COMMIT");
     let git_hash = find_git_hash();
     println!("cargo:rustc-env=GIT_HASH={git_hash}");
 
@@ -110,6 +111,7 @@ fn generate_template_files() {
 
     // Embed skill files from skills/*/SKILL.md
     let skills_dir = repo_root.join("skills");
+    println!("cargo:rerun-if-changed={}", skills_dir.display());
     let skill_names = discover_skill_names(&skills_dir);
 
     generated_code.push_str("pub fn get_skill(name: &str) -> Option<&'static str> {\n");