@abloatai/ablo 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # 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
+
+- Loud 0-row writes: surface unmatched UPDATE/DELETE ids and add `AbloNotFoundError`
+
+  A commit now reports the ids of any UPDATE/DELETE that matched zero rows on
+  `CommitReceipt.missingIds`, and the new exported `AbloNotFoundError` lets typed
+  write wrappers throw instead of silently treating a missed write as success.
+  Additive and back-compatible (the field is omitted when nothing missed). This
+  unblocks the slides-sdk name-addressing / own-your-id work, which relies on a
+  loud failure when a stale id is written.
+
 ## 0.15.0
 
 ### Minor Changes
@@ -11,7 +69,7 @@
   **`onStale` redesigned — Stripe-aligned values (BREAKING).**
 
   The mode set is now `'reject' | 'overwrite' | 'notify'`. Each value names its outcome:
-  - **`notify` (new, non-coercive)** — the conflicting write is **held** (not applied) and the commit returns a `StaleNotification` carrying the conflicting field's *current* value, so the actor reconciles and re-commits rather than losing work. The rest of the batch still commits.
+  - **`notify` (new, non-coercive)** — the conflicting write is **held** (not applied) and the commit returns a `StaleNotification` carrying the conflicting field's _current_ value, so the actor reconciles and re-commits rather than losing work. The rest of the batch still commits.
   - **`overwrite`** (was `force`) — blind last-writer-wins, no signal.
   - **`reject`** (default, unchanged) — throws `AbloStaleContextError`.
 
@@ -33,10 +91,9 @@
   **Conflict policy.** `ConflictDecision` gains `{ action: 'notify' }`; `defaultPolicy` maps `onStale: 'notify'` → notify-and-hold, everything else → reject. `StaleContextConflict.requestedMode` is added so custom policies can honor the caller's declared intent.
 
 - **Data Source reverse-channel connector (new).** A customer Data Source can now **dial out** to the engine over a single outbound WebSocket (`ablo.source.v1` subprotocol) instead of exposing an inbound HTTP endpoint — the deployment shape private/VPC stores need.
-
   - **`createSourceConnector({ apiKey, handler, baseURL? })`** (new public API, exported from the root and `/source`) — opens one outbound socket (Node global `WebSocket`, no new dependency), with reconnect/backoff, and serves the customer's existing Data Source `handler`.
   - Server side: a connector registry + `/v1/source/listen` upgrade route bridge requests down / responses up, teed into `SourceClient` through the storage resolver.
-  - **Trust model unchanged:** the Standard-Webhooks HMAC is signed *above* the transport, so the socket carries the signed envelope byte-for-byte and the customer's `verifyAbloSourceRequest` is untouched. Transport changes, trust model doesn't.
+  - **Trust model unchanged:** the Standard-Webhooks HMAC is signed _above_ the transport, so the socket carries the signed envelope byte-for-byte and the customer's `verifyAbloSourceRequest` is untouched. Transport changes, trust model doesn't.
   - Opt-in per source via `reverse_channel_prod` (migration `20260622150000`); gated in `authorizeUpgrade`.
 
 ## 0.14.0

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

@@ -469,6 +469,13 @@ export interface CommitReceipt {
      * resolve. Also fires on `conflict:notified`.
      */
     readonly notifications?: readonly StaleNotification[];
+    /**
+     * Ids of UPDATE/DELETE targets in this commit that matched ZERO rows (the row
+     * doesn't exist, or is outside the caller's org). Present (non-empty) only
+     * when a write missed. Typed resource wrappers turn this into a loud
+     * `AbloNotFoundError`; a raw `commits.create` caller can inspect it directly.
+     */
+    readonly missingIds?: readonly string[];
 }
 export interface CommitResource {
     create(options: CommitCreateOptions): Promise<CommitReceipt>;
@@ -1003,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/client/ApiClient.js

@@ -285,6 +285,9 @@ export function createProtocolClient(options) {
                 id: body.id ?? body.clientTxId ?? clientTxId,
                 status,
                 lastSyncId: body.lastSyncId,
+                ...(body.missingIds && body.missingIds.length > 0
+                    ? { missingIds: body.missingIds }
+                    : {}),
             };
         },
     };

package/dist/errors.d.ts

@@ -118,6 +118,21 @@ export declare class AbloConnectionError extends AbloError {
 export declare class AbloValidationError extends AbloError {
     readonly type: "AbloValidationError";
 }
+/**
+ * 404 — an UPDATE/DELETE addressed a row that doesn't exist (or is outside the
+ * caller's org). The engine reports such targets on `CommitReceipt.missingIds`;
+ * the typed resource wrappers raise this instead of returning a success receipt
+ * for a write that quietly matched zero rows. Carries the offending ids so a
+ * caller can see exactly which targets were absent.
+ */
+export declare class AbloNotFoundError extends AbloError {
+    readonly type: "AbloNotFoundError";
+    /** The id(s) that matched no row. */
+    readonly missingIds: readonly string[];
+    constructor(message: string, missingIds: readonly string[], options?: {
+        requestId?: string;
+    });
+}
 /** 5xx — server-side error. Usually retryable with backoff. */
 export declare class AbloServerError extends AbloError {
     readonly type: "AbloServerError";
@@ -272,6 +287,10 @@ export interface CommitReceipt {
     /** Number of operations metered. Reported on both success and
      *  rejection so quota systems see attempted work. */
     readonly ops?: number;
+    /** Ids of UPDATE/DELETE targets that matched ZERO rows (loud 0-row writes).
+     *  Present (non-empty) only when a write missed; typed wrappers raise
+     *  `AbloNotFoundError` from it. */
+    readonly missingIds?: readonly string[];
     /** Populated on rejection. `requiredCapability` (when present)
      *  carries the x402-style structured retry hint. */
     readonly error?: {

package/dist/errors.js

@@ -132,6 +132,27 @@ export class AbloConnectionError extends AbloError {
 export class AbloValidationError extends AbloError {
     type = 'AbloValidationError';
 }
+/**
+ * 404 — an UPDATE/DELETE addressed a row that doesn't exist (or is outside the
+ * caller's org). The engine reports such targets on `CommitReceipt.missingIds`;
+ * the typed resource wrappers raise this instead of returning a success receipt
+ * for a write that quietly matched zero rows. Carries the offending ids so a
+ * caller can see exactly which targets were absent.
+ */
+export class AbloNotFoundError extends AbloError {
+    type = 'AbloNotFoundError';
+    /** The id(s) that matched no row. */
+    missingIds;
+    constructor(message, missingIds, options) {
+        super(message, {
+            code: 'mutate_update_entity_not_found',
+            httpStatus: 404,
+            details: { missingIds },
+            ...(options?.requestId !== undefined ? { requestId: options.requestId } : {}),
+        });
+        this.missingIds = missingIds;
+    }
+}
 /** 5xx — server-side error. Usually retryable with backoff. */
 export class AbloServerError extends AbloError {
     type = 'AbloServerError';

package/dist/index.d.ts

@@ -58,8 +58,8 @@ 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 { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.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';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';

package/dist/index.js

@@ -80,11 +80,11 @@ 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.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.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 { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every

package/dist/interfaces/index.d.ts

@@ -148,6 +148,11 @@ export interface CommitResult {
      * receiving an `AbloStaleContextError`. See `StaleNotification`.
      */
     notifications?: StaleNotification[];
+    /**
+     * Ids of UPDATE/DELETE targets that matched ZERO rows (loud 0-row writes).
+     * Present (non-empty) only when a write missed.
+     */
+    missingIds?: string[];
 }
 /**
  * Per-call knobs attached to any mutation. Mirrors Stripe's options

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/dist/server/commit.d.ts

@@ -114,4 +114,13 @@ export interface CommitResult {
      * `StaleNotification` in `coordination/schema.ts`.
      */
     notifications?: StaleNotification[];
+    /**
+     * Ids of UPDATE/DELETE targets that matched ZERO rows — the row doesn't
+     * exist (or is outside the caller's org). The engine has always detected
+     * this (and logged it); surfacing it here lets the client turn a silent
+     * no-op into a loud `AbloNotFoundError`. Present (non-empty) only when at
+     * least one op missed. Ids are globally-unique uuids, so a caller can match
+     * its own target id against this set without ambiguity.
+     */
+    missingIds?: string[];
 }

package/dist/wire/frames.d.ts

@@ -122,6 +122,13 @@ export interface MutationResultMessage {
          * `conflict:notified` event and the commit receipt instead of rejecting.
          */
         notifications?: StaleNotification[];
+        /**
+         * Ids of UPDATE/DELETE targets that matched ZERO rows (don't exist or are
+         * outside the org). Present (non-empty) only when a write missed. The
+         * client turns this into a loud `AbloNotFoundError` for the affected
+         * caller instead of treating the no-op as success.
+         */
+        missingIds?: string[];
         error?: {
             code: ErrorCode;
             message: string;

package/package.json

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