rastack 0.0.63 → 0.0.69

package/provider/provider.tsx

@@ -14,23 +14,10 @@ import {
   RastackEngine,
   RAStackProviderConfig,
   RadStatus,
-  WarehouseSource,
 } from "./types";
-import { createEngine, createWasmAdapter, defaultEngineLoader } from "./wasm";
 import {
-  debounce,
-  downloadBlob,
-  manifestResources,
-  seedFromIceberg,
-  WarehousePersistence,
-} from "./warehouse";
-import {
-  CacheStorage,
   defaultCacheStorage,
   deleteIndexedDb,
-  httpFileSource,
-  IcebergFileCache,
-  isAccessRevoked,
   purgeIdentityCache,
 } from "../cache";
 import {
@@ -45,13 +32,18 @@ import { getGlobalManifest } from "../hooks/manifest";
 const RastackContext = createContext<RastackClient | null>(null);
 
 /**
- * The one place a React app configures *where the API runs* — over HTTP
- * (`remote`), in the browser via WebAssembly (`local`), or in the browser
- * against S3 (`s3`). It reconfigures the shared axios client in place, so every
- * generated hook keeps working with no changes.
+ * The one place a React app configures *where the API runs*. Every mode talks
+ * HTTP to a native Rust server (`rastack-server` locally, Lambda in
+ * production). The browser does not execute the engine.
+ *
+ * - `local` — same origin (or `baseURL`). `rastack dev` proxies `/api` to the
+ *   native process whose warehouse is the on-disk directory.
+ * - `s3` — the same HTTP client. The native process owns an `s3://` warehouse.
+ *   The page does not open the bucket.
+ * - `remote` — HTTP to `baseURL` (Lambda or a server you already started).
  *
  * ```tsx
- * <RAStackProvider mode="local" manifest={schema} warehouseBaseUrl="/data/warehouse/">
+ * <RAStackProvider mode="local" manifest={schema}>
  *   <App />
  * </RAStackProvider>
  * ```
@@ -62,8 +54,6 @@ export function RAStackProvider({
 }: RAStackProviderConfig & { children: ReactNode }): JSX.Element {
   const [status, setStatus] = useState<RadStatus>("idle");
   const engineRef = useRef<RastackEngine | null>(null);
-  const persistRef = useRef<(() => void) & { flush: () => void }>();
-  const cacheStorageRef = useRef<CacheStorage | null>(null);
 
   // The `manifest` prop is optional: when the rastack dev-server plugin is
   // in the bundler it registers the compiled schema globally before the app
@@ -90,7 +80,6 @@ export function RAStackProvider({
       ? userAuth(config.identity, config.groups ?? [])
       : undefined);
   const identity = config.identity ?? auth?.sub;
-  const groups = config.groups ?? auth?.groups ?? [];
 
   // Locally persisted state is namespaced per identity, so two accounts on
   // one device never share bytes.
@@ -99,10 +88,12 @@ export function RAStackProvider({
     identity,
   );
 
-  /** Delete everything this identity persisted locally. */
+  /** Delete leftover device bytes (file cache, old warehouse snapshots). */
   const purgeLocal = async () => {
-    if (cacheStorageRef.current) {
-      await purgeIdentityCache(cacheStorageRef.current, identity);
+    try {
+      await purgeIdentityCache(defaultCacheStorage(), identity);
+    } catch {
+      /* no IndexedDB in this runtime */
     }
     await deleteIndexedDb(warehouseDb);
     // Replicated rows in the sync engine's store are derived from the same
@@ -132,87 +123,15 @@ export function RAStackProvider({
         });
       }
 
-      if (config.mode === "remote") {
+      // Every mode is HTTP to a native server. `local` uses this origin
+      // (`rastack dev` proxies `/api`). `s3` is the same client — the native
+      // process holds the `s3://` warehouse. `remote` with no baseURL keeps
+      // the historical default (NEXT_PUBLIC_BASE_URL or 127.0.0.1:8000).
+      if (config.mode === "remote" && config.baseURL === undefined) {
+        resetApi();
+      } else {
         configureApi({ baseURL: config.baseURL ?? "", adapter: null });
-        if (config.baseURL === undefined) resetApi();
-        setStatusSafe("ready");
-        return;
-      }
-
-      // -- WASM modes (local / s3) --
-      if (!manifest) {
-        throw new Error(
-          "RAStackProvider: no manifest found for local/s3 mode — add rastackPlugin() to your bundler (rastack/plugin), or pass the `manifest` prop.",
-        );
-      }
-
-      setStatusSafe("loading");
-      const loader = config.loadEngine ?? defaultEngineLoader;
-      const mod = await loader();
-      if (cancelled) return;
-      const engine = createEngine(mod, manifest, config.openapi);
-
-      // Run the in-browser engine as the signed-in identity so owner stamping
-      // and row-level security match the server exactly.
-      if (identity) {
-        engine.setAuth?.(identity, groups);
-      }
-
-      // Warehouse persistence: IndexedDB for `local`, an S3 sink for `s3`.
-      const persistence = pickPersistence(config, warehouseDb);
-
-      setStatusSafe("seeding");
-      try {
-        // A persisted local copy (with the user's edits) wins; otherwise seed
-        // from the warehouse's own Iceberg files — through the local file
-        // cache by default, so a warm client revalidates one small pointer
-        // per table and reads everything else from the device.
-        const existing = await persistence.load();
-        if (existing) {
-          await engine.importWarehouse(existing);
-        } else {
-          const base = config.warehouseBaseUrl ?? "/data/warehouse/";
-          const resources = manifestResources(manifest);
-          if (config.cache === false) {
-            await seedFromIceberg(engine, base, resources);
-          } else {
-            const storage =
-              typeof config.cache === "object"
-                ? config.cache
-                : defaultCacheStorage();
-            cacheStorageRef.current = storage;
-            const cache = new IcebergFileCache({
-              storage,
-              source: config.fileSource ?? httpFileSource(base),
-              identity,
-              maxOfflineMs: config.maxOfflineMs,
-            });
-            await cache.seed(engine, resources);
-          }
-        }
-      } catch (error) {
-        if (isAccessRevoked(error)) {
-          // Access is gone ⇒ so is every locally persisted byte it fetched.
-          await handleAccessRevoked();
-          return;
-        }
-        throw error;
       }
-      if (cancelled) return;
-
-      const persist = debounce(() => {
-        void engine
-          .exportWarehouse()
-          .then((blob) => persistence.save(blob))
-          .catch((error) => config.onError?.(error));
-      }, 400);
-      persistRef.current = persist;
-
-      engineRef.current = engine;
-      configureApi({
-        baseURL: "",
-        adapter: createWasmAdapter(engine, persist),
-      });
       setStatusSafe("ready");
     }
 
@@ -224,7 +143,6 @@ export function RAStackProvider({
 
     return () => {
       cancelled = true;
-      persistRef.current?.flush();
       if (ejectToken !== undefined) API.interceptors.request.eject(ejectToken);
       resetApi();
       engineRef.current = null;
@@ -241,19 +159,17 @@ export function RAStackProvider({
         return engineRef.current;
       },
       async exportWarehouse() {
-        if (!engineRef.current) {
-          throw new Error(
-            "exportWarehouse is only available in local/s3 mode.",
-          );
-        }
-        return engineRef.current.exportWarehouse();
+        throw new Error(
+          "The warehouse lives in the native rastack-server process. The browser does not snapshot it.",
+        );
       },
-      async downloadWarehouse(filename = "warehouse-snapshot.json") {
-        const blob = await this.exportWarehouse();
-        downloadBlob(blob, filename);
+      async downloadWarehouse() {
+        throw new Error(
+          "The warehouse lives in the native rastack-server process. The browser does not snapshot it.",
+        );
       },
       async persistNow() {
-        persistRef.current?.flush();
+        /* The native server writes the warehouse as it handles each request. */
       },
       async purgeLocal() {
         await purgeLocal();
@@ -280,25 +196,6 @@ export function RAStackProvider({
   );
 }
 
-function pickPersistence(
-  config: RAStackProviderConfig,
-  databaseName: string,
-): WarehouseSource {
-  if (config.mode === "s3") {
-    if (!config.warehouse) {
-      throw new Error(
-        "RAStackProvider: `warehouse` (a WarehouseSource over S3) is required in s3 mode.",
-      );
-    }
-    return config.warehouse;
-  }
-  if (config.persist === false) {
-    return { load: async () => null, save: async () => {} };
-  }
-  const store = new WarehousePersistence(databaseName);
-  return { load: () => store.load(), save: (blob) => store.save(blob) };
-}
-
 /** Suffix a local database/cache name with the identity that owns it. */
 function withIdentity(name: string, identity?: string): string {
   return identity ? `${name}::${identity}` : name;
@@ -315,7 +212,7 @@ export function useRastackClient(): RastackClient {
   return client;
 }
 
-/** Just the current status — handy for a loading gate while WASM boots. */
+/** Just the current status — handy for a loading gate. */
 export function useRadStatus(): RadStatus {
   return useRastackClient().status;
 }

package/provider/types.ts

@@ -2,19 +2,17 @@
  * Configuration for `<RAStackProvider>` — the single place a React app chooses
  * *where the API runs*:
  *
- * - `remote` — talk to the Rust API over HTTP (Lambda in prod, `rastack serve`
- *   locally). The classic client/server split.
- * - `local`  — compile-free local development: the entire API runs in the
- *   browser via WebAssembly over an in-memory Iceberg warehouse, seeded from a
- *   repo `data/` folder and persisted to IndexedDB. No server, no network,
- *   instant reads/writes.
- * - `s3`     — full client mode: the same WASM engine, but the warehouse is
- *   loaded from and saved back to S3, so a static site reads and writes the
- *   object-storage database directly.
+ * - `remote` — talk to the Rust API over HTTP (Lambda in prod, a
+ *   `rastack-server` you already started).
+ * - `local`  — HTTP to the native `rastack-server` that `rastack dev` starts
+ *   and proxies at `/api` on this origin. The warehouse is that process's
+ *   on-disk directory. The browser does not run the engine.
+ * - `s3`     — the same HTTP client. The native server (Lambda, or
+ *   `rastack-server` pointed at `s3://`) owns the bucket. The page does not.
  */
 export type RadMode = "remote" | "local" | "s3";
 
-/** The subset of the WASM `RastackApi` class the provider uses. */
+/** The `handle` seam the admin console uses. Backed by HTTP to the native server. */
 export interface RastackEngine {
   handle(
     method: string,
@@ -22,34 +20,14 @@ export interface RastackEngine {
     query: Record<string, string> | undefined,
     body: unknown,
   ): Promise<{ status: number; body: any }>;
-  /** Seed one Iceberg file (metadata or `.parquet` data file) at its key. */
+  /** Not available. The native server owns warehouse files. */
   seedFile(key: string, bytes: Uint8Array): Promise<void>;
   importWarehouse(blob: Uint8Array): Promise<void>;
   exportWarehouse(): Promise<Uint8Array>;
-  /**
-   * Run requests as a signed-in identity (Cognito `sub` + `cognito:groups`),
-   * so owner stamping / row-level security in the in-browser engine match the
-   * server. Optional for older engine bundles.
-   */
+  /** Not used. Identity is the bearer token the native server verifies. */
   setAuth?(subject: string | undefined, groups?: string[]): void;
 }
 
-/** Constructor of the generated `RastackApi` class. */
-export interface RastackEngineCtor {
-  new (manifestJson: string, openapiJson?: string): RastackEngine;
-}
-
-/** What a WASM bundle loader must resolve to. */
-export interface RastackWasmModule {
-  /** wasm-pack `web` target exposes an init fn that fetches the `.wasm`. */
-  default?: (input?: any) => Promise<any>;
-  init?: (input?: any) => Promise<any>;
-  RastackApi: RastackEngineCtor;
-}
-
-/** Load and initialise the compiled WASM engine module. */
-export type RastackEngineLoader = () => Promise<RastackWasmModule>;
-
 /** Where to read/write the warehouse blob in `s3` mode (or any custom sink). */
 export interface WarehouseSource {
   /** Fetch the current warehouse blob, or `null` if none exists yet. */
@@ -71,7 +49,7 @@ export interface RAStackProviderConfig {
   /**
    * The signed-in identity as a typed {@link import("../auth").RastackAuth} —
    * the one auth object the whole stack shares. Supplies `identity`/`groups`
-   * when those aren't set, runs the WASM engine as this identity, and is
+   * when those aren't set, and is
    * provided to the component tree (via `rastack/auth`'s context) so
    * `<AutoForm>` / `<DataTable>` gate their affordances against each
    * resource's `permission` + `access` policy automatically.
@@ -81,7 +59,7 @@ export interface RAStackProviderConfig {
    * The signed-in identity — the verified Cognito `sub`. It namespaces every
    * locally persisted byte (Iceberg file cache, warehouse snapshot DB), so
    * accounts sharing a device can't read each other's data, and it is the
-   * subject the WASM engine stamps/filters owner rows with. Defaults to
+   * subject the native server stamps/filters owner rows with. Defaults to
    * `auth.sub`.
    */
   identity?: string;
@@ -115,50 +93,33 @@ export interface RAStackProviderConfig {
    * `schema.rastack.json` (object or JSON string), the
    * `virtual:rastack-manifest` module, or `resource()` definitions (an array
    * or a module namespace), from which the provider builds the identical
-   * manifest at runtime. One of the two (plugin or prop) is required for
-   * WASM modes (the manifest drives the in-browser engine); it is also what
-   * lets `useData(Entity)` / `useForm(Entity)` resolve a plain TypeScript
-   * type to its resource at runtime.
+   * manifest at runtime. The native server reads the compiled manifest from
+   * disk; this copy is what lets `useData(Entity)` / `useForm(Entity)`
+   * resolve a plain TypeScript type to its resource in the browser.
    */
   manifest?: object | readonly object[] | string;
   /** `openapi.json` — object or JSON string. Optional (`/api/schema/`). */
   openapi?: object | string;
   /**
-   * Base URL of the committed Iceberg warehouse (a *directory of files*, not a
-   * blob) to seed `local` mode from. The provider walks the tree —
-   * `version-hint.text` → snapshot metadata → `.parquet` data files — exactly
-   * as the server walks it over object storage. Defaults to `/data/warehouse/`.
-   * Ignored once a persisted local copy exists.
+   * Unused by the request path. The native server opens the warehouse
+   * directory itself. Kept so existing call sites still type-check.
    */
   warehouseBaseUrl?: string;
-  /** Persist the local warehouse to IndexedDB between reloads (default true). */
+  /** Unused. The native server writes the warehouse itself. */
   persist?: boolean;
   /** IndexedDB database name for the local warehouse. */
   databaseName?: string;
   /**
-   * Cache the warehouse's Iceberg files locally (IndexedDB on web; supply a
-   * `CacheStorage` for React Native) so repeat loads revalidate one tiny
-   * pointer per table and read everything else from the device. `false`
-   * disables caching; default on. Immutable Parquet/metadata files are cached
-   * forever by key — invalidation is driven by Iceberg's own snapshot pointer.
+   * Unused by the request path. The native server reads the warehouse from
+   * disk or S3. Kept so existing call sites still type-check.
    */
   cache?: boolean | import("../cache").CacheStorage;
-  /**
-   * Where warehouse files are fetched from — defaults to HTTP GETs against
-   * `warehouseBaseUrl`. Supply a SigV4-signing source (AWS SDK S3 client over
-   * Cognito Identity Pool credentials) for `s3` mode. Must throw
-   * `AccessRevokedError` on 401/403 so revocation deletes local data.
-   */
+  /** Unused. The browser does not fetch warehouse files into an engine. */
   fileSource?: import("../cache").WarehouseFileSource;
-  /** `s3` mode: how to load/save the warehouse blob from object storage. */
+  /** Unused. The native server owns the `s3://` warehouse. */
   warehouse?: WarehouseSource;
-  /**
-   * Override how the WASM module is loaded. Supply this from app code (where
-   * your bundler can resolve the generated bundle) if the default loader can't
-   * find it. Defaults to importing `rastack/wasm/rastack_wasm.js`.
-   */
-  loadEngine?: RastackEngineLoader;
-
+  /** Unused. The native server opens the warehouse directory on disk. */
+  seedWarehouse?: () => Uint8Array | null | Promise<Uint8Array | null>;
   // -- lifecycle --
   onStatusChange?: (status: RadStatus) => void;
   onError?: (error: unknown) => void;
@@ -166,8 +127,8 @@ export interface RAStackProviderConfig {
 
 export type RadStatus =
   | "idle"
-  | "loading" // fetching/instantiating the WASM engine
-  | "seeding" // importing the warehouse
+  | "loading" // contacting the native server
+  | "seeding" // unused; the native server opens the warehouse itself
   | "ready"
   | "revoked" // access revoked — local data has been deleted
   | "error";
@@ -178,13 +139,13 @@ export interface RastackClient {
   status: RadStatus;
   /** The resolved identity this client runs as (from `auth` or `identity`). */
   auth?: import("../auth").RastackAuth;
-  /** The live WASM engine (null in `remote` mode). */
+  /** Always null. The engine is the native server, not an object in the page. */
   engine: RastackEngine | null;
-  /** Snapshot the local warehouse to a portable blob (WASM modes only). */
+  /** Throws. The native server owns the warehouse. */
   exportWarehouse(): Promise<Uint8Array>;
-  /** Download that snapshot as a file — a portable backup of local edits. */
+  /** Throws. The native server owns the warehouse. */
   downloadWarehouse(filename?: string): Promise<void>;
-  /** Force-persist now (IndexedDB and/or the `s3` sink). */
+  /** No-op. The native server writes each request as it handles it. */
   persistNow(): Promise<void>;
   /**
    * Delete everything this identity has persisted on the device — the Iceberg

package/src/compile/analyze.ts

@@ -179,7 +179,17 @@ function analyzeField(
     const app = literalTypeProp(fieldType, "__app", checker, initializer);
     const model = literalTypeProp(fieldType, "__model", checker, initializer);
     if (app && model) {
-      return { name, type: "fk", relation: { app, model } };
+      const fk: FieldModel = { name, type: "fk", relation: { app, model } };
+      // `s.ref(() => X, { null: true })` — a nullable relation (a shared secret
+      // with no project, an unassigned task). The options object is the ref
+      // call's second argument, read the same way scalar constraints are.
+      if (ts.isCallExpression(initializer)) {
+        const opts = literalToValue(initializer.arguments[1]);
+        if (opts && typeof opts === "object" && opts.null === true) {
+          fk.null = true;
+        }
+      }
+      return fk;
     }
     return undefined;
   }

package/src/compile/model.ts

@@ -87,7 +87,7 @@ export interface TransitionEdgeModel {
 /**
  * A resource's declarative state machine, keyed off one state field. Compiled
  * into the manifest and enforced on every write surface: the TS record machine
- * (forms, `rastack import`) and `rastack-api-core` (server, Lambda, WASM) all
+ * (forms, `rastack import`) and `rastack-api-core` (the native server) all
  * reject a write that jumps between states without a declared edge.
  */
 export interface TransitionsModel {

package/src/compile/run.ts

@@ -9,8 +9,8 @@ import { compile } from "./index";
  *
  * This is the single entry point the two real modalities of use share instead
  * of shelling out to a standalone `compile` command:
- *   • `rastack dev` / `rastack admin` — local development (compile, then serve
- *     the app + admin in the browser over WASM), and
+ *   • `rastack dev` / `rastack admin` — local development (compile, then start
+ *     the native rastack-server; the browser is only the UI), and
  *   • `rastack ci` — the deploy pipeline (compile the manifest the Rust backend
  *     reads + the OpenAPI contract, then build/ship).
  */

package/src/define/index.ts

@@ -66,6 +66,9 @@ export interface Ref<App extends string, Model extends string> {
   readonly __model: Model;
   /** The authored `() => Resource` thunk — carried at runtime. */
   readonly target?: () => ResourceType<App, Model, any>;
+  /** Optional FK constraints — `null: true` makes the relation nullable
+   * (e.g. a shared secret with no project, or an unassigned task). */
+  readonly options?: { null?: boolean };
 }
 
 export interface StringOptions {
@@ -153,8 +156,9 @@ export const s = {
    */
   ref<A extends string, M extends string>(
     thunk: () => ResourceType<A, M, any>,
+    options?: { null?: boolean },
   ): Ref<A, M> {
-    return { __rastackRef: true, target: thunk } as Ref<A, M>;
+    return { __rastackRef: true, target: thunk, options } as Ref<A, M>;
   },
 };
 
@@ -171,8 +175,7 @@ export interface SyncOptions {
 
 /**
  * Row-level access control. Enforced by `rastack-api-core`, so the rules are
- * identical on the server (Lambda / `rastack serve`) and in the in-browser WASM
- * engine.
+ * identical on the native server (laptop and Lambda).
  *
  * - `ownerField` — the field that records the owning identity (the verified
  *   token `sub`). Rows are only listed/read/written by their owner; the field
@@ -212,7 +215,7 @@ export type Permission = "authenticatedOrReadOnly" | "authenticated" | "public";
  * transition may fire from, `to` the state it enters, and `set` the effect —
  * field patches the engine applies alongside the state change. The block is
  * static data: it compiles into the manifest and is enforced by
- * `rastack-api-core` on every surface (server, Lambda, in-browser WASM), so a
+ * `rastack-api-core` on the native server (laptop and Lambda), so a
  * transition behaves as a declarative, typesafe backend function with no
  * per-resource server code.
  */

package/src/define/manifest.ts

@@ -121,11 +121,17 @@ function runtimeField(
         `manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`,
       );
     }
-    return {
+    const fk: FieldModel = {
       name,
       type: "fk",
       relation: { app: target.app, model: target.model },
     };
+    // A nullable FK (`s.ref(() => X, { null: true })`) — e.g. a shared secret
+    // with no project — so the engine allows and stores a null relation.
+    if ((field.options as { null?: boolean } | undefined)?.null === true) {
+      fk.null = true;
+    }
+    return fk;
   }
 
   if (typeof field.__rastackScalar !== "string") return undefined;