@axiom-lattice/protocols 3.0.4 → 4.0.1

package/src/TaskBeliefProtocol.ts

@@ -0,0 +1,324 @@
+/** A single canonical belief recorded in a task description. */
+export interface TaskBeliefEntry {
+  key: string;
+  probability: number;
+  target: number;
+  basis: string;
+}
+
+/** The canonical belief snapshot embedded in task Markdown. */
+export interface TaskBeliefState {
+  entries: TaskBeliefEntry[];
+}
+
+/** Stable diagnostic identifiers returned by the Belief State parser. */
+export type TaskBeliefDiagnosticCode =
+  | "MISSING_BELIEF_STATE"
+  | "DUPLICATE_BELIEF_STATE"
+  | "INVALID_BELIEF_HEADERS"
+  | "MALFORMED_BELIEF_ROW"
+  | "INVALID_BELIEF_KEY"
+  | "INVALID_BELIEF_PERCENT"
+  | "DUPLICATE_BELIEF_KEY";
+
+/** A structured failure produced while parsing a task Belief State. */
+export interface TaskBeliefParseFailure {
+  success: false;
+  code: TaskBeliefDiagnosticCode;
+  message: string;
+  line?: number;
+  key?: string;
+  column?: "probability" | "target";
+}
+
+/** A successfully parsed task Belief State. */
+export interface TaskBeliefParseSuccess {
+  success: true;
+  state: TaskBeliefState;
+}
+
+/** The discriminated result of parsing a task Belief State. */
+export type TaskBeliefParseResult = TaskBeliefParseSuccess | TaskBeliefParseFailure;
+
+interface MarkdownLine {
+  text: string;
+  start: number;
+  end: number;
+  fenced: boolean;
+  lineNumber: number;
+}
+
+interface SectionRange {
+  headingLine: number;
+  start: number;
+  end: number;
+}
+
+const BELIEF_HEADING = "## Belief State";
+const ACCEPTANCE_HEADING = "## Acceptance Criteria";
+const EXPECTED_HEADERS = ["Belief Key", "Probability", "Target", "Basis"];
+const KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PERCENT_PATTERN = /^(?:100|[0-9]{1,2})%$/;
+
+function markdownLines(markdown: string): MarkdownLine[] {
+  const lines: MarkdownLine[] = [];
+  let start = 0;
+  let fence: { marker: "`" | "~"; length: number } | undefined;
+
+  while (start <= markdown.length) {
+    const newline = markdown.indexOf("\n", start);
+    const end = newline === -1 ? markdown.length : newline + 1;
+    const textEnd = newline === -1 ? markdown.length : newline;
+    const rawText = markdown.slice(start, textEnd);
+    const text = rawText.endsWith("\r") ? rawText.slice(0, -1) : rawText;
+    const fenceMatch = text.match(/^ {0,3}(`{3,}|~{3,})/);
+    const fenced = fence !== undefined;
+
+    if (!fence && fenceMatch) {
+      const marker = fenceMatch[1][0] as "`" | "~";
+      fence = { marker, length: fenceMatch[1].length };
+    } else if (fence) {
+      const closePattern = new RegExp(`^ {0,3}\\${fence.marker}{${fence.length},}[ \\t]*$`);
+      if (closePattern.test(text)) fence = undefined;
+    }
+
+    lines.push({
+      text,
+      start,
+      end,
+      fenced: fenced || fenceMatch !== null,
+      lineNumber: lines.length + 1,
+    });
+    if (newline === -1) break;
+    start = end;
+  }
+
+  return lines;
+}
+
+function sectionRanges(markdown: string, heading: string): SectionRange[] {
+  const lines = markdownLines(markdown);
+  const ranges: SectionRange[] = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.fenced || line.text.trimEnd().replace(/^ {0,3}/, "") !== heading) continue;
+
+    let end = markdown.length;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      if (!lines[next].fenced && /^ {0,3}#{1,2}(?:[ \t]+|$)/.test(lines[next].text)) {
+        end = lines[next].start;
+        break;
+      }
+    }
+    ranges.push({ headingLine: index, start: line.start, end });
+  }
+
+  return ranges;
+}
+
+function splitTableRow(line: string): string[] | undefined {
+  const trimmed = line.trim();
+  const finalPipe = trimmed.length - 1;
+  if (!trimmed.startsWith("|") || !trimmed.endsWith("|") || isEscapedPipe(trimmed, finalPipe)) {
+    return undefined;
+  }
+
+  const cells: string[] = [];
+  let cell = "";
+  for (let index = 1; index < trimmed.length - 1; index += 1) {
+    const character = trimmed[index];
+    if (character === "|" && isEscapedPipe(trimmed, index)) {
+      cell += character;
+    } else if (character === "|") {
+      cells.push(unescapeTableCell(cell.trim()));
+      cell = "";
+    } else {
+      cell += character;
+    }
+  }
+  cells.push(unescapeTableCell(cell.trim()));
+  return cells;
+}
+
+function unescapeTableCell(cell: string): string {
+  let unescaped = "";
+  for (let index = 0; index < cell.length; index += 1) {
+    if (cell[index] === "\\" && (cell[index + 1] === "\\" || cell[index + 1] === "|")) {
+      index += 1;
+    }
+    unescaped += cell[index];
+  }
+  return unescaped;
+}
+
+function isEscapedPipe(line: string, pipeIndex: number): boolean {
+  let backslashes = 0;
+  for (let index = pipeIndex - 1; index >= 0 && line[index] === "\\"; index -= 1) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+}
+
+function failure(
+  code: TaskBeliefDiagnosticCode,
+  message: string,
+  details: Pick<TaskBeliefParseFailure, "line" | "key" | "column"> = {},
+): TaskBeliefParseFailure {
+  return { success: false, code, message, ...details };
+}
+
+function normalizedText(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function validateTaskBeliefState(state: TaskBeliefState): void {
+  const keys = new Set<string>();
+  for (const entry of state.entries) {
+    if (!KEY_PATTERN.test(entry.key)) {
+      throw new Error("Belief keys must be kebab-case without backticks or newlines.");
+    }
+    if (keys.has(entry.key)) {
+      throw new Error(`Belief key '${entry.key}' appears more than once.`);
+    }
+    for (const field of ["probability", "target"] as const) {
+      const value = entry[field];
+      if (!Number.isInteger(value) || value < 0 || value > 100) {
+        throw new Error(`Belief ${field} must be an integer from 0 to 100.`);
+      }
+    }
+    if (entry.basis.trim().length === 0 || /[\r\n]/.test(entry.basis)) {
+      throw new Error("Belief basis must be a nonempty single line.");
+    }
+    keys.add(entry.key);
+  }
+}
+
+function formatTaskBeliefState(state: TaskBeliefState): string {
+  validateTaskBeliefState(state);
+  const rows = state.entries.map(({ key, probability, target, basis }) => {
+    const escapedBasis = normalizedText(basis).replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+    return `| \`${key}\` | ${probability}% | ${target}% | ${escapedBasis} |`;
+  });
+  return [
+    BELIEF_HEADING,
+    "",
+    "| Belief Key | Probability | Target | Basis |",
+    "|---|---:|---:|---|",
+    ...rows,
+  ].join("\n");
+}
+
+/** Parses the unique non-code-fenced canonical Belief State section in Markdown. */
+export function parseTaskBeliefState(markdown: string): TaskBeliefParseResult {
+  const sections = sectionRanges(markdown, BELIEF_HEADING);
+  if (sections.length === 0) {
+    return failure("MISSING_BELIEF_STATE", "Markdown does not contain a Belief State section.");
+  }
+  if (sections.length > 1) {
+    return failure("DUPLICATE_BELIEF_STATE", "Markdown contains more than one Belief State section.");
+  }
+
+  const lines = markdownLines(markdown);
+  const section = sections[0];
+  const content = lines
+    .slice(section.headingLine + 1)
+    .filter((line) => line.start < section.end && line.text.trim() !== "");
+  const header = content[0] && splitTableRow(content[0].text);
+  const separator = content[1] && splitTableRow(content[1].text);
+  if (
+    !header ||
+    header.length !== EXPECTED_HEADERS.length ||
+    header.some((cell, index) => cell !== EXPECTED_HEADERS[index]) ||
+    !separator ||
+    separator.length !== EXPECTED_HEADERS.length ||
+    separator.some((cell) => !/^:?-{3,}:?$/.test(cell))
+  ) {
+    return failure("INVALID_BELIEF_HEADERS", "Belief State must use the canonical four-column headers.");
+  }
+
+  const entries: TaskBeliefEntry[] = [];
+  const keys = new Set<string>();
+  for (const line of content.slice(2)) {
+    const cells = splitTableRow(line.text);
+    if (!cells || cells.length !== 4 || cells[3].length === 0) {
+      return failure("MALFORMED_BELIEF_ROW", "Belief State contains a malformed row.", {
+        line: line.lineNumber,
+      });
+    }
+
+    const keyMatch = cells[0].match(/^`([^`]+)`$/);
+    if (!keyMatch || !KEY_PATTERN.test(keyMatch[1])) {
+      return failure("INVALID_BELIEF_KEY", "Belief keys must be backtick-wrapped kebab-case.", {
+        line: line.lineNumber,
+      });
+    }
+    const key = keyMatch[1];
+    if (keys.has(key)) {
+      return failure("DUPLICATE_BELIEF_KEY", `Belief key '${key}' appears more than once.`, {
+        line: line.lineNumber,
+        key,
+      });
+    }
+
+    for (const [index, column] of [[1, "probability"], [2, "target"]] as const) {
+      if (!PERCENT_PATTERN.test(cells[index])) {
+        return failure("INVALID_BELIEF_PERCENT", `Belief ${column} must be an integer from 0% to 100%.`, {
+          line: line.lineNumber,
+          column,
+        });
+      }
+    }
+
+    keys.add(key);
+    entries.push({
+      key,
+      probability: Number.parseInt(cells[1], 10),
+      target: Number.parseInt(cells[2], 10),
+      basis: cells[3],
+    });
+  }
+
+  return { success: true, state: { entries } };
+}
+
+/** Compares two Belief States while ignoring entry order and insignificant whitespace. */
+export function taskBeliefStatesEqual(left: TaskBeliefState, right: TaskBeliefState): boolean {
+  if (left.entries.length !== right.entries.length) return false;
+
+  const byKey = new Map(right.entries.map((entry) => [entry.key, entry]));
+  return left.entries.every((entry) => {
+    const other = byKey.get(entry.key);
+    return other !== undefined &&
+      entry.probability === other.probability &&
+      entry.target === other.target &&
+      normalizedText(entry.basis) === normalizedText(other.basis);
+  });
+}
+
+/**
+ * Replaces a unique Belief State section, or inserts one after Acceptance Criteria content.
+ *
+ * @throws {Error} If the state is noncanonical or the Markdown contains duplicate sections.
+ */
+export function replaceTaskBeliefState(markdown: string, state: TaskBeliefState): string {
+  const replacement = formatTaskBeliefState(state);
+  const sections = sectionRanges(markdown, BELIEF_HEADING);
+  if (sections.length > 1) {
+    throw new Error("Cannot replace duplicate Belief State sections.");
+  }
+  if (sections.length === 1) {
+    const section = sections[0];
+    const originalSection = markdown.slice(section.start, section.end);
+    const trailingWhitespace = originalSection.match(/\s*$/)?.[0] ?? "";
+    return markdown.slice(0, section.start) + replacement + trailingWhitespace + markdown.slice(section.end);
+  }
+
+  const acceptance = sectionRanges(markdown, ACCEPTANCE_HEADING)[0];
+  const insertion = acceptance?.end ?? markdown.length;
+  const before = markdown.slice(0, insertion);
+  const after = markdown.slice(insertion);
+  const leadingBreaks = before.length === 0 ? "" : before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  const trailingBreaks = after.length === 0 ? "" : after.startsWith("\n") ? "\n" : "\n\n";
+  return before + leadingBreaks + replacement + trailingBreaks + after;
+}

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>;