@abloatai/ablo 0.29.3 → 0.30.1

package/dist/interfaces/index.d.ts

@@ -6,7 +6,8 @@
  * session-error detection, online-status checks, and the transport that carries
  * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
-import type { StaleNotification, ReadDependency, ParticipantKind } from '../coordination/schema.js';
+import type { ReadDependency, ParticipantKind } from '../coordination/schema.js';
+import type { CommitStatus, MutationCommitResultInput } from '../wire/commit.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -177,22 +178,12 @@ export interface ModelDebugLoggerContract {
     logCreation(modelName: string, data: unknown, constructor: unknown): void;
     logObservableSetup(modelName: string, observableProps: string[], computedProps: string[]): void;
 }
-/** Result of a successful `commit()` — server's sync cursor after the batch landed. */
-export interface CommitResult {
-    lastSyncId: number;
-    /**
-     * Stale-context notifications. Present only when a write guarded with
-     * `onStale: 'notify'` collided with a concurrent change: rather than throwing
-     * an `AbloStaleContextError`, the commit succeeds and reports the collision
-     * here so the caller can reconcile. See {@link StaleNotification}.
-     */
-    notifications?: StaleNotification[];
-    /**
-     * Ids of update or delete targets that matched no rows. Present, and non-empty,
-     * only when a write missed the row it addressed.
-     */
-    missingIds?: string[];
-}
+/**
+ * Result returned by an injected mutation executor. The input type is inferred
+ * from the runtime compatibility schema: legacy `{lastSyncId}` remains valid,
+ * while every explicit queued result requires a WAL correlation.
+ */
+export type CommitResult = MutationCommitResultInput;
 /**
  * Per-call options accepted by any mutation, passed as the last argument.
  * Every field is optional; omitted fields fall back to sensible defaults.
@@ -208,9 +199,15 @@ export interface CommitResult {
 export interface MutationOptions {
     idempotencyKey?: string | null;
     label?: string;
-    wait?: 'queued' | 'confirmed';
+    wait?: CommitStatus;
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    /**
+     * The fencing token (Option B) of the held claim this write belongs to. The
+     * server validates it against the entity's persisted high-water and rejects a
+     * stale token. Sourced from the claim handle, never set by hand.
+     */
+    fenceToken?: number | null;
     /** The id (or `{ id }`) of the claim this write belongs to. This is the
      *  low-level reference the commit carries so the write is attributed to a claim
      *  and can pass the holder's own lock. It is distinct from the `claim` handle on
@@ -243,7 +240,7 @@ export interface MutationOptions {
  * `claim` are deliberately absent: both are resolved on the client before a write
  * is staged, so neither reaches this layer.
  */
-export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label'>;
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label' | 'fenceToken'>;
 /** A single mutation within a batch. Its `options` travel with it so the server
  *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {
@@ -265,6 +262,11 @@ export interface MutationOperation {
     transactionId?: string;
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    /**
+     * The fencing token (Option B) carried on the wire for this op — the held
+     * claim's token, validated against the entity's high-water at commit.
+     */
+    fenceToken?: number | null;
     /**
      * Per-operation idempotency and audit metadata. `idempotencyKey` is also the
      * cache key the server uses to de-duplicate retries; `label` is stored for
@@ -365,6 +367,16 @@ export interface SyncEngineConfig {
      * enforced.
      */
     expectedSchemaHash?: string;
+    /**
+     * Set only when the bound schema is a projection (`selectModels`/`omitModels`):
+     * the content hash of the full source schema the subset was cut from. A subset
+     * hashes differently from its full schema, so without this a projection-bound
+     * client always reports drift against a server running the full schema. The
+     * drift check treats the client as in-sync when the server's active hash
+     * matches either `expectedSchemaHash` or this source hash. Advisory, like the
+     * hash above.
+     */
+    expectedSourceSchemaHash?: string;
 }
 /**
  * Extends the WebSocket event map with your own collaboration events, such as

package/dist/schema/index.d.ts

@@ -25,7 +25,7 @@ export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from
 export { relation, type RelationDef, type RelationType } from './relation.js';
 export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } from './tenancy.js';
 export { residencySchema, DEFAULT_RESIDENCY, type ModelResidency, planeSchema, DEFAULT_PLANE, type SchemaPlane, } from './residency.js';
-export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './syncDeltaRow.js';
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_DATA_CLASSIFICATION, DELTA_PHYSICAL_STORAGE, DELTA_RESIDENCY, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './syncDeltaRow.js';
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from '../wire/delta.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, type ConflictAxis, } from './model.js';
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, type ConflictRule, } from './coordination.js';

package/dist/schema/index.js

@@ -38,7 +38,10 @@ planeSchema,
 DEFAULT_PLANE, } 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, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, } from './syncDeltaRow.js';
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_DATA_CLASSIFICATION, DELTA_PHYSICAL_STORAGE, 
+// Deliberate back-compat re-export; physical storage is the precise name.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+DELTA_RESIDENCY, } from './syncDeltaRow.js';
 // The wire delta contract — the server-to-client projection of the stored row.
 // Both the client SDK and the server derive their `SyncDelta` type from these with
 // `z.infer`, so the two ends cannot drift apart.

package/dist/schema/schema.d.ts

@@ -114,6 +114,19 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
      * to derive a participant's allowed sync-group set.
      */
     readonly identityRoles: readonly IdentityRole[];
+    /**
+     * Set only on a projection produced by `selectModels`/`omitModels`: the
+     * content hash of the FULL source schema the subset was cut from. A subset
+     * hashes differently from the full schema it belongs to, so a projection-bound
+     * client would otherwise always report drift against a server running the full
+     * schema. The drift check treats the client as in-sync when the server's active
+     * hash matches EITHER this client's own (subset) hash or this source hash — so
+     * a current projection stays quiet while a genuinely behind server still warns.
+     * Absent on a schema authored directly, where the client's own hash is the
+     * deployed hash and plain equality is correct. Excluded from `toSchemaJSON`, so
+     * stamping it never perturbs `schemaHash`.
+     */
+    readonly sourceSchemaHash?: string;
 }
 /**
  * Infer the full model type from a schema.

package/dist/schema/select.js

@@ -22,6 +22,7 @@
  * a record's fan-out — the selected set must be closed under `parent` edges.
  */
 import { AbloValidationError } from '../errors.js';
+import { schemaHash } from './serialize.js';
 export function selectModels(schema, keys) {
     const keep = new Set(keys);
     const models = {};
@@ -51,6 +52,12 @@ export function selectModels(schema, keys) {
         models: models,
         validators: validators,
         identityRoles: schema.identityRoles,
+        // Record the full source's hash so the drift check can recognize this subset
+        // as current against a server running that full schema. Prefer the source's
+        // OWN `sourceSchemaHash` when it is itself a projection, so a subset-of-a-
+        // subset still points at the original full schema rather than an intermediate
+        // one. `schemaHash` ignores this field, so re-projecting stays deterministic.
+        sourceSchemaHash: schema.sourceSchemaHash ?? schemaHash(schema),
     };
 }
 /**

package/dist/schema/syncDeltaRow.d.ts

@@ -4,14 +4,17 @@
  * serves:
  *
  *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
- *     needs to reconstruct the change, plus the tenant key. This is the portable
- *     part, and the only part written atomically with the application row.
+ *     needs to reconstruct the change, plus the tenant key. This is a portable
+ *     payload shape; it is not a statement that the row is physically stored in
+ *     the customer's database.
  *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
  *   - {@link deltaProvenanceSchema} — which AI task, if any, produced it.
  *
  * {@link syncDeltaRowSchema} composes all three into the full stored row.
- * {@link DELTA_RESIDENCY} records which database each slice lives in, so
- * provisioning can derive that boundary from the schema instead of hand-coding it.
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
+ * Keeping those axes separate prevents a portable schema slice from being cited
+ * incorrectly as a physical-residency guarantee.
  *
  * This is the stored shape. The delta broadcast to clients is a narrower projection
  * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
@@ -29,10 +32,11 @@ export declare const backfillProvenanceSchema: z.ZodEnum<{
 export type BackfillProvenance = z.infer<typeof backfillProvenanceSchema>;
 /**
  * Everything a client needs to materialize the change, plus the tenant key. This
- * is the portable slice: the only part written atomically with the application
- * row, and the shape an outbox marker in a customer's own database carries. `id`,
- * `createdAt`, and `syncGroups` are assigned by the server when the delta is
- * appended, so they are optional here — an outbox marker does not have them yet.
+ * is the portable shape an authoritative WAL change or endpoint event carries.
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
+ * sync log; it is not written atomically with a direct application-row mutation.
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
+ * appended, so they are optional at the ingestion boundary.
  */
 export declare const syncDeltaCoreSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
@@ -45,6 +49,7 @@ export declare const syncDeltaCoreSchema: z.ZodObject<{
     organizationId: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodString>;
     transactionId: z.ZodNullable<z.ZodString>;
+    sourceChangeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type SyncDeltaCore = z.infer<typeof syncDeltaCoreSchema>;
 export declare const deltaAttributionSchema: z.ZodObject<{
@@ -93,6 +98,7 @@ export declare const syncDeltaRowSchema: z.ZodObject<{
     organizationId: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodString>;
     transactionId: z.ZodNullable<z.ZodString>;
+    sourceChangeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     createdBy: z.ZodNullable<z.ZodString>;
     actorId: z.ZodNullable<z.ZodString>;
     actorKind: z.ZodNullable<z.ZodEnum<{
@@ -123,14 +129,26 @@ export declare const syncDeltaRowSchema: z.ZodObject<{
     causedByTaskId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type SyncDeltaRow = z.infer<typeof syncDeltaRowSchema>;
+/** Which slices contain retained customer row data versus control metadata. */
+export declare const DELTA_DATA_CLASSIFICATION: {
+    readonly core: "customer-data";
+    readonly attribution: "control-metadata";
+    readonly provenance: "control-metadata";
+};
 /**
- * Maps each slice to the database it belongs in. A customer's own database holds
- * only the `tenant` slice; the `control` slices are enriched and stored in the
- * host's own database. Provisioning reads this map to decide which columns a given
- * database receives, rather than hand-coding the boundary.
+ * Where the current runtime physically persists each slice. All three live in
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
+ * payloads (and optional previous payloads), so `control` here must not be read
+ * as "metadata only."
  */
+export declare const DELTA_PHYSICAL_STORAGE: {
+    readonly core: "control";
+    readonly attribution: "control";
+    readonly provenance: "control";
+};
+/** @deprecated Use `DELTA_PHYSICAL_STORAGE`; classification is a separate axis. */
 export declare const DELTA_RESIDENCY: {
-    readonly core: "tenant";
+    readonly core: "control";
     readonly attribution: "control";
     readonly provenance: "control";
 };

package/dist/schema/syncDeltaRow.js

@@ -4,14 +4,17 @@
  * serves:
  *
  *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
- *     needs to reconstruct the change, plus the tenant key. This is the portable
- *     part, and the only part written atomically with the application row.
+ *     needs to reconstruct the change, plus the tenant key. This is a portable
+ *     payload shape; it is not a statement that the row is physically stored in
+ *     the customer's database.
  *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
  *   - {@link deltaProvenanceSchema} — which AI task, if any, produced it.
  *
  * {@link syncDeltaRowSchema} composes all three into the full stored row.
- * {@link DELTA_RESIDENCY} records which database each slice lives in, so
- * provisioning can derive that boundary from the schema instead of hand-coding it.
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
+ * Keeping those axes separate prevents a portable schema slice from being cited
+ * incorrectly as a physical-residency guarantee.
  *
  * This is the stored shape. The delta broadcast to clients is a narrower projection
  * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
@@ -31,10 +34,11 @@ const deltaDataSchema = z.record(z.string(), z.unknown()).nullable();
 // ── Core — the sync-protocol slice ────────────────────────────────────────────
 /**
  * Everything a client needs to materialize the change, plus the tenant key. This
- * is the portable slice: the only part written atomically with the application
- * row, and the shape an outbox marker in a customer's own database carries. `id`,
- * `createdAt`, and `syncGroups` are assigned by the server when the delta is
- * appended, so they are optional here — an outbox marker does not have them yet.
+ * is the portable shape an authoritative WAL change or endpoint event carries.
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
+ * sync log; it is not written atomically with a direct application-row mutation.
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
+ * appended, so they are optional at the ingestion boundary.
  */
 export const syncDeltaCoreSchema = z.object({
     /** Monotonically increasing sync id, assigned by the server when the delta is appended; absent on an outbox marker. */
@@ -52,6 +56,12 @@ export const syncDeltaCoreSchema = z.object({
     /** ISO 8601 timestamp, assigned by the server when the delta is appended. */
     createdAt: z.string().optional(),
     transactionId: z.string().nullable(),
+    /**
+     * Stable identity of the authoritative WAL row or endpoint event. It is
+     * nullable for hosted/legacy rows and is never exposed as the optimistic
+     * client transaction id.
+     */
+    sourceChangeId: z.string().min(1).nullable().optional(),
 });
 // ── Attribution — who made the change, and on whose authority ─────────────────
 export const deltaAttributionSchema = z.object({
@@ -71,19 +81,27 @@ export const deltaProvenanceSchema = z.object({
     /** Foreign key to the task record for the AI turn that produced this commit; null when no task applies. */
     causedByTaskId: z.string().nullable(),
 });
-// ── Full stored row and its residency map ─────────────────────────────────────
+// ── Full stored row, classification, and physical storage ─────────────────────
 /** The complete `sync_deltas` row: core, attribution, and provenance combined. */
 export const syncDeltaRowSchema = syncDeltaCoreSchema
     .extend(deltaAttributionSchema.shape)
     .extend(deltaProvenanceSchema.shape);
+/** Which slices contain retained customer row data versus control metadata. */
+export const DELTA_DATA_CLASSIFICATION = {
+    core: 'customer-data',
+    attribution: 'control-metadata',
+    provenance: 'control-metadata',
+};
 /**
- * Maps each slice to the database it belongs in. A customer's own database holds
- * only the `tenant` slice; the `control` slices are enriched and stored in the
- * host's own database. Provisioning reads this map to decide which columns a given
- * database receives, rather than hand-coding the boundary.
+ * Where the current runtime physically persists each slice. All three live in
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
+ * payloads (and optional previous payloads), so `control` here must not be read
+ * as "metadata only."
  */
-export const DELTA_RESIDENCY = {
-    core: 'tenant',
+export const DELTA_PHYSICAL_STORAGE = {
+    core: 'control',
     attribution: 'control',
     provenance: 'control',
 };
+/** @deprecated Use `DELTA_PHYSICAL_STORAGE`; classification is a separate axis. */
+export const DELTA_RESIDENCY = DELTA_PHYSICAL_STORAGE;

package/dist/schema/tenancy.d.ts

@@ -14,9 +14,12 @@
  *      model is built, so the authoring vocabulary never reaches the wire or any
  *      consumer.
  *
- * Both forms discriminate on a single tag, which makes the opt-out from tenant
- * scoping (`{ by: 'none' }`) an explicit, named branch rather than a falsy flag —
- * important, because that branch makes an entire table readable across tenants.
+ * The canonical form is an exhaustively switchable discriminated union, so the type
+ * system enforces the isolation boundary at every consumer. The authoring form is a
+ * flat object whose `by` names the choice and whose per-branch rules are checked by a
+ * refinement — the opt-out from tenant scoping (`{ by: 'none' }`) and the
+ * source-derived case (`{ by: 'source' }`) are explicit, named values rather than
+ * falsy flags, important because `none` makes an entire table readable across tenants.
  */
 import { z } from 'zod';
 /** The default physical tenancy column. This is the single canonical definition of that column name. */
@@ -49,36 +52,69 @@ export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"none">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"source">;
 }, z.core.$strip>], "kind">;
 export type Tenancy = z.infer<typeof tenancySchema>;
 /**
  * The authoring form of tenancy — what a schema author writes as the model's
  * `policy` option. The name follows SQL row-level security, where a policy is the
- * rule that decides which rows a tenant may read. It is a discriminated union on
- * `by`, so the three branches are mutually exclusive and the opt-out
- * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
+ * rule that decides which rows a tenant may read.
+ *
+ * The four choices `by` can take:
  *
  * - `{ by: 'column' }` — a row-local tenancy column (the default). `column`
  *   overrides the name (default {@link DEFAULT_ORG_COLUMN}).
  * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
  *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
  *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ by: 'source' }` — derive the organization from the connected source that
+ *   registered the model, for a single-tenant connected database that carries no
+ *   `organization_id` column. The registration is the tenant boundary.
  * - `{ by: 'none' }` — genuinely global or reference data. This makes the whole
  *   table readable across tenants, so it is correct only for tables that have no tenant.
+ *
+ * The runtime schema is one flat object rather than a discriminated union: `by`
+ * selects the branch, and the {@link https://zod.dev | superRefine} pass enforces
+ * the per-branch field rules (`parent` requires `fk` and `parent`; the other three
+ * take no branch fields). The exported {@link PolicyInput} type is hand-written as a
+ * precise union so the compiler still requires the right fields per `by` — the flat
+ * schema validates at runtime, the union guides at author time, and the type guard
+ * below keeps the two from drifting.
  */
-export declare const policyInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    by: z.ZodLiteral<"column">;
+export declare const policyInputSchema: z.ZodObject<{
+    by: z.ZodEnum<{
+        none: "none";
+        source: "source";
+        column: "column";
+        parent: "parent";
+    }>;
     column: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    by: z.ZodLiteral<"parent">;
-    fk: z.ZodString;
-    parent: z.ZodString;
+    fk: z.ZodOptional<z.ZodString>;
+    parent: z.ZodOptional<z.ZodString>;
     parentKey: z.ZodOptional<z.ZodString>;
     parentTenantColumn: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    by: z.ZodLiteral<"none">;
-}, z.core.$strip>], "by">;
-export type PolicyInput = z.infer<typeof policyInputSchema>;
+}, z.core.$strip>;
+/**
+ * The precise authoring type. Hand-written rather than inferred from
+ * {@link policyInputSchema} so the compiler enforces the per-branch fields the flat
+ * runtime schema can only check at parse time — an author writing `{ by: 'parent' }`
+ * gets a type error for the missing `fk`/`parent`, not a runtime one.
+ */
+export type PolicyInput = {
+    by: 'column';
+    column?: string;
+} | {
+    by: 'parent';
+    fk: string;
+    parent: string;
+    parentKey?: string;
+    parentTenantColumn?: string;
+} | {
+    by: 'source';
+} | {
+    by: 'none';
+};
 /**
  * Normalizes the authoring {@link PolicyInput} into the canonical {@link Tenancy}.
  * Called once, when the model is built, so that `ModelDef`, `ModelJSON`, and every

package/dist/schema/tenancy.js

@@ -14,9 +14,12 @@
  *      model is built, so the authoring vocabulary never reaches the wire or any
  *      consumer.
  *
- * Both forms discriminate on a single tag, which makes the opt-out from tenant
- * scoping (`{ by: 'none' }`) an explicit, named branch rather than a falsy flag —
- * important, because that branch makes an entire table readable across tenants.
+ * The canonical form is an exhaustively switchable discriminated union, so the type
+ * system enforces the isolation boundary at every consumer. The authoring form is a
+ * flat object whose `by` names the choice and whose per-branch rules are checked by a
+ * refinement — the opt-out from tenant scoping (`{ by: 'none' }`) and the
+ * source-derived case (`{ by: 'source' }`) are explicit, named values rather than
+ * falsy flags, important because `none` makes an entire table readable across tenants.
  */
 import { z } from 'zod';
 /** The default physical tenancy column. This is the single canonical definition of that column name. */
@@ -46,41 +49,97 @@ export const tenancySchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('parent'), via: scopedViaRefSchema }),
     /** Not tenant-scoped (global / reference data). */
     z.object({ kind: z.literal('none') }),
+    /**
+     * Scoped by the data source itself: the model carries no tenancy column, and the
+     * owning organization is derived from the connected source that registered it — the
+     * registration is the tenant boundary. This is the natural default for a
+     * single-tenant connected database (`ablo connect`), which holds one org's rows and
+     * so has no per-row `organization_id` to read. Carries no payload for the same
+     * reason `none` does: the binding lives in the source registration, not the model.
+     */
+    z.object({ kind: z.literal('source') }),
 ]);
 /**
  * The authoring form of tenancy — what a schema author writes as the model's
  * `policy` option. The name follows SQL row-level security, where a policy is the
- * rule that decides which rows a tenant may read. It is a discriminated union on
- * `by`, so the three branches are mutually exclusive and the opt-out
- * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
+ * rule that decides which rows a tenant may read.
+ *
+ * The four choices `by` can take:
  *
  * - `{ by: 'column' }` — a row-local tenancy column (the default). `column`
  *   overrides the name (default {@link DEFAULT_ORG_COLUMN}).
  * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
  *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
  *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ by: 'source' }` — derive the organization from the connected source that
+ *   registered the model, for a single-tenant connected database that carries no
+ *   `organization_id` column. The registration is the tenant boundary.
  * - `{ by: 'none' }` — genuinely global or reference data. This makes the whole
  *   table readable across tenants, so it is correct only for tables that have no tenant.
+ *
+ * The runtime schema is one flat object rather than a discriminated union: `by`
+ * selects the branch, and the {@link https://zod.dev | superRefine} pass enforces
+ * the per-branch field rules (`parent` requires `fk` and `parent`; the other three
+ * take no branch fields). The exported {@link PolicyInput} type is hand-written as a
+ * precise union so the compiler still requires the right fields per `by` — the flat
+ * schema validates at runtime, the union guides at author time, and the type guard
+ * below keeps the two from drifting.
  */
-export const policyInputSchema = z.discriminatedUnion('by', [
-    z.object({
-        by: z.literal('column'),
-        /** Override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
-        column: z.string().min(1).optional(),
-    }),
-    z.object({
-        by: z.literal('parent'),
-        /** Column on this table that points at the parent (for example, `'slideId'`). */
-        fk: z.string().min(1),
-        /** Parent table name (e.g. `'slides'`). */
-        parent: z.string().min(1),
-        /** Column on the parent that `fk` references. Default `'id'`. */
-        parentKey: z.string().min(1).optional(),
-        /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
-        parentTenantColumn: z.string().min(1).optional(),
-    }),
-    z.object({ by: z.literal('none') }),
-]);
+export const policyInputSchema = z
+    .object({
+    by: z.enum(['column', 'parent', 'none', 'source']),
+    /** `by: 'column'` — override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
+    column: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on this table that points at the parent (for example, `'slideId'`). */
+    fk: z.string().min(1).optional(),
+    /** `by: 'parent'` — parent table name (e.g. `'slides'`). */
+    parent: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on the parent that `fk` references. Default `'id'`. */
+    parentKey: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+    parentTenantColumn: z.string().min(1).optional(),
+})
+    .superRefine((policy, ctx) => {
+    if (policy.by === 'parent') {
+        if (!policy.fk) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['fk'],
+                message: "A `by: 'parent'` policy needs `fk` — the column on this table that points at the parent row whose tenancy it inherits.",
+            });
+        }
+        if (!policy.parent) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['parent'],
+                message: "A `by: 'parent'` policy needs `parent` — the name of the parent table this table is scoped through.",
+            });
+        }
+    }
+    // A `column` policy may carry `column`; the parent fields belong only to `parent`.
+    // Flag a field that landed on the wrong branch so a typo doesn't silently no-op.
+    const parentOnly = ['fk', 'parent', 'parentKey', 'parentTenantColumn'];
+    if (policy.by !== 'parent') {
+        for (const field of parentOnly) {
+            if (policy[field] !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field],
+                    message: `\`${field}\` only applies to a \`by: 'parent'\` policy; remove it or set \`by: 'parent'\`.`,
+                });
+            }
+        }
+    }
+    if (policy.by !== 'column' && policy.column !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['column'],
+            message: "`column` only applies to a `by: 'column'` policy; remove it or set `by: 'column'`.",
+        });
+    }
+});
+const _policyInputAssignable = true;
+void _policyInputAssignable;
 /**
  * Normalizes the authoring {@link PolicyInput} into the canonical {@link Tenancy}.
  * Called once, when the model is built, so that `ModelDef`, `ModelJSON`, and every
@@ -103,6 +162,8 @@ export function resolvePolicy(input) {
                     parentOrgColumn: input.parentTenantColumn,
                 },
             };
+        case 'source':
+            return { kind: 'source' };
         case 'none':
             return { kind: 'none' };
     }

package/dist/server/commit.d.ts

@@ -15,8 +15,9 @@
  */
 import type { ParticipantKind, ConfirmationState } from '../schema/syncDeltaRow.js';
 import type { ParticipantRef } from '../wire/delta.js';
+import type { CommitExecutionResultInput } from '../wire/commit.js';
 import type { Environment } from '../environment.js';
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency } from '../coordination/schema.js';
 export interface CommitContext {
     participantId: string;
     /**
@@ -30,6 +31,8 @@ export interface CommitContext {
      * targets the organization's default project.
      */
     projectId?: string;
+    /** Exact sandbox plane derived from the authenticated key, when present. */
+    sandboxId?: string;
     /** Optional external account scope forwarded to storage resolvers. */
     accountScope?: string;
     /**
@@ -96,27 +99,8 @@ export interface CommitContext {
     reads?: ReadDependency[] | null;
 }
 /**
- * The receipt returned when a commit finishes. It pins the exact range of
- * `sync_deltas` ids the batch produced, so a caller can broadcast just this batch's
- * deltas without racing concurrent commits that hold adjacent ids. `firstSyncId` is
- * 0 when the batch produced no deltas (no operations, or all of them were no-ops).
+ * The server execution receipt persisted in `mutation_log`. Its runtime schema
+ * lives with the HTTP/WS settlement contract so queued correlation cannot drift
+ * between cache, transport, and client.
  */
-export interface CommitResult {
-    lastSyncId: number;
-    firstSyncId: number;
-    /**
-     * Stale-context notifications for operations the committer guarded with
-     * `onStale: 'notify'`. Non-empty only when a guarded write collided with a
-     * concurrent change; the committer heals from these instead of receiving an
-     * `AbloStaleContextError`. See {@link StaleNotification}.
-     */
-    notifications?: StaleNotification[];
-    /**
-     * Ids of update or delete targets that matched no rows — the row does not exist, or
-     * lies outside the caller's organization. Surfacing them here lets a client turn a
-     * silent no-op into an `AbloNotFoundError`. Non-empty only when at least one
-     * operation missed. The ids are globally unique, so a caller can match its own
-     * target id against this set without ambiguity.
-     */
-    missingIds?: string[];
-}
+export type CommitResult = CommitExecutionResultInput;