@abloatai/ablo 0.26.0 → 0.28.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]>>;
@@ -230,24 +228,19 @@ export declare function composeEntitySyncGroups(record: EntityContext, def: {
     readonly entityRoles?: readonly EntityRole[];
 }): readonly SyncGroup[];
 /**
- * Apply capability-style intersection to a client-requested sync-group
- * set. Mirrors the cap-bearer path where Biscuit caveats narrow the
- * client's requested set to what's actually authorized. Fully generic —
- * it never inspects the group strings — so it lives here beside the
- * composition helpers rather than in any product schema package
- * (`@ablo/schema` re-exports it for compat).
+ * 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 (the default subscription scope for this participant).
- *   - If the client requested a non-empty subset, intersect against the
- *     identity-derived allowed set — drop any group the participant is
- *     not authorized to subscribe to. Logs the dropped groups via the
- *     optional `logDropped` callback for observability.
- *   - If the intersection is empty after filtering, fall back to the
- *     full allowed set rather than emit `[]` (which would degenerate to
- *     the server-side `['default']` fallback and produce silent zero-
- *     delta delivery).
+ *   - 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[];

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(),
@@ -198,24 +197,19 @@ export function composeEntitySyncGroups(record, def) {
     return Array.from(out);
 }
 /**
- * Apply capability-style intersection to a client-requested sync-group
- * set. Mirrors the cap-bearer path where Biscuit caveats narrow the
- * client's requested set to what's actually authorized. Fully generic —
- * it never inspects the group strings — so it lives here beside the
- * composition helpers rather than in any product schema package
- * (`@ablo/schema` re-exports it for compat).
+ * 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 (the default subscription scope for this participant).
- *   - If the client requested a non-empty subset, intersect against the
- *     identity-derived allowed set — drop any group the participant is
- *     not authorized to subscribe to. Logs the dropped groups via the
- *     optional `logDropped` callback for observability.
- *   - If the intersection is empty after filtering, fall back to the
- *     full allowed set rather than emit `[]` (which would degenerate to
- *     the server-side `['default']` fallback and produce silent zero-
- *     delta delivery).
+ *   - 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;

package/dist/schema/schema.d.ts

@@ -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,43 +129,71 @@ 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;
+    readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
 };
+/**
+ * The row shape a reactive read returns: the model's data fields, base fields,
+ * and schema computed getters — WITHOUT relation accessors and WITHOUT model
+ * methods. Derived from the model definition, exactly like {@link InferModel},
+ * mirroring what `toReactiveSnapshot()` produces at runtime.
+ *
+ * Relations (`hasMany` / `belongsTo`) are store-backed getters that exist only
+ * on the pool's model instances, so a reactive row honestly omits them —
+ * reading `row.layers` is a compile error instead of a silent `undefined`.
+ * Compose relations through a selector or hook instead.
+ *
+ * The same pairing other data layers converged on: Zero's data-only `Row<...>`
+ * with relations added per-query, Prisma's scalar-only model types with
+ * `GetPayload<{ include }>`, mobx-state-tree's `Instance<T>` / `SnapshotOut<T>`.
+ */
+export type InferRow<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, RelationRecord, infer C> ? // Same reserved-field guard as InferModel — see the comment there.
+Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & InferComputed<C> : never;
+/**
+ * The reactive-row companion to {@link Model}. Once your project's
+ * `ablo/register.ts` registers the schema, a single argument is all it takes:
+ *
+ * ```ts
+ * type SlideRow = Row<'slides'>;    // data fields + computeds, no relations
+ * type Slide    = Model<'slides'>;  // the pool's model instance
+ * ```
+ *
+ * Without that registration, or for a second schema, pass the schema
+ * explicitly: `Row<typeof schema, 'slides'>`.
+ */
+export type Row<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferRow<RegisteredSchema, A> : never : A extends Schema ? InferRow<A, B extends keyof A['models'] ? B : never> : never;
 /**
  * Infer the return types of computed getters.
  * Maps each computed function's return type into a readonly property.
@@ -202,9 +229,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,16 +242,12 @@ 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 interface DeleteId<S extends Schema, ModelName extends keyof S['models']> {
     id: string;

package/dist/schema/schema.js

@@ -22,9 +22,9 @@
 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.
+// 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)
@@ -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.
@@ -135,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'`)
@@ -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)) {

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) {