Bradley/stackbench test

.gitattributes

@@ -2,3 +2,28 @@
 **/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
+/tools/stack-bench/qualification-evidence/**/*.json -text whitespace=cr-at-eol
+/tools/stack-bench/qualification-evidence/ecommerce-l3-navigation-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-readiness-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-module-layout-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-count-observation-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-catalog-support-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-readiness-final-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-entry-navigation-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-audit-fixes-ea80500/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-crash-order-20260927/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-signup-writes-20260928/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-restored-navigation-20260928/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-faceted-ranking-20260928/Dockerfile -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-checkout-readiness-20260928/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-click-classifier-20260928/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-probe-removal-20260928/** -text -whitespace
+
+# Preserve exact measured cookie-control evidence bytes.
+tools/stack-bench/qualification-evidence/ecommerce-l3-cookie-session-20260928/** -text -whitespace
+
+# Preserve exact measured combined-control evidence bytes.
+tools/stack-bench/qualification-evidence/ecommerce-l3-combined-20260929/** -text -whitespace
+/tools/stack-bench/qualification-evidence/ecommerce-l3-opus55-c34ab8c8a7/** -text -whitespace

.gitignore

@@ -276,6 +276,9 @@ nul
 # Any local file
 *.local
 
+# Local working notes and temporary builds
+/local-notes/
+
 # Generated when testing or publishing the TypeScript module test utilities.
 /crates/bindings-typescript/src/server/test-utils/portable-datastore-wasm/
 /crates/bindings-typescript/src/server/test-utils/.portable-datastore-wasm-*/

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
@@ -114,7 +116,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
@@ -172,10 +174,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

@@ -152,7 +152,9 @@ Calls made while disconnected fail immediately. Pending reducer and procedure pr
 
 ## 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,27 @@ 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. `ctx.connectionId` identifies that connection.
+`ctx.sender` identifies the authenticated caller and stays the same when the client
+reconnects with the same token.
+
+Use connection IDs for connection state, such as presence. A reload or network loss can
+cause a disconnect. A disconnect alone does not mean the user signed out or their
+application login expired. Keep connection cleanup separate from session revocation.
+
+`ctx.sender` is a SpacetimeDB identity, not necessarily an application account. Separate
+identities can authenticate to the same application account. An application sign-out leaves
+the identity unchanged, so data scoped to `ctx.sender` stays available to that client.
+
+`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
@@ -282,17 +306,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):
@@ -328,6 +365,9 @@ Procedural views read through `ctx.db` and return materialized values such as ar
 
 ## Client Visibility Filters
 
+Client visibility filters are experimental and may change or be removed. Use views for access
+control. `:sender` is the requesting client's identity.
+
 ```typescript
 export const privateNoteFilter = spacetimedb.clientVisibilityFilter.sql(
   'SELECT * FROM owned_row WHERE owner = :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/src/sdk/ws.ts

@@ -95,12 +95,16 @@ export async function openWebSocket({
 
   const WS = await resolveWS();
 
+  // Endpoints resolve under the URI's path, so `ws://host/stdb` reaches `/stdb/v1/...`.
+  const base = new URL(url);
+  if (!base.pathname.endsWith('/')) base.pathname += '/';
+
   // We swap our original token to a shorter-lived token
   // to avoid sending the original via query params.
   let temporaryAuthToken: string | undefined;
   if (authToken) {
     headers.set('Authorization', `Bearer ${authToken}`);
-    const tokenUrl = new URL('v1/identity/websocket-token', url);
+    const tokenUrl = new URL('v1/identity/websocket-token', base);
     tokenUrl.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
 
     const response = await fetch(tokenUrl, { method: 'POST', headers });
@@ -112,7 +116,7 @@ export async function openWebSocket({
     }
   }
 
-  const databaseUrl = new URL(`v1/database/${nameOrAddress}/subscribe`, url);
+  const databaseUrl = new URL(`v1/database/${nameOrAddress}/subscribe`, base);
   if (temporaryAuthToken) {
     databaseUrl.searchParams.set('token', temporaryAuthToken);
   }

crates/bindings-typescript/src/server/runtime.ts

@@ -218,15 +218,27 @@ class AuthCtxImpl implements AuthCtx {
     });
   }
 
-  /** If there is a connection id, look up the JWT payload from the system tables. */
+  /** Create a context for an HTTP request, which has no connection but is not host-originated. */
+  static httpRequest(): AuthCtx {
+    return new AuthCtxImpl({
+      isInternal: false,
+      jwtSource: () => null,
+      senderIdentity: Identity.zero(),
+    });
+  }
+
+  /**
+   * If there is a connection id, look up the JWT payload from the system tables.
+   * A call without one was spawned by the database, such as `init` or a scheduled function.
+   */
   static fromBackend(
     connectionId: ConnectionId | null,
     sender: Identity,
     backend: DatastoreBackend
   ): AuthCtx {
     if (connectionId === null) {
       return new AuthCtxImpl({
-        isInternal: false,
+        isInternal: true,
         jwtSource: () => null,
         senderIdentity: sender,
       });
@@ -357,6 +369,13 @@ export const ReducerCtxImpl = class ReducerCtx<
     }
   }
 
+  /** A transaction inside an HTTP handler, which reports external authority. */
+  static forHttpHandler(timestamp: Timestamp, dbView: DbView<any>) {
+    const tx = new ReducerCtx<any>(Identity.zero(), timestamp, null, dbView);
+    tx.#senderAuth = AuthCtxImpl.httpRequest();
+    return tx;
+  }
+
   get databaseIdentity() {
     return (this.#identity ??= new Identity(this.#backend.identity()));
   }
@@ -887,12 +906,7 @@ class HandlerContextImpl<S extends UntypedSchemaDef = UntypedSchemaDef>
   withTx<T>(body: (ctx: any) => T): T {
     const dispatches = this.#dispatches;
     return runWithTx(timestamp => {
-      const tx = new ReducerCtxImpl(
-        Identity.zero(),
-        timestamp,
-        null,
-        this.#dbView()
-      );
+      const tx = ReducerCtxImpl.forHttpHandler(timestamp, this.#dbView());
       if (dispatches.length > 0) {
         tx.as = buildAliasCtxMap(tx, dispatches, '') as any;
       }
@@ -1011,10 +1025,8 @@ function buildHandlerAliasCtx(
     as: subAs,
     withTx(body: any) {
       return runWithTx((ts: Timestamp) => {
-        const tx = new ReducerCtxImpl(
-          Identity.zero(),
+        const tx = ReducerCtxImpl.forHttpHandler(
           ts,
-          null,
           (nsDb_ ??= buildDbViewForDispatch(
             dispatch,
             namePrefix

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import * as sys from 'spacetime:sys@2.0';
+import { schema } from '../src/server/schema';
+import { ReducerCtxImpl } from '../src/server/runtime';
+import { table } from '../src/lib/table';
+import { t } from '../src/lib/type_builders';
+import { Timestamp } from '../src/lib/timestamp';
+
+describe('ctx.senderAuth', () => {
+  function senderAuthFor(connectionId: bigint) {
+    const items = table({ name: 'items' }, { id: t.u32().primaryKey() });
+    const module = schema({ items });
+    let isInternal: boolean | undefined;
+    const check = module.reducer(ctx => {
+      isInternal = ctx.senderAuth.isInternal;
+    });
+    const hooks = (module as any)[(sys as any).moduleHooks]({ check });
+    hooks.__call_reducer__(
+      0,
+      0n,
+      connectionId,
+      0n,
+      new DataView(new ArrayBuffer(0))
+    );
+    return isInternal;
+  }
+
+  it('is internal for a reducer the database spawns without a connection', () => {
+    expect(senderAuthFor(0n)).toBe(true);
+  });
+
+  it('is external for a reducer called over a connection', () => {
+    expect(senderAuthFor(7n)).toBe(false);
+  });
+
+  it('is external for a transaction inside an HTTP handler', () => {
+    const tx = ReducerCtxImpl.forHttpHandler(new Timestamp(0n), {} as never);
+    expect(tx.connectionId).toBeNull();
+    expect(tx.senderAuth.isInternal).toBe(false);
+    expect(tx.senderAuth.hasJWT).toBe(false);
+  });
+});