@abloatai/transaction 0.37.0

package/src/schema/index.ts

@@ -0,0 +1,278 @@
+/**
+ * @abloatai/transaction/schema — Schema Definition DSL
+ *
+ * Define your data models with Zod. Types are inferred automatically.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineSchema, model, relation } from '@abloatai/transaction/schema';
+ *
+ * export const schema = defineSchema({
+ *   tasks: model({
+ *     title: z.string(),
+ *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
+ *     projectId: z.string().optional(),
+ *   }, {
+ *     project: relation.belongsTo('projects', 'projectId'),
+ *   }),
+ * });
+ *
+ * type Task = Model<typeof schema, 'tasks'>;
+ * ```
+ */
+
+// Re-export Zod for convenience (consumers can also import directly)
+export { z } from 'zod';
+
+// Field helpers (optional convenience wrappers around Zod)
+export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
+
+// A field as a value rather than a quoted name — `schema.fields.tasks.status`.
+// Surfaces that name a field (claims today) take one of these so a name that
+// does not exist stops compiling.
+export {
+  fieldSelection,
+  isFieldRef,
+  type FieldRef,
+  type FieldSelection,
+  type FieldSelector,
+} from './fieldRef.js';
+
+// Relation builders
+export { relation, type RelationDef, type RelationType } 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,
+  type Tenancy,
+  type ScopedViaRef,
+  type PolicyInput,
+} from './tenancy.js';
+
+// 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,
+  type ModelResidency,
+} from './residency.js';
+
+// The stored `sync_deltas` row, described as Zod schemas grouped by subsystem and by
+// which database the columns live in.
+export {
+  syncDeltaCoreSchema,
+  deltaAttributionSchema,
+  syncDeltaRowSchema,
+  participantKindSchema,
+  confirmationStateSchema,
+  backfillProvenanceSchema,
+  DELTA_DATA_CLASSIFICATION,
+  DELTA_PHYSICAL_STORAGE,
+  type SyncDeltaCore,
+  type DeltaAttribution,
+  type SyncDeltaRow,
+  type ParticipantKind,
+  type ConfirmationState,
+  type BackfillProvenance,
+} from '../log/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,
+  type SyncDeltaAction,
+  type WireDeltaData,
+  type ParticipantRef,
+  type SyncDeltaWireCore,
+  type ClientSyncDelta,
+  type ServerSyncDelta,
+} from '../wire/delta.js';
+
+// Model builder
+export {
+  model,
+  scopeKindOf,
+  // Both meanings: the value a tool enumerates to learn the strategies, and the
+  // type a `load` option is checked against. `loadsAtBootstrap` is the one
+  // predicate both the client subscription and the server payload ask.
+  LoadStrategy,
+  DEFAULT_LOAD_STRATEGY,
+  loadsAtBootstrap,
+  type ModelDef,
+  type ModelOptions,
+  type PersistOptions,
+  type RelationRecord,
+  type GrantsRef,
+  type ConflictAxis,
+} from './model.js';
+
+// 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,
+  type ConflictRule,
+} from './coordination.js';
+
+// 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, type SugarOptions } from './sugar.js';
+
+// Schema definition + type inference
+export {
+  defineSchema,
+  composeIdentitySyncGroups,
+  type Schema,
+  type SchemaRecord,
+  type Model,
+  type Row,
+  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,
+  type SessionSettings,
+  type SessionSettingSource,
+  RESERVED_SESSION_SETTINGS,
+} from './schema.js';
+
+// Schema ⇄ JSON — serialize a schema for transport and rebuild it on the far side.
+export {
+  serializeSchema,
+  parseSchema,
+  toSchemaJSON,
+  fromSchemaJSON,
+  schemaHash,
+  modelHash,
+  type SchemaJSON,
+  type ModelJSON,
+  type RelationJSON,
+} from './serialize.js';
+
+// Schema projection — derive an app's subset from one canonical schema.
+export { selectModels, omitModels } from './select.js';
+
+// Schema → Postgres DDL — shared by the host implementation and the command-line tools.
+export {
+  generateProvisionPlan,
+  generateMigrationPlan,
+  appSchemaName,
+  camelToSnake,
+  snakeToCamel,
+  q,
+  sqlType,
+  type ProvisionPlan,
+  type MigrationPlan,
+} from './ddl.js';
+
+// 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,
+  type DdlLockEnv,
+} from './ddlLock.js';
+
+// Schema diff + migration planning — produces the plan the DDL layer turns into SQL.
+export {
+  diffSchema,
+  classifyMigration,
+  classifyCast,
+  isAutoApplicable,
+  isBlockerResolved,
+  unresolvedBlockers,
+  type BackfillValue,
+  type MigrationStep,
+  type FieldChanges,
+  type FieldColumnChange,
+  type FieldTypeChange,
+  type NullabilityChange,
+  type EnumValuesChange,
+  type IndexChange,
+  type CastSafety,
+  type FieldType,
+  type RenameHints,
+  type MigrationSignal,
+  type MigrationClassification,
+  type WarningCode,
+  type BlockerCode,
+} from './diff.js';
+
+// Schema → TypeScript type emission.
+export { generateTypes } from './generate.js';
+
+// Query definition DSL + type inference
+export {
+  query,
+  defineQueries,
+  type QueryDef,
+  type QueryRecord,
+  type Queries,
+  type InferQueryInput,
+  type InferQueryResult,
+} from './queries.js';
+
+// The OpenAPI generator describes the language-agnostic `/v1` surface — the
+// primitive itself, which a Python or Go caller consumes with no TypeScript
+// anywhere — so it lives in the settlement core (ADR 0016). Re-exported here so
+// the `@abloatai/ablo/schema` import path keeps resolving.
+export { abloOpenApi, schemaToOpenApi, type SchemaToOpenApiOptions } from './openapi.js';

package/src/schema/loadStrategy.ts

@@ -0,0 +1,52 @@
+/**
+ * When a model's rows are loaded from the server.
+ *
+ *   - `instant` — loaded during bootstrap, before the model is first used.
+ *   - `lazy`    — loaded all at once on first access.
+ *
+ * One declaration serves both sides of the seam. `LoadStrategy.instant` is the
+ * value the engine branches on once a model is registered; `'instant'` is the
+ * word an author writes in `model(…, { load })`. They are the same name because
+ * they are the same axis — a const object merged with the type of its own
+ * values, rather than an enum, because a string enum is nominal and would
+ * refuse the plain `'instant'` an author actually types.
+ *
+ * The set is deliberately this small. It previously named `partial`,
+ * `explicitlyRequested`, and `local` on the runtime side and `manual` on the
+ * authoring side, and not one of those was reachable end to end: `manual` had
+ * no implementation and resolved to `lazy`, while the other three had no way to
+ * be declared. A member no schema can produce, or no branch can observe, is a
+ * promise the engine has no way to keep.
+ */
+
+export const LoadStrategy = {
+  /** Loaded during startup, before it is first used — for models needed right away. */
+  instant: 'instant',
+
+  /** Loaded all at once the first time it is needed — for secondary models. */
+  lazy: 'lazy',
+} as const;
+
+export type LoadStrategy = (typeof LoadStrategy)[keyof typeof LoadStrategy];
+
+/** The strategy a model gets when it declares none. */
+export const DEFAULT_LOAD_STRATEGY: LoadStrategy = LoadStrategy.instant;
+
+/**
+ * Whether a model's rows arrive in the bootstrap payload rather than on first
+ * access. This is the question the client asks when it builds the bootstrap
+ * subscription and the question the server asks when it assembles the payload,
+ * and the two must answer it identically or a model is requested by one side
+ * and withheld by the other.
+ *
+ * It is a function rather than a comparison spelled at each site because the
+ * sites disagreed about how to spell it: one asked `load !== 'lazy'`, another
+ * `load === 'instant'`, a third `load === 'lazy' ? … : …`. Against a two-member
+ * set those are the same predicate, so nothing failed. Against a third member
+ * they are three different predicates, and the first would have enrolled it in
+ * bootstrap while the second withheld it — the kind of split that surfaces as
+ * rows that never arrive, far from the line that caused it.
+ */
+export function loadsAtBootstrap(load: LoadStrategy | undefined): boolean {
+  return (load ?? DEFAULT_LOAD_STRATEGY) === LoadStrategy.instant;
+}