@axiom-lattice/protocols 3.0.3 → 4.0.0

package/src/TaskStoreProtocol.ts

@@ -122,6 +122,12 @@ export interface TaskItem {
  * Create task request type
  */
 export interface CreateTaskRequest {
+  /**
+   * Caller-provided task identifier. When set, the store uses this id instead of
+   * generating one — used for single-ID mapping with external systems (e.g. A2A).
+   */
+  id?: string;
+
   /**
    * Task title
    */
@@ -226,6 +232,8 @@ export interface TaskFileRef {
   uri: string;
   /** Display name (useful when uri is a uuid or bare path) */
   name?: string;
+  /** MIME type of the referenced file (e.g. "application/pdf"), when known */
+  mimeType?: string;
   /** Who attached the file: the user (reference material) or an agent (artifact) */
   addedBy?: "user" | "agent";
 }
@@ -287,7 +295,7 @@ export interface UpdateTaskRequest {
   /**
    * Additional contextual data
    */
-  context?: Record<string, unknown>;
+  context?: Record<string, unknown> | null;
 
   /**
    * Owner type
@@ -312,12 +320,12 @@ export interface UpdateTaskRequest {
   /**
    * Task result output
    */
-  result?: string;
+  result?: string | null;
 
   /**
    * Reason for task failure (when status is 'failed')
    */
-  failureReason?: string;
+  failureReason?: string | null;
 
   /** File references attached to this task */
   files?: TaskFileRef[];
@@ -424,6 +432,89 @@ export interface TaskStore {
    */
   update(tenantId: string, id: string, updates: UpdateTaskRequest): Promise<TaskItem | null>;
 
+  /**
+   * Atomically update a task only when its current status is expected.
+   *
+   * Storage implementations must evaluate the status predicate in the same
+   * atomic mutation that applies `updates`; callers must not emulate this with
+   * a separate read followed by {@link update}.
+   *
+   * @param tenantId Tenant identifier.
+   * @param id Task identifier.
+   * @param updates Partial task data to update.
+   * @param expectedStatuses Current statuses that permit the update.
+   * @returns The updated task, or `null` when the task is missing or its status is not expected.
+   */
+  updateIfStatusIn(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+  ): Promise<TaskItem | null>;
+
+  /**
+   * Atomically updates a task only when its status and update timestamp match a read snapshot.
+   *
+   * Implementations must normalize `Date` and string timestamps to the same stable ISO
+   * representation and evaluate both predicates in the mutation itself.
+   *
+   * @param tenantId Tenant identifier.
+   * @param id Task identifier.
+   * @param updates Partial task data to update.
+   * @param expectedStatuses Current statuses that permit the update.
+   * @param expectedUpdatedAt Update timestamp captured from the validated task snapshot.
+   * @returns The updated task, or `null` when the task is missing or either snapshot predicate differs.
+   */
+  updateIfStatusAndUpdatedAt(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+    expectedUpdatedAt: Date | string,
+  ): Promise<TaskItem | null>;
+
+  /**
+   * Atomically updates a child only when both child and parent snapshots match.
+   *
+   * @param tenantId Tenant identifier shared by the child and parent.
+   * @param id Child task identifier.
+   * @param updates Partial child task data to update.
+   * @param expectedStatuses Child statuses that permit the update.
+   * @param expectedUpdatedAt Child update timestamp captured during validation.
+   * @param parentId Parent task identifier captured during validation.
+   * @param expectedParentUpdatedAt Parent update timestamp captured during validation.
+   * @returns The updated child, or `null` when either task is missing or either snapshot differs.
+   */
+  updateIfStatusUpdatedAtAndParentUpdatedAt(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+    expectedUpdatedAt: Date | string,
+    parentId: string,
+    expectedParentUpdatedAt: Date | string,
+  ): Promise<TaskItem | null>;
+
+  /**
+   * Atomically update a task unless its current status is blocked.
+   *
+   * Storage implementations must evaluate the status predicate in the same
+   * atomic mutation that applies `updates`; callers must not emulate this with
+   * a separate read followed by {@link update}.
+   *
+   * @param tenantId Tenant identifier.
+   * @param id Task identifier.
+   * @param updates Partial task data to update.
+   * @param blockedStatuses Current statuses that prevent the update.
+   * @returns The updated task, or `null` when the task is missing or blocked.
+   */
+  updateIfStatusNotIn(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    blockedStatuses: TaskItem["status"][],
+  ): Promise<TaskItem | null>;
+
   /**
    * Delete a task by ID
    * @param tenantId Tenant identifier

package/src/TaskWorkItemProtocol.ts

@@ -17,6 +17,8 @@ export interface TaskWorkItem {
   summary?: string;
   detail?: Record<string, unknown>;
   attempt?: number;
+  /** Deterministic task-scoped identity used for idempotent event replay. */
+  eventKey?: string;
   createdAt: Date;
 }
 
@@ -33,12 +35,23 @@ export interface CreateWorkItemRequest {
   attempt?: number;
 }
 
+/**
+ * Work-item creation request requiring a deterministic event identity.
+ *
+ * Event keys are unique within a tenant and task, not globally.
+ */
+export interface CreateWorkItemIfAbsentRequest extends CreateWorkItemRequest {
+  /** Deterministic task-scoped identity used for idempotent event replay. */
+  eventKey: string;
+}
+
 export interface TaskWorkItemListFilter {
   tenantId: string;
   taskId: string;
   workspaceId?: string;
   projectId?: string;
   action?: string;
+  order?: 'asc' | 'desc';
   limit?: number;
   offset?: number;
 }
@@ -46,4 +59,23 @@ export interface TaskWorkItemListFilter {
 export interface TaskWorkItemStore {
   create(params: CreateWorkItemRequest): Promise<TaskWorkItem>;
   list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]>;
+
+  /**
+   * Find an event by deterministic identity without list pagination.
+   *
+   * @param tenantId Tenant identifier.
+   * @param taskId Task identifier that scopes the event key.
+   * @param eventKey Deterministic event identity.
+   * @returns The matching item, or `null` when absent.
+   */
+  findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null>;
+
+  /**
+   * Atomically create an event unless its task-scoped key already exists.
+   * Existing events are returned unchanged, preserving immutable replay.
+   *
+   * @param params Work-item fields including the required event key.
+   * @returns The existing or newly created work item.
+   */
+  createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem>;
 }

package/src/WorkspaceStoreProtocol.ts

@@ -50,6 +50,13 @@ export interface WorkspaceStore {
   deleteWorkspace(tenantId: string, id: string): Promise<boolean>;
 }
 
+/**
+ * Project kind classification
+ *
+ * Defaults to "business" for legacy rows and omitted input.
+ */
+export type ProjectKind = "business" | "training" | "personal";
+
 /**
  * Project type definition
  */
@@ -61,6 +68,8 @@ export interface Project {
   description?: string;
   /** Application-specific configuration stored as JSON */
   config?: Record<string, unknown>;
+  /** Project classification; defaults to "business" when omitted */
+  kind?: ProjectKind;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -73,6 +82,8 @@ export interface CreateProjectRequest {
   description?: string;
   /** Application-specific configuration stored as JSON (optional) */
   config?: Record<string, unknown>;
+  /** Project classification; defaults to "business" when omitted */
+  kind?: ProjectKind;
 }
 
 /**
@@ -87,6 +98,15 @@ export interface UpdateProjectRequest {
   description?: string;
   /** Application-specific configuration stored as JSON (replaces existing if provided) */
   config?: Record<string, unknown>;
+  /** Project classification */
+  kind?: ProjectKind;
+}
+
+/**
+ * Filter options for listing projects within a workspace
+ */
+export interface ProjectFilter {
+  kind?: ProjectKind;
 }
 
 /**
@@ -94,7 +114,7 @@ export interface UpdateProjectRequest {
  * Provides CRUD operations for project data
  */
 export interface ProjectStore {
-  getProjectsByWorkspace(tenantId: string, workspaceId: string): Promise<Project[]>;
+  getProjectsByWorkspace(tenantId: string, workspaceId: string, filter?: ProjectFilter): Promise<Project[]>;
   getProjectById(tenantId: string, id: string): Promise<Project | null>;
   createProject(tenantId: string, workspaceId: string, id: string, data: CreateProjectRequest): Promise<Project>;
   updateProject(tenantId: string, id: string, updates: UpdateProjectRequest): Promise<Project | null>;

package/src/__tests__/TaskBeliefProtocol.test.ts

@@ -0,0 +1,421 @@
+import {
+  parseTaskBeliefState,
+  replaceTaskBeliefState,
+  taskBeliefStatesEqual,
+  type TaskBeliefState,
+} from "../TaskBeliefProtocol";
+
+const HEADER = "| Belief Key | Probability | Target | Basis |";
+const SEPARATOR = "|---|---:|---:|---|";
+
+function beliefSection(rows: string[]): string {
+  return ["## Belief State", "", HEADER, SEPARATOR, ...rows].join("\n");
+}
+
+describe("parseTaskBeliefState", () => {
+  it("parses the canonical four-column Belief State", () => {
+    const markdown = [
+      "## Objective",
+      "Ship",
+      "",
+      beliefSection(["| `input-valid` | 60% | 90% | File exists |"]),
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toEqual({
+      success: true,
+      state: {
+        entries: [
+          { key: "input-valid", probability: 60, target: 90, basis: "File exists" },
+        ],
+      },
+    });
+  });
+
+  it("accepts escaped pipes in Basis", () => {
+    const result = parseTaskBeliefState(
+      beliefSection(["| `input-valid` | 60% | 90% | JSON parser A \\| B passed |"]),
+    );
+
+    expect(result).toEqual({
+      success: true,
+      state: {
+        entries: [
+          {
+            key: "input-valid",
+            probability: 60,
+            target: 90,
+            basis: "JSON parser A | B passed",
+          },
+        ],
+      },
+    });
+  });
+
+  it("stops the section at an ATX heading with up to three leading spaces", () => {
+    const markdown = [
+      beliefSection(["| `input-valid` | 60% | 90% | File exists |"]),
+      "",
+      "  ## Notes",
+      "This is not a belief row.",
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toEqual({
+      success: true,
+      state: {
+        entries: [
+          { key: "input-valid", probability: 60, target: 90, basis: "File exists" },
+        ],
+      },
+    });
+  });
+
+  it("rejects a row whose apparent closing pipe is escaped", () => {
+    const result = parseTaskBeliefState(
+      beliefSection(["| `input-valid` | 60% | 90% | basis \\|"]),
+    );
+
+    expect(result).toMatchObject({
+      success: false,
+      code: "MALFORMED_BELIEF_ROW",
+    });
+  });
+
+  it("parses a Basis ending in a literal pipe followed by a closing delimiter", () => {
+    const result = parseTaskBeliefState(
+      beliefSection(["| `input-valid` | 60% | 90% | basis \\| |"]),
+    );
+
+    expect(result).toEqual({
+      success: true,
+      state: {
+        entries: [
+          { key: "input-valid", probability: 60, target: 90, basis: "basis |" },
+        ],
+      },
+    });
+  });
+
+  it("ignores a fake section inside a code fence", () => {
+    const markdown = [
+      "```markdown",
+      beliefSection(["| `fake-key` | 1% | 2% | fake |"]),
+      "```",
+      "",
+      beliefSection(["| `real-key` | 40% | 80% | observed |"]),
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toMatchObject({
+      success: true,
+      state: { entries: [{ key: "real-key" }] },
+    });
+  });
+
+  it.each([
+    ["backtick", "```markdown", "```not-a-close", "```"],
+    ["tilde", "~~~markdown", "~~~not-a-close", "~~~"],
+  ])("keeps headings fenced after a malformed %s close candidate", (_, opener, malformedClose, close) => {
+    const markdown = [
+      opener,
+      malformedClose,
+      beliefSection(["| `fake-key` | 1% | 2% | fake |"]),
+      close,
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toMatchObject({
+      success: false,
+      code: "MISSING_BELIEF_STATE",
+    });
+  });
+
+  it("reports a missing non-fenced section", () => {
+    const markdown = [
+      "## Objective",
+      "Ship",
+      "",
+      "~~~markdown",
+      beliefSection(["| `fake-key` | 1% | 2% | fake |"]),
+      "~~~",
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toMatchObject({
+      success: false,
+      code: "MISSING_BELIEF_STATE",
+    });
+  });
+
+  it("reports duplicate non-fenced sections", () => {
+    const markdown = [
+      beliefSection(["| `first-key` | 10% | 90% | first |"]),
+      "",
+      beliefSection(["| `second-key` | 20% | 90% | second |"]),
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toMatchObject({
+      success: false,
+      code: "DUPLICATE_BELIEF_STATE",
+    });
+  });
+
+  it("reports duplicate keys", () => {
+    const result = parseTaskBeliefState(
+      beliefSection([
+        "| `same-key` | 10% | 90% | one |",
+        "| `same-key` | 20% | 90% | two |",
+      ]),
+    );
+
+    expect(result).toMatchObject({
+      success: false,
+      code: "DUPLICATE_BELIEF_KEY",
+      key: "same-key",
+    });
+  });
+
+  it("reports localized or reordered headers", () => {
+    const markdown = [
+      "## Belief State",
+      "",
+      "| Belief Key | Target | Probability | Basis |",
+      SEPARATOR,
+      "| `input-valid` | 90% | 60% | exists |",
+    ].join("\n");
+
+    expect(parseTaskBeliefState(markdown)).toMatchObject({
+      success: false,
+      code: "INVALID_BELIEF_HEADERS",
+    });
+  });
+
+  it.each(["60.5%", "-1%", "101%", "60", " 60 % "])(
+    "reports malformed probability %s",
+    (probability) => {
+      const result = parseTaskBeliefState(
+        beliefSection([`| \`input-valid\` | ${probability} | 90% | exists |`]),
+      );
+
+      expect(result).toMatchObject({
+        success: false,
+        code: "INVALID_BELIEF_PERCENT",
+        column: "probability",
+      });
+    },
+  );
+
+  it("reports malformed target percentages", () => {
+    const result = parseTaskBeliefState(
+      beliefSection(["| `input-valid` | 60% | nope | exists |"]),
+    );
+
+    expect(result).toMatchObject({
+      success: false,
+      code: "INVALID_BELIEF_PERCENT",
+      column: "target",
+    });
+  });
+
+  it.each(["input-valid", "`Input-valid`", "`input_valid`", "`-input-valid`"]) (
+    "reports malformed belief key %s",
+    (key) => {
+      const result = parseTaskBeliefState(
+        beliefSection([`| ${key} | 60% | 90% | exists |`]),
+      );
+
+      expect(result).toMatchObject({
+        success: false,
+        code: "INVALID_BELIEF_KEY",
+      });
+    },
+  );
+
+  it("reports malformed rows", () => {
+    const result = parseTaskBeliefState(
+      beliefSection(["| `input-valid` | 60% | 90% | basis | extra |"]),
+    );
+
+    expect(result).toMatchObject({
+      success: false,
+      code: "MALFORMED_BELIEF_ROW",
+    });
+  });
+});
+
+describe("taskBeliefStatesEqual", () => {
+  it("ignores row order and insignificant whitespace", () => {
+    const left: TaskBeliefState = {
+      entries: [
+        { key: "alpha-ready", probability: 20, target: 80, basis: " first  observation " },
+        { key: "beta-ready", probability: 30, target: 90, basis: "line one\n  line two" },
+      ],
+    };
+    const right: TaskBeliefState = {
+      entries: [
+        { key: "beta-ready", probability: 30, target: 90, basis: "line one line two" },
+        { key: "alpha-ready", probability: 20, target: 80, basis: "first observation" },
+      ],
+    };
+
+    expect(taskBeliefStatesEqual(left, right)).toBe(true);
+  });
+
+  it.each(["probability", "target", "basis"] as const)("compares %s", (field) => {
+    const left: TaskBeliefState = {
+      entries: [{ key: "input-valid", probability: 60, target: 90, basis: "exists" }],
+    };
+    const changed = {
+      probability: 61,
+      target: 91,
+      basis: "verified",
+    }[field];
+    const right: TaskBeliefState = {
+      entries: [{ ...left.entries[0], [field]: changed }],
+    };
+
+    expect(taskBeliefStatesEqual(left, right)).toBe(false);
+  });
+});
+
+describe("replaceTaskBeliefState", () => {
+  const replacement: TaskBeliefState = {
+    entries: [
+      { key: "input-valid", probability: 75, target: 90, basis: "A | B verified" },
+    ],
+  };
+
+  it.each([
+    ["literal pipe", "|", "\\|"],
+    ["backslash before pipe", "\\|", "\\\\\\|"],
+    ["trailing backslash and pipe", "evidence \\|", "evidence \\\\\\|"],
+    ["multiple backslashes before pipe", "\\\\|", "\\\\\\\\\\|"],
+    ["plain backslash", "path\\segment", "path\\\\segment"],
+  ])("round-trips a Basis containing %s", (_, basis, escapedBasis) => {
+    const state: TaskBeliefState = {
+      entries: [{ key: "input-valid", probability: 75, target: 90, basis }],
+    };
+
+    const replaced = replaceTaskBeliefState("# Task", state);
+    expect(replaced).toContain(`| \`input-valid\` | 75% | 90% | ${escapedBasis} |`);
+
+    const parsed = parseTaskBeliefState(replaced);
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(taskBeliefStatesEqual(parsed.state, state)).toBe(true);
+    }
+  });
+
+  it("replaces only the existing Belief State section", () => {
+    const before = [
+      "# Task",
+      "",
+      "## Objective",
+      "Keep this text exactly.  ",
+      "",
+      beliefSection(["| `old-key` | 10% | 80% | old |"]),
+      "",
+      "## Acceptance Criteria",
+      "- [ ] Preserve this | text",
+      "",
+    ].join("\n");
+
+    const replaced = replaceTaskBeliefState(before, replacement);
+
+    expect(replaced).toBe([
+      "# Task",
+      "",
+      "## Objective",
+      "Keep this text exactly.  ",
+      "",
+      beliefSection(["| `input-valid` | 75% | 90% | A \\| B verified |"]),
+      "",
+      "## Acceptance Criteria",
+      "- [ ] Preserve this | text",
+      "",
+    ].join("\n"));
+  });
+
+  it("preserves a following ATX heading with leading spaces", () => {
+    const before = [
+      beliefSection(["| `old-key` | 10% | 80% | old |"]),
+      "",
+      "  ## Notes",
+      "Keep this text exactly.",
+    ].join("\n");
+
+    expect(replaceTaskBeliefState(before, replacement)).toBe([
+      beliefSection(["| `input-valid` | 75% | 90% | A \\| B verified |"]),
+      "",
+      "  ## Notes",
+      "Keep this text exactly.",
+    ].join("\n"));
+  });
+
+  it("inserts after Acceptance Criteria content and before the next section", () => {
+    const before = [
+      "## Objective",
+      "Ship",
+      "",
+      "## Acceptance Criteria",
+      "- [ ] Tests pass",
+      "",
+      "## Notes",
+      "Do not damage this text.",
+    ].join("\n");
+
+    expect(replaceTaskBeliefState(before, replacement)).toBe([
+      "## Objective",
+      "Ship",
+      "",
+      "## Acceptance Criteria",
+      "- [ ] Tests pass",
+      "",
+      beliefSection(["| `input-valid` | 75% | 90% | A \\| B verified |"]),
+      "",
+      "## Notes",
+      "Do not damage this text.",
+    ].join("\n"));
+  });
+
+  it("inserts at the end when Acceptance Criteria is the final section", () => {
+    const before = "## Acceptance Criteria\n\n- [ ] Tests pass\n";
+
+    expect(replaceTaskBeliefState(before, replacement)).toBe(
+      `${before}\n${beliefSection(["| `input-valid` | 75% | 90% | A \\| B verified |"])}`,
+    );
+  });
+
+  it.each(["Input-valid", "`input-valid`", "input_valid", "input-valid\nextra"])(
+    "rejects invalid state key %j",
+    (key) => {
+      expect(() => replaceTaskBeliefState("", {
+        entries: [{ ...replacement.entries[0], key }],
+      })).toThrow("Belief keys must be kebab-case without backticks or newlines.");
+    },
+  );
+
+  it.each([
+    ["probability", 60.5],
+    ["probability", -1],
+    ["probability", 101],
+    ["target", 90.5],
+    ["target", -1],
+    ["target", 101],
+  ] as const)("rejects invalid state %s %s", (field, value) => {
+    expect(() => replaceTaskBeliefState("", {
+      entries: [{ ...replacement.entries[0], [field]: value }],
+    })).toThrow(`Belief ${field} must be an integer from 0 to 100.`);
+  });
+
+  it.each(["", "   ", "line one\nline two", "line one\rline two"])(
+    "rejects blank or multiline state basis %j",
+    (basis) => {
+      expect(() => replaceTaskBeliefState("", {
+        entries: [{ ...replacement.entries[0], basis }],
+      })).toThrow("Belief basis must be a nonempty single line.");
+    },
+  );
+
+  it("rejects duplicate state keys", () => {
+    expect(() => replaceTaskBeliefState("", {
+      entries: [replacement.entries[0], { ...replacement.entries[0], probability: 80 }],
+    })).toThrow("Belief key 'input-valid' appears more than once.");
+  });
+});

package/src/__tests__/a2a-types.test.ts

@@ -0,0 +1,30 @@
+import type { TaskFileRef, CreateTaskRequest } from "../TaskStoreProtocol";
+import type { A2AApiKeyRecord, CreateA2AApiKeyInput } from "../A2AApiKeyStoreProtocol";
+import type { A2AExposure } from "../A2AProtocol";
+
+describe("A2A protocol types", () => {
+  it("TaskFileRef supports mimeType", () => {
+    const ref: TaskFileRef = { uri: "/project/uploads/a.pdf", name: "a.pdf", mimeType: "application/pdf", addedBy: "user" };
+    expect(ref.mimeType).toBe("application/pdf");
+  });
+
+  it("CreateTaskRequest supports caller-provided id", () => {
+    const req: CreateTaskRequest = { id: "a2a-task-1", title: "t" };
+    expect(req.id).toBe("a2a-task-1");
+  });
+
+  it("A2A key model requires projectId and supports assistantIds, no workspaceId", () => {
+    const input: CreateA2AApiKeyInput = { tenantId: "t1", projectId: "p1", assistantIds: ["a1"], label: "l" };
+    expect(input.projectId).toBe("p1");
+    const rec: A2AApiKeyRecord = {
+      id: "k1", key: "a2a_x", tenantId: "t1", projectId: "p1",
+      assistantIds: ["a1"], enabled: true, createdAt: new Date(), updatedAt: new Date(),
+    };
+    expect("workspaceId" in rec).toBe(false);
+  });
+
+  it("A2AExposure shape", () => {
+    const exp: A2AExposure = { enabled: true, skills: [{ id: "s", name: "n", description: "d" }] };
+    expect(exp.enabled).toBe(true);
+  });
+});