@abloatai/ablo 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- **Axis 3 — declare write-conflict behaviour in the schema (new).** A model can now
+  state what happens when a commit collides with a foreign claim or a stale snapshot —
+  per committer kind (`user` / `agent` / `system`) — right next to its fields, using the
+  same `overwrite | reject | notify` vocabulary as the `onStale` write guard. It is a
+  third axis, orthogonal to `policy` (read access) and `groups` (delta routing).
+
+  - **`conflict` on `model()`** — a plain, serializable disposition map. Pure data, so it
+    round-trips through the schema registry to the server; the generic engine interprets it
+    at the commit chokepoint (no per-model logic in the engine).
+
+    ```ts
+    // "a human's edit always wins (never blocked); an agent yields"
+    conflict: { user: 'overwrite', agent: 'reject' }
+    ```
+
+  - **Composable authoring helpers (new, from `@abloatai/ablo/schema`)** — disposition
+    functions plus a `cn`/`cx`-style combinator, so conflict policy reads like the rest of
+    the DSL (`relation.belongsTo()`) and like modern config (`plugins: [admin(), …]`):
+
+    ```ts
+    import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
+
+    conflict: coordination(humansOverwrite(), agentsReject())
+    // → { user: 'overwrite', agent: 'reject' }
+    ```
+
+    Exports: `coordination`, `humansOverwrite` / `humansReject` / `humansNotify`,
+    `agentsOverwrite` / `agentsReject` / `agentsNotify`,
+    `systemOverwrite` / `systemReject` / `systemNotify`, and the `ConflictRule` type.
+
+  - An omitted committer kind falls through to the engine default (reject; honor
+    `onStale: 'notify'`), so this is fully additive — existing schemas are unchanged.
+    New public types `ConflictAxis` (also `Ablo.Conflict.Axis`) and the
+    `interpretConflictAxis` interpreter are exported for custom policy composition.
+
+- **First-party shared schema for ephemeral keys (new).** `mintUserSessionKey` now accepts
+  `schemaProjectId` + `schemaOwnerOrgId`, binding the minted `ek_` to a schema owner-org +
+  project so **schema** resolves org-independently (one schema serves all of an integrator's
+  end-user orgs) while **data** stays scoped to `organizationId`. Requires the `sk_` to carry
+  `ephemeral:mint-any-org`; omit both for the existing per-org (BYO) behaviour.
+
 ## 0.15.1
 
 ### Patch Changes

package/dist/auth/index.d.ts

@@ -38,6 +38,13 @@ export interface MintUserSessionRequest {
      *  `Stripe-Account` analogue. Requires the `sk_` to carry
      *  `ephemeral:mint-any-org`; omit to mint into the key's own org. */
     readonly organizationId?: string;
+    /** FIRST-PARTY SHARED SCHEMA: bind the minted `ek_` to a schema owner-org +
+     *  project so SCHEMA resolves org-independently (one schema for all the
+     *  integrator's end-user orgs), while DATA stays scoped to `organizationId`.
+     *  Requires the `sk_` to carry `ephemeral:mint-any-org`. Omit for the normal
+     *  per-org behaviour (every external BYO customer). */
+    readonly schemaProjectId?: string;
+    readonly schemaOwnerOrgId?: string;
     readonly syncGroups?: readonly string[];
     readonly ttlSeconds: number;
     readonly label?: string;

package/dist/auth/index.js

@@ -108,6 +108,8 @@ export async function mintUserSessionKey(options) {
             body: JSON.stringify({
                 user: { id: options.userId },
                 ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+                ...(options.schemaProjectId ? { schemaProjectId: options.schemaProjectId } : {}),
+                ...(options.schemaOwnerOrgId ? { schemaOwnerOrgId: options.schemaOwnerOrgId } : {}),
                 ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
                 ttlSeconds: options.ttlSeconds,
                 ...(options.label ? { label: options.label } : {}),

package/dist/client/Ablo.d.ts

@@ -1010,6 +1010,7 @@ export declare namespace Ablo {
         type Operation = _Policy.ConflictOperation;
         type Decision = _Policy.ConflictDecision;
         type Policy = _Policy.ConflictPolicy;
+        type Axis = _Policy.ConflictAxis;
     }
     namespace Commit {
         type Wait = import('./Ablo.js').CommitWait;

package/dist/index.d.ts

@@ -58,7 +58,7 @@ import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
-export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './policy/index.js';
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';

package/dist/index.js

@@ -80,7 +80,7 @@ export { createSourceConnector, } from './source/connector.js';
 // (reject-on-stale) is already applied server-side, so you only import it
 // to COMPOSE a custom policy. Leave it alone and stale writes are rejected
 // safely by default. Type counterparts live under `Ablo.Conflict.*`.
-export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.

package/dist/policy/index.d.ts

@@ -15,5 +15,5 @@
  * };
  * ```
  */
-export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from './types.js';
-export { defaultPolicy, capabilityPreemptPolicy } from './types.js';
+export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './types.js';

package/dist/policy/index.js

@@ -15,4 +15,4 @@
  * };
  * ```
  */
-export { defaultPolicy, capabilityPreemptPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './types.js';

package/dist/policy/types.d.ts

@@ -7,6 +7,7 @@
  * Adding new shapes is additive on the discriminated union.
  */
 import type { ParticipantRef } from '../types/streams.js';
+import type { OnStaleMode } from '../coordination/schema.js';
 export type ConflictKind = 'stale_context' | 'claim_held';
 /** Fields shared by every conflict shape. */
 interface ConflictBase {
@@ -134,7 +135,7 @@ export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<
  * detection. This preserves the legacy always-reject default for callers that
  * don't opt into `notify`.
  */
-export declare const defaultPolicy: ConflictPolicy;
+export declare const defaultPolicy: (conflict: Conflict) => ConflictDecision;
 /**
  * Capability-gated preemption. An `claim_held` conflict is PREEMPTED when the
  * committer holds the `claim.preempt` operation in its capability allowlist
@@ -144,4 +145,45 @@ export declare const defaultPolicy: ConflictPolicy;
  * policy. The authorization is the capability, not an identity string.
  */
 export declare const capabilityPreemptPolicy: ConflictPolicy;
+/**
+ * **Axis 3 — declared write-conflict disposition, per committer kind.**
+ *
+ * A model declares this in its schema (`conflict: { user: 'overwrite', agent:
+ * 'reject' }`); the generic engine interprets it at the commit chokepoint. It's
+ * pure data — the same `OnStaleMode` vocabulary used by write guards
+ * (`'reject' | 'overwrite' | 'notify'`) — so it serializes through the schema
+ * registry to the schema-agnostic server, which names no app model.
+ *
+ * Keys are the COMMITTER's participant kind (server-derived, forge-proof): an
+ * omitted kind falls through to the engine default. So `{ user: 'overwrite',
+ * agent: 'reject' }` reads "a human's write wins (never blocked); an agent's
+ * write yields", and `system` (unlisted) takes the default.
+ */
+export interface ConflictAxis {
+    /** What happens when a human (`user` session) commits into a conflict. */
+    readonly user?: OnStaleMode;
+    /** What happens when an AI `agent` commits into a conflict. */
+    readonly agent?: OnStaleMode;
+    /** What happens when a `system` / automation actor commits into a conflict. */
+    readonly system?: OnStaleMode;
+}
+/**
+ * Interpret a declared {@link ConflictAxis} for a concrete conflict — pure and
+ * synchronous (no I/O), so it runs on either side of the schema-agnostic
+ * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
+ *
+ *   - undefined   → the engine default (`defaultPolicy`: reject; honor
+ *                   `onStale: 'notify'` on a stale write)
+ *   - `overwrite` → `allow` — the write wins / the committer is never blocked
+ *   - `reject`    → `reject` — the committer yields
+ *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);
+ *                   on `claim_held`: notify has no held op to reconcile against
+ *                   (see {@link ConflictDecision} `notify`), so degrade to
+ *                   `reject` rather than silently allowing a claimed-row write.
+ *
+ * NOTE: this is a generic interpretation only. Server-side invariants (e.g. an
+ * agent may never bypass a foreign claim) are enforced where the decision is
+ * applied, not here.
+ */
+export declare function interpretConflictAxis(axis: ConflictAxis, conflict: Conflict): ConflictDecision;
 export {};

package/dist/policy/types.js

@@ -20,14 +20,19 @@
  * detection. This preserves the legacy always-reject default for callers that
  * don't opt into `notify`.
  */
-export const defaultPolicy = (conflict) => {
+// Typed by its real SYNCHRONOUS shape (via `satisfies`) rather than the
+// async-permissive `ConflictPolicy` alias, so sync callers like
+// `interpretConflictAxis` and `capabilityPreemptPolicy` get a plain
+// `ConflictDecision` back (not `… | Promise<…>`). Still assignable to
+// `ConflictPolicy` everywhere it's used as a policy.
+export const defaultPolicy = ((conflict) => {
     if (conflict.kind !== 'stale_context') {
         return { action: 'reject', reason: 'claim_conflict' };
     }
     return conflict.requestedMode === 'notify'
         ? { action: 'notify', reason: 'stale_notify_hold' }
         : { action: 'reject', reason: 'stale_context' };
-};
+});
 /**
  * Capability-gated preemption. An `claim_held` conflict is PREEMPTED when the
  * committer holds the `claim.preempt` operation in its capability allowlist
@@ -43,3 +48,45 @@ export const capabilityPreemptPolicy = (conflict) => {
     }
     return defaultPolicy(conflict);
 };
+/**
+ * Interpret a declared {@link ConflictAxis} for a concrete conflict — pure and
+ * synchronous (no I/O), so it runs on either side of the schema-agnostic
+ * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
+ *
+ *   - undefined   → the engine default (`defaultPolicy`: reject; honor
+ *                   `onStale: 'notify'` on a stale write)
+ *   - `overwrite` → `allow` — the write wins / the committer is never blocked
+ *   - `reject`    → `reject` — the committer yields
+ *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);
+ *                   on `claim_held`: notify has no held op to reconcile against
+ *                   (see {@link ConflictDecision} `notify`), so degrade to
+ *                   `reject` rather than silently allowing a claimed-row write.
+ *
+ * NOTE: this is a generic interpretation only. Server-side invariants (e.g. an
+ * agent may never bypass a foreign claim) are enforced where the decision is
+ * applied, not here.
+ */
+export function interpretConflictAxis(axis, conflict) {
+    const mode = axis[conflict.committer.kind];
+    if (mode === undefined)
+        return defaultPolicy(conflict);
+    switch (mode) {
+        case 'overwrite':
+            return { action: 'allow', note: 'conflict:overwrite' };
+        case 'reject':
+            return {
+                action: 'reject',
+                reason: conflict.kind === 'claim_held' ? 'claim_conflict' : 'stale_context',
+            };
+        case 'notify':
+            return conflict.kind === 'stale_context'
+                ? { action: 'notify', reason: 'stale_notify_hold' }
+                : { action: 'reject', reason: 'claim_conflict' };
+        default: {
+            // Exhaustiveness backstop: a future `OnStaleMode` member surfaces as a
+            // localized compile error here, not a missing-return at the signature.
+            const _exhaustive = mode;
+            return _exhaustive;
+        }
+    }
+}

package/dist/schema/coordination.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Coordination authoring helpers for the model `conflict` axis.
+ *
+ * Composable disposition functions + a `cn`/`cx`-style combinator, so a model
+ * declares conflict behaviour the way the rest of the DSL reads
+ * (`relation.belongsTo()`, `field.string()`) — and the way modern libraries
+ * compose config (Better Auth's `plugins: [admin(), twoFactor()]`, shadcn's
+ * `cx(a, b)`) — instead of a raw disposition map:
+ *
+ * ```ts
+ * import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
+ *
+ * conflict: coordination(humansOverwrite(), agentsReject())
+ * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
+ * ```
+ *
+ * Each helper is named for the exact disposition it applies — the same
+ * `overwrite | reject | notify` vocabulary used by write guards (`onStale`) —
+ * and returns a partial {@link ConflictAxis}. {@link coordination} merges them
+ * (later rules win on key collisions). The result is plain, serializable data —
+ * the engine interpreter and schema round-trip are unchanged; this is only a
+ * nicer authoring surface.
+ */
+import type { ConflictAxis } from '../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 OVERWRITES — wins; never blocked (LWW among humans). */
+export declare const humansOverwrite: () => ConflictRule;
+/** A human's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+export declare const humansReject: () => ConflictRule;
+/** A human's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+export declare const humansNotify: () => ConflictRule;
+/** An agent's conflicting write OVERWRITES — wins (rarely wanted). */
+export declare const agentsOverwrite: () => ConflictRule;
+/** An agent's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+export declare const agentsReject: () => ConflictRule;
+/** An agent's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+export declare const agentsNotify: () => ConflictRule;
+/** A system/automation conflicting write OVERWRITES. */
+export declare const systemOverwrite: () => ConflictRule;
+/** A system/automation conflicting write is REJECTED. */
+export declare const systemReject: () => ConflictRule;
+/** A system/automation stale write NOTIFIES (re-read & re-apply). */
+export declare const systemNotify: () => ConflictRule;
+/**
+ * Merge coordination rules into one {@link ConflictAxis} — the `cn`/`cx` of
+ * conflict policy. Later rules win on key collisions; an omitted committer kind
+ * falls through to the engine default at commit time.
+ *
+ * ```ts
+ * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }
+ * ```
+ */
+export declare function coordination(...rules: readonly ConflictRule[]): ConflictAxis;

package/dist/schema/coordination.js

@@ -0,0 +1,56 @@
+/**
+ * Coordination authoring helpers for the model `conflict` axis.
+ *
+ * Composable disposition functions + a `cn`/`cx`-style combinator, so a model
+ * declares conflict behaviour the way the rest of the DSL reads
+ * (`relation.belongsTo()`, `field.string()`) — and the way modern libraries
+ * compose config (Better Auth's `plugins: [admin(), twoFactor()]`, shadcn's
+ * `cx(a, b)`) — instead of a raw disposition map:
+ *
+ * ```ts
+ * import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
+ *
+ * conflict: coordination(humansOverwrite(), agentsReject())
+ * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
+ * ```
+ *
+ * Each helper is named for the exact disposition it applies — the same
+ * `overwrite | reject | notify` vocabulary used by write guards (`onStale`) —
+ * and returns a partial {@link ConflictAxis}. {@link coordination} merges them
+ * (later rules win on key collisions). The result is plain, serializable data —
+ * the engine interpreter and schema round-trip are unchanged; this is only a
+ * nicer authoring surface.
+ */
+// ── Humans (user sessions) ──────────────────────────────────────────────
+/** A human's conflicting write OVERWRITES — wins; never blocked (LWW among humans). */
+export const humansOverwrite = () => ({ user: 'overwrite' });
+/** A human's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+export const humansReject = () => ({ user: 'reject' });
+/** A human's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+export const humansNotify = () => ({ user: 'notify' });
+// ── Agents (AI) ─────────────────────────────────────────────────────────
+/** An agent's conflicting write OVERWRITES — wins (rarely wanted). */
+export const agentsOverwrite = () => ({ agent: 'overwrite' });
+/** An agent's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+export const agentsReject = () => ({ agent: 'reject' });
+/** An agent's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+export const agentsNotify = () => ({ agent: 'notify' });
+// ── System / automation ─────────────────────────────────────────────────
+/** A system/automation conflicting write OVERWRITES. */
+export const systemOverwrite = () => ({ system: 'overwrite' });
+/** A system/automation conflicting write is REJECTED. */
+export const systemReject = () => ({ system: 'reject' });
+/** A system/automation stale write NOTIFIES (re-read & re-apply). */
+export const systemNotify = () => ({ system: 'notify' });
+/**
+ * Merge coordination rules into one {@link ConflictAxis} — the `cn`/`cx` of
+ * conflict policy. Later rules win on key collisions; an omitted committer kind
+ * falls through to the engine default at commit time.
+ *
+ * ```ts
+ * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }
+ * ```
+ */
+export function coordination(...rules) {
+    return Object.assign({}, ...rules);
+}

package/dist/schema/index.d.ts

@@ -27,7 +27,8 @@ export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, re
 export { planeSchema, DEFAULT_PLANE, type SchemaPlane } from './plane.js';
 export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, 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 { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.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, 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';

package/dist/schema/index.js

@@ -41,6 +41,9 @@ export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syn
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './sync-delta-wire.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).
+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.

package/dist/schema/model.d.ts

@@ -23,6 +23,8 @@ import { type FieldMeta } from './field.js';
 import { type Tenancy, type PolicyInput } from './tenancy.js';
 export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { type SchemaPlane } from './plane.js';
+import type { ConflictAxis } from '../policy/types.js';
+export type { ConflictAxis } from '../policy/types.js';
 /**
  * Controls when model data is loaded from the server.
  *
@@ -147,6 +149,28 @@ export interface ModelOptions {
      * ```
      */
     groups?: GroupsInput;
+    /**
+     * **Axis 3 — write-conflict disposition, per committer kind.** Decides what
+     * happens when a commit collides with a foreign claim or a stale snapshot on
+     * this model — orthogonal to {@link policy} (read access) and {@link groups}
+     * (delta routing). A plain map keyed by the COMMITTER's participant kind
+     * (`user` / `agent` / `system`), with the `onStale` vocabulary as values:
+     *
+     * - `'overwrite'` — the write wins; that committer is never blocked.
+     * - `'reject'`    — the write is refused; that committer yields.
+     * - `'notify'`    — hold the write and hand back the current value so the
+     *                   committer re-reads and re-applies (stale writes only).
+     *
+     * An omitted kind falls through to the engine default (reject; honor
+     * `onStale: 'notify'`). It is pure data (serializes through the schema
+     * registry to the server) and the generic engine interprets it — so e.g.
+     *
+     * ```ts
+     * // "a human's edit always wins (never blocked); an agent yields"
+     * conflict: { user: 'overwrite', agent: 'reject' }
+     * ```
+     */
+    conflict?: ConflictAxis;
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
      * model via the `commit` wire protocol. Default: **true** — declaring a
@@ -301,6 +325,9 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     readonly grants?: GrantsRef;
     /** Explicit non-relational record→group roles (normalized to an array). See {@link ModelOptions.entityRoles}. */
     readonly entityRoles?: readonly EntityRole[];
+    /** Axis 3 — declared write-conflict disposition per committer kind. Already
+     *  canonical pure data (unlike `policy`, no resolve step). See {@link ModelOptions.conflict}. */
+    readonly conflict?: ConflictAxis;
     /** Whether wire-level CREATE/UPDATE/DELETE is allowed. See {@link ModelOptions.mutable}. */
     readonly mutable?: boolean;
     /** Defer MobX setup until first observer access. See {@link ModelOptions.lazyObservable}. */

package/dist/schema/model.js

@@ -99,6 +99,9 @@ export function model(shape, relations, options) {
         scope: options?.groups?.root,
         grants: options?.groups?.grants,
         entityRoles: normalizeEntityRoles(options?.groups?.roles),
+        // Axis 3 — already canonical pure data (a per-kind disposition map), so it
+        // passes through verbatim; no resolve step like `resolvePolicy`.
+        conflict: options?.conflict,
         mutable: options?.mutable ?? true,
         lazyObservable: options?.lazyObservable,
         computed: options?.computed,

package/dist/schema/serialize.d.ts

@@ -14,9 +14,11 @@
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
  *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
- *     grants, entityRoles, persist, autoFill, requiredFields, lazyObservable).
+ *     grants, entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     requiredFields, lazyObservable).
  *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
- *     `model()`-build; only the canonical wire fields cross here.
+ *     `model()`-build; only the canonical wire fields cross here. `conflict`
+ *     is already canonical pure data, so it crosses verbatim.
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)
@@ -29,7 +31,7 @@
 import type { FieldMeta } from './field.js';
 import type { Tenancy } from './tenancy.js';
 import type { SchemaPlane } from './plane.js';
-import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule } from './model.js';
+import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule, ConflictAxis } from './model.js';
 import type { RelationType } from './relation.js';
 import { type Schema, type SchemaRecord, type IdentityRole, type EntityRole } from './schema.js';
 /** Current schema-JSON envelope version. Bump on a breaking change to the
@@ -60,6 +62,9 @@ export interface ModelJSON {
     readonly scope?: boolean | string;
     readonly grants?: GrantsRef;
     readonly entityRoles?: readonly EntityRole[];
+    /** Axis 3 — declared write-conflict disposition per committer kind. Pure data;
+     *  absent in pre-conflict-axis artifacts → undefined → engine default. */
+    readonly conflict?: ConflictAxis;
     readonly bootstrapLimit?: number;
     readonly bootstrapOrderBy?: string;
     readonly mutable?: boolean;

package/dist/schema/serialize.js

@@ -14,9 +14,11 @@
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
  *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
- *     grants, entityRoles, persist, autoFill, requiredFields, lazyObservable).
+ *     grants, entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     requiredFields, lazyObservable).
  *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
- *     `model()`-build; only the canonical wire fields cross here.
+ *     `model()`-build; only the canonical wire fields cross here. `conflict`
+ *     is already canonical pure data, so it crosses verbatim.
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)
@@ -64,6 +66,7 @@ function modelToJSON(def) {
         scope: def.scope,
         grants: def.grants,
         entityRoles: def.entityRoles,
+        conflict: def.conflict,
         bootstrapLimit: def.bootstrapLimit,
         bootstrapOrderBy: def.bootstrapOrderBy,
         mutable: def.mutable,
@@ -171,6 +174,9 @@ function modelFromJSON(json) {
         scope: json.scope,
         grants: json.grants,
         entityRoles: json.entityRoles,
+        // Axis 3 — pure data; absent in pre-conflict-axis artifacts → undefined →
+        // the commit path falls through to the function registry / engine default.
+        conflict: json.conflict,
         mutable: json.mutable,
         lazyObservable: json.lazyObservable,
         // computed getters are closures and intentionally not serialized; a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",