@abloatai/ablo 0.26.0 → 0.27.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,8 +25,8 @@ 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';

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';