@abloatai/ablo 0.35.0 → 0.37.0

package/dist/schema/coordination.d.ts

@@ -1,112 +0,0 @@
-/**
- * Authoring helpers for a model's `conflict` axis — the setting that decides
- * what happens when two writers touch the same row. Instead of writing a raw
- * disposition map, you name the rules the way the rest of the schema DSL reads
- * (`relation.belongsTo()`, `field.string()`), and chain them the way a field
- * chains its own modifiers:
- *
- * ```ts
- * import { coordination } from '@abloatai/ablo/schema';
- *
- * conflict: coordination.humansOverwrite().agentsReject()
- * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
- * ```
- *
- * Each rule is named for the disposition it applies — drawn from the same
- * `overwrite | reject | notify` vocabulary the write guards use (`onStale`) —
- * and every one of them is also available as a standalone function, which
- * {@link coordination} merges when the rules are assembled dynamically rather
- * than written out:
- *
- * ```ts
- * conflict: coordination(humansOverwrite(), agentsReject())
- * ```
- *
- * Either way the result is plain, serializable data that the engine reads at
- * commit time. The `humans`/`agents` wording belongs to the author; the `user`/
- * `agent`/`system` keys belong to the wire, and this module is the one place
- * the two are mapped to each other.
- */
-import type { ConflictAxis } from '../transaction/policy/types.js';
-/**
- * One coordination rule: a partial {@link ConflictAxis} produced by a
- * disposition helper below. Compose with {@link coordination}.
- */
-export type ConflictRule = ConflictAxis;
-/** A human's conflicting write wins and overwrites the other; it is never blocked. Among humans this gives last-write-wins. */
-export declare const humansOverwrite: () => ConflictRule;
-/** A human's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
-export declare const humansReject: () => ConflictRule;
-/** A human's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
-export declare const humansNotify: () => ConflictRule;
-/** An agent's conflicting write wins and overwrites the other (rarely what you want). */
-export declare const agentsOverwrite: () => ConflictRule;
-/** An agent's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
-export declare const agentsReject: () => ConflictRule;
-/** An agent's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
-export declare const agentsNotify: () => ConflictRule;
-/** A system or automation write wins and overwrites the other. */
-export declare const systemOverwrite: () => ConflictRule;
-/** A system or automation write is rejected. */
-export declare const systemReject: () => ConflictRule;
-/** A system or automation stale write triggers a notification: it re-reads and re-applies. */
-export declare const systemNotify: () => ConflictRule;
-/**
- * A conflict axis that is still open to more rules. Every method applies one
- * disposition and hands back a new axis, so a model's whole stance reads as a
- * single sentence and the reader never has to hold a merge in their head.
- *
- * Each method delegates to the standalone rule of the same name, so a
- * disposition map like `{ user: 'overwrite' }` is written in exactly one place
- * no matter which authoring style a schema uses. Dispositions are own
- * enumerable properties and the methods live on the prototype, so an axis
- * serializes to the same plain object the server has always received.
- */
-declare class CoordinationAxis implements ConflictAxis {
-    readonly user?: ConflictAxis['user'];
-    readonly agent?: ConflictAxis['agent'];
-    readonly system?: ConflictAxis['system'];
-    constructor(axis: ConflictAxis);
-    /** Apply one more rule, later winning on a repeated kind. */
-    private and;
-    humansOverwrite(): CoordinationAxis;
-    humansReject(): CoordinationAxis;
-    humansNotify(): CoordinationAxis;
-    agentsOverwrite(): CoordinationAxis;
-    agentsReject(): CoordinationAxis;
-    agentsNotify(): CoordinationAxis;
-    systemOverwrite(): CoordinationAxis;
-    systemReject(): CoordinationAxis;
-    systemNotify(): CoordinationAxis;
-}
-/**
- * Merges coordination rules into a single {@link ConflictAxis}. Later rules win
- * on key collisions, and a committer kind you leave out falls through to the
- * engine's default at commit time.
- *
- * ```ts
- * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }
- * ```
- */
-declare function mergeRules(...rules: readonly ConflictRule[]): ConflictAxis;
-/**
- * The coordination vocabulary, reachable through one name. Call it to merge
- * rules you have assembled; reach through it to start a chain.
- *
- * ```ts
- * conflict: coordination.humansOverwrite().agentsReject()
- * conflict: coordination(humansOverwrite(), agentsReject())
- * ```
- */
-export declare const coordination: typeof mergeRules & {
-    humansOverwrite: () => CoordinationAxis;
-    humansReject: () => CoordinationAxis;
-    humansNotify: () => CoordinationAxis;
-    agentsOverwrite: () => CoordinationAxis;
-    agentsReject: () => CoordinationAxis;
-    agentsNotify: () => CoordinationAxis;
-    systemOverwrite: () => CoordinationAxis;
-    systemReject: () => CoordinationAxis;
-    systemNotify: () => CoordinationAxis;
-};
-export {};

package/dist/schema/coordination.js

@@ -1,129 +0,0 @@
-/**
- * Authoring helpers for a model's `conflict` axis — the setting that decides
- * what happens when two writers touch the same row. Instead of writing a raw
- * disposition map, you name the rules the way the rest of the schema DSL reads
- * (`relation.belongsTo()`, `field.string()`), and chain them the way a field
- * chains its own modifiers:
- *
- * ```ts
- * import { coordination } from '@abloatai/ablo/schema';
- *
- * conflict: coordination.humansOverwrite().agentsReject()
- * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
- * ```
- *
- * Each rule is named for the disposition it applies — drawn from the same
- * `overwrite | reject | notify` vocabulary the write guards use (`onStale`) —
- * and every one of them is also available as a standalone function, which
- * {@link coordination} merges when the rules are assembled dynamically rather
- * than written out:
- *
- * ```ts
- * conflict: coordination(humansOverwrite(), agentsReject())
- * ```
- *
- * Either way the result is plain, serializable data that the engine reads at
- * commit time. The `humans`/`agents` wording belongs to the author; the `user`/
- * `agent`/`system` keys belong to the wire, and this module is the one place
- * the two are mapped to each other.
- */
-// ── Humans (user sessions) ──────────────────────────────────────────────
-/** A human's conflicting write wins and overwrites the other; it is never blocked. Among humans this gives last-write-wins. */
-export const humansOverwrite = () => ({ user: 'overwrite' });
-/** A human's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
-export const humansReject = () => ({ user: 'reject' });
-/** A human's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
-export const humansNotify = () => ({ user: 'notify' });
-// ── Agents (AI) ─────────────────────────────────────────────────────────
-/** An agent's conflicting write wins and overwrites the other (rarely what you want). */
-export const agentsOverwrite = () => ({ agent: 'overwrite' });
-/** An agent's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
-export const agentsReject = () => ({ agent: 'reject' });
-/** An agent's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
-export const agentsNotify = () => ({ agent: 'notify' });
-// ── System / automation ─────────────────────────────────────────────────
-/** A system or automation write wins and overwrites the other. */
-export const systemOverwrite = () => ({ system: 'overwrite' });
-/** A system or automation write is rejected. */
-export const systemReject = () => ({ system: 'reject' });
-/** A system or automation stale write triggers a notification: it re-reads and re-applies. */
-export const systemNotify = () => ({ system: 'notify' });
-/**
- * A conflict axis that is still open to more rules. Every method applies one
- * disposition and hands back a new axis, so a model's whole stance reads as a
- * single sentence and the reader never has to hold a merge in their head.
- *
- * Each method delegates to the standalone rule of the same name, so a
- * disposition map like `{ user: 'overwrite' }` is written in exactly one place
- * no matter which authoring style a schema uses. Dispositions are own
- * enumerable properties and the methods live on the prototype, so an axis
- * serializes to the same plain object the server has always received.
- */
-class CoordinationAxis {
-    constructor(axis) {
-        Object.assign(this, Object.fromEntries(Object.entries(axis).filter(([, mode]) => mode !== undefined)));
-    }
-    /** Apply one more rule, later winning on a repeated kind. */
-    and(rule) {
-        return new CoordinationAxis({ ...this, ...rule });
-    }
-    humansOverwrite() {
-        return this.and(humansOverwrite());
-    }
-    humansReject() {
-        return this.and(humansReject());
-    }
-    humansNotify() {
-        return this.and(humansNotify());
-    }
-    agentsOverwrite() {
-        return this.and(agentsOverwrite());
-    }
-    agentsReject() {
-        return this.and(agentsReject());
-    }
-    agentsNotify() {
-        return this.and(agentsNotify());
-    }
-    systemOverwrite() {
-        return this.and(systemOverwrite());
-    }
-    systemReject() {
-        return this.and(systemReject());
-    }
-    systemNotify() {
-        return this.and(systemNotify());
-    }
-}
-/**
- * Merges coordination rules into a single {@link ConflictAxis}. Later rules win
- * on key collisions, and a committer kind you leave out falls through to the
- * engine's default at commit time.
- *
- * ```ts
- * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }
- * ```
- */
-function mergeRules(...rules) {
-    return Object.assign({}, ...rules);
-}
-/**
- * The coordination vocabulary, reachable through one name. Call it to merge
- * rules you have assembled; reach through it to start a chain.
- *
- * ```ts
- * conflict: coordination.humansOverwrite().agentsReject()
- * conflict: coordination(humansOverwrite(), agentsReject())
- * ```
- */
-export const coordination = Object.assign(mergeRules, {
-    humansOverwrite: () => new CoordinationAxis(humansOverwrite()),
-    humansReject: () => new CoordinationAxis(humansReject()),
-    humansNotify: () => new CoordinationAxis(humansNotify()),
-    agentsOverwrite: () => new CoordinationAxis(agentsOverwrite()),
-    agentsReject: () => new CoordinationAxis(agentsReject()),
-    agentsNotify: () => new CoordinationAxis(agentsNotify()),
-    systemOverwrite: () => new CoordinationAxis(systemOverwrite()),
-    systemReject: () => new CoordinationAxis(systemReject()),
-    systemNotify: () => new CoordinationAxis(systemNotify()),
-});

package/dist/schema/ddl.d.ts

@@ -1,97 +0,0 @@
-/**
- * Turns a schema definition into the ordered Postgres DDL that provisions and
- * migrates its tables. A schema built with `defineSchema(...)` and serialized to
- * {@link SchemaJSON} is the single source of truth, and this module lowers it to
- * ordered SQL strings.
- *
- * The same generators run wherever tables are created — in a hosted server
- * applying them to the Postgres it manages, and in the `ablo migrate` CLI
- * applying them to a customer's own Postgres — so the SQL, from column types to
- * row-level security to enum checks, is identical no matter who runs it.
- *
- * Everything here is pure: it returns strings and touches no database. The
- * execution side — the transaction and advisory lock that actually run the
- * statements — lives with each caller, because it is coupled to that caller's
- * Postgres client and error types.
- *
- *  - {@link generateProvisionPlan} builds an additive, idempotent plan (CREATE
- *    and ADD … IF NOT EXISTS, plus row-level security) that never loses data —
- *    the "create my tables" primitive.
- *  - {@link generateMigrationPlan} is its destructive-aware counterpart, driven
- *    by a {@link diffSchema} step list: drops, renames, type casts, and
- *    backfills.
- */
-import type { SchemaJSON, ModelJSON } from './serialize.js';
-import type { MigrationStep, BackfillValue } from './diff.js';
-export interface ProvisionPlan {
-    /** The Postgres schema the tables live in (`app_<id>` or `public`). */
-    readonly appSchema: string;
-    /** Ordered, idempotent DDL statements. Safe to run repeatedly. Executors run
-     *  these together in one transaction. */
-    readonly statements: readonly string[];
-    /** Post-commit, non-transactional DDL (`VALIDATE CONSTRAINT`, `CREATE INDEX
-     *  CONCURRENTLY`) — run after {@link statements} commit, each outside any
-     *  transaction, best-effort. Keeps the lock-heavy and scan-heavy work off the
-     *  main transaction so adding a foreign key never freezes a large, live table.
-     *  Optional: when absent, there is nothing to run. */
-    readonly concurrent?: readonly string[];
-}
-export interface ProvisionOptions {
-    /**
-     * Emit `DEFERRABLE INITIALLY DEFERRED` foreign-key constraints for the
-     * belongsTo relations that opt in; see {@link foreignKeyStatements} for exactly
-     * which relations qualify. Off by default, so soft references keep out-of-order
-     * sync robust. Turn it on for a customer's own database, where a clean,
-     * navigable relational schema is wanted and the database starts empty, so a
-     * constraint has nothing to fail against.
-     */
-    readonly foreignKeys?: boolean;
-}
-export interface MigrationPlan {
-    /** The app Postgres schema the DDL targets (`app_<id>` or `public`). */
-    readonly appSchema: string;
-    /** Ordered DDL statements (expand → contract). Run in one transaction. */
-    readonly statements: readonly string[];
-    /** Post-commit, non-transactional DDL — see {@link ProvisionPlan.concurrent}. */
-    readonly concurrent?: readonly string[];
-}
-/** Per-app schema name for an app (organization) id. */
-export declare function appSchemaName(organizationId: string): string;
-export declare function camelToSnake(identifier: string): string;
-/**
- * Converts snake_case to camelCase — the inverse of {@link camelToSnake}. This
- * is the read-side translation: a column read back from a customer's own
- * database maps to the same JavaScript field the SDK wrote, so
- * `camelToSnake('operatorId') === 'operator_id'` and
- * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
- */
-export declare function snakeToCamel(identifier: string): string;
-/** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
-export declare function q(identifier: string): string;
-export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;
-/**
- * Builds the additive, idempotent provisioning plan for an app. Pure — it does
- * not touch a database.
- *
- * `targetSchema` is where the tables live: a per-app Postgres schema such as
- * `app_<id>`, or `public` when the database itself is the isolation boundary
- * (for example a customer's own database). For `public` the `CREATE SCHEMA`
- * statement is skipped, since it always exists.
- */
-export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string, opts?: ProvisionOptions): ProvisionPlan;
-/**
- * Lower an ordered migration step list to DDL. `next` is the schema being pushed
- * (the target column shapes are read from it), `prev` the active one (used to
- * resolve the *old* table name on a model rename).
- */
-export declare function generateMigrationPlan(steps: readonly MigrationStep[], opts: {
-    readonly prev: SchemaJSON | null;
-    readonly next: SchemaJSON;
-    readonly targetSchema: string;
-    /** Constant seed values that let a required-field add / made-required step
-     *  set NOT NULL on a non-empty table. Keyed by (model, field). */
-    readonly backfills?: readonly BackfillValue[];
-    /** Emit deferrable foreign-key constraints for the relations that opt in.
-     *  Off by default — see {@link ProvisionOptions.foreignKeys}. */
-    readonly foreignKeys?: boolean;
-}): MigrationPlan;