@abloatai/ablo 0.26.0 → 0.28.0

package/dist/schema/field.js

@@ -1,9 +1,10 @@
 /**
- * Schema Field Helpers
- *
- * Thin wrappers around Zod that add sync-engine metadata (type tag, indexed).
- * Metadata is stored in `z.describe()` as a JSON-encoded string so it
- * survives `.optional()`, `.nullable()`, and `.default()` chain calls.
+ * Field builders for schema definitions. Each helper — {@link field}.string(),
+ * .number(), .enum(), and so on — returns an ordinary Zod schema with a little
+ * sync-engine metadata attached (its type tag and whether it is indexed) plus a
+ * couple of chainable methods. The metadata is tucked into the schema's description
+ * as a JSON string so it survives `.optional()`, `.nullable()`, and `.default()`
+ * chaining, and {@link resolveFieldMeta} reads it back out as a {@link FieldMeta}.
  *
  * Usage:
  *   import { field } from '@abloatai/ablo/schema';
@@ -92,17 +93,11 @@ export function getFieldMeta(schema) {
     return { ...base, isOptional };
 }
 /**
- * Fallback: infer FieldMeta directly from a raw Zod schema when no
- * `field.*()` metadata was attached.
- *
- * Walks through `.optional()` / `.nullable()` / `.default()` wrappers
- * to find the inner primitive, then maps Zod's `_def.typeName` to
- * the sync-engine type tag. Used by `resolveFieldMeta` and by
- * `model()` / `query()` at definition time.
- *
- * Kept as an internal helper rather than exported directly — the
- * public API is `resolveFieldMeta`, which combines this fallback
- * with the `getFieldMeta` fast path.
+ * Infers a {@link FieldMeta} from a plain Zod schema that carries no field-builder
+ * metadata — for example a bare `z.string()`. It unwraps `.optional()`,
+ * `.nullable()`, and `.default()` to reach the inner type, then maps that Zod type
+ * to a sync-engine type tag. Most callers should use {@link resolveFieldMeta}
+ * instead, which tries the attached metadata first and falls back to this.
  */
 export function inferFieldMetaFromZod(schema) {
     let current = schema;
@@ -144,33 +139,24 @@ export function inferFieldMetaFromZod(schema) {
         current instanceof z.ZodRecord ||
         current instanceof z.ZodUnion ||
         current instanceof z.ZodUnknown ||
-        // `z.custom<T>()` is an opaque, structurally-uninspectable blob —
-        // by construction the engine can't see its shape, which is exactly
-        // the JSON-blob pattern (ProseMirror docs, LayerData/LayerStyle maps,
-        // chart specs). Classifying it as `'string'` (the fallthrough default)
-        // gave these fields deep MobX observability instead of the intended
-        // `observable.ref` (see Ablo.ts registerProperty), producing the
-        // microtask-storm + nested-reactivity-drift bug on live updates.
+        // `z.custom<T>()` is opaque — its shape cannot be inspected — so it is treated
+        // as a JSON blob rather than falling through to the `'string'` default. The type
+        // tag drives how the runtime observes the field, and an opaque custom value
+        // should be tracked by reference rather than deeply.
         current instanceof z.ZodCustom) {
         type = 'json';
     }
     return { type, isOptional, isIndexed: false, enumValues };
 }
 /**
- * Resolve FieldMeta for any Zod schema — whether it was built with
- * `field.*()` (which attaches sync-engine metadata) or with raw Zod
- * (which requires fallback inference from `_def.typeName`).
- *
- * This is the single public entry point for "given a Zod field, tell
- * me its sync-engine type tag and optionality." Both `model()` and
- * `query()` use it to populate their `fields` / `inputFields` maps at
- * definition time, and the schema serializer reads those maps at
- * serialization time.
+ * Resolves a {@link FieldMeta} for any Zod schema, whether it was built with a
+ * {@link field} builder (which attaches metadata) or with plain Zod (which needs
+ * inference). This is the single entry point for "given a Zod field, tell me its
+ * sync-engine type tag and whether it is optional"; the model and query builders use
+ * it to populate their field maps, and the serializer reads those maps.
  *
- * Contract: always returns a value. Never returns null. Unknown Zod
- * types fall through to `'string'` — this is intentional and matches
- * the existing behavior that was previously duplicated in
- * `model.ts:inferMetaFromZod`.
+ * It always returns a value and never returns null. A Zod type it does not recognize
+ * falls through to the `string` tag by design.
  */
 export function resolveFieldMeta(schema) {
     const attached = getFieldMeta(schema);
@@ -197,28 +183,28 @@ function buildField(schema, baseMeta) {
     return withFieldMethods(schema, { ...baseMeta, isIndexed: false });
 }
 export const field = {
-    /** String field */
+    /** Defines a text field. */
     string() {
         return buildField(z.string(), { type: 'string' });
     },
-    /** Number field */
+    /** Defines a numeric field. */
     number() {
         return buildField(z.number(), { type: 'number' });
     },
-    /** Boolean field */
+    /** Defines a true/false field. */
     boolean() {
         return buildField(z.boolean(), { type: 'boolean' });
     },
-    /** Date field */
+    /** Defines a timestamp field, represented as a JavaScript `Date`. */
     date() {
         return buildField(z.date(), { type: 'date' });
     },
-    /** Enum field with constrained string values */
+    /** Defines a field constrained to a fixed set of string values. */
     enum(values) {
         return buildField(z.enum(values), { type: 'enum', enumValues: values });
     },
     /**
-     * JSON field. Three call shapes:
+     * Defines a JSON field, with three call shapes:
      *
      * ```ts
      * field.json()                                        // unknown JSON blob
@@ -226,9 +212,9 @@ export const field = {
      * field.json({ icon: z.string().default('default') }) // typed sub-properties with defaults
      * ```
      *
-     * The third form is the key DX feature for metadata fields. It wraps the
-     * plain object in `z.object()` automatically, and the model runtime generates
-     * a `${field}Json` getter that parses the JSON string on read, applies Zod
+     * The third form is especially handy for metadata fields. It wraps the plain
+     * object in `z.object()` automatically, and the model runtime adds a
+     * `${field}Json` getter that parses the JSON string on read, applies the Zod
      * defaults, and caches the result.
      *
      * Example:
@@ -261,13 +247,14 @@ export const field = {
         }
         return buildField(inner, { type: 'json' });
     },
-    /** Indexed string field (shorthand for `field.string().indexed()`). */
+    /** Defines an indexed text field — shorthand for `field.string().indexed()`. */
     id() {
         return field.string().indexed();
     },
 };
-// ── Legacy function form (kept for backward compat) ──────────────────────
-/** Mark a Zod schema as indexed for fast lookups (function form). */
+// ── Function form ────────────────────────────────────────────────────────
+/** Marks a Zod schema as indexed so lookups on it use a database index. This is the
+ *  standalone-function form of the `.indexed()` chain method. */
 export function indexed(schema) {
     // Try to preserve existing metadata type tag if present.
     const meta = decodeMeta(schema.description);

package/dist/schema/generate.d.ts

@@ -1,18 +1,18 @@
 /**
- * Schema → TypeScript type emission — the `generate` half of the loop (the
- * counterpart to `diff`/migrate). Lowers a serialized schema to a `.ts` file of
- * row interfaces + an `AbloSchema` map, so a consumer's app is typed against the
- * exact schema that the database and sync layer enforce. Pure (returns source
- * text); the CLI writes it to disk.
+ * Generates TypeScript types from a serialized schema. Given the schema, it produces
+ * the source text of a `.ts` module containing one row interface per model plus an
+ * `AbloSchema` map, so an app is typed against the same schema the database and sync
+ * layer enforce. This function is pure and returns the source as a string; the
+ * command-line tool writes it to disk.
  *
- * This is the SDK's front door: the developer writes ONE `defineSchema`, pushes
- * it (which migrates the DB), and generates types FROM the same schema — so the
- * types they code against, the rows the DB stores, and the entities sync moves
- * are provably the same thing.
+ * It is the counterpart to the migration planner in {@link diffSchema}: you write one
+ * schema definition, push it (which migrates the database), and generate types from
+ * that same schema, so the types you code against, the rows the database stores, and
+ * the entities the sync layer moves all describe the same thing.
  *
- * v1 emits the row shape (base columns + declared fields, enums as literal
- * unions). Relations are resolved by the runtime SDK's typed accessors and are
- * not expanded here.
+ * The generated interface covers the base columns plus each declared field, with
+ * enums emitted as string-literal unions. Relations are not expanded here — the
+ * runtime SDK resolves those through its typed accessors.
  */
 import type { SchemaJSON } from './serialize.js';
 /** Emit a TypeScript module of row interfaces + the `AbloSchema` map. */

package/dist/schema/generate.js

@@ -1,18 +1,18 @@
 /**
- * Schema → TypeScript type emission — the `generate` half of the loop (the
- * counterpart to `diff`/migrate). Lowers a serialized schema to a `.ts` file of
- * row interfaces + an `AbloSchema` map, so a consumer's app is typed against the
- * exact schema that the database and sync layer enforce. Pure (returns source
- * text); the CLI writes it to disk.
+ * Generates TypeScript types from a serialized schema. Given the schema, it produces
+ * the source text of a `.ts` module containing one row interface per model plus an
+ * `AbloSchema` map, so an app is typed against the same schema the database and sync
+ * layer enforce. This function is pure and returns the source as a string; the
+ * command-line tool writes it to disk.
  *
- * This is the SDK's front door: the developer writes ONE `defineSchema`, pushes
- * it (which migrates the DB), and generates types FROM the same schema — so the
- * types they code against, the rows the DB stores, and the entities sync moves
- * are provably the same thing.
+ * It is the counterpart to the migration planner in {@link diffSchema}: you write one
+ * schema definition, push it (which migrates the database), and generate types from
+ * that same schema, so the types you code against, the rows the database stores, and
+ * the entities the sync layer moves all describe the same thing.
  *
- * v1 emits the row shape (base columns + declared fields, enums as literal
- * unions). Relations are resolved by the runtime SDK's typed accessors and are
- * not expanded here.
+ * The generated interface covers the base columns plus each declared field, with
+ * enums emitted as string-literal unions. Relations are not expanded here — the
+ * runtime SDK resolves those through its typed accessors.
  */
 import { BASE_FIELDS } from './schema.js';
 function tsType(meta) {

package/dist/schema/index.d.ts

@@ -25,12 +25,12 @@ export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from
 export { relation, type RelationDef, type RelationType } from './relation.js';
 export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } from './tenancy.js';
 export { residencySchema, DEFAULT_RESIDENCY, type ModelResidency, planeSchema, DEFAULT_PLANE, type SchemaPlane, } from './residency.js';
-export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, 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 { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './syncDeltaRow.js';
+export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from '../wire/delta.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, type ConflictAxis, } from './model.js';
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, type ConflictRule, } from './coordination.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, intersectRequestedWithAllowed, 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 { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, 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

@@ -28,47 +28,45 @@ export { field, indexed, getFieldMeta } from './field.js';
 export { relation } from './relation.js';
 // Tenancy — the single source of truth for how a model's rows are tenant-scoped.
 export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
-// Model residency — which DB a model's rows live in (`tenant` portable to a
-// customer's own DB, `control` = Ablo's own). Sibling axis to `tenancy`.
-// (Renamed from "plane" — that word is the server's tenancy scope.)
+// Model residency — which database a model's rows live in (`tenant` can be a
+// customer's own database, `control` is Ablo's). A sibling axis to `tenancy`.
 export { residencySchema, DEFAULT_RESIDENCY, 
 // Deliberate back-compat re-export of the deprecated aliases:
 // eslint-disable-next-line @typescript-eslint/no-deprecated
 planeSchema, 
 // eslint-disable-next-line @typescript-eslint/no-deprecated
 DEFAULT_PLANE, } from './residency.js';
-// Decomposed sync-delta storage row (P0 of the control/tenant plane split —
-// see docs/plans/sync-delta-zod-decomposition.md). Describes the existing
-// `sync_deltas` columns as Zod schemas grouped by subsystem + database plane.
-export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, } from './sync-delta-row.js';
-// Canonical WIRE delta contract — the broadcast (server→client) projection of
-// the stored row. The SDK client and the sync-server both derive their
-// `SyncDelta` type from these via `z.infer` so the contract cannot drift.
-export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './sync-delta-wire.js';
+// The stored `sync_deltas` row, described as Zod schemas grouped by subsystem and by
+// which database the columns live in.
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, } from './syncDeltaRow.js';
+// The wire delta contract — the server-to-client projection of the stored row.
+// Both the client SDK and the server derive their `SyncDelta` type from these with
+// `z.infer`, so the two ends cannot drift apart.
+export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from '../wire/delta.js';
 // Model builder
 export { model, scopeKindOf, } from './model.js';
-// Axis 3 — coordination authoring helpers for the `conflict` axis (composable
-// disposition fns + a `cn`-style combinator).
+// Coordination authoring helpers for the `conflict` axis — composable disposition
+// functions plus a combinator that merges them.
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, } from './coordination.js';
-// Claim-first shorthand: `mutable.lazy({...})` and friends. Read the
-// safety posture and load shape off the verb tokens; everything else
-// falls back to sensible defaults. See sugar.ts for the full pattern.
+// Claim-first shorthand for common model options: `mutable.lazy({...})` and friends
+// encode a model's write-safety and load strategy in the verb, and fall back to
+// sensible defaults for everything else.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
 export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, 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)
+// Schema ⇄ JSON — serialize a schema for transport and rebuild it on the far side.
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels } from './select.js';
-// Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
+// Schema → Postgres DDL — shared by the host implementation and the command-line tools.
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
-// Safe-DDL locking knobs (lock_timeout + bounded 55P03 retry) — the ONE
-// reader shared by `ablo migrate` and the hosted executor (ddlExec.ts), so an
-// operator tuning ABLO_SCHEMA_LOCK_* gets the same behavior on both paths.
+// Safe-DDL locking knobs (lock_timeout plus a bounded retry on lock contention),
+// shared by `ablo migrate` and the host that applies a schema push, so tuning the
+// ABLO_SCHEMA_LOCK_* variables changes both paths the same way.
 export { PG_LOCK_NOT_AVAILABLE, resolveDdlLockTimeout, resolveDdlMaxLockAttempts, ddlLockRetryBackoffMs, } from './ddlLock.js';
-// Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
+// Schema diff + migration planning — produces the plan the DDL layer turns into SQL.
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
-// Schema → TypeScript type emission (the `generate` half; pure)
+// Schema → TypeScript type emission.
 export { generateTypes } from './generate.js';
 // Query definition DSL + type inference
 export { query, defineQueries, } from './queries.js';