@abloatai/ablo 0.34.0 → 0.35.0

package/dist/transaction/coordination/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
+ *
+ * Exports are listed by name rather than re-exported wholesale, so every symbol
+ * that becomes part of this package's public API is a deliberate choice.
+ */
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, claimDescription, DEFAULT_CLAIM_DESCRIPTION, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, wireClaimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, claimLostSchema, claimAcquiredSchema, claimGrantedSchema, claimQueuedSchema, claimQueueSchema, claimQueueEntrySchema, claimExpiredSchema, claimEventReasonSchema, modelTargetSchema, claimRecordSchema, heldClaimStatusSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateSchema, presenceUpdatePayloadSchema, presenceUpdateFrameSchema, } from './schema.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
+export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, TrackDependency, ClaimStatus, WireClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ClaimLost, ClaimAcquired, ClaimGranted, ClaimQueued, ClaimQueue, ClaimQueueEntry, ClaimExpired, ClaimEventReason, ModelTarget, ClaimRecord, HeldClaimStatus, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdate, PresenceUpdatePayload, PresenceUpdateFrame, } from './schema.js';
+export type { ClaimEvent, ClaimCounterparty, ConflictEvent, CoordinationObserver, } from './events.js';
+export { targetsConflict } from './targetConflict.js';
+export type { ClaimTargetDetails, ClaimTargetSource, EntityLocator, } from './locator.js';
+export { isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';

package/dist/transaction/coordination/index.js

@@ -0,0 +1,44 @@
+/**
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
+ *
+ * Exports are listed by name rather than re-exported wholesale, so every symbol
+ * that becomes part of this package's public API is a deliberate choice.
+ */
+// Runtime schemas + helpers.
+export { 
+// Shared primitives
+targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, claimDescription, DEFAULT_CLAIM_DESCRIPTION, targetRefSchema, 
+// Layer 3 — optimistic stale-context
+onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, 
+// Layer 2 — pessimistic claim / claim-lease
+claimStatusSchema, wireClaimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, 
+// The rest of the claim frames, each the validation boundary for one
+// server-sent event — see WS_INBOUND_FRAMES for where they are applied.
+claimLostSchema, claimAcquiredSchema, claimGrantedSchema, claimQueuedSchema, claimQueueSchema, claimQueueEntrySchema, claimExpiredSchema, claimEventReasonSchema, modelTargetSchema, 
+// The one claim record, and the peer-visible projection of it.
+claimRecordSchema, heldClaimStatusSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, 
+// Read interest — area-of-interest navigation
+updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, 
+// Commit operation — carries the optimistic write-guard
+commitOperationTypeSchema, commitOperationSchema, 
+// Layer 1 — presence
+presenceKindSchema, presenceActivitySchema, presenceUpdateSchema, presenceUpdatePayloadSchema, 
+// Deprecated alias, removed in 0.36.0 — this line publishes it.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+presenceUpdateFrameSchema, } from './schema.js';
+// Conflict-policy runtime — the engine detects a conflict, and the policy
+// decides what to do about it. These are re-exported here so that server-side
+// code can reach both the coordination vocabulary and its default conflict
+// resolution from this one subpath, without importing the full client from the
+// package root.
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
+// The conflict rule itself — whether two claims on one row collide. It is the
+// protocol's decision, not the server's deployment of it, so it lives here and
+// every claim authority imports it.
+export { targetsConflict } from './targetConflict.js';
+export { isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';

package/dist/transaction/coordination/locator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The locator — what a claim points at, in every spelling it travels under.
+ *
+ * A target has two halves. The sub-entity half (`path`, `range`, `field`,
+ * `fields`, `meta`) is spelled identically everywhere; the entity half is not.
+ * It is `entityType`/`entityId` on the wire, `model`/`id` on the HTTP DTO and
+ * the SDK's model surface, and `type`/`id` on the claim handle and the wait
+ * line. The three coexist deliberately — unifying them changes every surface at
+ * once, and that is scheduled behind the protocol version — but while they
+ * coexist, the translation between them belongs in one place.
+ *
+ * It was copied member by member at more than twenty sites instead, which is
+ * how `fields` came to be added to the schema and to the conflict rule while
+ * several hops quietly dropped it: the rule learned to compare field sets while
+ * no path carried one, so the fix looked complete and changed nothing. Widening
+ * the locator again should touch this module and the schema, not every hop.
+ */
+import type { ModelTarget, TargetRef, WireClaim } from './schema.js';
+import type { ClaimTarget, PresenceTarget } from '../types/streams.js';
+import type { ResolveClaimMeta } from '../types/global.js';
+/**
+ * The part of a claim that narrows it below the whole entity. A claim with none
+ * of these set is a claim on the entity itself.
+ *
+ * `meta` is carried because it travels with the target everywhere else, not
+ * because the rule reads it: application metadata is opaque to coordination and
+ * never decides a conflict.
+ */
+export type ClaimTargetDetails = Pick<WireClaim, 'path' | 'range' | 'field' | 'fields' | 'meta'>;
+/**
+ * A locator as a *caller* may hold it — identical to {@link ClaimTargetDetails}
+ * except that `meta` may already be the shape the program registered on
+ * `Register`'s `ClaimMeta` slot, which an `interface` registration makes
+ * distinct from the wire's open record.
+ *
+ * A projection that only accepted the wire spelling would push the conversion
+ * back out to every call site that starts from a public target — the claim
+ * handle, the model surface, the HTTP claim params — which is the same
+ * member-by-member copying this module exists to end.
+ */
+export type ClaimTargetSource = Omit<ClaimTargetDetails, 'meta'> & {
+    readonly meta?: ClaimTargetDetails['meta'] | ResolveClaimMeta;
+};
+/**
+ * Copy the sub-entity part of a locator from one target shape to another.
+ *
+ * These five members are spelled identically wherever a target appears, so this
+ * owns all of them and the entity half is handled by its own projections below.
+ *
+ * Absent members are omitted rather than set to `undefined`, so a projected
+ * target can be spread into an object under `exactOptionalPropertyTypes`.
+ *
+ * The result is wire-shaped, `meta` included: this is the projection every path
+ * out of the SDK goes through, so it is also the single declared→wire crossing
+ * for claim metadata. The way back is {@link declaredMeta}, at the two decodes
+ * that build a public claim.
+ */
+export declare function subTarget(source: ClaimTargetSource | null | undefined): ClaimTargetDetails;
+/**
+ * Whether a target was given in the `[type, id]` shorthand rather than the
+ * object form.
+ *
+ * A predicate rather than an assertion, because `Array.isArray` leaves a
+ * readonly tuple in both branches and the alternative — asserting the object
+ * form — describes the locator by hand at every call site that resolves one.
+ */
+export declare function isTargetTuple(target: PresenceTarget): target is readonly [type: string, id: string];
+/**
+ * An entity named in any of the three spellings a claim travels under.
+ *
+ * The union is discriminated by which key is present, and `{ model, id }` and
+ * `{ type, id }` share `id` — so the read below tests `entityType` first, then
+ * `model`, and falls through to `type`. A source carrying both `model` and
+ * `type` is not expressible here and does not occur; it would take the earlier
+ * branch if it did.
+ */
+export type EntityLocator = Pick<TargetRef, 'entityType' | 'entityId'> | Pick<ModelTarget, 'model' | 'id'> | Pick<ClaimTarget, 'type' | 'id'>;
+/** The entity half in the wire's spelling — claim frames, presence activity. */
+export declare function wireTarget(source: EntityLocator): Pick<TargetRef, 'entityType' | 'entityId'>;
+/** The entity half in the spelling SDK callers and the HTTP routes read. */
+export declare function modelTarget(source: EntityLocator): Pick<ModelTarget, 'model' | 'id'>;
+/** The entity half as the claim handle and the wait line carry it. */
+export declare function streamTarget(source: EntityLocator): Pick<ClaimTarget, 'type' | 'id'>;

package/dist/transaction/coordination/locator.js

@@ -0,0 +1,82 @@
+/**
+ * The locator — what a claim points at, in every spelling it travels under.
+ *
+ * A target has two halves. The sub-entity half (`path`, `range`, `field`,
+ * `fields`, `meta`) is spelled identically everywhere; the entity half is not.
+ * It is `entityType`/`entityId` on the wire, `model`/`id` on the HTTP DTO and
+ * the SDK's model surface, and `type`/`id` on the claim handle and the wait
+ * line. The three coexist deliberately — unifying them changes every surface at
+ * once, and that is scheduled behind the protocol version — but while they
+ * coexist, the translation between them belongs in one place.
+ *
+ * It was copied member by member at more than twenty sites instead, which is
+ * how `fields` came to be added to the schema and to the conflict rule while
+ * several hops quietly dropped it: the rule learned to compare field sets while
+ * no path carried one, so the fix looked complete and changed nothing. Widening
+ * the locator again should touch this module and the schema, not every hop.
+ */
+// The one declared→wire conversion for claim metadata; `declaredMeta` is its
+// counterpart, called by the decodes that build a public claim.
+import { wireMeta } from './claimMeta.js';
+/**
+ * Copy the sub-entity part of a locator from one target shape to another.
+ *
+ * These five members are spelled identically wherever a target appears, so this
+ * owns all of them and the entity half is handled by its own projections below.
+ *
+ * Absent members are omitted rather than set to `undefined`, so a projected
+ * target can be spread into an object under `exactOptionalPropertyTypes`.
+ *
+ * The result is wire-shaped, `meta` included: this is the projection every path
+ * out of the SDK goes through, so it is also the single declared→wire crossing
+ * for claim metadata. The way back is {@link declaredMeta}, at the two decodes
+ * that build a public claim.
+ */
+export function subTarget(
+// `null` as well as absent, because the claim body declares its target
+// nullish and the projection is most useful exactly where that body is read.
+source) {
+    if (!source)
+        return {};
+    return {
+        ...(source.path !== undefined ? { path: source.path } : {}),
+        ...(source.range !== undefined ? { range: source.range } : {}),
+        ...(source.field !== undefined ? { field: source.field } : {}),
+        ...(source.fields !== undefined ? { fields: source.fields } : {}),
+        ...(source.meta !== undefined ? { meta: wireMeta(source.meta) } : {}),
+    };
+}
+/**
+ * Whether a target was given in the `[type, id]` shorthand rather than the
+ * object form.
+ *
+ * A predicate rather than an assertion, because `Array.isArray` leaves a
+ * readonly tuple in both branches and the alternative — asserting the object
+ * form — describes the locator by hand at every call site that resolves one.
+ */
+export function isTargetTuple(target) {
+    return Array.isArray(target);
+}
+/** The entity as a name and an identifier, whichever spelling named it. */
+function entityOf(source) {
+    if ('entityType' in source)
+        return [source.entityType, source.entityId];
+    if ('model' in source)
+        return [source.model, source.id];
+    return [source.type, source.id];
+}
+/** The entity half in the wire's spelling — claim frames, presence activity. */
+export function wireTarget(source) {
+    const [entityType, entityId] = entityOf(source);
+    return { entityType, entityId };
+}
+/** The entity half in the spelling SDK callers and the HTTP routes read. */
+export function modelTarget(source) {
+    const [model, id] = entityOf(source);
+    return { model, id };
+}
+/** The entity half as the claim handle and the wait line carry it. */
+export function streamTarget(source) {
+    const [type, id] = entityOf(source);
+    return { type, id };
+}