@contractspec/example.workflow-system 1.57.0 → 1.59.0

package/dist/browser/entities/instance.js

@@ -0,0 +1,161 @@
+// src/entities/instance.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var InstanceStatusEnum = defineEntityEnum({
+  name: "InstanceStatus",
+  values: [
+    "PENDING",
+    "RUNNING",
+    "WAITING",
+    "PAUSED",
+    "COMPLETED",
+    "CANCELLED",
+    "FAILED",
+    "TIMEOUT"
+  ],
+  schema: "workflow",
+  description: "Status of a workflow instance."
+});
+var StepExecutionStatusEnum = defineEntityEnum({
+  name: "StepExecutionStatus",
+  values: [
+    "PENDING",
+    "ACTIVE",
+    "COMPLETED",
+    "SKIPPED",
+    "FAILED",
+    "TIMEOUT"
+  ],
+  schema: "workflow",
+  description: "Status of a step execution."
+});
+var WorkflowInstanceEntity = defineEntity({
+  name: "WorkflowInstance",
+  description: "A running instance of a workflow definition.",
+  schema: "workflow",
+  map: "workflow_instance",
+  fields: {
+    id: field.id({ description: "Unique instance ID" }),
+    workflowDefinitionId: field.foreignKey(),
+    referenceId: field.string({
+      isOptional: true,
+      description: "External reference (e.g., order ID)"
+    }),
+    referenceType: field.string({
+      isOptional: true,
+      description: 'Type of reference (e.g., "Order")'
+    }),
+    status: field.enum("InstanceStatus", { default: "PENDING" }),
+    currentStepId: field.string({
+      isOptional: true,
+      description: "Current step being executed"
+    }),
+    contextData: field.json({ description: "Data context for this instance" }),
+    triggeredBy: field.foreignKey({
+      description: "User who triggered the workflow"
+    }),
+    triggerSource: field.string({
+      isOptional: true,
+      description: 'Source of trigger (e.g., "api", "ui")'
+    }),
+    organizationId: field.foreignKey(),
+    priority: field.int({
+      default: 0,
+      description: "Processing priority (higher = more urgent)"
+    }),
+    dueAt: field.dateTime({
+      isOptional: true,
+      description: "When this instance should complete"
+    }),
+    outcome: field.string({
+      isOptional: true,
+      description: 'Final outcome (e.g., "approved", "rejected")'
+    }),
+    resultData: field.json({
+      isOptional: true,
+      description: "Final result data"
+    }),
+    errorMessage: field.string({
+      isOptional: true,
+      description: "Error message if failed"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    startedAt: field.dateTime({ isOptional: true }),
+    completedAt: field.dateTime({ isOptional: true }),
+    workflowDefinition: field.belongsTo("WorkflowDefinition", ["workflowDefinitionId"], ["id"]),
+    currentStep: field.belongsTo("WorkflowStep", ["currentStepId"], ["id"]),
+    stepExecutions: field.hasMany("StepExecution"),
+    approvalRequests: field.hasMany("ApprovalRequest")
+  },
+  indexes: [
+    index.on(["organizationId", "status"]),
+    index.on(["workflowDefinitionId", "status"]),
+    index.on(["referenceType", "referenceId"]),
+    index.on(["triggeredBy", "status"]),
+    index.on(["status", "dueAt"]),
+    index.on(["createdAt"])
+  ],
+  enums: [InstanceStatusEnum]
+});
+var StepExecutionEntity = defineEntity({
+  name: "StepExecution",
+  description: "Execution record of a step within a workflow instance.",
+  schema: "workflow",
+  map: "step_execution",
+  fields: {
+    id: field.id({ description: "Unique execution ID" }),
+    workflowInstanceId: field.foreignKey(),
+    workflowStepId: field.foreignKey(),
+    status: field.enum("StepExecutionStatus", { default: "PENDING" }),
+    executionOrder: field.int({
+      default: 0,
+      description: "Order of execution within instance"
+    }),
+    inputData: field.json({
+      isOptional: true,
+      description: "Data when entering step"
+    }),
+    outputData: field.json({
+      isOptional: true,
+      description: "Data when exiting step"
+    }),
+    actionTaken: field.string({
+      isOptional: true,
+      description: 'Action that caused transition (e.g., "approve")'
+    }),
+    transitionedTo: field.string({
+      isOptional: true,
+      description: "Step key transitioned to"
+    }),
+    executedBy: field.string({
+      isOptional: true,
+      description: "User who completed this step"
+    }),
+    errorMessage: field.string({ isOptional: true }),
+    errorDetails: field.json({ isOptional: true }),
+    retryCount: field.int({ default: 0 }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    startedAt: field.dateTime({ isOptional: true }),
+    completedAt: field.dateTime({ isOptional: true }),
+    workflowInstance: field.belongsTo("WorkflowInstance", ["workflowInstanceId"], ["id"], { onDelete: "Cascade" }),
+    workflowStep: field.belongsTo("WorkflowStep", ["workflowStepId"], ["id"])
+  },
+  indexes: [
+    index.on(["workflowInstanceId", "executionOrder"]),
+    index.on(["workflowInstanceId", "workflowStepId"]),
+    index.on(["status"])
+  ],
+  enums: [StepExecutionStatusEnum]
+});
+export {
+  WorkflowInstanceEntity,
+  StepExecutionStatusEnum,
+  StepExecutionEntity,
+  InstanceStatusEnum
+};

package/dist/browser/entities/step.js

@@ -0,0 +1,124 @@
+// src/entities/step.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var StepTypeEnum = defineEntityEnum({
+  name: "StepType",
+  values: [
+    "START",
+    "APPROVAL",
+    "TASK",
+    "CONDITION",
+    "PARALLEL",
+    "WAIT",
+    "ACTION",
+    "END"
+  ],
+  schema: "workflow",
+  description: "Type of workflow step."
+});
+var ApprovalModeEnum = defineEntityEnum({
+  name: "ApprovalMode",
+  values: [
+    "ANY",
+    "ALL",
+    "MAJORITY",
+    "SEQUENTIAL"
+  ],
+  schema: "workflow",
+  description: "How multiple approvers are handled."
+});
+var WorkflowStepEntity = defineEntity({
+  name: "WorkflowStep",
+  description: "A single step/state in a workflow definition.",
+  schema: "workflow",
+  map: "workflow_step",
+  fields: {
+    id: field.id({ description: "Unique step ID" }),
+    workflowDefinitionId: field.foreignKey(),
+    name: field.string({ description: "Human-readable step name" }),
+    key: field.string({
+      description: 'Unique key within workflow (e.g., "manager_approval")'
+    }),
+    description: field.string({ isOptional: true }),
+    type: field.enum("StepType", { default: "TASK" }),
+    position: field.int({ default: 0, description: "Order for display" }),
+    transitions: field.json({ description: "Map of action -> next step key" }),
+    approvalMode: field.enum("ApprovalMode", {
+      default: "ANY",
+      isOptional: true
+    }),
+    approverRoles: field.string({
+      isArray: true,
+      description: "Roles that can approve"
+    }),
+    approverUserIds: field.string({
+      isArray: true,
+      description: "Specific users that can approve"
+    }),
+    escalationConfig: field.json({
+      isOptional: true,
+      description: "Escalation rules"
+    }),
+    assigneeRoles: field.string({
+      isArray: true,
+      description: "Roles that can be assigned"
+    }),
+    taskTemplate: field.json({
+      isOptional: true,
+      description: "Template for task creation"
+    }),
+    conditionExpression: field.string({
+      isOptional: true,
+      description: "Expression for branching"
+    }),
+    waitDuration: field.int({
+      isOptional: true,
+      description: "Wait duration in seconds"
+    }),
+    waitForEvent: field.string({
+      isOptional: true,
+      description: "Event name to wait for"
+    }),
+    actionType: field.string({
+      isOptional: true,
+      description: "Action to execute"
+    }),
+    actionConfig: field.json({
+      isOptional: true,
+      description: "Action parameters"
+    }),
+    timeoutSeconds: field.int({
+      isOptional: true,
+      description: "Step timeout"
+    }),
+    slaSeconds: field.int({ isOptional: true, description: "SLA deadline" }),
+    notifyOnEnter: field.json({
+      isOptional: true,
+      description: "Notification config when entering step"
+    }),
+    notifyOnExit: field.json({
+      isOptional: true,
+      description: "Notification config when exiting step"
+    }),
+    metadata: field.json({ isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    workflowDefinition: field.belongsTo("WorkflowDefinition", ["workflowDefinitionId"], ["id"], { onDelete: "Cascade" }),
+    executions: field.hasMany("StepExecution")
+  },
+  indexes: [
+    index.unique(["workflowDefinitionId", "key"]),
+    index.on(["workflowDefinitionId", "position"]),
+    index.on(["type"])
+  ],
+  enums: [StepTypeEnum, ApprovalModeEnum]
+});
+export {
+  WorkflowStepEntity,
+  StepTypeEnum,
+  ApprovalModeEnum
+};

package/dist/browser/entities/workflow.js

@@ -0,0 +1,82 @@
+// src/entities/workflow.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var WorkflowStatusEnum = defineEntityEnum({
+  name: "WorkflowStatus",
+  values: ["DRAFT", "ACTIVE", "DEPRECATED", "ARCHIVED"],
+  schema: "workflow",
+  description: "Status of a workflow definition."
+});
+var WorkflowTriggerTypeEnum = defineEntityEnum({
+  name: "WorkflowTriggerType",
+  values: ["MANUAL", "EVENT", "SCHEDULED", "API"],
+  schema: "workflow",
+  description: "What triggers workflow instantiation."
+});
+var WorkflowDefinitionEntity = defineEntity({
+  name: "WorkflowDefinition",
+  description: "A workflow blueprint that defines the process structure.",
+  schema: "workflow",
+  map: "workflow_definition",
+  fields: {
+    id: field.id({ description: "Unique workflow definition ID" }),
+    name: field.string({ description: "Human-readable workflow name" }),
+    key: field.string({
+      description: 'Unique key for referencing (e.g., "purchase_approval")'
+    }),
+    description: field.string({
+      isOptional: true,
+      description: "Detailed description"
+    }),
+    version: field.int({
+      default: 1,
+      description: "Version number for versioning definitions"
+    }),
+    status: field.enum("WorkflowStatus", { default: "DRAFT" }),
+    triggerType: field.enum("WorkflowTriggerType", { default: "MANUAL" }),
+    triggerConfig: field.json({
+      isOptional: true,
+      description: "Trigger-specific configuration"
+    }),
+    initialStepId: field.string({
+      isOptional: true,
+      description: "First step when workflow starts"
+    }),
+    featureFlagKey: field.string({
+      isOptional: true,
+      description: "Feature flag to control availability"
+    }),
+    settings: field.json({
+      isOptional: true,
+      description: "Workflow-wide settings"
+    }),
+    metadata: field.json({ isOptional: true, description: "Custom metadata" }),
+    organizationId: field.foreignKey({ description: "Owning organization" }),
+    createdBy: field.foreignKey({
+      description: "User who created this workflow"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    publishedAt: field.dateTime({
+      isOptional: true,
+      description: "When workflow was activated"
+    }),
+    steps: field.hasMany("WorkflowStep"),
+    instances: field.hasMany("WorkflowInstance")
+  },
+  indexes: [
+    index.unique(["organizationId", "key", "version"]),
+    index.on(["organizationId", "status"]),
+    index.on(["key", "version"])
+  ],
+  enums: [WorkflowStatusEnum, WorkflowTriggerTypeEnum]
+});
+export {
+  WorkflowTriggerTypeEnum,
+  WorkflowStatusEnum,
+  WorkflowDefinitionEntity
+};

package/dist/browser/example.js

@@ -0,0 +1,42 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "workflow-system",
+    version: "1.0.0",
+    title: "Workflow / Approval System",
+    description: "State-machine driven approvals with RBAC, audit trail, notifications, and jobs.",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["workflow", "approval", "state-machine", "rbac"]
+  },
+  docs: {
+    rootDocId: "docs.examples.workflow-system",
+    goalDocId: "docs.examples.workflow-system.goal",
+    usageDocId: "docs.examples.workflow-system.usage",
+    constraintsDocId: "docs.examples.workflow-system.constraints"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.workflow-system",
+    feature: "./feature",
+    contracts: "./contracts",
+    presentations: "./presentations",
+    handlers: "./handlers",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ["playground", "specs", "builder", "markdown", "evolution"]
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/browser/handlers/index.js

@@ -0,0 +1,253 @@
+// src/handlers/workflow.handlers.ts
+import { web } from "@contractspec/lib.runtime-sandbox";
+var { generateId } = web;
+function rowToDefinition(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    type: row.type,
+    status: row.status,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function rowToStep(row) {
+  return {
+    id: row.id,
+    definitionId: row.definitionId,
+    name: row.name,
+    description: row.description ?? undefined,
+    stepOrder: row.stepOrder,
+    type: row.type,
+    requiredRoles: row.requiredRoles ? JSON.parse(row.requiredRoles) : [],
+    autoApproveCondition: row.autoApproveCondition ?? undefined,
+    timeoutHours: row.timeoutHours ?? undefined,
+    createdAt: new Date(row.createdAt)
+  };
+}
+function rowToInstance(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    definitionId: row.definitionId,
+    status: row.status,
+    currentStepId: row.currentStepId ?? undefined,
+    data: row.data ? JSON.parse(row.data) : undefined,
+    requestedBy: row.requestedBy,
+    startedAt: new Date(row.startedAt),
+    completedAt: row.completedAt ? new Date(row.completedAt) : undefined
+  };
+}
+function rowToApproval(row) {
+  return {
+    id: row.id,
+    instanceId: row.instanceId,
+    stepId: row.stepId,
+    status: row.status,
+    actorId: row.actorId ?? undefined,
+    comment: row.comment ?? undefined,
+    decidedAt: row.decidedAt ? new Date(row.decidedAt) : undefined,
+    createdAt: new Date(row.createdAt)
+  };
+}
+function createWorkflowHandlers(db) {
+  async function listDefinitions(input) {
+    const { projectId, status, search, limit = 20, offset = 0 } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (status && status !== "all") {
+      whereClause += " AND status = ?";
+      params.push(status);
+    }
+    if (search) {
+      whereClause += " AND name LIKE ?";
+      params.push(`%${search}%`);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM workflow_definition ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM workflow_definition ${whereClause} ORDER BY updatedAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      definitions: rows.map(rowToDefinition),
+      total
+    };
+  }
+  async function createDefinition(input, context) {
+    const id = generateId("wfdef");
+    const now = new Date().toISOString();
+    await db.execute(`INSERT INTO workflow_definition (id, projectId, organizationId, name, description, type, status, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      context.projectId,
+      context.organizationId,
+      input.name,
+      input.description ?? null,
+      input.type ?? "APPROVAL",
+      "DRAFT",
+      now,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM workflow_definition WHERE id = ?`, [id])).rows;
+    return rowToDefinition(rows[0]);
+  }
+  async function addStep(input) {
+    const id = generateId("wfstep");
+    const now = new Date().toISOString();
+    const maxOrderResult = (await db.query(`SELECT MAX(stepOrder) as maxOrder FROM workflow_step WHERE definitionId = ?`, [input.definitionId])).rows;
+    const nextOrder = (maxOrderResult[0]?.maxOrder ?? 0) + 1;
+    await db.execute(`INSERT INTO workflow_step (id, definitionId, name, description, stepOrder, type, requiredRoles, autoApproveCondition, timeoutHours, createdAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      input.definitionId,
+      input.name,
+      input.description ?? null,
+      nextOrder,
+      input.type ?? "APPROVAL",
+      JSON.stringify(input.requiredRoles),
+      input.autoApproveCondition ?? null,
+      input.timeoutHours ?? null,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM workflow_step WHERE id = ?`, [id])).rows;
+    return rowToStep(rows[0]);
+  }
+  async function getSteps(definitionId) {
+    const rows = (await db.query(`SELECT * FROM workflow_step WHERE definitionId = ? ORDER BY stepOrder`, [definitionId])).rows;
+    return rows.map(rowToStep);
+  }
+  async function listInstances(input) {
+    const {
+      projectId,
+      definitionId,
+      status,
+      requestedBy,
+      limit = 20,
+      offset = 0
+    } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (definitionId) {
+      whereClause += " AND definitionId = ?";
+      params.push(definitionId);
+    }
+    if (status && status !== "all") {
+      whereClause += " AND status = ?";
+      params.push(status);
+    }
+    if (requestedBy) {
+      whereClause += " AND requestedBy = ?";
+      params.push(requestedBy);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM workflow_instance ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM workflow_instance ${whereClause} ORDER BY startedAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      instances: rows.map(rowToInstance),
+      total
+    };
+  }
+  async function startInstance(input, context) {
+    const id = generateId("wfinst");
+    const now = new Date().toISOString();
+    const steps = (await db.query(`SELECT * FROM workflow_step WHERE definitionId = ? ORDER BY stepOrder LIMIT 1`, [input.definitionId])).rows;
+    const firstStepId = steps[0]?.id ?? null;
+    await db.execute(`INSERT INTO workflow_instance (id, projectId, definitionId, status, currentStepId, data, requestedBy, startedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      context.projectId,
+      input.definitionId,
+      firstStepId ? "IN_PROGRESS" : "PENDING",
+      firstStepId,
+      input.data ? JSON.stringify(input.data) : null,
+      context.requestedBy,
+      now
+    ]);
+    if (firstStepId) {
+      await db.execute(`INSERT INTO workflow_approval (id, instanceId, stepId, status, createdAt)
+         VALUES (?, ?, ?, ?, ?)`, [generateId("wfappr"), id, firstStepId, "PENDING", now]);
+    }
+    const rows = (await db.query(`SELECT * FROM workflow_instance WHERE id = ?`, [id])).rows;
+    return rowToInstance(rows[0]);
+  }
+  async function approveStep(input, context) {
+    const now = new Date().toISOString();
+    const instances = (await db.query(`SELECT * FROM workflow_instance WHERE id = ?`, [
+      input.instanceId
+    ])).rows;
+    if (!instances[0]) {
+      throw new Error("NOT_FOUND");
+    }
+    const instance = instances[0];
+    await db.execute(`UPDATE workflow_approval SET status = 'APPROVED', actorId = ?, comment = ?, decidedAt = ? 
+       WHERE instanceId = ? AND stepId = ? AND status = 'PENDING'`, [
+      context.actorId,
+      input.comment ?? null,
+      now,
+      input.instanceId,
+      instance.currentStepId
+    ]);
+    const currentStep = (await db.query(`SELECT * FROM workflow_step WHERE id = ?`, [
+      instance.currentStepId
+    ])).rows;
+    const nextSteps = (await db.query(`SELECT * FROM workflow_step WHERE definitionId = ? AND stepOrder > ? ORDER BY stepOrder LIMIT 1`, [instance.definitionId, currentStep[0]?.stepOrder ?? 0])).rows;
+    if (nextSteps[0]) {
+      await db.execute(`UPDATE workflow_instance SET currentStepId = ? WHERE id = ?`, [nextSteps[0].id, input.instanceId]);
+      await db.execute(`INSERT INTO workflow_approval (id, instanceId, stepId, status, createdAt)
+         VALUES (?, ?, ?, ?, ?)`, [
+        generateId("wfappr"),
+        input.instanceId,
+        nextSteps[0].id,
+        "PENDING",
+        now
+      ]);
+    } else {
+      await db.execute(`UPDATE workflow_instance SET status = 'COMPLETED', currentStepId = NULL, completedAt = ? WHERE id = ?`, [now, input.instanceId]);
+    }
+    const updated = (await db.query(`SELECT * FROM workflow_instance WHERE id = ?`, [
+      input.instanceId
+    ])).rows;
+    return rowToInstance(updated[0]);
+  }
+  async function rejectStep(input, context) {
+    const now = new Date().toISOString();
+    const instances = (await db.query(`SELECT * FROM workflow_instance WHERE id = ?`, [
+      input.instanceId
+    ])).rows;
+    if (!instances[0]) {
+      throw new Error("NOT_FOUND");
+    }
+    await db.execute(`UPDATE workflow_approval SET status = 'REJECTED', actorId = ?, comment = ?, decidedAt = ? 
+       WHERE instanceId = ? AND stepId = ? AND status = 'PENDING'`, [
+      context.actorId,
+      input.reason,
+      now,
+      input.instanceId,
+      instances[0].currentStepId
+    ]);
+    await db.execute(`UPDATE workflow_instance SET status = 'REJECTED', completedAt = ? WHERE id = ?`, [now, input.instanceId]);
+    const updated = (await db.query(`SELECT * FROM workflow_instance WHERE id = ?`, [
+      input.instanceId
+    ])).rows;
+    return rowToInstance(updated[0]);
+  }
+  async function getApprovals(instanceId) {
+    const rows = (await db.query(`SELECT * FROM workflow_approval WHERE instanceId = ? ORDER BY createdAt`, [instanceId])).rows;
+    return rows.map(rowToApproval);
+  }
+  return {
+    listDefinitions,
+    createDefinition,
+    addStep,
+    getSteps,
+    listInstances,
+    startInstance,
+    approveStep,
+    rejectStep,
+    getApprovals
+  };
+}
+export {
+  createWorkflowHandlers
+};