alepha 0.22.0 → 0.24.0

package/src/api/parameters/__tests__/$parameter.spec.ts

@@ -1,6 +1,7 @@
-import { Alepha, t } from "alepha";
+import { Alepha, jsonSchemaToZod, z } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { currentTenantAtom } from "alepha/security";
 import { describe, expect, it } from "vitest";
 import {
   $parameter,
@@ -8,9 +9,9 @@ import {
   ParameterProvider,
 } from "../index.ts";
 
-const featureSchema = t.object({
-  enableBeta: t.boolean(),
-  maxUploadSize: t.number(),
+const featureSchema = z.object({
+  enableBeta: z.boolean(),
+  maxUploadSize: z.number(),
 });
 
 describe("$parameter", () => {
@@ -578,9 +579,9 @@ describe("Cross-instance sync", () => {
 
 describe("Schema migration", () => {
   it("should keep valid value when schema is compatible", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.optional(t.number()),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number().optional(),
     });
 
     class AppConfig {
@@ -613,9 +614,9 @@ describe("Schema migration", () => {
   });
 
   it("should merge with defaults when adding a required field", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -650,11 +651,11 @@ describe("Schema migration", () => {
   });
 
   it("should reset to defaults when merge still invalid", async () => {
-    const schema = t.object({
-      items: t.array(
-        t.object({
-          x: t.number(),
-          y: t.number(),
+    const schema = z.object({
+      items: z.array(
+        z.object({
+          x: z.number(),
+          y: z.number(),
         }),
       ),
     });
@@ -694,9 +695,9 @@ describe("Schema migration", () => {
   });
 
   it("should use migrate function when provided", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -736,9 +737,9 @@ describe("Schema migration", () => {
   });
 
   it("should fall through to merge when migrate returns invalid value", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -775,9 +776,9 @@ describe("Schema migration", () => {
   });
 
   it("should not migrate when schema hash matches", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -818,8 +819,8 @@ describe("Schema migration", () => {
   });
 
   it("should handle type change by resetting to defaults", async () => {
-    const schema = t.object({
-      name: t.number(),
+    const schema = z.object({
+      name: z.number(),
     });
 
     class AppConfig {
@@ -853,8 +854,8 @@ describe("Schema migration", () => {
   });
 
   it("should handle removed fields gracefully", async () => {
-    const schema = t.object({
-      name: t.text(),
+    const schema = z.object({
+      name: z.text(),
     });
 
     class AppConfig {
@@ -888,9 +889,9 @@ describe("Schema migration", () => {
   });
 
   it("should not migrate when there is no DB value", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -916,9 +917,9 @@ describe("Schema migration", () => {
   });
 
   it("should handle migrate function that throws", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class AppConfig {
@@ -950,9 +951,9 @@ describe("Schema migration", () => {
   });
 
   it("should notify subscribers after auto-migration", async () => {
-    const schema = t.object({
-      name: t.text(),
-      age: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      age: z.number(),
     });
 
     class Config {
@@ -979,8 +980,9 @@ describe("Schema migration", () => {
     config.param.sub((v) => received.push(v));
 
     // Now save a value with old schema hash to trigger migration
-    // Reset migrationChecked to allow re-migration
-    (provider as any).migrationChecked.delete("migrate.notify.sub");
+    // Reset migrationChecked to allow re-migration. The value caches are now
+    // keyed `${org}:${name}` — no org atom in this test → the `~global` org.
+    (provider as any).migrationChecked.delete("~global:migrate.notify.sub");
     await provider.save(
       "migrate.notify.sub",
       { name: "alice" },
@@ -998,9 +1000,9 @@ describe("Schema migration", () => {
   });
 
   it("should handle completely new shape by resetting to defaults", async () => {
-    const schema = t.object({
-      width: t.number(),
-      height: t.number(),
+    const schema = z.object({
+      width: z.number(),
+      height: z.number(),
     });
 
     class Config {
@@ -1034,9 +1036,9 @@ describe("Schema migration", () => {
   });
 
   it("should only migrate once per lifecycle in Node.js", async () => {
-    const schema = t.object({
-      name: t.text(),
-      count: t.number(),
+    const schema = z.object({
+      name: z.text(),
+      count: z.number(),
     });
 
     class Config {
@@ -1421,6 +1423,44 @@ describe("getCurrentWithDefault", () => {
     });
     expect(result.schema).not.toBeNull();
   });
+
+  it("should return the schema as JSON Schema, not a raw ZodObject", async () => {
+    // Regression: the parameter's `schema` is a live `ZodObject`. It must be
+    // serialized to JSON Schema before transport — otherwise the action's
+    // `schema: z.json()` response validation rejects it ("expected record,
+    // received ZodObject at /schema"), 500-ing the admin Parameters UI when an
+    // item is opened. The UI rebuilds its form by round-tripping the value back
+    // through `jsonSchemaToZod` (the inverse of `z.toJSONSchema`).
+    class AppConfig {
+      features = $parameter({
+        name: "gwd.schema.json",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+    const result = await provider.getCurrentWithDefault("gwd.schema.json");
+
+    // A plain JSON-Schema record describing the parameter shape — never the
+    // Zod instance (which would have `_zod`/`def`, not `type`/`properties`).
+    expect(z.schema.isObject(result.schema as never)).toBe(false);
+    expect((result.schema as { type?: string }).type).toBe("object");
+    expect(
+      Object.keys((result.schema as { properties?: object }).properties ?? {}),
+    ).toEqual(expect.arrayContaining(["enableBeta", "maxUploadSize"]));
+
+    // Round-trips back to a working Zod schema for the admin form.
+    const rebuilt = jsonSchemaToZod(result.schema);
+    expect(
+      rebuilt.safeParse({ enableBeta: true, maxUploadSize: 42 }).success,
+    ).toBe(true);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1654,7 +1694,8 @@ describe("set with scheduled activation", () => {
 
     // cachedNext should be populated
     const providerAny = provider as any;
-    const cachedNext = providerAny.cachedNext.get("set.sched.cache");
+    // Value caches are keyed `${org}:${name}`; no org atom here → `~global`.
+    const cachedNext = providerAny.cachedNext.get("~global:set.sched.cache");
     expect(cachedNext).not.toBeUndefined();
     expect(cachedNext.content).toEqual({
       enableBeta: true,
@@ -1878,11 +1919,11 @@ describe("reloadNextInBackground", () => {
 });
 
 // ---------------------------------------------------------------------------
-// 10. ParameterTreeNode schema uses t.any() for children
+// 10. ParameterTreeNode schema uses z.any() for children
 // ---------------------------------------------------------------------------
 
 describe("ParameterTreeNode children structure", () => {
-  it("should produce correctly typed children at runtime despite t.any() schema", async () => {
+  it("should produce correctly typed children at runtime despite z.any() schema", async () => {
     const alepha = Alepha.create().with(AlephaOrmPostgres);
     alepha.with(AlephaApiParameters);
     await alepha.start();
@@ -2013,7 +2054,7 @@ describe("$parameter.name fallback", () => {
   it("should use ClassName.propertyKey when name option is omitted", async () => {
     class MySettings {
       theme = $parameter({
-        schema: t.object({ dark: t.boolean() }),
+        schema: z.object({ dark: z.boolean() }),
         default: { dark: false },
       });
     }
@@ -2031,7 +2072,7 @@ describe("$parameter.name fallback", () => {
     class MySettings {
       theme = $parameter({
         name: "app.ui.theme",
-        schema: t.object({ dark: t.boolean() }),
+        schema: z.object({ dark: z.boolean() }),
         default: { dark: false },
       });
     }
@@ -2246,3 +2287,141 @@ describe("set idempotency", () => {
     expect(received.length).toBe(0);
   });
 });
+
+describe("$parameter multi-tenant isolation", () => {
+  it("partitions stored values + caches by the active org (no cross-tenant read/write)", async () => {
+    class AppConfig {
+      settings = $parameter({
+        name: "club.settings",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 1 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+    const orgA = "00000000-0000-0000-0000-0000000000aa";
+    const orgB = "00000000-0000-0000-0000-0000000000bb";
+
+    // Org A writes its own value.
+    alepha.store.set(currentTenantAtom, { id: orgA });
+    await config.settings.set({ enableBeta: true, maxUploadSize: 10 });
+    expect(await config.settings.get()).toEqual({
+      enableBeta: true,
+      maxUploadSize: 10,
+    });
+
+    // Org B sees ONLY its default — never org A's value (the bug this fixes).
+    alepha.store.set(currentTenantAtom, { id: orgB });
+    expect(await config.settings.get()).toEqual({
+      enableBeta: false,
+      maxUploadSize: 1,
+    });
+
+    // Org B writes its own; org A is untouched.
+    await config.settings.set({ enableBeta: false, maxUploadSize: 99 });
+    expect(await config.settings.get()).toEqual({
+      enableBeta: false,
+      maxUploadSize: 99,
+    });
+
+    alepha.store.set(currentTenantAtom, { id: orgA });
+    expect(await config.settings.get()).toEqual({
+      enableBeta: true,
+      maxUploadSize: 10,
+    });
+
+    await alepha.stop();
+  });
+
+  it("revalidates a stale cache after PARAMETERS_CACHE_TTL_MS (cross-isolate write)", async () => {
+    class AppConfig {
+      flags = $parameter({
+        name: "app.ttlRevalidation.flags",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 1 },
+      });
+    }
+
+    // Writes a new version to the DB WITHOUT touching this instance's
+    // in-memory cache — exactly what a `set()` handled by ANOTHER worker
+    // isolate looks like from here (the sync topic rides the in-memory
+    // queue, so it never crosses isolates).
+    class TestableProvider extends ParameterProvider {
+      writeBehindCache(name: string, value: Record<string, unknown>) {
+        return this.save(name, value, this.schemaHashes.get(name) ?? "", {});
+      }
+    }
+
+    const alepha = Alepha.create({
+      env: { ...process.env, PARAMETERS_CACHE_TTL_MS: "50" },
+    });
+    alepha.with({ provide: ParameterProvider, use: TestableProvider });
+    alepha.with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+    await config.flags.set({ enableBeta: false, maxUploadSize: 1 });
+    expect((await config.flags.get()).enableBeta).toBe(false);
+
+    const provider = alepha.inject(ParameterProvider) as TestableProvider;
+    await provider.writeBehindCache("app.ttlRevalidation.flags", {
+      enableBeta: true,
+      maxUploadSize: 2,
+    });
+
+    // Within the TTL the (stale) cache still serves.
+    expect((await config.flags.get()).enableBeta).toBe(false);
+
+    // Past the TTL, get() re-reads the DB and converges.
+    await new Promise((r) => setTimeout(r, 80));
+    expect((await config.flags.get()).enableBeta).toBe(true);
+
+    await alepha.stop();
+  });
+
+  it("keeps the historical never-revalidate behaviour when the TTL is 0", async () => {
+    class AppConfig {
+      flags = $parameter({
+        name: "app.ttlZero.flags",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 1 },
+      });
+    }
+
+    class TestableProvider extends ParameterProvider {
+      writeBehindCache(name: string, value: Record<string, unknown>) {
+        return this.save(name, value, this.schemaHashes.get(name) ?? "", {});
+      }
+    }
+
+    const alepha = Alepha.create({
+      env: { ...process.env, PARAMETERS_CACHE_TTL_MS: "0" },
+    });
+    alepha.with({ provide: ParameterProvider, use: TestableProvider });
+    alepha.with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+    await config.flags.set({ enableBeta: false, maxUploadSize: 1 });
+
+    const provider = alepha.inject(ParameterProvider) as TestableProvider;
+    await provider.writeBehindCache("app.ttlZero.flags", {
+      enableBeta: true,
+      maxUploadSize: 2,
+    });
+
+    await new Promise((r) => setTimeout(r, 80));
+    expect((await config.flags.get()).enableBeta).toBe(false);
+
+    await alepha.stop();
+  });
+});

package/src/api/parameters/controllers/AdminParameterController.ts

@@ -1,4 +1,4 @@
-import { $inject, Alepha, AlephaError, t } from "alepha";
+import { $inject, Alepha, AlephaError, z } from "alepha";
 import { $secure } from "alepha/security";
 import { $action, okSchema } from "alepha/server";
 import { ParameterAudits } from "../audits/ParameterAudits.ts";
@@ -43,7 +43,7 @@ export class AdminParameterController {
     path: "/parameters/tree",
     method: "GET",
     schema: {
-      response: t.array(parameterTreeNodeSchema),
+      response: z.array(parameterTreeNodeSchema),
     },
     handler: async () => {
       return this.provider.getParameterTree();
@@ -80,9 +80,9 @@ export class AdminParameterController {
     method: "GET",
     schema: {
       params: parameterNameParamSchema,
-      query: t.object({
-        limit: t.optional(t.integer({ minimum: 1, maximum: 100 })),
-        offset: t.optional(t.integer({ minimum: 0 })),
+      query: z.object({
+        limit: z.integer().min(1).max(100).optional(),
+        offset: z.integer().min(0).optional(),
       }),
       response: parameterHistoryResponseSchema,
     },
@@ -305,14 +305,11 @@ export class AdminParameterController {
     path: "/parameters/delete",
     method: "POST",
     schema: {
-      body: t.object({
-        names: t.array(t.string({ minLength: 1 }), {
-          minItems: 1,
-          maxItems: 1000,
-        }),
+      body: z.object({
+        names: z.array(z.string().min(1)).min(1).max(1000),
       }),
-      response: t.object({
-        deleted: t.array(t.string()),
+      response: z.object({
+        deleted: z.array(z.string()),
       }),
     },
     handler: async ({ body }) => {

package/src/api/parameters/entities/parameters.ts

@@ -1,4 +1,4 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 import { $entity, db } from "alepha/orm";
 
 /**
@@ -12,73 +12,86 @@ import { $entity, db } from "alepha/orm";
  */
 export const parameters = $entity({
   name: "parameters",
-  schema: t.object({
-    id: db.primaryKey(t.uuid()),
+  schema: z.object({
+    id: db.primaryKey(z.uuid()),
     createdAt: db.createdAt(),
     updatedAt: db.updatedAt(),
 
+    /**
+     * Tenant scope. NULLABLE on purpose (backward compatible): single-tenant
+     * apps keep writing org-less (NULL) rows with the historic global
+     * semantics. In a MULTI-TENANT process (e.g. one pooled worker serving
+     * many orgs), the active tenant is stamped by the Repository
+     * (`stampOrganization`) and reads/writes auto-filter by it — so one org's
+     * `app.settings`/`portal.site`/… can never be read or overwritten by
+     * another. The provider's in-memory value caches are keyed by org too.
+     */
+    organizationId: db.organization(),
+
     /**
      * Configuration name using dot notation for tree hierarchy.
      * Examples: "app.features", "app.pricing.tiers", "system.limits"
      */
-    name: t.text(),
+    name: z.text(),
 
     /**
      * The configuration content as JSON.
      */
-    content: t.json(),
+    content: z.json(),
 
     /**
      * Schema version hash for detecting schema changes.
      * Used for auto-migration when schema evolves.
      */
-    schemaHash: t.text(),
+    schemaHash: z.text(),
 
     /**
      * When this version should become active.
      * Default is immediate (now).
      */
-    activationDate: t.datetime(),
+    activationDate: z.datetime(),
 
     /**
      * Version number for this configuration.
      * Auto-incremented per config name.
      */
-    version: t.integer(),
+    version: z.integer(),
 
     /**
      * Optional description of changes in this version.
      */
-    changeDescription: t.optional(t.text()),
+    changeDescription: z.text().optional(),
 
     /**
      * Optional tags for filtering/categorization.
      */
-    tags: t.optional(t.array(t.text())),
+    tags: z.array(z.text()).optional(),
 
     /**
      * Creator user ID (if available).
      */
-    creatorId: t.optional(t.uuid()),
+    creatorId: z.uuid().optional(),
 
     /**
      * Creator display name for audit trail.
      */
-    creatorName: t.optional(t.text()),
+    creatorName: z.text().optional(),
 
     /**
      * Previous content before this change (for rollback reference).
      */
-    previousContent: t.optional(t.json()),
+    previousContent: z.json().optional(),
 
     /**
      * Migration log if schema changed.
      */
-    migrationLog: t.optional(t.text()),
+    migrationLog: z.text().optional(),
   }),
   indexes: [
-    { columns: ["name", "activationDate"] },
-    { columns: ["name", "version"], unique: true },
+    { columns: ["organizationId", "name", "activationDate"] },
+    // Version numbering is per-(org, name): two tenants each own an
+    // independent v1/v2/… of the same parameter name.
+    { columns: ["organizationId", "name", "version"], unique: true },
     { columns: ["activationDate"] },
   ],
 });

package/src/api/parameters/primitives/$parameter.ts

@@ -26,9 +26,9 @@ import { ParameterProvider } from "../services/ParameterProvider.ts";
  * class AppConfig {
  *   features = $parameter({
  *     name: "app.features.flags",
- *     schema: t.object({
- *       enableBeta: t.boolean(),
- *       maxUploadSize: t.number()
+ *     schema: z.object({
+ *       enableBeta: z.boolean(),
+ *       maxUploadSize: z.number()
  *     }),
  *     default: { enableBeta: false, maxUploadSize: 10485760 }
  *   });

package/src/api/parameters/schemas/activateParameterBodySchema.ts

@@ -1,4 +1,4 @@
-import { type Static, t } from "alepha";
+import type { Static } from "alepha";
 import { parameters } from "../entities/parameters.ts";
 
 /**
@@ -7,8 +7,8 @@ import { parameters } from "../entities/parameters.ts";
  * Creator fields are omitted; the controller captures the authenticated user
  * server-side.
  */
-export const activateParameterBodySchema = t.pick(parameters.schema, [
-  "version",
-]);
+export const activateParameterBodySchema = parameters.schema.pick({
+  version: true,
+});
 
 export type ActivateParameterBody = Static<typeof activateParameterBodySchema>;

package/src/api/parameters/schemas/createParameterVersionBodySchema.ts

@@ -1,26 +1,26 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 import { parameters } from "../entities/parameters.ts";
 
 /**
  * Create parameter version body schema.
- * Uses t.pick to derive from entity, with required fields made non-optional.
+ * Uses z.pick to derive from entity, with required fields made non-optional.
  *
  * Creator fields are intentionally omitted: the controller captures the
  * authenticated user server-side, so they cannot be spoofed by the client.
  */
-export const createParameterVersionBodySchema = t.extend(
-  t.pick(parameters.schema, [
-    "content",
-    "schemaHash",
-    "changeDescription",
-    "tags",
-  ]),
-  {
-    activationDate: t.optional(
-      t.datetime({ description: "When to activate (default: now)" }),
-    ),
-  },
-);
+export const createParameterVersionBodySchema = parameters.schema
+  .pick({
+    content: true,
+    schemaHash: true,
+    changeDescription: true,
+    tags: true,
+  })
+  .extend({
+    activationDate: z
+      .datetime()
+      .describe("When to activate (default: now)")
+      .optional(),
+  });
 
 export type CreateParameterVersionBody = Static<
   typeof createParameterVersionBodySchema

package/src/api/parameters/schemas/parameterCreatorSummarySchema.ts

@@ -1,4 +1,4 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 
 /**
  * Slim view of a parameter version's creator, embedded by the admin history
@@ -12,12 +12,12 @@ import { type Static, t } from "alepha";
  * realm — comes back with `creator` undefined. Callers fall back to the raw
  * `creatorId`.
  */
-export const parameterCreatorSummarySchema = t.object({
-  id: t.uuid(),
-  email: t.optional(t.string({ format: "email" })),
-  username: t.optional(t.shortText({ minLength: 3, maxLength: 30 })),
-  firstName: t.optional(t.string()),
-  lastName: t.optional(t.string()),
+export const parameterCreatorSummarySchema = z.object({
+  id: z.uuid(),
+  email: z.string().meta({ format: "email" }).optional(),
+  username: z.shortText({ minLength: 3, maxLength: 30 }).optional(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
 });
 
 export type ParameterCreatorSummary = Static<