feat(vinculum): build CLI pipeline and fix cycle detection logic

Author: COMMENCINGTHESCOURGE

docs/vinculum-spec.md

@@ -25,13 +25,14 @@ modules:
     shader: "src/compute/diffusion.wgsl"
     reads: [rock, soil, sand, water, ice, organic]
     writes: [soil, sand]
+    requires: [advection]
     flux_producer: false
 
   semi_implicit_conservation:
     shader: "src/compute/semi_implicit_conservation.wgsl"
     reads: [water, sand]  # minimal: only channels that were written
     writes: [water, sand, soil, rock, ice, organic]  # renormalization touches all
-    requires: [advection]  # must run after any flux_producer
+    requires: [advection, diffusion]  # must run after any flux_producer and modifiers
     injection_rule: "auto-on-write"  # compiler injects when water/sand are mutated
 
   qef_extract:

scripts/manifold-build.ts

@@ -0,0 +1,27 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import * as path from 'path';
+import { VinculumCompiler } from '../src/compiler/vinculum-compiler';
+
+const specPath = path.resolve(process.cwd(), 'docs/vinculum-spec.md');
+const outPath = path.resolve(process.cwd(), 'src/dispatchSequence.ts');
+
+try {
+    const fileContents = fs.readFileSync(specPath, 'utf8');
+    // Extract yaml from markdown code blocks or just parse directly if it's pure yaml.
+    // Our spec has some markdown. Let's try to parse the whole thing, or strip markdown.
+    const yamlMatch = fileContents.match(/```yaml\n([\s\S]*?)\n```/);
+    const yamlString = yamlMatch ? yamlMatch[1] : fileContents;
+
+    const spec = yaml.load(yamlString) as any;
+    
+    console.log("Compiling Vinculum Dependency Graph...");
+    const compiler = new VinculumCompiler(spec);
+    const code = compiler.generateDispatchCode();
+    
+    fs.writeFileSync(outPath, code, 'utf8');
+    console.log(`Successfully generated ${outPath}`);
+} catch (e) {
+    console.error("Vinculum Compilation Failed:", e);
+    process.exit(1);
+}

src/compiler/vinculum-compiler.ts

@@ -11,6 +11,7 @@ interface VinculumModule {
 
 interface VinculumSpec {
   version: string;
+  engine: string;
   channels: string[];
   modules: Record<string, VinculumModule>;
   compiler: {
@@ -35,9 +36,10 @@ export class VinculumCompiler {
       this.dag.set(name, new Set(mod.requires || []));
       // Auto-inject conservation if flux_producer writes water/sand
       if (mod.flux_producer && (mod.writes.includes('water') || mod.writes.includes('sand'))) {
-        if (!mod.requires?.includes('semi_implicit_conservation')) {
-          mod.requires = [...(mod.requires || []), 'semi_implicit_conservation'];
-          this.dag.set(name, new Set(mod.requires));
+        const consMod = this.spec.modules['semi_implicit_conservation'];
+        if (consMod && !consMod.requires?.includes(name)) {
+          consMod.requires = [...(consMod.requires || []), name];
+          this.dag.set('semi_implicit_conservation', new Set(consMod.requires));
         }
       }
     }
@@ -93,18 +95,36 @@ export class VinculumCompiler {
 
     // Generate WebGPU dispatch sequence
     let code = `// Auto-generated by Vinculum Compiler v${this.spec.version}\n`;
-    code += `const dispatchSequence = [\n`;
+    code += `// Pipeline: ${this.spec.engine}\n\n`;
+    code += `export const dispatchSequence = [\n`;
+    
+    let currentState = 'state_A';
 
     for (const modName of order) {
       const mod = this.spec.modules[modName];
-      code += `  { name: '${modName}', shader: '${mod.shader}', binds: this.setupBindGroup('${modName}') },\n`;
+      const mutatesState = mod.writes && mod.writes.length > 0;
+      
+      let inputBuffer = currentState;
+      let outputBuffer = currentState;
+      
+      if (mutatesState) {
+          outputBuffer = currentState === 'state_A' ? 'state_B' : 'state_A';
+          currentState = outputBuffer; // state flips for next read
+      }
+
+      code += `  {\n`;
+      code += `    name: '${modName}',\n`;
+      code += `    shader: '${mod.shader}',\n`;
+      code += `    bufferRoles: { input: '${inputBuffer}', output: '${outputBuffer}' },\n`;
+      code += `    binds: () => setupBindGroup('${modName}')\n`;
+      code += `  },\n`;
     }
-    code += `];\n`;
+    code += `];\n\n`;
 
     // Inject adaptive substep hint if high-flux modules present
-    if (this.spec.compiler.injection.substep_hint === 'high-flux') {
+    if (this.spec.compiler?.injection?.substep_hint === 'high-flux') {
       code += `// Hint: enable adaptive substepping for high-flux modules\n`;
-      code += `simulationParams.substepThreshold = 0.05;\n`;
+      code += `export const recommendedSubstepThreshold = 0.05;\n`;
     }
 
     return code;
@@ -116,24 +136,35 @@ export class VinculumCompiler {
     const result: string[] = [];
     const queue: string[] = [];
 
+    console.log("DAG contents:");
+    for (const [mod, deps] of this.dag.entries()) {
+        console.log(`${mod} requires:`, Array.from(deps));
+    }
+
     // Initialize in-degrees
     for (const mod of Object.keys(this.spec.modules)) {
       inDegree.set(mod, 0);
     }
-    for (const deps of this.dag.values()) {
+    // If mod requires dep, edge is dep -> mod. 
+    // So mod's inDegree increases.
+    for (const [mod, deps] of this.dag) {
       for (const dep of deps) {
-        inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
+        // If a required dependency isn't in modules, skip or initialize
+        if (inDegree.has(dep)) {
+          inDegree.set(mod, (inDegree.get(mod) || 0) + 1);
+        }
       }
     }
 
-    // Start with nodes that have no dependencies
+    // Start with nodes that have no dependencies (inDegree = 0)
     for (const [mod, deg] of inDegree) {
       if (deg === 0) queue.push(mod);
     }
 
     while (queue.length) {
       const curr = queue.shift()!;
       result.push(curr);
+      // curr just executed. Find any mod that requires curr, and decrement its inDegree.
       for (const [mod, deps] of this.dag) {
         if (deps.has(curr)) {
           inDegree.set(mod, inDegree.get(mod)! - 1);

src/dispatchSequence.ts

@@ -0,0 +1,32 @@
+// Auto-generated by Vinculum Compiler v0.1.0
+// Pipeline: hyperpoly-terrain
+
+export const dispatchSequence = [
+  {
+    name: 'advection',
+    shader: 'src/compute/advection.wgsl',
+    bufferRoles: { input: 'state_A', output: 'state_B' },
+    binds: () => setupBindGroup('advection')
+  },
+  {
+    name: 'qef_extract',
+    shader: 'src/compute/qef_solve.wgsl',
+    bufferRoles: { input: 'state_B', output: 'state_B' },
+    binds: () => setupBindGroup('qef_extract')
+  },
+  {
+    name: 'diffusion',
+    shader: 'src/compute/diffusion.wgsl',
+    bufferRoles: { input: 'state_B', output: 'state_A' },
+    binds: () => setupBindGroup('diffusion')
+  },
+  {
+    name: 'semi_implicit_conservation',
+    shader: 'src/compute/semi_implicit_conservation.wgsl',
+    bufferRoles: { input: 'state_A', output: 'state_B' },
+    binds: () => setupBindGroup('semi_implicit_conservation')
+  },
+];
+
+// Hint: enable adaptive substepping for high-flux modules
+export const recommendedSubstepThreshold = 0.05;

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "commonjs",
+    "rootDir": "./",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": false,
+    "skipLibCheck": true
+  }
+}