@abloatai/transaction 0.37.0

package/dist/coordination/claimMeta.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+import type { ResolveClaimMeta } from '../types/global.js';
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export declare function declaredMeta(raw: unknown): ResolveClaimMeta;
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export declare function wireMeta(meta: unknown): Record<string, unknown>;
+//# sourceMappingURL=claimMeta.d.ts.map

package/dist/coordination/claimMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimMeta.d.ts","sourceRoot":"","sources":["../../src/coordination/claimMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/D"}

package/dist/coordination/claimMeta.js

@@ -0,0 +1,53 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export function declaredMeta(raw) {
+    return raw;
+}
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export function wireMeta(meta) {
+    return meta;
+}
+//# sourceMappingURL=claimMeta.js.map

package/dist/coordination/claimMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimMeta.js","sourceRoot":"","sources":["../../src/coordination/claimMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAuB,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,OAAO,IAA+B,CAAC;AACzC,CAAC"}

package/dist/coordination/events.d.ts

@@ -0,0 +1,75 @@
+/**
+ * In-process observation events emitted by the transaction layer's
+ * coordination protocol. The wire claim and stale-write contracts live in
+ * `coordination/schema.ts`; these two projections are the stable event shapes
+ * an observer receives after those frames have been interpreted.
+ */
+import type { ParticipantKind } from '../types/participant.js';
+export type { ClaimEventReason } from './schema.js';
+import type { ClaimEventReason } from './schema.js';
+/** The participant that blocked a claim — present on `rejected`. */
+export interface ClaimCounterparty {
+    /** Who holds it. */
+    actor?: string;
+    /**
+     * Whether the holder is a person, an agent, or the system — the distinction
+     * a caller acts on, since yielding to a person and queueing behind an agent
+     * are different decisions. It lives here rather than on the event because
+     * only a counterparty has a kind worth reporting: on an acquisition the
+     * participant is you, and you already know what you are.
+     */
+    participantKind?: ParticipantKind;
+    /** The lease they hold, so a caller can poll or wait on it by id. */
+    claimId?: string;
+    /** When their lease lapses without a heartbeat. */
+    expiresAt?: number;
+    /** What they said they were doing — prose, for a person to read. */
+    description?: string;
+}
+/** A single state transition in the lifecycle of a claim. */
+export interface ClaimEvent {
+    phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
+    claimId?: string;
+    model?: string;
+    id?: string;
+    field?: string;
+    actor?: string;
+    position?: number;
+    /**
+     * What this claim's holder said they were doing — prose, written for a
+     * person. Separate from {@link ClaimEvent.reason}, which is machine-readable
+     * and only ever says why a claim ended. One field used to carry both, so an
+     * `acquired` event's "reason" was really a description and a `rejected`
+     * event's was really a cause.
+     */
+    description?: string;
+    /** Why the claim ended or was refused. Absent while it is simply alive. */
+    reason?: ClaimEventReason;
+    /**
+     * A policy's own words when a policy decided the outcome — free text by
+     * nature, and kept beside the closed {@link ClaimEvent.reason} rather than
+     * collapsed into it.
+     */
+    policyReason?: string;
+    /**
+     * Who blocked this claim. Present on `rejected`, where the wire already
+     * carried the holder and this projection used to discard it.
+     */
+    heldBy?: ClaimCounterparty;
+}
+/** A committed notify-instead-of-abort stale-write collision. */
+export interface ConflictEvent {
+    clientTxId: string;
+    rows: readonly {
+        model: string;
+        id: string;
+        fields: readonly string[];
+        writtenBy?: ParticipantKind;
+    }[];
+}
+/** The narrow behavior a transaction-layer coordination observer implements. */
+export interface CoordinationObserver {
+    captureClaim(event: ClaimEvent): void;
+    captureConflict(event: ConflictEvent): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/coordination/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/coordination/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,KAAK,EACD,UAAU,GACV,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,GACV,SAAS,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS;QACb,KAAK,EAAE,MAAM,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B,EAAE,CAAC;CACL;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACtC,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7C"}

package/dist/coordination/events.js

@@ -0,0 +1,8 @@
+/**
+ * In-process observation events emitted by the transaction layer's
+ * coordination protocol. The wire claim and stale-write contracts live in
+ * `coordination/schema.ts`; these two projections are the stable event shapes
+ * an observer receives after those frames have been interpreted.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/coordination/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/coordination/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/coordination/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `@abloatai/transaction/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 { 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, MAX_FRAME_SYNC_GROUPS, participantClaimPayloadSchema, participantReleasePayloadSchema, 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 { 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, ParticipantClaimPayload, ParticipantReleasePayload, 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 { BatchFence, ClaimTargetDetails, ClaimTargetSource, EntityLocator, } from './locator.js';
+export { batchFence, fenceTokenFor, isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAEL,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,eAAe,EAEf,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EAErB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EAGpB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EAEjB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,8BAA8B,EAC9B,gCAAgC,EAChC,mCAAmC,EAGnC,qBAAqB,EACrB,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,EAE5B,yBAAyB,EACzB,qBAAqB,EAErB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B,EAG3B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACnG,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAEV,eAAe,EACf,SAAS,EAET,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EAEf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,cAAc,EACd,SAAS,EACT,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,6BAA6B,EAE7B,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,EAEtB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAElB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EAErB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAIrB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAKtD,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/coordination/index.js

@@ -0,0 +1,46 @@
+/**
+ * The `@abloatai/transaction/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
+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 — what a connection receives, leased (`claim`/`release`,
+// the frames behind `join`) and unleased (`update_subscription`).
+MAX_FRAME_SYNC_GROUPS, participantClaimPayloadSchema, participantReleasePayloadSchema, 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 { batchFence, fenceTokenFor, isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';
+//# sourceMappingURL=index.js.map

package/dist/coordination/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,6BAA6B;AAC7B,OAAO;AACL,oBAAoB;AACpB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,eAAe;AACf,qCAAqC;AACrC,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB;AACrB,4CAA4C;AAC5C,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,oBAAoB;AACpB,qEAAqE;AACrE,wEAAwE;AACxE,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB;AACjB,+DAA+D;AAC/D,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,8BAA8B,EAC9B,gCAAgC,EAChC,mCAAmC;AACnC,yEAAyE;AACzE,kEAAkE;AAClE,qBAAqB,EACrB,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B;AAC5B,wDAAwD;AACxD,yBAAyB,EACzB,qBAAqB;AACrB,qBAAqB;AACrB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B;AAC3B,gEAAgE;AAChE,4DAA4D;AAC5D,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,gBAAgB;AAChB,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AA4EnG,8EAA8E;AAC9E,+EAA+E;AAC/E,oCAAoC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAWtD,OAAO,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/coordination/locator.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { ClaimPart, ModelTarget, TargetRef, WireClaim } from './schema.js';
+import { type FieldRef, type FieldSelector } from '../schema/fieldRef.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, '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<T = Record<string, unknown>> = Omit<ClaimTargetDetails, 'meta' | 'field' | 'fields'> & {
+    /** A schema field reference, wire name, or low-level app-defined part. */
+    readonly field?: string | ClaimPart | FieldRef;
+    readonly fields?: readonly (string | ClaimPart | FieldRef)[] | FieldSelector<T>;
+    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<T = Record<string, unknown>>(source: ClaimTargetSource<T> | null | undefined, model?: string): 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'>;
+/**
+ * A batch claim's grant: its fencing token, and the one row it was granted over.
+ *
+ * A claim's `readAt` generalises across a batch; its token does not. The token
+ * is evidence of one row's place in the grant order, so it belongs only on the
+ * operation writing the row the claim covers. Presented anywhere else the server
+ * refuses it, because a token that travels is a fence any writer can raise.
+ */
+export type BatchFence = Pick<ModelTarget, 'model' | 'id'> & {
+    readonly token: number;
+};
+/** The batch's grant, or nothing when there is no claim, or none with a token. */
+export declare function batchFence(source: EntityLocator | null | undefined, token: number | null | undefined): BatchFence | null;
+/**
+ * The token an operation carries: its own if it names one, the batch's when it
+ * writes the claimed row, otherwise none.
+ */
+export declare function fenceTokenFor(fence: BatchFence | null, model: string, id: string | null): number | null;
+//# sourceMappingURL=locator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../src/coordination/locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,SAAS,EACT,OAAO,GAAG,QAAQ,GAAG,MAAM,CAC5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACvD,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG;IACxD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EACZ,SAAS,CAAC,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC,EAAE,GAC1C,aAAa,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAAC;CAC/D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAGnD,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAC/C,KAAK,CAAC,EAAE,MAAM,GACb,kBAAkB,CAmBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,GACrB,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAE/C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,CAAC,GAC1C,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC,GACjC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AASrC,gFAAgF;AAChF,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,GACpB,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,CAAC,CAG5C;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,GACpB,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC,CAGnC;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,GACpB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC,CAGlC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,kFAAkF;AAClF,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACxC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,UAAU,GAAG,IAAI,CAInB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,IAAI,GAChB,MAAM,GAAG,IAAI,CAKf"}

package/dist/coordination/locator.js

@@ -0,0 +1,110 @@
+/**
+ * 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 { fieldSelection, } from '../schema/fieldRef.js';
+import { partName } from './schema.js';
+// 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, model) {
+    if (!source)
+        return {};
+    const selection = typeof source.fields === 'function'
+        ? source.fields(fieldSelection(model ?? ''))
+        : source.fields;
+    const selectedFields = selection === undefined
+        ? undefined
+        : Array.isArray(selection)
+            ? selection
+            : [selection];
+    return {
+        // Part names cross to their wire spelling here — the one declared→wire
+        // seam — so a `part('B2')` object never leaks into a frame or a URL.
+        ...(source.field !== undefined ? { field: partName(source.field) } : {}),
+        ...(selectedFields !== undefined ? { fields: selectedFields.map(partName) } : {}),
+        ...(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 };
+}
+/** The batch's grant, or nothing when there is no claim, or none with a token. */
+export function batchFence(source, token) {
+    return source == null || token == null
+        ? null
+        : { ...modelTarget(source), token };
+}
+/**
+ * The token an operation carries: its own if it names one, the batch's when it
+ * writes the claimed row, otherwise none.
+ */
+export function fenceTokenFor(fence, model, id) {
+    if (fence === null || id === null)
+        return null;
+    return model.toLowerCase() === fence.model.toLowerCase() && id === fence.id
+        ? fence.token
+        : null;
+}
+//# sourceMappingURL=locator.js.map

package/dist/coordination/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../../src/coordination/locator.ts"],"names":[],"mappings":"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"}