@axiom-lattice/protocols 4.6.1 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.6.1",
+  "version": "4.7.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/AgentAffinity.ts

@@ -0,0 +1,50 @@
+import type { MessageChunk } from "./MessageProtocol";
+
+/**
+ * Request header carrying the per-thread affinity key (the thread id).
+ *
+ * A multi-replica ingress hashes this header (consistently) so every
+ * execution-driving request for a thread lands on the replica that owns its
+ * process-local chunk buffer. Inert when no affinity is configured.
+ */
+export const AGENT_AFFINITY_HEADER = "x-axiom-affinity";
+
+/** Response header advertising the replica (`getReplicaId()`) that served a request. */
+export const REPLICA_HEADER = "x-axiom-replica";
+
+/** Response header echoing back the received `x-axiom-affinity` value (diagnostics). */
+export const AFFINITY_ECHO_HEADER = "x-axiom-affinity-echo";
+
+/** Builds the echo response header from a request's raw affinity value, or `{}` when absent/empty. */
+export function affinityEchoHeaders(value: string | string[] | undefined): Record<string, string> {
+  const single = Array.isArray(value) ? value[0] : value;
+  return typeof single === "string" && single.length > 0 ? { [AFFINITY_ECHO_HEADER]: single } : {};
+}
+
+/** Terminal error code emitted when a run is confirmed owned by another replica. */
+export const AFFINITY_MISS_CODE = "AFFINITY_MISS";
+
+/**
+ * Builds the request headers that pin a request to a thread's owner replica.
+ * Returns an empty object when no thread id is available.
+ */
+export function threadAffinityHeaders(threadId: string | undefined): Record<string, string> {
+  return threadId ? { [AGENT_AFFINITY_HEADER]: threadId } : {};
+}
+
+/**
+ * One terminal error chunk telling the client the run is owned elsewhere.
+ * Reuses the existing `error` chunk type; clients surface it via their error branch.
+ */
+export function buildAffinityMissChunk(owner: string, threadId: string): MessageChunk {
+  return {
+    type: "error",
+    data: {
+      id: "",
+      content: "Run is owned by another replica",
+      code: AFFINITY_MISS_CODE,
+      owner,
+      thread_id: threadId,
+    },
+  } as MessageChunk;
+}

package/src/LeaseStoreProtocol.ts

@@ -0,0 +1,44 @@
+/** One held distributed lease. */
+export interface LeaseRecord {
+  /** Lease key (e.g. `task-run:<taskId>`); unique across replicas. */
+  key: string;
+  /** Replica (holder) currently owning the key. */
+  holder: string;
+  /** ISO timestamp the current holder acquired it. */
+  acquiredAt: string;
+  /** ISO timestamp after which the lease is considered free. */
+  expiresAt: string;
+}
+
+/**
+ * Cross-replica lease store used for mutual exclusion, run ownership, and
+ * leader election. There is no Redis in this deployment: the reference
+ * implementation is PostgreSQL-backed, but the contract is transport-neutral.
+ *
+ * @remarks
+ * - `tryAcquire` is atomic: exactly one concurrent caller wins for a free or
+ *   expired key.
+ * - Leases are advisory. A holder that stops heartbeating loses the key at
+ *   `expiresAt`; callers doing non-idempotent work MUST re-check ownership or
+ *   use CAS-protected writes.
+ */
+export interface LeaseStore {
+  /**
+   * Atomically acquires `key` for `holder` for `ttlMs` when the key is free or
+   * its lease has expired (a holder may also re-acquire its own expired lease).
+   * @returns `true` when `holder` owns the lease after the call.
+   */
+  tryAcquire(key: string, holder: string, ttlMs: number): Promise<boolean>;
+  /**
+   * Extends a lease already held by `holder`.
+   * @returns `false` when the key is not held by `holder` (lost or taken).
+   */
+  renew(key: string, holder: string, ttlMs: number): Promise<boolean>;
+  /**
+   * Releases a lease held by `holder`.
+   * @returns `true` when a lease held by `holder` was removed.
+   */
+  release(key: string, holder: string): Promise<boolean>;
+  /** Reads the live lease for `key`, or `null` when free/expired/absent. */
+  get(key: string): Promise<LeaseRecord | null>;
+}

package/src/OutboxStoreProtocol.ts

@@ -0,0 +1,30 @@
+/** One durable outbox event, totally ordered by `id`. */
+export interface OutboxEvent {
+  /** Monotonic id (an integer serialized as a string). */
+  id: string;
+  /** Logical channel, e.g. `task-lifecycle`. */
+  topic: string;
+  /** JSON-safe payload delivered to local listeners. */
+  payload: unknown;
+  /** Replica that authored the event (skipped by its own poller). */
+  originReplicaId: string;
+  /** ISO timestamp. */
+  createdAt: string;
+}
+
+/** Append-only durable event log used to fan process-local notifications across replicas. */
+export interface OutboxStore {
+  /** Appends one event and returns it (with its assigned id). */
+  append(input: { topic: string; payload: unknown; originReplicaId: string }): Promise<OutboxEvent>;
+  /** Returns up to `limit` events with `id > cursor` (ascending); `null` cursor = from the start. */
+  listAfter(cursor: string | null, limit: number): Promise<OutboxEvent[]>;
+  /** Returns the newest id, or null when empty (used to skip history on poller start). */
+  latestId(): Promise<string | null>;
+  /**
+   * Deletes events older than `olderThanMs`.
+   *
+   * @param olderThanMs Age threshold in milliseconds.
+   * @returns The number of rows deleted.
+   */
+  pruneOlderThan(olderThanMs: number): Promise<number>;
+}

package/src/ProjectRoomRealtimeProtocol.ts

@@ -160,7 +160,7 @@ export interface ProjectRoomEventSubscription {
 /** The narrow broker contract consumed by realtime publishers and services. */
 export interface ProjectRoomEventBrokerProtocol {
   readonly epoch: string;
-  publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft): ProjectRoomScopedBusinessEvent;
+  publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft, sourceKey?: string): ProjectRoomScopedBusinessEvent;
   subscribe(
     scope: ProjectRoomEventScope,
     afterEventId: string | undefined,

package/src/ScheduleLatticeProtocol.ts

@@ -151,6 +151,24 @@ export interface ScheduleStorage {
     updates: Partial<ScheduledTaskDefinition>
   ): Promise<void>;
 
+  /**
+   * Atomically claims one due fire by transitioning the task `pending -> running`.
+   *
+   * @param taskId Task to claim.
+   * @returns True when this caller won the claim (task was `pending`); false if
+   *   another replica already claimed it or it is not pending.
+   */
+  claimScheduledRun(taskId: string): Promise<boolean>;
+
+  /**
+   * Requeues `running` tasks whose `updatedAt` is older than `olderThanMs` back
+   * to `pending` (recovery after a crash that left a claim unsettled).
+   *
+   * @param olderThanMs Age threshold in milliseconds.
+   * @returns The number of tasks requeued.
+   */
+  requeueStaleRunning(olderThanMs: number): Promise<number>;
+
   /**
    * Delete task
    */

package/src/__tests__/agentAffinity.test.ts

@@ -0,0 +1,45 @@
+import {
+  AGENT_AFFINITY_HEADER,
+  REPLICA_HEADER,
+  AFFINITY_MISS_CODE,
+  AFFINITY_ECHO_HEADER,
+  threadAffinityHeaders,
+  affinityEchoHeaders,
+  buildAffinityMissChunk,
+} from "../AgentAffinity";
+
+describe("AgentAffinity", () => {
+  it("exposes stable header/code names", () => {
+    expect(AGENT_AFFINITY_HEADER).toBe("x-axiom-affinity");
+    expect(REPLICA_HEADER).toBe("x-axiom-replica");
+    expect(AFFINITY_MISS_CODE).toBe("AFFINITY_MISS");
+  });
+
+  it("builds thread affinity headers only for a non-empty thread id", () => {
+    expect(threadAffinityHeaders("t1")).toEqual({ "x-axiom-affinity": "t1" });
+    expect(threadAffinityHeaders(undefined)).toEqual({});
+    expect(threadAffinityHeaders("")).toEqual({});
+  });
+
+  it("echoes the received affinity value", () => {
+    expect(AFFINITY_ECHO_HEADER).toBe("x-axiom-affinity-echo");
+    expect(affinityEchoHeaders("t1")).toEqual({ "x-axiom-affinity-echo": "t1" });
+  });
+
+  it("echoes the first value of an array affinity header", () => {
+    expect(affinityEchoHeaders(["t1", "t2"])).toEqual({ "x-axiom-affinity-echo": "t1" });
+  });
+
+  it("echoes nothing for an absent or empty affinity header", () => {
+    expect(affinityEchoHeaders(undefined)).toEqual({});
+    expect(affinityEchoHeaders("")).toEqual({});
+  });
+
+  it("builds one terminal error chunk carrying the owner", () => {
+    const chunk = buildAffinityMissChunk("replica-b", "t1") as { type: string; data: Record<string, unknown> };
+    expect(chunk.type).toBe("error");
+    expect(chunk.data.code).toBe("AFFINITY_MISS");
+    expect(chunk.data.owner).toBe("replica-b");
+    expect(chunk.data.thread_id).toBe("t1");
+  });
+});

package/src/index.ts

@@ -59,6 +59,8 @@ export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
 export * from "./ProjectRoomReadStateProtocol";
 export * from "./UserPushSubscriptionStoreProtocol";
+export * from "./LeaseStoreProtocol";
+export * from "./OutboxStoreProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";
 
@@ -95,5 +97,6 @@ export * from "./SandboxPluginProtocol";
 export * from "./types";
 export * from "./TrustedRunContextProtocol";
 export * from "./RunScope";
+export * from "./AgentAffinity";
 export * from "./OpenProtocol";
 export * from "./McpUiProtocol";