@abloatai/ablo 0.12.0 → 0.13.0

package/AGENTS.md

@@ -31,7 +31,7 @@ Every model verb takes ONE options object. The common loop:
 
 1. **Read** the row — `await ablo.<model>.retrieve({ id })` (async; from the server) or `await ablo.<model>.list({ where })` for many. In React render, read synchronously with `useAblo((a) => a.<model>.get(id))`.
 2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
-3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, action?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
+3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, reason?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
 4. **Write** — `await ablo.<model>.update({ id: claim.data.id, data })`. Because you hold the claim, the write is rejected if the row changed underneath you.
 
 Keep coding assistants on this schema-backed path.
@@ -59,7 +59,7 @@ if (!report) throw new Error('Report not found');
 // row before resolving. Auto-released at the end of this scope (`await using`).
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'forecasting',
+  reason: 'forecasting',
   ttl: '2m',
 });
 const claimed = claim.data;

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- Schema authoring: split model routing into two orthogonal axes — `policy` (row access) and `groups` (sync-group routing).
+
+  **Breaking (schema authoring).** The flat, collision-prone model options are replaced by two namespaced ones:
+  - **`policy`** — row-access / tenant isolation (named after Postgres/Supabase RLS policies: the rule that scopes which rows a tenant may read). A discriminated union on `by` replaces the old `orgScoped` / `scopedVia` / `orgColumn` trio:
+    - `{ by: 'column' }` — row-local tenancy column (the default when omitted; column name still overridable).
+    - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when the table has no tenancy column of its own (e.g. `slide_layers` → `slides`).
+    - Type `TenancyInput` is renamed `PolicyInput`; `policyInputSchema` / `resolvePolicy` are now exported.
+  - **`groups: { root, grants, roles }`** — which delta channels a row fans into (orthogonal to `policy`, which governs read access). One namespaced object replaces the old flat `scope` / `grants` / `entityRoles`:
+    - `root` (was `scope`) — mark a model a scope root; its records form the group `<kind>:<id>`. Renamed so it no longer collides with the old `scopedVia` tenancy sugar or the inner `grants.scope` relation name.
+    - `grants` — a membership edge granting an identity access to a scope root.
+    - `roles` (was `entityRoles`) — explicit non-relational record→group roles; accepts one role or an array.
+    - `groupsInputSchema` / `GroupsInput` are now exported.
+
+  **CLI.** `config.json` now stores per-project profile key pairs (`profiles: Record<string, ProfileKeys>`) instead of a single top-level pair; older flat layouts are folded into the active profile automatically on read, so existing logins keep working. `login` / `projects` updated to the profile model.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -274,7 +274,7 @@ ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 
 {
-  await using claim = await ablo.weatherReports.claim({ id, wait: false });
+  await using claim = await ablo.weatherReports.claim({ id, queue: false });
   /* do the held work */
 }
 
@@ -285,11 +285,11 @@ ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 ```
 
 `claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
-behind it. `wait: false` skips rather than waiting when the row is held;
+behind it. `queue: false` skips rather than waiting when the row is held;
 `maxQueueDepth: 2` bails when two or more are already ahead.
 
 Default reads keep working while a row is claimed. Server reads that need claimed
-semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
+semantics can opt in with `ifClaimed: 'return' | 'fail'`.
 
 Even an unclaimed write can't land on stale reasoning — the commit is guarded:
 

package/dist/cli.cjs

@@ -277023,6 +277023,7 @@ var roleSchema = import_zod2.z.object({
   kind: import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "deck"'),
   source: roleSourceSchema
 });
+var entityRoleSchema = roleSchema;
 var scopeSchema = import_zod2.z.union([
   import_zod2.z.boolean(),
   import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "dataroom"')
@@ -277031,6 +277032,11 @@ var grantsRefSchema = import_zod2.z.object({
   subject: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.subject must name a relation"),
   scope: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.scope must name a relation")
 });
+var groupsInputSchema = import_zod2.z.object({
+  root: scopeSchema.optional(),
+  grants: grantsRefSchema.optional(),
+  roles: import_zod2.z.union([entityRoleSchema, import_zod2.z.array(entityRoleSchema)]).optional()
+});
 
 // src/coordination/schema.ts
 var targetRangeSchema = import_zod3.z.object({
@@ -279646,6 +279652,7 @@ init_cjs_shims();
 var import_os2 = require("os");
 var import_path2 = require("path");
 var import_fs3 = require("fs");
+var DEFAULT_PROFILE = "default";
 function configDir() {
   if (process.env.ABLO_CONFIG_DIR) return process.env.ABLO_CONFIG_DIR;
   const xdg = process.env.XDG_CONFIG_HOME;
@@ -279657,12 +279664,32 @@ function configPath() {
 function credentialsPath() {
   return (0, import_path2.join)(configDir(), "credentials.json");
 }
+function activeProfileName(cfg) {
+  return cfg.activeProject?.slug ?? DEFAULT_PROFILE;
+}
 function asKeyEntry(value) {
   if (value && typeof value === "object" && typeof value.apiKey === "string") {
     return value;
   }
   return void 0;
 }
+function asProfileKeys(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const sandbox = asKeyEntry(v.sandbox);
+  const production = asKeyEntry(v.production);
+  if (!sandbox && !production) return void 0;
+  return { ...sandbox ? { sandbox } : {}, ...production ? { production } : {} };
+}
+function asProfileMap(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [name, v] of Object.entries(value)) {
+    const keys = asProfileKeys(v);
+    if (keys) out[name] = keys;
+  }
+  return out;
+}
 function readJson(path) {
   if (!(0, import_fs3.existsSync)(path)) return null;
   try {
@@ -279683,7 +279710,7 @@ function normalizeStoredMode(value) {
   if (value === "sandbox" || value === "production") return value;
   return void 0;
 }
-function extractEntries(obj) {
+function extractLegacyEntries(obj) {
   const sandbox = asKeyEntry(obj.sandbox);
   const production = asKeyEntry(obj.production);
   if (sandbox || production) {
@@ -279692,24 +279719,33 @@ function extractEntries(obj) {
   const flat = asKeyEntry(obj);
   return flat ? { sandbox: flat } : {};
 }
+function hasKey(keys) {
+  return !!(keys?.sandbox || keys?.production);
+}
 function readConfig() {
   const cfgObj = readJson(configPath());
   const credObj = readJson(credentialsPath());
   const mode2 = normalizeStoredMode(cfgObj?.mode) ?? normalizeStoredMode(credObj?.mode);
   const activeProject = asActiveProject(cfgObj?.activeProject);
-  const cfgEntries = cfgObj ? extractEntries(cfgObj) : {};
-  const entries = {
-    ...cfgEntries,
-    ...credObj ? extractEntries(credObj) : {}
-    // credentials file wins
+  const activeName = activeProject?.slug ?? DEFAULT_PROFILE;
+  const profiles = {
+    ...asProfileMap(credObj?.profiles),
+    ...asProfileMap(cfgObj?.profiles)
   };
-  if (!mode2 && !entries.sandbox && !entries.production) return null;
+  const legacyCfg = cfgObj ? extractLegacyEntries(cfgObj) : {};
+  const legacyCred = credObj ? extractLegacyEntries(credObj) : {};
+  const legacy = { ...legacyCfg, ...legacyCred };
+  const migratedLegacy = hasKey(legacy) && !hasKey(profiles[activeName]);
+  if (migratedLegacy) profiles[activeName] = legacy;
+  const anyKey = Object.values(profiles).some(hasKey);
+  if (!mode2 && !anyKey) return null;
   const config = {
     mode: mode2 ?? "sandbox",
     ...activeProject ? { activeProject } : {},
-    ...entries
+    profiles
   };
-  if (cfgEntries.sandbox || cfgEntries.production) writeConfig(config);
+  const secretsInConfig = hasKey(legacyCfg);
+  if (secretsInConfig || migratedLegacy) writeConfig(config);
   return config;
 }
 function writeConfig(cfg) {
@@ -279725,16 +279761,34 @@ function writeConfig(cfg) {
 `,
     { mode: 384 }
   );
-  const credentials = {
-    ...cfg.sandbox ? { sandbox: cfg.sandbox } : {},
-    ...cfg.production ? { production: cfg.production } : {}
-  };
-  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify(credentials, null, 2)}
+  const profiles = {};
+  for (const [name, keys] of Object.entries(cfg.profiles)) {
+    if (!hasKey(keys)) continue;
+    profiles[name] = {
+      ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+      ...keys.production ? { production: keys.production } : {}
+    };
+  }
+  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify({ profiles }, null, 2)}
 `, { mode: 384 });
   return credentialsPath();
 }
+function emptyConfig(mode2 = "sandbox") {
+  return { mode: mode2, profiles: {} };
+}
+function setProfileKeys(profileName, keys, opts) {
+  const cfg = readConfig() ?? emptyConfig(opts.mode);
+  cfg.mode = opts.mode;
+  cfg.profiles[profileName] = {
+    ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+    ...keys.production ? { production: keys.production } : {}
+  };
+  if (opts.activeProject) cfg.activeProject = opts.activeProject;
+  else delete cfg.activeProject;
+  return writeConfig(cfg);
+}
 function setMode(mode2) {
-  const cfg = readConfig() ?? { mode: mode2 };
+  const cfg = readConfig() ?? emptyConfig(mode2);
   cfg.mode = mode2;
   return writeConfig(cfg);
 }
@@ -279745,13 +279799,15 @@ function getActiveProject() {
   return readConfig()?.activeProject;
 }
 function setActiveProject(project) {
-  const cfg = readConfig() ?? { mode: "sandbox" };
+  const cfg = readConfig() ?? emptyConfig("sandbox");
   if (project) cfg.activeProject = project;
   else delete cfg.activeProject;
   return writeConfig(cfg);
 }
 function getKeyEntry(mode2) {
-  return readConfig()?.[mode2];
+  const cfg = readConfig();
+  if (!cfg) return void 0;
+  return cfg.profiles[activeProfileName(cfg)]?.[mode2];
 }
 function modeFromKey(key) {
   if (/^(sk|rk)_test_/.test(key)) return "sandbox";
@@ -279775,11 +279831,21 @@ function resolveApiKey(modeOverride) {
   if (process.env.ABLO_API_KEY) return process.env.ABLO_API_KEY;
   const cfg = readConfig();
   if (!cfg) return void 0;
-  const entry = cfg[modeOverride ?? cfg.mode];
+  const entry = cfg.profiles[activeProfileName(cfg)]?.[modeOverride ?? cfg.mode];
   if (!entry) return void 0;
   if (entry.expiresAt && Date.parse(entry.expiresAt) <= Date.now()) return void 0;
   return entry.apiKey;
 }
+function guardActiveProjectKey() {
+  if (process.env.ABLO_API_KEY) {
+    return { ok: true, activeProfile: DEFAULT_PROFILE, available: [] };
+  }
+  const cfg = readConfig();
+  const activeProfile = cfg ? activeProfileName(cfg) : DEFAULT_PROFILE;
+  const profiles = cfg?.profiles ?? {};
+  const available = Object.entries(profiles).filter(([, keys]) => hasKey(keys)).map(([name]) => name);
+  return { ok: hasKey(profiles[activeProfile]), activeProfile, available };
+}
 function resolvePushPlan() {
   const envKey = process.env.ABLO_API_KEY;
   if (envKey) return { flow: modeFromKey(envKey) ?? getMode(), apiKey: envKey, source: "env" };
@@ -280425,8 +280491,19 @@ function openBrowser(url) {
   } catch {
   }
 }
-async function deviceLogin() {
+function parseProjectFlag(argv) {
+  const i = argv.indexOf("--project");
+  if (i >= 0) {
+    const slug = argv[i + 1];
+    if (slug && !slug.startsWith("-")) return slug;
+  }
+  const eq = argv.find((a) => a.startsWith("--project="));
+  return eq ? eq.slice("--project=".length) || void 0 : void 0;
+}
+async function deviceLogin(argv) {
   Ie(`${brand("ablo")} login`);
+  const requested = parseProjectFlag(argv) ?? getActiveProject()?.slug;
+  const targetProject = requested === DEFAULT_PROFILE ? void 0 : requested;
   const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
   let account = "login";
   if (interactive) {
@@ -280504,13 +280581,19 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     s.stop("Timed out waiting for approval.");
     process.exit(1);
   }
-  s.message("Provisioning a sandbox key\u2026");
+  s.message(
+    targetProject ? `Provisioning keys for ${targetProject}\u2026` : "Provisioning a sandbox key\u2026"
+  );
   const provRes = await fetch(`${AUTH_URL}/api/cli/provision-key`, {
     method: "POST",
     headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-    // Pass the device_code so the server can scope the minted keys to the
-    // project the user picked at /cli (login project picker). Harmless if none.
-    body: JSON.stringify({ device_code: code.device_code })
+    // Scope the minted keys to the chosen project (`--project`/active), with
+    // the device_code as a legacy fallback for the /cli picker. Both harmless
+    // if absent → org-default keys.
+    body: JSON.stringify({
+      device_code: code.device_code,
+      ...targetProject ? { project_slug: targetProject } : {}
+    })
   }).catch(() => null);
   if (!provRes || !provRes.ok) {
     s.stop("Could not provision a key.");
@@ -280528,16 +280611,23 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     ...prov.organizationId ? { organizationId: prov.organizationId } : {},
     ...k3.expiresAt ? { expiresAt: k3.expiresAt } : {}
   });
-  const path = writeConfig({
-    mode: "sandbox",
-    sandbox: entry(prov.test),
-    ...prov.live ? { production: entry(prov.live) } : {}
-  });
+  const profileName = prov.project?.slug ?? DEFAULT_PROFILE;
+  const path = setProfileKeys(
+    profileName,
+    {
+      sandbox: entry(prov.test),
+      ...prov.live ? { production: entry(prov.live) } : {}
+    },
+    { mode: "sandbox", activeProject: prov.project ?? void 0 }
+  );
   s.stop(`Saved keys to ${path}`);
-  Se(`${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`);
+  const where = prov.project ? ` ${import_picocolors7.default.dim(`(project ${prov.project.slug})`)}` : "";
+  Se(
+    `${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}${where}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`
+  );
 }
-async function login() {
-  await deviceLogin();
+async function login(argv = []) {
+  await deviceLogin(argv);
 }
 function logout() {
   const removed = clearCredential();
@@ -280790,11 +280880,13 @@ async function projects(argv) {
       setActiveProject({ id: target.id, slug: target.slug });
       console.log(`  ${import_picocolors9.default.green("\u2713")} now targeting project ${import_picocolors9.default.bold(target.slug)} ${import_picocolors9.default.dim(`(${target.id})`)}`);
     }
-    console.log(
-      import_picocolors9.default.dim(
-        "  Note: a key\u2019s project scope is fixed at mint \u2014 switch keys (or mint one for this project) to act in it."
-      )
-    );
+    const guard = guardActiveProjectKey();
+    if (!guard.ok) {
+      const loginCmd = guard.activeProfile === DEFAULT_PROFILE ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.log(
+        import_picocolors9.default.dim(`  No key stored for this project yet \u2014 run ${import_picocolors9.default.bold(loginCmd)} to mint one.`)
+      );
+    }
     return;
   }
   console.error(
@@ -281370,7 +281462,7 @@ function spreadOpts(optsArg) {
   }
   return `, ...${optsArg.getText()}`;
 }
-function hasKey(obj, key) {
+function hasKey2(obj, key) {
   return obj.getProperties().some(
     (p2) => (import_ts_morph.Node.isPropertyAssignment(p2) || import_ts_morph.Node.isShorthandPropertyAssignment(p2)) && p2.getName() === key
   );
@@ -281383,7 +281475,7 @@ function verbRewrite(call, verb) {
   const first = args[0];
   const calleeText = call.getExpression().getText();
   if (verb === "create") {
-    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey(first, "data")) return null;
+    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey2(first, "data")) return null;
     return `${calleeText}({ data: ${first.getText()}${spreadOpts(args[1])} })`;
   }
   if (import_ts_morph.Node.isObjectLiteralExpression(first)) return null;
@@ -282212,7 +282304,7 @@ async function main() {
   if (command === "init") {
     await init(process.argv.slice(3));
   } else if (command === "login") {
-    await login();
+    await login(process.argv.slice(3));
   } else if (command === "logout") {
     logout();
   } else if (command === "mode") {
@@ -282251,6 +282343,22 @@ async function main() {
     const rest = process.argv.slice(3);
     const advanced = rest.some((a) => ["--force", "--rename", "--backfill", "--url"].includes(a));
     const watching = rest.includes("--watch");
+    const guard = guardActiveProjectKey();
+    if (!guard.ok && guard.available.length > 0 && !rest.includes("--url")) {
+      console.error(
+        `  ${import_picocolors18.default.yellow("\u26A0")} active project ${import_picocolors18.default.bold(guard.activeProfile)} has no stored key ${import_picocolors18.default.dim(
+          `(you have keys for: ${guard.available.join(", ")})`
+        )}`
+      );
+      const loginCmd = guard.activeProfile === "default" ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.error(
+        import_picocolors18.default.dim(
+          `    Mint one with ${import_picocolors18.default.bold(loginCmd)}, or switch with ${import_picocolors18.default.bold("ablo projects use <slug>")}.`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     const plan = resolvePushPlan();
     if (advanced || plan.flow === "production" && !watching) {
       await push(rest);
@@ -282275,11 +282383,12 @@ async function main() {
     console.log(`                  [--auth apikey] [--storage direct|endpoint] [--project <slug>] [--no-project]`);
     console.log(`                  [--no-agent] [--no-pull] [--no-install] [--no-login]`);
     console.log(`    npx ablo login                         Authorize in your browser (provisions sandbox + production keys)`);
+    console.log(`    npx ablo login --project <slug>        Same, scoped to a project (mints its keys, makes it active)`);
     console.log(`    npx ablo logout                        Remove the stored API key`);
     console.log(`    npx ablo mode [sandbox|production]     Switch active environment, like Stripe`);
     console.log(`    npx ablo projects list                 List the org's projects (default + your own)`);
     console.log(`    npx ablo projects create <slug>        Create a project (its keys/schema/data are isolated)`);
-    console.log(`    npx ablo projects use <slug|default>   Set the active project for new key mints`);
+    console.log(`    npx ablo projects use <slug|default>   Switch the active project (run login --project to mint its keys)`);
     console.log(`    npx ablo status                        Show org, mode, keys, and server health`);
     console.log(`    npx ablo status --json                 Same, machine-readable (mode, key prefix, org id, api host)`);
     console.log(`    npx ablo logs [-n N] [--since 15m]     Tail commit activity (follows; --no-follow to exit)`);

package/dist/schema/index.d.ts

@@ -23,13 +23,13 @@
 export { z } from 'zod';
 export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } from './tenancy.js';
 export { planeSchema, DEFAULT_PLANE, type SchemaPlane } from './plane.js';
 export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './sync-delta-row.js';
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from './sync-delta-wire.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';

package/dist/schema/index.js

@@ -27,7 +27,7 @@ export { field, indexed, getFieldMeta } from './field.js';
 // Relation builders
 export { relation } from './relation.js';
 // Tenancy — the single source of truth for how a model's rows are tenant-scoped.
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
 // Database plane — which DB a model's rows live in (`tenant` portable to a BYO
 // customer DB, `control` = Ablo's own). Sibling axis to `tenancy`.
 export { planeSchema, DEFAULT_PLANE } from './plane.js';
@@ -46,7 +46,7 @@ export { model, scopeKindOf, } from './model.js';
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.

package/dist/schema/model.d.ts

@@ -18,10 +18,10 @@
  */
 import { z } from 'zod';
 import type { RelationDef } from './relation.js';
-import type { EntityRole } from './roles.js';
+import type { EntityRole, GroupsInput } from './roles.js';
 import { type FieldMeta } from './field.js';
-import { type Tenancy, type ScopedViaRef } from './tenancy.js';
-export type { ScopedViaRef, Tenancy } from './tenancy.js';
+import { type Tenancy, type PolicyInput } from './tenancy.js';
+export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { type SchemaPlane } from './plane.js';
 /**
  * Controls when model data is loaded from the server.
@@ -95,49 +95,27 @@ export interface ModelOptions {
      */
     tableName?: string;
     /**
-     * Whether this model's table has an `organization_id` column. Default: true.
-     * When false, the bootstrap/read query omits the `WHERE organization_id = $1`
-     * tenant filter for this model.
+     * **Axis 1 — row-access policy (tenant isolation / RLS).** Decides who may
+     * *read* a row at all. Named after Postgres/Supabase, where a `policy` is the
+     * rule that scopes which rows a tenant sees. A discriminated union on `by` —
+     * one option replacing the old `orgScoped`/`scopedVia`/`orgColumn` trio:
      *
-     * ⚠ SECURITY — `orgScoped: false` makes the table GLOBALLY READABLE: every
-     * client of every tenant sees every row. It is ONLY correct for genuinely
-     * tenant-less tables (the `organizations` table itself, global lookups). If
-     * rows belong to a tenant through a foreign key but this table has no
-     * `organization_id` of its own, use {@link scopedVia} INSTEAD — reaching for
-     * `orgScoped: false` there silently exposes the entire table cross-tenant.
-     */
-    orgScoped?: boolean;
-    /**
-     * Scope rows via a parent table when THIS table has no
-     * `organization_id` column of its own, but rows still belong to a
-     * tenant via a foreign key (e.g. `memberRoles.member_id → member.id`,
-     * `teamMember.team_id → team.id`, `users.id ← member.user_id`).
-     *
-     * Emits, in place of the missing `organization_id = $1` clause:
-     *
-     *   WHERE <table>.<localKey> IN
-     *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-     *
-     * Use this INSTEAD of `orgScoped: false` for any `load: 'instant'`
-     * model whose rows would otherwise leak cross-tenant on bootstrap —
-     * dropping the filter entirely exposes the entire DB to every client.
+     * - `{ by: 'column' }` — row-local tenancy column (the DEFAULT when omitted).
+     *   `column` overrides the name (default `organization_id`).
+     * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key
+     *   when THIS table has no tenancy column of its own (e.g. `slide_layers` →
+     *   slide → deck → org). Emits, in place of `organization_id = $1`:
+     *   `WHERE <table>.<fk> IN (SELECT <parentKey> FROM <parent> WHERE
+     *   <parentTenantColumn> = $1)`. Use this for any `load: 'instant'` child
+     *   table that would otherwise leak cross-tenant on bootstrap.
+     * - `{ by: 'none' }` — genuinely global / reference data (the `organizations`
+     *   table itself, global lookups). ⚠ Makes the whole table readable
+     *   cross-tenant — only correct for tenant-less tables. Because it's an
+     *   explicit, named branch (not a falsy flag) it can't be reached by accident.
      *
-     * Identifiers must match the regular `[a-zA-Z_][a-zA-Z0-9_]*` shape;
-     * the SQL compiler validates them to keep this away from injection
-     * paths.
+     * Normalized into the canonical {@link Tenancy} by `resolvePolicy` at build.
      */
-    scopedVia?: ScopedViaRef;
-    /**
-     * Override the physical tenancy column name (default `organization_id`).
-     * Authoring sugar — normalized into the canonical {@link tenancy} descriptor.
-     */
-    orgColumn?: string;
-    /**
-     * Canonical tenancy descriptor. You normally don't set this — `orgScoped`,
-     * `scopedVia`, and `orgColumn` are normalized into it at build time. Set it
-     * directly only to author the union form explicitly.
-     */
-    tenancy?: Tenancy;
+    policy?: PolicyInput;
     /**
      * Which database plane this model's rows live in. `tenant` (default) =
      * the tenant data plane, emitted into a customer's BYO/dedicated DB by
@@ -146,53 +124,29 @@ export interface ModelOptions {
      */
     plane?: SchemaPlane;
     /**
-     * Marks this model as a **scope root** — a model that forms a sync group of
-     * its own. A scope-root record lives in the group `<kind>:<id>`, where `kind`
-     * defaults to the lowercased `typename` (so a `Deck` → `deck:<id>`). Pass a
-     * string to override the kind explicitly (`scope: 'matter'`).
-     *
-     * Replaces the old `syncGroupFormat` template string: there is no `{id}`
-     * placeholder to author — the engine mints the branded {@link SyncGroup} from
-     * `(kind, id)`. Child models inherit a root's group via their `belongsTo`
-     * relations (a `document` with `dataroomId` fans into `dataroom:<id>`), so
-     * only the root declares anything.
-     */
-    scope?: boolean | string;
-    /**
-     * Declares this model as a **membership edge** that grants an identity access
-     * to a scope root — the relation-driven equivalent of "this user can see that
-     * dataroom." Both values are *relation names* already declared on this model:
-     * `subject` is the `belongsTo` to the identity (e.g. a `user`), `scope` is the
-     * `belongsTo` to the scope-root entity (e.g. a `dataroom`).
+     * **Axis 2 — sync-group routing.** Decides which delta *channels* a row fans
+     * into. Orthogonal to {@link policy} (read access). One namespaced object
+     * replacing the old flat `scope`/`grants`/`entityRoles`:
      *
-     * The server's membership resolver reads this at connect time — for identity
-     * `U`, it queries `WHERE <subject FK> = U` and adds `<scopeKind>:<scope FK>`
-     * to the identity's subscribed groups (Linear's `/sync/user_sync_groups`).
+     * - `root` — mark this model a scope root; its records form the group
+     *   `<kind>:<id>` (kind defaults from the lowercased typename, e.g. `Deck` →
+     *   `deck:<id>`; pass a string to override, `root: 'matter'`). Child models
+     *   inherit a root's group via their `belongsTo` relations. Was `scope` —
+     *   renamed so it no longer collides with the old `scopedVia` tenancy sugar.
+     * - `grants` — a membership edge granting an identity access to a scope root.
+     *   Both values name `belongsTo` relations on this model (`subject` → identity,
+     *   `scope` → scope root). Only needed for sub-org sharing.
+     * - `roles` — explicit non-relational record→group roles (the inbox-fan-out
+     *   escape hatch, keyed on a plain field). Was `entityRoles`. One or many.
      *
      * ```ts
      * // dataroomMember: { userId, dataroomId }
-     * grants: { subject: 'user', scope: 'dataroom' } // both are relation names
-     * ```
-     *
-     * Not needed for org-level access — a `dataroom.organizationId` already routes
-     * via the `org:<id>` group. `grants` is only for sub-org membership.
-     */
-    grants?: GrantsRef;
-    /**
-     * Explicit record→group roles for routing that isn't relational — a group
-     * keyed on a plain field rather than the record's own id or a `belongsTo`
-     * scope root. The escape hatch for cases like per-recipient inbox fan-out:
-     *
-     * ```ts
-     * // a message routes to its addressee's inbox, keyed on `toId`
-     * entityRoles: [entityRole({ kind: 'inbox', source: 'toId' })]
+     * groups: { grants: { subject: 'user', scope: 'dataroom' } }
+     * // a message → its addressee's inbox, keyed on `toId`
+     * groups: { roles: [entityRole({ kind: 'inbox', source: 'toId' })] }
      * ```
-     *
-     * Prefer {@link scope} (self group) + `belongsTo` relations (parent groups)
-     * when the routing follows the relation graph — reach for `entityRoles` only
-     * when it genuinely doesn't.
      */
-    entityRoles?: EntityRole | readonly EntityRole[];
+    groups?: GroupsInput;
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
      * model via the `commit` wire protocol. Default: **true** — declaring a