@driftgate/workflow-compiler 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+
+declare const WorkflowYamlSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"driftgate.ai/v1">;
+    kind: z.ZodLiteral<"Workflow">;
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        workspace: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        workspace: string;
+    }, {
+        name: string;
+        workspace: string;
+    }>;
+    spec: z.ZodObject<{
+        governance: z.ZodDefault<z.ZodObject<{
+            policyBindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                policyId: z.ZodString;
+                mode: z.ZodDefault<z.ZodEnum<["monitor", "enforce"]>>;
+            }, "strip", z.ZodTypeAny, {
+                policyId: string;
+                mode: "monitor" | "enforce";
+            }, {
+                policyId: string;
+                mode?: "monitor" | "enforce" | undefined;
+            }>, "many">>;
+            slaBindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                slaId: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                slaId: string;
+            }, {
+                slaId: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            policyBindings: {
+                policyId: string;
+                mode: "monitor" | "enforce";
+            }[];
+            slaBindings: {
+                slaId: string;
+            }[];
+        }, {
+            policyBindings?: {
+                policyId: string;
+                mode?: "monitor" | "enforce" | undefined;
+            }[] | undefined;
+            slaBindings?: {
+                slaId: string;
+            }[] | undefined;
+        }>>;
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+            mutation: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            config: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            id: string;
+            mutation: boolean;
+            config: Record<string, unknown>;
+        }, {
+            type: string;
+            id: string;
+            mutation?: boolean | undefined;
+            config?: Record<string, unknown> | undefined;
+        }>, "many">;
+        edges: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            from: string;
+            to: string;
+        }, {
+            from: string;
+            to: string;
+        }>, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        governance: {
+            policyBindings: {
+                policyId: string;
+                mode: "monitor" | "enforce";
+            }[];
+            slaBindings: {
+                slaId: string;
+            }[];
+        };
+        nodes: {
+            type: string;
+            id: string;
+            mutation: boolean;
+            config: Record<string, unknown>;
+        }[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+    }, {
+        nodes: {
+            type: string;
+            id: string;
+            mutation?: boolean | undefined;
+            config?: Record<string, unknown> | undefined;
+        }[];
+        governance?: {
+            policyBindings?: {
+                policyId: string;
+                mode?: "monitor" | "enforce" | undefined;
+            }[] | undefined;
+            slaBindings?: {
+                slaId: string;
+            }[] | undefined;
+        } | undefined;
+        edges?: {
+            from: string;
+            to: string;
+        }[] | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    apiVersion: "driftgate.ai/v1";
+    kind: "Workflow";
+    metadata: {
+        name: string;
+        workspace: string;
+    };
+    spec: {
+        governance: {
+            policyBindings: {
+                policyId: string;
+                mode: "monitor" | "enforce";
+            }[];
+            slaBindings: {
+                slaId: string;
+            }[];
+        };
+        nodes: {
+            type: string;
+            id: string;
+            mutation: boolean;
+            config: Record<string, unknown>;
+        }[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+    };
+}, {
+    apiVersion: "driftgate.ai/v1";
+    kind: "Workflow";
+    metadata: {
+        name: string;
+        workspace: string;
+    };
+    spec: {
+        nodes: {
+            type: string;
+            id: string;
+            mutation?: boolean | undefined;
+            config?: Record<string, unknown> | undefined;
+        }[];
+        governance?: {
+            policyBindings?: {
+                policyId: string;
+                mode?: "monitor" | "enforce" | undefined;
+            }[] | undefined;
+            slaBindings?: {
+                slaId: string;
+            }[] | undefined;
+        } | undefined;
+        edges?: {
+            from: string;
+            to: string;
+        }[] | undefined;
+    };
+}>;
+type WorkflowYaml = z.infer<typeof WorkflowYamlSchema>;
+
+type CompiledWorkflow = {
+    workflow: WorkflowYaml;
+    compiledPlan: {
+        metadata: WorkflowYaml["metadata"];
+        governance: WorkflowYaml["spec"]["governance"];
+        nodes: Array<{
+            id: string;
+            type: string;
+            mutation: boolean;
+            config: Record<string, unknown>;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+    };
+    mutationNodeIds: string[];
+    checksum: string;
+};
+declare function compileWorkflowYaml(yamlText: string): CompiledWorkflow;
+
+export { type CompiledWorkflow, type WorkflowYaml, WorkflowYamlSchema, compileWorkflowYaml };

package/dist/index.js

@@ -0,0 +1,103 @@
+// src/schema.ts
+import { z } from "zod";
+var MetadataSchema = z.object({
+  name: z.string().min(1),
+  workspace: z.string().min(1)
+});
+var PolicyBindingSchema = z.object({
+  policyId: z.string().min(1),
+  mode: z.enum(["monitor", "enforce"]).default("enforce")
+});
+var SlaBindingSchema = z.object({
+  slaId: z.string().min(1)
+});
+var NodeSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().min(1),
+  mutation: z.boolean().optional().default(false),
+  config: z.record(z.unknown()).optional().default({})
+});
+var EdgeSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1)
+});
+var WorkflowYamlSchema = z.object({
+  apiVersion: z.literal("driftgate.ai/v1"),
+  kind: z.literal("Workflow"),
+  metadata: MetadataSchema,
+  spec: z.object({
+    governance: z.object({
+      policyBindings: z.array(PolicyBindingSchema).default([]),
+      slaBindings: z.array(SlaBindingSchema).default([])
+    }).default({ policyBindings: [], slaBindings: [] }),
+    nodes: z.array(NodeSchema).min(1),
+    edges: z.array(EdgeSchema).optional().default([])
+  })
+});
+
+// src/compiler.ts
+import { createHash } from "crypto";
+import { parse } from "yaml";
+function stableStringify(value) {
+  return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortValue(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const objectValue = value;
+  const sortedKeys = Object.keys(objectValue).sort((left, right) => left.localeCompare(right));
+  const next = {};
+  for (const key of sortedKeys) {
+    next[key] = sortValue(objectValue[key]);
+  }
+  return next;
+}
+function assertValidReferences(workflow) {
+  const nodeIds = new Set(workflow.spec.nodes.map((node) => node.id));
+  for (const edge of workflow.spec.edges) {
+    if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {
+      throw new Error(`invalid edge reference: ${edge.from} -> ${edge.to}`);
+    }
+  }
+}
+function compileWorkflowYaml(yamlText) {
+  const parsed = parse(yamlText);
+  const workflow = WorkflowYamlSchema.parse(parsed);
+  assertValidReferences(workflow);
+  const nodes = [...workflow.spec.nodes].sort((left, right) => left.id.localeCompare(right.id));
+  const edges = [...workflow.spec.edges].sort((left, right) => {
+    const fromOrder = left.from.localeCompare(right.from);
+    if (fromOrder !== 0) {
+      return fromOrder;
+    }
+    return left.to.localeCompare(right.to);
+  });
+  const compiledPlan = {
+    metadata: workflow.metadata,
+    governance: workflow.spec.governance,
+    nodes: nodes.map((node) => ({
+      id: node.id,
+      type: node.type,
+      mutation: Boolean(node.mutation),
+      config: node.config ?? {}
+    })),
+    edges
+  };
+  const mutationNodeIds = compiledPlan.nodes.filter((node) => node.mutation).map((node) => node.id).sort((left, right) => left.localeCompare(right));
+  const checksum = createHash("sha256").update(stableStringify(compiledPlan)).digest("hex");
+  return {
+    workflow,
+    compiledPlan,
+    mutationNodeIds,
+    checksum
+  };
+}
+export {
+  WorkflowYamlSchema,
+  compileWorkflowYaml
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/compiler.ts"],"sourcesContent":["import { z } from \"zod\";\n\nconst MetadataSchema = z.object({\n  name: z.string().min(1),\n  workspace: z.string().min(1)\n});\n\nconst PolicyBindingSchema = z.object({\n  policyId: z.string().min(1),\n  mode: z.enum([\"monitor\", \"enforce\"]).default(\"enforce\")\n});\n\nconst SlaBindingSchema = z.object({\n  slaId: z.string().min(1)\n});\n\nconst NodeSchema = z.object({\n  id: z.string().min(1),\n  type: z.string().min(1),\n  mutation: z.boolean().optional().default(false),\n  config: z.record(z.unknown()).optional().default({})\n});\n\nconst EdgeSchema = z.object({\n  from: z.string().min(1),\n  to: z.string().min(1)\n});\n\nexport const WorkflowYamlSchema = z.object({\n  apiVersion: z.literal(\"driftgate.ai/v1\"),\n  kind: z.literal(\"Workflow\"),\n  metadata: MetadataSchema,\n  spec: z.object({\n    governance: z\n      .object({\n        policyBindings: z.array(PolicyBindingSchema).default([]),\n        slaBindings: z.array(SlaBindingSchema).default([])\n      })\n      .default({ policyBindings: [], slaBindings: [] }),\n    nodes: z.array(NodeSchema).min(1),\n    edges: z.array(EdgeSchema).optional().default([])\n  })\n});\n\nexport type WorkflowYaml = z.infer<typeof WorkflowYamlSchema>;\n","import { createHash } from \"node:crypto\";\nimport { parse } from \"yaml\";\nimport { WorkflowYamlSchema, type WorkflowYaml } from \"./schema.ts\";\n\nexport type CompiledWorkflow = {\n  workflow: WorkflowYaml;\n  compiledPlan: {\n    metadata: WorkflowYaml[\"metadata\"];\n    governance: WorkflowYaml[\"spec\"][\"governance\"];\n    nodes: Array<{\n      id: string;\n      type: string;\n      mutation: boolean;\n      config: Record<string, unknown>;\n    }>;\n    edges: Array<{ from: string; to: string }>;\n  };\n  mutationNodeIds: string[];\n  checksum: string;\n};\n\nfunction stableStringify(value: unknown): string {\n  return JSON.stringify(sortValue(value));\n}\n\nfunction sortValue(value: unknown): unknown {\n  if (Array.isArray(value)) {\n    return value.map((item) => sortValue(item));\n  }\n  if (!value || typeof value !== \"object\") {\n    return value;\n  }\n  const objectValue = value as Record<string, unknown>;\n  const sortedKeys = Object.keys(objectValue).sort((left, right) => left.localeCompare(right));\n  const next: Record<string, unknown> = {};\n  for (const key of sortedKeys) {\n    next[key] = sortValue(objectValue[key]);\n  }\n  return next;\n}\n\nfunction assertValidReferences(workflow: WorkflowYaml): void {\n  const nodeIds = new Set(workflow.spec.nodes.map((node) => node.id));\n  for (const edge of workflow.spec.edges) {\n    if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {\n      throw new Error(`invalid edge reference: ${edge.from} -> ${edge.to}`);\n    }\n  }\n}\n\nexport function compileWorkflowYaml(yamlText: string): CompiledWorkflow {\n  const parsed = parse(yamlText);\n  const workflow = WorkflowYamlSchema.parse(parsed);\n  assertValidReferences(workflow);\n\n  const nodes = [...workflow.spec.nodes].sort((left, right) => left.id.localeCompare(right.id));\n  const edges = [...workflow.spec.edges].sort((left, right) => {\n    const fromOrder = left.from.localeCompare(right.from);\n    if (fromOrder !== 0) {\n      return fromOrder;\n    }\n    return left.to.localeCompare(right.to);\n  });\n\n  const compiledPlan = {\n    metadata: workflow.metadata,\n    governance: workflow.spec.governance,\n    nodes: nodes.map((node) => ({\n      id: node.id,\n      type: node.type,\n      mutation: Boolean(node.mutation),\n      config: node.config ?? {}\n    })),\n    edges\n  };\n\n  const mutationNodeIds = compiledPlan.nodes\n    .filter((node) => node.mutation)\n    .map((node) => node.id)\n    .sort((left, right) => left.localeCompare(right));\n\n  const checksum = createHash(\"sha256\").update(stableStringify(compiledPlan)).digest(\"hex\");\n\n  return {\n    workflow,\n    compiledPlan,\n    mutationNodeIds,\n    checksum\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@driftgate/workflow-compiler",
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "description": "Workflow YAML compiler for DriftGate runtime.",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/driftgate/driftgate-sdk.git"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --target node20 --dts --sourcemap --clean --tsconfig tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "zod": "^3.23.8"
+  }
+}

package/src/compiler.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { compileWorkflowYaml } from "./compiler.ts";
+
+const workflowYaml = `
+apiVersion: driftgate.ai/v1
+kind: Workflow
+metadata:
+  name: refund-agent
+  workspace: acme-payments
+spec:
+  governance:
+    policyBindings:
+      - policyId: pol_refunds
+        mode: enforce
+    slaBindings:
+      - slaId: sla_default
+  nodes:
+    - id: fetch_order
+      type: http
+      config:
+        path: /orders/:id
+    - id: decide_refund
+      type: llm
+    - id: issue_refund
+      type: http
+      mutation: true
+  edges:
+    - from: fetch_order
+      to: decide_refund
+    - from: decide_refund
+      to: issue_refund
+`;
+
+test("compiler is deterministic for stable input", () => {
+  const first = compileWorkflowYaml(workflowYaml);
+  const second = compileWorkflowYaml(workflowYaml);
+  assert.equal(first.checksum, second.checksum);
+  assert.deepEqual(first.compiledPlan, second.compiledPlan);
+});
+
+test("compiler detects mutation nodes", () => {
+  const compiled = compileWorkflowYaml(workflowYaml);
+  assert.deepEqual(compiled.mutationNodeIds, ["issue_refund"]);
+});
+
+test("compiler rejects invalid edge references", () => {
+  assert.throws(() =>
+    compileWorkflowYaml(`
+apiVersion: driftgate.ai/v1
+kind: Workflow
+metadata:
+  name: broken
+  workspace: acme
+spec:
+  nodes:
+    - id: a
+      type: http
+  edges:
+    - from: a
+      to: missing
+`)
+  );
+});

package/src/compiler.ts

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { parse } from "yaml";
+import { WorkflowYamlSchema, type WorkflowYaml } from "./schema.ts";
+
+export type CompiledWorkflow = {
+  workflow: WorkflowYaml;
+  compiledPlan: {
+    metadata: WorkflowYaml["metadata"];
+    governance: WorkflowYaml["spec"]["governance"];
+    nodes: Array<{
+      id: string;
+      type: string;
+      mutation: boolean;
+      config: Record<string, unknown>;
+    }>;
+    edges: Array<{ from: string; to: string }>;
+  };
+  mutationNodeIds: string[];
+  checksum: string;
+};
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortValue(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const objectValue = value as Record<string, unknown>;
+  const sortedKeys = Object.keys(objectValue).sort((left, right) => left.localeCompare(right));
+  const next: Record<string, unknown> = {};
+  for (const key of sortedKeys) {
+    next[key] = sortValue(objectValue[key]);
+  }
+  return next;
+}
+
+function assertValidReferences(workflow: WorkflowYaml): void {
+  const nodeIds = new Set(workflow.spec.nodes.map((node) => node.id));
+  for (const edge of workflow.spec.edges) {
+    if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {
+      throw new Error(`invalid edge reference: ${edge.from} -> ${edge.to}`);
+    }
+  }
+}
+
+export function compileWorkflowYaml(yamlText: string): CompiledWorkflow {
+  const parsed = parse(yamlText);
+  const workflow = WorkflowYamlSchema.parse(parsed);
+  assertValidReferences(workflow);
+
+  const nodes = [...workflow.spec.nodes].sort((left, right) => left.id.localeCompare(right.id));
+  const edges = [...workflow.spec.edges].sort((left, right) => {
+    const fromOrder = left.from.localeCompare(right.from);
+    if (fromOrder !== 0) {
+      return fromOrder;
+    }
+    return left.to.localeCompare(right.to);
+  });
+
+  const compiledPlan = {
+    metadata: workflow.metadata,
+    governance: workflow.spec.governance,
+    nodes: nodes.map((node) => ({
+      id: node.id,
+      type: node.type,
+      mutation: Boolean(node.mutation),
+      config: node.config ?? {}
+    })),
+    edges
+  };
+
+  const mutationNodeIds = compiledPlan.nodes
+    .filter((node) => node.mutation)
+    .map((node) => node.id)
+    .sort((left, right) => left.localeCompare(right));
+
+  const checksum = createHash("sha256").update(stableStringify(compiledPlan)).digest("hex");
+
+  return {
+    workflow,
+    compiledPlan,
+    mutationNodeIds,
+    checksum
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { WorkflowYamlSchema, type WorkflowYaml } from "./schema.ts";
+export { compileWorkflowYaml, type CompiledWorkflow } from "./compiler.ts";

package/src/schema.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+const MetadataSchema = z.object({
+  name: z.string().min(1),
+  workspace: z.string().min(1)
+});
+
+const PolicyBindingSchema = z.object({
+  policyId: z.string().min(1),
+  mode: z.enum(["monitor", "enforce"]).default("enforce")
+});
+
+const SlaBindingSchema = z.object({
+  slaId: z.string().min(1)
+});
+
+const NodeSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().min(1),
+  mutation: z.boolean().optional().default(false),
+  config: z.record(z.unknown()).optional().default({})
+});
+
+const EdgeSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1)
+});
+
+export const WorkflowYamlSchema = z.object({
+  apiVersion: z.literal("driftgate.ai/v1"),
+  kind: z.literal("Workflow"),
+  metadata: MetadataSchema,
+  spec: z.object({
+    governance: z
+      .object({
+        policyBindings: z.array(PolicyBindingSchema).default([]),
+        slaBindings: z.array(SlaBindingSchema).default([])
+      })
+      .default({ policyBindings: [], slaBindings: [] }),
+    nodes: z.array(NodeSchema).min(1),
+    edges: z.array(EdgeSchema).optional().default([])
+  })
+});
+
+export type WorkflowYaml = z.infer<typeof WorkflowYamlSchema>;