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

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

@@ -30,6 +30,9 @@ function Root() {
     DbConnection.builder()
       .withUri(SPACETIMEDB_URI)
       .withDatabaseName(MODULE_NAME)
+      // Paired with the setItem in App.tsx below — read here, saved there.
+      // Without the save, every reload connects anonymously and is issued a
+      // new Identity, so the signed-in account appears to vanish.
       .withToken(localStorage.getItem('auth_token') || undefined),
     []
   );
@@ -53,7 +56,8 @@ function App() {
   const { isActive, identity: myIdentity, token, getConnection } = useSpacetimeDB();
   const conn = getConnection() as DbConnection | null;
 
-  // Save auth token
+  // Save the auth token. Required: without it the withToken read in main.tsx
+  // always misses, and a reload gets a new Identity instead of the account.
   useEffect(() => { if (token) localStorage.setItem('auth_token', token); }, [token]);
 
   // Subscribe when connected. Prefer typed query builders over raw SQL

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

@@ -98,6 +98,33 @@ Every column is a `t` builder value:
 
 Modifiers: `.primaryKey()`, `.autoInc()`, `.unique()`, `.index('btree')`, `.default(value)`.
 
+`.primaryKey()` and `.unique()` apply to **one column**. There is no composite
+primary key and no multi-column unique constraint — a uniqueness rule spanning
+two columns cannot be declared, and the database will not enforce it for you.
+
+For a table that is naturally keyed by a pair — stock per item per warehouse,
+membership per group per user — give it a surrogate key, add a multi-column
+index for lookups, and enforce the pair's uniqueness in the reducer that
+inserts:
+
+```typescript
+export const stock = table(
+  { name: 'stock', indexes: [{ accessor: 'by_item_warehouse', algorithm: 'btree',
+                               columns: ['itemId', 'warehouseId'] }] },
+  {
+    id: t.u64().primaryKey().autoInc(),   // surrogate: the pair cannot be the key
+    itemId: t.u64(),
+    warehouseId: t.u64(),
+    quantity: t.i32(),
+  }
+);
+
+// The reducer is what keeps the pair unique:
+const existing = [...ctx.db.stock.by_item_warehouse.filter([itemId, warehouseId])][0];
+if (existing) ctx.db.stock.id.update({ ...existing, quantity: existing.quantity + n });
+else ctx.db.stock.insert({ id: 0n, itemId, warehouseId, quantity: n });
+```
+
 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 +157,7 @@ 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(...)`; the export name becomes the reducer name. Clients call it by that name, but the **wire name is snake_case**, so `spacetime call` and `describe` want `sign_up` for an exported `signUp`:
 
 ```typescript
 export const createEntity = spacetimedb.reducer(
@@ -278,17 +305,35 @@ 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.
+Index accessors keep a view's work proportional to the rows it returns. A view covering
+several keys reads the index once per key: `for (const roomId of myRoomIds) for (const m
+of ctx.db.message.roomId.filter(roomId)) out.push(m);`.
 
 `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) { ... }
+```
+
+Passing a view context where a `ReducerCtx` is expected reports the mismatch as
+a fully expanded structural type, not as the name `ViewCtx` — so read the
+parameter, not the error.
+
 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,27 @@ 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;
+// Declared as an interface, not `Readonly<{ ... }>`, and that is load-bearing:
+// TypeScript prints anonymous object types STRUCTURALLY and interfaces BY NAME.
+// As an anonymous type, every constraint failure involving a table reference
+// recited all ten members with `cols` expanding through four levels of type
+// functions — 637 characters even after TypeScript's own truncation had fired.
+// As an interface the same error reads
+// `Type 'TableRef<...>' does not satisfy the constraint 'UntypedTableDef'`.
+// See tests/table_ref_error_message.test.ts.
+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/src/sdk/connection_manager.ts

@@ -145,9 +145,7 @@ class ConnectionManagerImpl {
         clearTimeout(managed.reconnectTimer);
         managed.reconnectTimer = null;
         managed.reconnectAttempt = 0;
-        if (managed.builder) {
-          this.#buildManagedConnection(managed, managed.builder);
-        }
+        this.#reconnectManagedConnection(managed);
         continue;
       }
 
@@ -179,9 +177,7 @@ class ConnectionManagerImpl {
     connection.disconnect();
     this.#updateState(managed, { isActive: false });
     managed.reconnectAttempt = 0;
-    if (managed.builder) {
-      this.#buildManagedConnection(managed, managed.builder);
-    }
+    this.#reconnectManagedConnection(managed);
   }
 
   /** Generates a unique key for a connection based on URI and module name. */
@@ -294,6 +290,33 @@ class ConnectionManagerImpl {
     }
   }
 
+  /**
+   * Reconnect as the identity we were last issued.
+   *
+   * A client that first connects anonymously builds its builder *before* it has
+   * a token, so that builder's token stays `undefined` for the lifetime of the
+   * page. Rebuilding from it presents no credentials, the host mints a **new**
+   * identity, and every row owned by the previous one silently becomes
+   * invisible — no error, and no callback in between for the application to
+   * intervene. Saving the token diligently does not help, because the stale
+   * builder is what gets rebuilt.
+   *
+   * The token is already known here: the connection adopts it on
+   * `IdentityToken` and `#updateState` records it, one line from where it was
+   * needed.
+   *
+   * Only the automatic reconnect paths use this. `retain()` and `rebuild()`
+   * take the caller's builder verbatim, because supplying a *different* token is
+   * exactly what `rebuild()` is for — swapping an anonymous session for a
+   * signed-in one, or logging out.
+   */
+  #reconnectManagedConnection(managed: ManagedConnection): void {
+    if (!managed.builder) return;
+    const token = managed.state?.token;
+    if (token) managed.builder.withToken(token);
+    this.#buildManagedConnection(managed, managed.builder);
+  }
+
   #buildManagedConnection<T extends DbConnectionImpl<any>>(
     managed: ManagedConnection,
     builder: DbConnectionBuilder<T>
@@ -349,7 +372,7 @@ class ConnectionManagerImpl {
         return;
       }
 
-      this.#buildManagedConnection(managed, managed.builder);
+      this.#reconnectManagedConnection(managed);
     }, delay);
   }