@abloatai/ablo 0.25.0 → 0.27.0

package/dist/schema/roles.d.ts

@@ -36,34 +36,35 @@ export type SyncGroup = z.infer<typeof syncGroupSchema>;
  */
 export declare function syncGroup(kind: string, id: string): SyncGroup;
 /**
- * Caller-facing input form of a sync group. Accepts a constructor-minted
- * {@link SyncGroup}, a contextually-typed template literal of the right shape
- * (`` `org:${orgId}` `` checks without importing the constructor), or the
- * server-reserved `'default'` anchor. A bare colon-less string is a COMPILE
- * error — it would subscribe to nothing and fail silently (the `['default']`
- * zero-fan-out ghost made flesh).
+ * The caller-facing input form of a sync group. Accepts a {@link SyncGroup}
+ * from the constructor, a template literal of the right shape
+ * (`` `org:${orgId}` `` type-checks without importing the constructor), or the
+ * reserved `'default'` anchor. A plain string with no colon is a compile error,
+ * because it would match no group and silently subscribe to nothing.
  */
 export type SyncGroupInput = SyncGroup | `${string}:${string}` | 'default';
 /**
- * Runtime gate for {@link SyncGroupInput} at parse boundaries (capability
- * mint, ephemeral-key mint). One schema, every door — a malformed group is
- * rejected loudly (`invalid_sync_group`) instead of stored and silently
- * subscribed-to-nothing.
+ * Runtime validation for {@link SyncGroupInput}, used wherever a group crosses a
+ * trust boundary such as minting a capability or an ephemeral key. A malformed
+ * group is rejected with `invalid_sync_group` rather than stored and left
+ * silently subscribed to nothing.
  */
 export declare const syncGroupInputSchema: z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>;
 /** Runtime guard matching {@link SyncGroupInput}. */
 export declare function isSyncGroupInput(value: unknown): value is SyncGroupInput;
 /**
- * The sync-group kinds the AUTH PROVIDER mints directly onto identities — a
- * CLOSED vocabulary: extend this list, never inline a new namespace string.
+ * The sync-group kinds the authentication provider mints directly onto an
+ * identity. This is a fixed vocabulary: add to this list rather than write a
+ * new namespace string inline.
  *
  *   - `org:<organizationId>`  — every member of the organization
  *   - `user:<participantId>`  — the participant itself
- *   - `project:<projectId>`   — every credential scoped to the project
- *     (project axis, 2026-06-11; the org-default project's id IS the org id)
+ *   - `project:<projectId>`   — every credential scoped to the project; the
+ *     organization's default project shares the organization's id
  *
- * Schema-declared roles ({@link identityRole} / {@link entityRole}) extend the
- * vocabulary per app; these are the engine-reserved anchors.
+ * Schema-declared roles ({@link identityRole} and {@link entityRole}) extend
+ * this vocabulary per application; the kinds here are the ones the engine
+ * reserves.
  */
 export declare const IDENTITY_ANCHOR_KINDS: readonly ["org", "user", "project"];
 export type IdentityAnchorKind = (typeof IDENTITY_ANCHOR_KINDS)[number];
@@ -138,20 +139,17 @@ export declare const grantsRefSchema: z.ZodObject<{
     scope: z.ZodString;
 }, z.core.$strip>;
 /**
- * The AUTHORING form of a model's sync-group routing — the `groups: { ... }`
- * option. One namespaced object collects the three independent routing knobs
- * that used to be flat, collision-prone model options (`scope` / `grants` /
- * `entityRoles`). Distinct axis from `policy` (tenant isolation): the policy
- * decides who may *read* a row, `groups` decides which delta *channels* a row
+ * The authoring form of a model's sync-group routing — the `groups: { ... }`
+ * option. One object collects the three independent routing controls. This is a
+ * separate concern from `policy`, which governs tenant isolation: `policy`
+ * decides who may read a row, while `groups` decides which change channels a row
  * fans into.
  *
- * - `root`   — mark this model a scope root; its records form `<kind>:<id>`
- *   (kind defaults from typename). Was the flat `scope` option — renamed to
- *   `root` so it no longer collides with the (now removed) `scopedVia` tenancy
- *   sugar or the inner `grants.scope` relation name.
+ * - `root`   — marks this model a scope root, so its records form the group
+ *   `<kind>:<id>` (the kind defaults to the typename).
  * - `grants` — a membership edge granting an identity access to a scope root.
- * - `roles`  — explicit non-relational record→group roles (e.g. inbox fan-out
- *   keyed on a plain field). Was `entityRoles`. Accepts one role or an array.
+ * - `roles`  — record-to-group roles keyed on a plain field rather than a
+ *   relation, such as inbox fan-out. Accepts a single role or an array.
  */
 export declare const groupsInputSchema: z.ZodObject<{
     root: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -229,3 +227,23 @@ export declare function composeIdentitySyncGroups(identity: IdentityContext, sch
 export declare function composeEntitySyncGroups(record: EntityContext, def: {
     readonly entityRoles?: readonly EntityRole[];
 }): readonly SyncGroup[];
+/**
+ * Narrow a client's requested sync-group set to the groups it is actually
+ * allowed to subscribe to. This helper is fully generic — it never inspects the
+ * group strings — so it lives beside the composition helpers above.
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-derived set,
+ *     which is this participant's default subscription scope.
+ *   - If the client requested some groups, keep only those that appear in the
+ *     identity-derived allowed set and drop the rest, reporting the dropped
+ *     groups through the optional `logDropped` callback.
+ *   - If nothing survives the filter, fall back to the full allowed set rather
+ *     than return `[]`, which would otherwise collapse to the server-side
+ *     `'default'` fallback and deliver no changes at all.
+ */
+export declare function intersectRequestedWithAllowed(args: {
+    readonly requested: readonly string[];
+    readonly allowed: readonly string[];
+    readonly logDropped?: (dropped: readonly string[]) => void;
+}): readonly string[];

package/dist/schema/roles.js

@@ -40,10 +40,10 @@ export function syncGroup(kind, id) {
     return `${kind}:${id}`;
 }
 /**
- * Runtime gate for {@link SyncGroupInput} at parse boundaries (capability
- * mint, ephemeral-key mint). One schema, every door — a malformed group is
- * rejected loudly (`invalid_sync_group`) instead of stored and silently
- * subscribed-to-nothing.
+ * Runtime validation for {@link SyncGroupInput}, used wherever a group crosses a
+ * trust boundary such as minting a capability or an ephemeral key. A malformed
+ * group is rejected with `invalid_sync_group` rather than stored and left
+ * silently subscribed to nothing.
  */
 export const syncGroupInputSchema = z.union([z.literal('default'), syncGroupSchema]);
 /** Runtime guard matching {@link SyncGroupInput}. */
@@ -52,16 +52,18 @@ export function isSyncGroupInput(value) {
 }
 // ── Identity anchors (closed vocabulary) ────────────────────────────────────
 /**
- * The sync-group kinds the AUTH PROVIDER mints directly onto identities — a
- * CLOSED vocabulary: extend this list, never inline a new namespace string.
+ * The sync-group kinds the authentication provider mints directly onto an
+ * identity. This is a fixed vocabulary: add to this list rather than write a
+ * new namespace string inline.
  *
  *   - `org:<organizationId>`  — every member of the organization
  *   - `user:<participantId>`  — the participant itself
- *   - `project:<projectId>`   — every credential scoped to the project
- *     (project axis, 2026-06-11; the org-default project's id IS the org id)
+ *   - `project:<projectId>`   — every credential scoped to the project; the
+ *     organization's default project shares the organization's id
  *
- * Schema-declared roles ({@link identityRole} / {@link entityRole}) extend the
- * vocabulary per app; these are the engine-reserved anchors.
+ * Schema-declared roles ({@link identityRole} and {@link entityRole}) extend
+ * this vocabulary per application; the kinds here are the ones the engine
+ * reserves.
  */
 export const IDENTITY_ANCHOR_KINDS = ['org', 'user', 'project'];
 /** Mint an engine-reserved identity anchor (typed wrapper over {@link syncGroup}). */
@@ -113,20 +115,17 @@ export const grantsRefSchema = z.object({
     scope: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'grants.scope must name a relation'),
 });
 /**
- * The AUTHORING form of a model's sync-group routing — the `groups: { ... }`
- * option. One namespaced object collects the three independent routing knobs
- * that used to be flat, collision-prone model options (`scope` / `grants` /
- * `entityRoles`). Distinct axis from `policy` (tenant isolation): the policy
- * decides who may *read* a row, `groups` decides which delta *channels* a row
+ * The authoring form of a model's sync-group routing — the `groups: { ... }`
+ * option. One object collects the three independent routing controls. This is a
+ * separate concern from `policy`, which governs tenant isolation: `policy`
+ * decides who may read a row, while `groups` decides which change channels a row
  * fans into.
  *
- * - `root`   — mark this model a scope root; its records form `<kind>:<id>`
- *   (kind defaults from typename). Was the flat `scope` option — renamed to
- *   `root` so it no longer collides with the (now removed) `scopedVia` tenancy
- *   sugar or the inner `grants.scope` relation name.
+ * - `root`   — marks this model a scope root, so its records form the group
+ *   `<kind>:<id>` (the kind defaults to the typename).
  * - `grants` — a membership edge granting an identity access to a scope root.
- * - `roles`  — explicit non-relational record→group roles (e.g. inbox fan-out
- *   keyed on a plain field). Was `entityRoles`. Accepts one role or an array.
+ * - `roles`  — record-to-group roles keyed on a plain field rather than a
+ *   relation, such as inbox fan-out. Accepts a single role or an array.
  */
 export const groupsInputSchema = z.object({
     root: scopeSchema.optional(),
@@ -197,3 +196,35 @@ export function composeEntitySyncGroups(record, def) {
     }
     return Array.from(out);
 }
+/**
+ * Narrow a client's requested sync-group set to the groups it is actually
+ * allowed to subscribe to. This helper is fully generic — it never inspects the
+ * group strings — so it lives beside the composition helpers above.
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-derived set,
+ *     which is this participant's default subscription scope.
+ *   - If the client requested some groups, keep only those that appear in the
+ *     identity-derived allowed set and drop the rest, reporting the dropped
+ *     groups through the optional `logDropped` callback.
+ *   - If nothing survives the filter, fall back to the full allowed set rather
+ *     than return `[]`, which would otherwise collapse to the server-side
+ *     `'default'` fallback and deliver no changes at all.
+ */
+export function intersectRequestedWithAllowed(args) {
+    const { requested, allowed, logDropped } = args;
+    if (requested.length === 0)
+        return allowed;
+    const allowedSet = new Set(allowed);
+    const accepted = [];
+    const dropped = [];
+    for (const g of requested) {
+        if (allowedSet.has(g))
+            accepted.push(g);
+        else
+            dropped.push(g);
+    }
+    if (dropped.length > 0 && logDropped)
+        logDropped(dropped);
+    return accepted.length > 0 ? accepted : allowed;
+}

package/dist/schema/schema.d.ts

@@ -23,7 +23,7 @@ import { z } from 'zod';
 import type { ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import type { IdentityRole } from './roles.js';
-export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
+export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
 /** The set of built-in casing conventions supported by `defineSchema`. */
 export type CasingConvention = 'snake_case' | 'camelCase';
 /** Plug point for custom conventions (e.g. mixed legacy databases). */
@@ -48,17 +48,16 @@ export interface DefineSchemaOptions {
      */
     readonly casing?: Casing;
     /**
-     * Identity-anchored sync-group roles. Server's
-     * `composeIdentitySyncGroups` iterates these to build the
-     * participant's allowed-set, replacing the prior hardcoded
-     * `org:/user:/team:` triad in `@ablo/schema`. See {@link IdentityRole}
-     * for the open-registration shape — no closed enum, consumer fully
-     * controls both the template string and the extractor function.
+     * Identity-anchored sync-group roles. The server's
+     * `composeIdentitySyncGroups` reads these to build the set of groups a
+     * participant may subscribe to. See {@link IdentityRole} for the shape: you
+     * define the `kind` and which identity field supplies the id, with no fixed
+     * vocabulary of kinds.
      *
-     * Leave unset for schemas that don't need identity-derived scoping
-     * (e.g. fully public read models). When unset, `composeIdentitySyncGroups`
-     * returns `[]` and consumers fall back to whatever explicit
-     * `syncGroups` the AuthProvider attaches to the Identity.
+     * Leave this unset for schemas that need no identity-derived scoping, such as
+     * fully public read models. When it is unset, `composeIdentitySyncGroups`
+     * returns `[]` and callers fall back to whatever explicit sync groups the
+     * authentication provider attached to the identity.
      */
     readonly identityRoles?: readonly IdentityRole[];
 }
@@ -79,20 +78,20 @@ export declare const baseFieldsSchema: z.ZodObject<{
     createdBy: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
- * The base-column names every model carries automatically (the keys of
- * {@link baseFieldsSchema}). The single source of truth — `generate.ts`
- * imports this to avoid double-emitting a redeclared base column, and the
- * `defineSchema` field loop uses it to reject a model that tries to redeclare
- * one (Zod `.merge` would otherwise silently overwrite the base field with the
- * user's, producing a `string & Date` type that breaks the build).
+ * The base-column names every model carries automatically — the keys of
+ * {@link baseFieldsSchema}, kept here as the single source of truth. Code
+ * generation reads it to avoid emitting a base column twice, and
+ * {@link defineSchema} uses it to reject a model that redeclares one, since
+ * merging the user's field over the base field would produce a `string & Date`
+ * type and break the build.
  */
 export declare const BASE_FIELDS: readonly ["id", "createdAt", "updatedAt", "organizationId", "createdBy"];
 /** The base fields type — pure data columns. */
 export type BaseModelFields = z.infer<typeof baseFieldsSchema>;
 /**
- * Methods every dynamic model class inherits from `Model`. Intersected
- * into `InferModel` (the read-side type) but NOT into `InferCreate` /
- * `UpdatePatch` — methods aren't legal create/update inputs.
+ * Methods every model instance carries. These are intersected into
+ * {@link InferModel}, the read-side type, but not into the create or update
+ * input types, since methods are not valid input.
  */
 export interface BaseModelMethods {
     /** Wire-format model name (e.g. `'Slide'`, `'Comment'`). */
@@ -130,39 +129,37 @@ type RegisteredSchema = import('../types/global.js').Register extends {
     Schema: infer S extends Schema;
 } ? S : never;
 /**
- * THE model type helper. With the scaffold's `ablo/register.ts` registration
- * in place, one parameter is all it takes:
+ * The primary model-type helper. Once your project's `ablo/register.ts`
+ * registers the schema, a single argument is all it takes:
  *
  * ```ts
  * type Task = Model<'tasks'>;
  * ```
  *
- * Without registration (or for a second schema), pass the schema explicitly:
- * `Model<typeof schema, 'tasks'>`.
+ * Without that registration, or for a second schema, pass the schema
+ * explicitly: `Model<typeof schema, 'tasks'>`.
  */
 export type Model<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferModel<RegisteredSchema, A> : never : A extends Schema ? InferModel<A, B extends keyof A['models'] ? B : never> : never;
 /**
- * @deprecated Use {@link Model} — `type Task = Model<typeof schema, 'tasks'>`
- * reads as the domain ("the Task model from my schema"), not the machinery.
- * Drizzle deprecated its own `InferModel` for the same reason. Kept as an
- * alias; no behavior difference.
+ * @deprecated Use {@link Model} instead — `Model<typeof schema, 'tasks'>` reads
+ * as the domain ("the Task model from my schema") rather than the machinery.
+ * Kept as an alias with no behavioral difference.
  */
 export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? // `Omit<…, keyof BaseModelFields>` so a model that (wrongly) redeclares a
 Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
 /**
- * Infer relation accessor types from a model's relations record.
+ * Infer the relation accessor types from a model's relations record.
  *
- * The dynamic class installs prototype getters for each declared relation in
- * `createSyncEngine.ts` (`hasMany` → `store.getByForeignKey(...)`, `belongsTo`
- * → pool lookup by FK). This type mirrors those installations so callers can
- * write `slide.layers` and `slide.deck` without manual casts.
+ * At runtime the engine installs a getter for each declared relation, so this
+ * type mirrors them and you can read `slide.layers` and `slide.deck` without a
+ * cast.
  *
  * - `hasMany` → `InferModel<S, Target>[]`
  * - `belongsTo` / `hasOne` → `InferModel<S, Target> | undefined` (undefined
- *   when the FK is unset or the parent isn't in the pool yet)
+ *   when the foreign key is unset or the parent has not loaded yet)
  *
- * Kept as `readonly` because the accessors are prototype-level getters with
- * no setter — writing to `slide.layers = [...]` would be a no-op at runtime.
+ * Kept `readonly` because the accessors are getters with no setter — assigning
+ * to `slide.layers` would have no effect at runtime.
  */
 export type InferRelations<S extends Schema, R extends RelationRecord> = string extends keyof R ? unknown : {
     readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target, infer _F, infer _O> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
@@ -202,9 +199,7 @@ Omit<z.input<z.ZodObject<Shape>>, keyof BaseModelFields> & Partial<BaseModelFiel
 export type InferModelNames<S extends Schema> = keyof S['models'] & string;
 /**
  * The value type for inserting a new row. Same shape as {@link InferCreate}:
- * consumer-writable fields + optional `id` for client-generated IDs.
- *
- * Matches Zero's `InsertValue<TableSchema>` from `zql/src/mutate/crud.ts`.
+ * the fields you can write, plus an optional `id` for client-generated ids.
  */
 export type InsertValue<S extends Schema, ModelName extends keyof S['models']> = InferCreate<S, ModelName>;
 /**
@@ -217,18 +212,14 @@ export type UpsertValue<S extends Schema, ModelName extends keyof S['models']> =
  * The value type for updating an existing row. `id` is required (identifies
  * the row to update); all other fields are optional (only provided fields
  * are changed).
- *
- * Matches Zero's `UpdateValue<TableSchema>` from `zql/src/mutate/crud.ts`.
  */
 export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape> ? {
     id: string;
 } & Partial<z.input<z.ZodObject<Shape>>> : never;
 /**
  * The value type for deleting a row. Just the primary key.
- *
- * Matches Zero's `DeleteID<TableSchema>` from `zql/src/mutate/crud.ts`.
  */
-export type DeleteId<S extends Schema, ModelName extends keyof S['models']> = {
+export interface DeleteId<S extends Schema, ModelName extends keyof S['models']> {
     id: string;
-};
+}
 export declare function defineSchema<const S extends SchemaRecord>(models: S, options?: DefineSchemaOptions): Schema<S>;

package/dist/schema/schema.js

@@ -22,10 +22,10 @@
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 import { scopeSchema, grantsRefSchema } from './roles.js';
-// Sync-group roles (identity + entity) live in `./roles.js`. Re-exported here
-// so the long-standing `@ablo/schema` / `./schema.js` import paths keep working
-// after the rehome — see roles.ts for the full vocabulary.
-export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './roles.js';
+// Sync-group roles (identity and entity) are defined in `./roles.js` and
+// re-exported here so they can also be imported from this module. See
+// `./roles.js` for the full vocabulary.
+export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './roles.js';
 function resolveCasing(fn) {
     if (fn === undefined)
         return (x) => x;
@@ -38,9 +38,9 @@ function resolveCasing(fn) {
             return (x) => x;
     }
 }
-/** Pure camelCase → snake_case. Matches postgres.fromCamel semantics but
- * kept local so the SDK stays free of any driver dependency — consumers
- * using Prisma/Drizzle/raw pg should all get the same result. */
+/** Converts a camelCase identifier to snake_case. Kept local so the package
+ * carries no database-driver dependency, and so consumers on any stack get the
+ * same result. */
 function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
@@ -59,12 +59,12 @@ export const baseFieldsSchema = z.object({
     createdBy: z.string().optional(),
 });
 /**
- * The base-column names every model carries automatically (the keys of
- * {@link baseFieldsSchema}). The single source of truth — `generate.ts`
- * imports this to avoid double-emitting a redeclared base column, and the
- * `defineSchema` field loop uses it to reject a model that tries to redeclare
- * one (Zod `.merge` would otherwise silently overwrite the base field with the
- * user's, producing a `string & Date` type that breaks the build).
+ * The base-column names every model carries automatically — the keys of
+ * {@link baseFieldsSchema}, kept here as the single source of truth. Code
+ * generation reads it to avoid emitting a base column twice, and
+ * {@link defineSchema} uses it to reject a model that redeclares one, since
+ * merging the user's field over the base field would produce a `string & Date`
+ * type and break the build.
  */
 export const BASE_FIELDS = [
     'id',
@@ -85,22 +85,21 @@ export const BASE_FIELDS = [
  * ```
  */
 /**
- * Lowercase-first camelCase round-trip check. Must match the convention used
- * by `postgres.camel` in the client driver (porsager/postgres), which is:
+ * Rejects field names that will not survive the sync driver's snake_case ↔
+ * camelCase round-trip. The driver maps identifiers like this:
  *
- *   `content_json`       → `contentJson`  (snake → camel)
- *   `contentJson`        → `content_json` (camel → snake)
- *   `contentJSON`        → `content_j_s_o_n` (BROKEN — doesn't round-trip)
+ *   `content_json`       → `contentJson`   (snake → camel)
+ *   `contentJson`        → `content_json`  (camel → snake)
+ *   `contentJSON`        → `content_j_s_o_n` (does not round-trip)
  *
- * Any field name that doesn't round-trip under this pair of transforms will
- * silently fail to populate on the client: the wire delivers one casing,
- * the dynamic class's constructor reads another, and the field lands as
- * `undefined`. We catch it here so schema authors see an error at
- * definition time rather than at runtime.
+ * A name that does not round-trip through this pair of transforms will silently
+ * fail to populate on the client: the wire delivers one casing, the model reads
+ * another, and the field lands as `undefined`. Catching it here surfaces the
+ * problem when the schema is defined rather than at runtime.
  *
- * Rule: a standard camelCase identifier has runs of one uppercase letter
- * followed by lowercase letters — never two consecutive uppercase letters.
- * `contentJSON` has `JSON` all-uppercase, so we reject it.
+ * The rule: a standard camelCase identifier has runs of a single uppercase
+ * letter followed by lowercase letters, never two uppercase letters in a row.
+ * `contentJSON` has `JSON` in all caps, so it is rejected.
  */
 function assertRoundTrippableCamelCase(modelName, fieldName) {
     // Base fields merged in by defineSchema are already validated; skip.
@@ -108,17 +107,18 @@ function assertRoundTrippableCamelCase(modelName, fieldName) {
         return;
     // Leading-lowercase constraint: fields must be camelCase, not PascalCase.
     // PascalCase is reserved for typenames.
-    if (fieldName[0] >= 'A' && fieldName[0] <= 'Z') {
+    const first = fieldName.charAt(0);
+    if (first >= 'A' && first <= 'Z') {
         throw new AbloValidationError(`[defineSchema] ${modelName}.${fieldName}: field names must start lowercase ` +
-            `(camelCase). Use "${fieldName[0].toLowerCase()}${fieldName.slice(1)}" instead.`, { code: 'schema_field_not_camelcase' });
+            `(camelCase). Use "${first.toLowerCase()}${fieldName.slice(1)}" instead.`, { code: 'schema_field_not_camelcase' });
     }
     // Two-consecutive-uppercase check. The classic failure mode is
     // `contentJSON`, `contentHTML`, `myURLParam`, etc. These don't round-trip
     // through `postgres.camel` — the snake_case intermediate would be
     // `content_j_s_o_n`, which is not a column that exists.
     for (let i = 0; i < fieldName.length - 1; i++) {
-        const a = fieldName[i];
-        const b = fieldName[i + 1];
+        const a = fieldName.charAt(i);
+        const b = fieldName.charAt(i + 1);
         const aUpper = a >= 'A' && a <= 'Z';
         const bUpper = b >= 'A' && b <= 'Z';
         if (aUpper && bUpper) {
@@ -134,9 +134,9 @@ function assertRoundTrippableCamelCase(modelName, fieldName) {
 }
 export function defineSchema(models, options) {
     // Build validators with base fields merged in, and resolve defaults for
-    // `typename` and `persist.store` so downstream code (the generic loader,
-    // the hydration pipeline, the Go named-query registry) can rely on these
-    // fields being set without re-deriving them at every call site.
+    // `typename` and `persist.store` so downstream code (the loader and the
+    // hydration pipeline) can rely on these fields being set without re-deriving
+    // them at every call site.
     //
     // Defaults:
     //   typename      ← schema key (e.g. `slideLayer` → `'slideLayer'`)
@@ -184,8 +184,7 @@ export function defineSchema(models, options) {
         // columns stay declared in the artifact instead of rediscovered by
         // SQL compilers. Server-side SQL compilers read the resolved value
         // directly.
-        for (const relName of Object.keys(def.relations)) {
-            const rel = def.relations[relName];
+        for (const rel of Object.values(def.relations)) {
             const fieldColumn = def.fields[rel.foreignKey]?.column;
             rel.foreignKeyColumn = fieldColumn ?? casing(rel.foreignKey);
         }
@@ -211,10 +210,10 @@ export function defineSchema(models, options) {
     };
 }
 /**
- * Validate the relation-driven sync-group declarations (`scope` / `grants`)
- * at schema-build time, so a mistyped membership edge fails *here* — with a
- * Stripe-shaped error (`code` + `param` + `doc_url`) pointing at the exact
- * declaration — instead of silently mis-routing deltas at runtime.
+ * Validates the relation-driven sync-group declarations (`scope` and `grants`)
+ * at schema-build time, so a mistyped membership edge fails here — with a
+ * structured error (`code`, `param`, `doc_url`) pointing at the exact
+ * declaration — rather than silently mis-routing changes at runtime.
  */
 function validateSyncGroupSchema(models) {
     for (const [name, def] of Object.entries(models)) {
@@ -245,6 +244,10 @@ function validateSyncGroupSchema(models) {
         // The scope edge must target a model that is actually a scope root —
         // otherwise the resolved `<kind>:<id>` group is one nothing fans into.
         const scopeRel = relations[def.grants.scope];
+        // Unreachable: the role loop above already threw if the scope relation
+        // is missing — this narrows the indexed access for the checks below.
+        if (!scopeRel)
+            continue;
         const target = models[scopeRel.target];
         if (target && !target.scope) {
             throw new AbloValidationError(`Model "${name}": grants.scope "${def.grants.scope}" targets "${scopeRel.target}", ` +

package/dist/schema/select.d.ts

@@ -1,25 +1,25 @@
 /**
- * `selectModels` — project a schema down to a subset of its models.
+ * `selectModels` projects a schema down to a subset of its models.
  *
- * The Prisma-style "one canonical schema, each app selects what it needs"
- * primitive. Instead of re-declaring a model's fields in a second schema (which
- * must then be kept shape-identical by hand), an app picks the models it
- * subscribes to from the canonical schema. Field shapes, resolved FK columns,
- * computeds, typenames, and identity roles all come from the source — so a
- * subset is structurally incapable of drifting from the canonical definition.
+ * It lets one canonical schema serve several apps, each subscribing only to the
+ * models it needs. Rather than re-declare a model's fields in a second schema —
+ * which you would then have to keep identical by hand — an app selects the
+ * models it wants from the canonical schema. Field shapes, resolved foreign-key
+ * columns, computed getters, typenames, and identity roles all come from the
+ * source, so a subset cannot drift from the canonical definition.
  *
  * ```ts
- * import { schema as full } from '@ablo/schema';
+ * import { schema as full } from './schema';
  * import { selectModels } from '@abloatai/ablo/schema';
  *
- * // Vault subscribes to identity + dataroom content only.
+ * // Subscribe to identity and dataroom content only.
  * export const schema = selectModels(full, ['users', 'organizations', 'datarooms', 'folders', 'files']);
  * ```
  *
- * Relations whose target falls outside the selected set are dropped — the
- * subset only sees its own models. A dropped relation that carries `parent`
- * scope-inheritance throws instead: silently losing it would mis-route a
- * record's fan-out, so the selected set must be closed under `parent` edges.
+ * Relations whose target falls outside the selected set are dropped, so the
+ * subset sees only its own models. Dropping a relation that carries `parent`
+ * scope-inheritance throws instead, because silently losing it would mis-route
+ * a record's fan-out — the selected set must be closed under `parent` edges.
  */
 import type { Schema, SchemaRecord } from './schema.js';
 export declare function selectModels<S extends SchemaRecord, K extends keyof S & string>(schema: Schema<S>, keys: readonly K[]): Schema<Pick<S, K>>;

package/dist/schema/select.js

@@ -1,25 +1,25 @@
 /**
- * `selectModels` — project a schema down to a subset of its models.
+ * `selectModels` projects a schema down to a subset of its models.
  *
- * The Prisma-style "one canonical schema, each app selects what it needs"
- * primitive. Instead of re-declaring a model's fields in a second schema (which
- * must then be kept shape-identical by hand), an app picks the models it
- * subscribes to from the canonical schema. Field shapes, resolved FK columns,
- * computeds, typenames, and identity roles all come from the source — so a
- * subset is structurally incapable of drifting from the canonical definition.
+ * It lets one canonical schema serve several apps, each subscribing only to the
+ * models it needs. Rather than re-declare a model's fields in a second schema —
+ * which you would then have to keep identical by hand — an app selects the
+ * models it wants from the canonical schema. Field shapes, resolved foreign-key
+ * columns, computed getters, typenames, and identity roles all come from the
+ * source, so a subset cannot drift from the canonical definition.
  *
  * ```ts
- * import { schema as full } from '@ablo/schema';
+ * import { schema as full } from './schema';
  * import { selectModels } from '@abloatai/ablo/schema';
  *
- * // Vault subscribes to identity + dataroom content only.
+ * // Subscribe to identity and dataroom content only.
  * export const schema = selectModels(full, ['users', 'organizations', 'datarooms', 'folders', 'files']);
  * ```
  *
- * Relations whose target falls outside the selected set are dropped — the
- * subset only sees its own models. A dropped relation that carries `parent`
- * scope-inheritance throws instead: silently losing it would mis-route a
- * record's fan-out, so the selected set must be closed under `parent` edges.
+ * Relations whose target falls outside the selected set are dropped, so the
+ * subset sees only its own models. Dropping a relation that carries `parent`
+ * scope-inheritance throws instead, because silently losing it would mis-route
+ * a record's fan-out — the selected set must be closed under `parent` edges.
  */
 import { AbloValidationError } from '../errors.js';
 export function selectModels(schema, keys) {