[fix.dirac.Ω.D9+] keep the live twin watcher honest

WHY: Real service restart exposed inotify exhaustion that the offline scope selftest could not see, and missing scientific prerequisites were still presented as runtime failure. Replace recursive watchers with Git-aware content polling, prove automatic file/function add and remove on the live service, and report prerequisite refusals as Needs Context.

Author: ivanicu

scripts/build_digital_twin.py

@@ -599,7 +599,7 @@ def add_system_and_flows(twin: Twin) -> None:
                   ('object-kind:program_snapshot', 'returns the evidence state to the Program')])
     twin.flow('source-sync', 'Automatic source synchronization',
               'Every in-scope first-party file change regenerates structural nodes, references, diagnostics and the offline twin.', [
-                  ('service:twin-watcher', 'observes recursive first-party roots'),
+                  ('service:twin-watcher', 'polls Git-aware first-party content'),
                   ('system:file-discovery', 'enumerates tracked and untracked files from ownership policy'),
                   ('store:twin-model', 'replaces JSON and embedded HTML atomically at generation completion')])
 
@@ -917,7 +917,7 @@ def architecture_analysis(twin: Twin, ts_data: dict, runtime: dict) -> dict:
                 'runtime_metrics_available': runtime_sync,
             },
             'is_continuously_synchronized': source_sync,
-            'synchronization': ('recursive source events with runtime captured at each rebuild; source and '
+            'synchronization': ('Git-aware content polling with runtime captured at each rebuild; source and '
                                 'telemetry freshness are reported separately'),
             'source_sync': 'continuous while dirac-digital-twin.service is active',
             'runtime_sync': 'snapshot on every source-triggered or manual twin rebuild',

scripts/watch_digital_twin.mjs

@@ -2,15 +2,15 @@
 /** Continuously regenerate the Dirac Architecture Optimization Twin on source changes. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { execFileSync, spawn } from 'node:child_process';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 const scope = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts/digital_twin_scope.json'), 'utf8'));
 const rootFiles = new Set(scope.include_root_files);
 const roots = scope.include_roots.map(x => x.replace(/\/$/, ''));
 const externalRoots = scope.external_roots.map(x => x.replace(/\/$/, ''));
 const outputs = new Set(scope.generated_outputs);
-const watched = new Map();
 let timer;
 let running = false;
 let rerun = false;
@@ -59,47 +59,31 @@ function schedule(reason) {
     timer = setTimeout(() => build(reason), 900);
 }
 
-function observed(base, filename) {
-    if (!filename) return;
-    const rel = normalized(path.relative(ROOT, path.join(base, filename.toString())));
-    if (!inScope(rel)) return;
-    changed.add(rel);
-    schedule('source change');
-}
-
-function watchDirectory(absolute) {
-    if (watched.has(absolute) || !fs.existsSync(absolute)) return;
-    const watcher = fs.watch(absolute, { recursive: true }, (_event, filename) => observed(absolute, filename));
-    watcher.on('error', () => {
-        watcher.close();
-        watched.delete(absolute);
+function sourceFiles() {
+    const raw = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
+        cwd: ROOT, encoding: 'buffer', maxBuffer: 32 * 1024 * 1024,
     });
-    watched.set(absolute, watcher);
+    return raw.toString().split('\0').filter(Boolean).map(normalized).filter(inScope).sort();
 }
 
-function watchChildren(parent, parentRel) {
-    const key = `${parent}:children`;
-    if (watched.has(key) || !fs.existsSync(parent)) return;
-    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const rel = normalized(`${parentRel}/${entry.name}`);
-        if (!externalRoots.some(root => rel === root || rel.startsWith(`${root}/`))) {
-            watchDirectory(path.join(parent, entry.name));
+function sourceState() {
+    const state = new Map();
+    for (const rel of sourceFiles()) {
+        try {
+            const absolute = path.join(ROOT, rel);
+            if (!fs.statSync(absolute).isFile()) continue;
+            const digest = createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+            state.set(rel, digest);
+        } catch (error) {
+            if (error?.code !== 'ENOENT') throw error;
         }
     }
-    const watcher = fs.watch(parent, (_event, filename) => {
-        if (!filename) return;
-        const name = filename.toString();
-        const rel = normalized(`${parentRel}/${name}`);
-        const absolute = path.join(parent, name);
-        const external = externalRoots.some(root => rel === root || rel.startsWith(`${root}/`));
-        if (fs.existsSync(absolute) && fs.statSync(absolute).isDirectory() && !external) {
-            watchDirectory(absolute);
-        } else if (inScope(rel)) {
-            observed(parent, filename);
-        }
-    });
-    watched.set(key, watcher);
+    return state;
+}
+
+function changedFiles(previous, current) {
+    const paths = new Set([...previous.keys(), ...current.keys()]);
+    return [...paths].filter(rel => previous.get(rel) !== current.get(rel)).sort();
 }
 
 if (process.argv.includes('--selftest')) {
@@ -111,37 +95,28 @@ if (process.argv.includes('--selftest')) {
         process.stderr.write(`${JSON.stringify(verdicts)}\n`);
         process.exit(1);
     }
-    process.stdout.write(`watch scope OK · ${roots.length} first-party roots · upstream and generated outputs excluded\n`);
+    const discovered = sourceState().size;
+    if (!discovered) throw new Error('source poller discovered no first-party files');
+    process.stdout.write(`watch scope OK · ${roots.length} first-party roots · ${discovered} files polled · upstream and generated outputs excluded\n`);
     process.exit(0);
 }
 
 if (process.argv.includes('--once')) {
     build('one-shot synchronization');
 } else {
+    let baseline = sourceState();
     build();
-    for (const root of roots) watchDirectory(path.join(ROOT, root));
-    for (const entry of fs.readdirSync(ROOT, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        if (entry.name === 'src') {
-            watchChildren(path.join(ROOT, 'src'), 'src');
-            continue;
-        }
-        if (externalRoots.includes(entry.name)) continue;
-        watchDirectory(path.join(ROOT, entry.name));
-    }
-    fs.watch(ROOT, (_event, filename) => {
-        if (!filename) return;
-        const name = filename.toString();
-        const absolute = path.join(ROOT, name);
-        if (!fs.existsSync(absolute) && watched.has(absolute)) {
-            watched.get(absolute).close();
-            watched.delete(absolute);
+    setInterval(() => {
+        try {
+            const current = sourceState();
+            const updates = changedFiles(baseline, current);
+            baseline = current;
+            if (!updates.length) return;
+            for (const rel of updates) changed.add(rel);
+            schedule('source change');
+        } catch (error) {
+            process.stderr.write(`[${new Date().toISOString()}] source poll failed · ${error.message}\n`);
         }
-        if (fs.existsSync(absolute) && fs.statSync(absolute).isDirectory()
-            && !externalRoots.some(root => name === root || root.startsWith(`${name}/`))) {
-            watchDirectory(absolute);
-        }
-        if (rootFiles.has(name) || inScope(name)) observed(ROOT, filename);
-    });
-    process.stdout.write(`watching ${roots.length} first-party roots · debounce 900 ms · runtime captured on rebuild\n`);
+    }, 2_000);
+    process.stdout.write(`polling ${baseline.size} first-party files · interval 2 s · debounce 900 ms · runtime captured on rebuild\n`);
 }