@neuroverseos/governance 0.3.1 → 0.3.4

package/dist/chunk-YEKMVDWK.js

@@ -0,0 +1,624 @@
+import {
+  loadConfig
+} from "./chunk-OT6PXH54.js";
+import {
+  createProvider
+} from "./chunk-INWQHLPS.js";
+import {
+  validateWorld
+} from "./chunk-7P3S7MAY.js";
+import {
+  parseWorldMarkdown
+} from "./chunk-EMQDLDAF.js";
+import {
+  emitWorldDefinition
+} from "./chunk-PVTQQS3Y.js";
+
+// src/engine/derive-normalizer.ts
+function findSections(lines) {
+  const sections = [];
+  let current = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("# ")) {
+      if (current) {
+        current.end = i;
+        sections.push(current);
+      }
+      current = { name: lines[i].replace(/^#\s+/, "").trim(), start: i, end: lines.length };
+    }
+  }
+  if (current) {
+    current.end = lines.length;
+    sections.push(current);
+  }
+  return sections;
+}
+var VALID_INVARIANT_RE = /^-\s+`[^`]+`\s*[—–-]\s*.+/;
+function normalizeInvariantLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("- ")) return line;
+  if (VALID_INVARIANT_RE.test(trimmed)) return line;
+  const boldMatch = trimmed.match(/^-\s+\*\*([^*]+)\*\*\s*([—–-])\s*(.+)$/);
+  if (boldMatch) {
+    const id = boldMatch[1].toLowerCase().replace(/\s+/g, "_");
+    const desc = boldMatch[3].trim();
+    const hasParens = /\([^)]+\)\s*$/.test(desc);
+    return `- \`${id}\` \u2014 ${hasParens ? desc : desc + " (structural, immutable)"}`;
+  }
+  const snakeMatch = trimmed.match(/^-\s+(\w[\w]*(?:_\w+)+)\s*([—–-])\s*(.+)$/);
+  if (snakeMatch) {
+    const id = snakeMatch[1];
+    const desc = snakeMatch[3].trim();
+    const hasParens = /\([^)]+\)\s*$/.test(desc);
+    return `- \`${id}\` \u2014 ${hasParens ? desc : desc + " (structural, immutable)"}`;
+  }
+  const proseMatch = trimmed.match(/^-\s+([A-Z][^(]+?)(?:\s*\(([^)]+)\))?\s*$/);
+  if (proseMatch) {
+    const desc = proseMatch[1].trim();
+    const parens = proseMatch[2] ?? "structural, immutable";
+    const id = desc.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, "_").slice(0, 50);
+    if (id.length >= 3) {
+      return `- \`${id}\` \u2014 ${desc} (${parens})`;
+    }
+  }
+  return line;
+}
+var VALID_GATE_RE = /^-\s+\w+:\s*\w+\s*(==|!=|>=|<=|>|<)\s*[\d.]+/;
+var SYMBOLIC_TO_NUMERIC = {
+  // Positive states
+  full: 100,
+  complete: 100,
+  total: 100,
+  optimal: 95,
+  maximum: 100,
+  high: 80,
+  strong: 80,
+  // Mid states
+  partial: 60,
+  moderate: 50,
+  medium: 50,
+  growing: 60,
+  developing: 50,
+  // Low/negative states
+  low: 30,
+  minimal: 20,
+  weak: 20,
+  declining: 40,
+  limited: 30,
+  escalating: 50,
+  // Extreme states
+  none: 0,
+  absent: 0,
+  zero: 0,
+  critical: 80,
+  extreme: 90,
+  severe: 85,
+  indiscriminate: 80,
+  uncontrolled: 90,
+  overwhelming: 90
+};
+function normalizeGateLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("- ")) return line;
+  if (VALID_GATE_RE.test(trimmed)) return line;
+  const symbolicMatch = trimmed.match(
+    /^-\s+(\w+):\s*(\w+)\s*(?:==?)\s*"?([a-zA-Z_]+)"?\s*$/
+  );
+  if (symbolicMatch) {
+    const status = symbolicMatch[1];
+    const field = symbolicMatch[2];
+    const symbolic = symbolicMatch[3].toLowerCase();
+    const numeric = SYMBOLIC_TO_NUMERIC[symbolic];
+    if (numeric !== void 0) {
+      return `- ${status}: ${field} >= ${numeric}`;
+    }
+    return `- ${status}: ${field} >= 50`;
+  }
+  const eqNumMatch = trimmed.match(/^-\s+(\w+):\s*(\w+)\s*=\s*([\d.]+)\s*$/);
+  if (eqNumMatch) {
+    return `- ${eqNumMatch[1]}: ${eqNumMatch[2]} >= ${eqNumMatch[3]}`;
+  }
+  return line;
+}
+function normalizeWhenLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("When ")) return line;
+  const parts = trimmed.slice(5).split(/\s+AND\s+/i);
+  const normalized = parts.map((part) => {
+    const p = part.trim();
+    if (/\[(state|assumption)\]\s*$/.test(p)) return p;
+    return p + " [state]";
+  });
+  return "When " + normalized.join(" AND ");
+}
+function normalizeWorldMarkdown(markdown) {
+  const lines = markdown.split("\n");
+  const sections = findSections(lines);
+  const report = { fixCount: 0, invariantIds: 0, gateThresholds: 0, triggerTags: 0 };
+  const invariantsSection = sections.find((s) => s.name.toLowerCase() === "invariants");
+  const gatesSection = sections.find((s) => s.name.toLowerCase() === "gates");
+  const rulesSection = sections.find((s) => s.name.toLowerCase() === "rules");
+  for (let i = 0; i < lines.length; i++) {
+    const original = lines[i];
+    if (invariantsSection && i > invariantsSection.start && i < invariantsSection.end) {
+      lines[i] = normalizeInvariantLine(lines[i]);
+      if (lines[i] !== original) report.invariantIds++;
+    }
+    if (gatesSection && i > gatesSection.start && i < gatesSection.end) {
+      lines[i] = normalizeGateLine(lines[i]);
+      if (lines[i] !== original) report.gateThresholds++;
+    }
+    if (rulesSection && i > rulesSection.start && i < rulesSection.end) {
+      lines[i] = normalizeWhenLine(lines[i]);
+      if (lines[i] !== original) report.triggerTags++;
+    }
+    if (lines[i] !== original) report.fixCount++;
+  }
+  return { normalized: lines.join("\n"), fixCount: report.fixCount, report };
+}
+
+// src/engine/derive-engine.ts
+import { writeFile } from "fs/promises";
+
+// src/engine/derive-prompt.ts
+import { readFile } from "fs/promises";
+import { join, dirname } from "path";
+var WORLD_FILENAME = "derivation-world.nv-world.md";
+function getModuleDir() {
+  try {
+    return dirname(new URL(import.meta.url).pathname);
+  } catch {
+    return __dirname;
+  }
+}
+async function loadDerivationWorld() {
+  const moduleDir = getModuleDir();
+  const candidates = [
+    join(moduleDir, "..", "worlds", WORLD_FILENAME),
+    join(moduleDir, "worlds", WORLD_FILENAME)
+  ];
+  for (const candidate of candidates) {
+    try {
+      return await readFile(candidate, "utf-8");
+    } catch {
+    }
+  }
+  throw new Error(
+    `DerivationWorld not found. Searched:
+${candidates.map((c) => `  - ${c}`).join("\n")}`
+  );
+}
+async function collectMarkdownSources(inputPath) {
+  const { stat, readFile: rf, readdir } = await import("fs/promises");
+  const { join: pathJoin, extname, basename } = await import("path");
+  const stats = await stat(inputPath);
+  if (stats.isFile()) {
+    const content = await rf(inputPath, "utf-8");
+    return [{ filename: basename(inputPath), content }];
+  }
+  if (stats.isDirectory()) {
+    const sources = [];
+    await collectDir(inputPath, sources, rf, pathJoin, extname, basename);
+    sources.sort((a, b) => a.filename.localeCompare(b.filename));
+    return sources;
+  }
+  throw new Error(`Input path is neither a file nor a directory: ${inputPath}`);
+}
+async function collectDir(dir, sources, rf, pathJoin, extname, basename) {
+  const { readdir } = await import("fs/promises");
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = pathJoin(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectDir(fullPath, sources, rf, pathJoin, extname, basename);
+    } else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
+      const content = await rf(fullPath, "utf-8");
+      sources.push({ filename: entry.name, content });
+    }
+  }
+}
+function concatenateSources(sources) {
+  return sources.map((s) => `=== FILE: ${s.filename} ===
+${s.content}`).join("\n\n");
+}
+var NV_WORLD_SPEC = `
+## .nv-world.md Format Specification
+
+A .nv-world.md file is a structured markdown document with YAML frontmatter and H1 sections.
+
+### Frontmatter (required)
+\`\`\`yaml
+---
+world_id: <snake_case_id>
+name: <Human Readable Name>
+version: 1.0.0
+---
+\`\`\`
+
+### Required Sections
+
+# Thesis
+A single paragraph stating the structural claim this world tests. Must be testable and falsifiable.
+
+# Invariants
+Bullet list of non-negotiable constraints.
+
+STRICT FORMAT \u2014 Invariant IDs MUST be wrapped in backticks. Every bullet MUST follow this exact pattern:
+- \\\`invariant_id\\\` \u2014 Description text (enforcement, mutability)
+
+VALID examples:
+- \\\`rage_manifestation\\\` \u2014 Suppressed rage manifests as a physical monster (structural, immutable)
+- \\\`healing_requires_integration\\\` \u2014 Recovery requires emotional integration (operational, immutable)
+
+INVALID examples (these WILL cause parse failures):
+- rage_manifestation \u2014 Suppressed rage manifests as a monster
+- Suppressed rage manifests as a monster (structural, immutable)
+- **rage_manifestation** \u2014 Description
+
+Rules:
+- The ID inside backticks must be snake_case (lowercase with underscores)
+- Use "structural" for constraints derived directly from source material
+- Use "operational" for constraints you inferred
+- Mutability is almost always "immutable"
+
+# State
+H2 sub-sections, each defining a state variable:
+## variable_name
+- type: number | enum | boolean
+- min: <number> (for number type)
+- max: <number> (for number type)
+- step: <number> (for number type)
+- options: option_a, option_b (for enum type)
+- default: <value>
+- label: Human Label
+- description: What this variable represents
+
+IMPORTANT: State variable IDs (the ## heading) must be snake_case. The "default" value MUST be numeric for number types and MUST be one of the declared options for enum types.
+
+# Assumptions
+H2 sub-sections, each defining a scenario profile:
+## profile_id
+- name: Profile Name
+- description: What this profile represents
+- param_key: param_value
+
+# Rules
+H2 sub-sections with this format:
+## rule-001: Rule Label (structural|degradation|advantage)
+Single sentence description.
+
+When field == "value" [state] AND other_field > 50 [state]
+Then target *= 0.30, other_target = false
+Collapse: field < 0.05
+
+> trigger: What triggers this rule
+> rule: What the rule means
+> shift: What changes
+> effect: The concrete effect
+
+Rules must have:
+- A "When" line with triggers referencing [state] or [assumption] sources
+- A "Then" line with effects using =, *=, +=, or -= operators
+- Optional "Collapse:" line for failure conditions
+
+STRICT FORMAT for triggers \u2014 each trigger MUST match: field_name <operator> <value> [state|assumption]
+- Operators: ==, !=, >=, <=, >, <
+- Values must be numeric (50), boolean (true/false), or quoted strings ("value")
+- Source tag [state] or [assumption] is REQUIRED
+
+STRICT FORMAT for effects \u2014 each effect MUST match: target_field <operator> <value>
+- Operators: =, *=, +=, -=
+- Values must be numeric (0.30), boolean (true/false), or quoted strings ("value")
+
+# Gates
+Bullet list of status thresholds (must be monotonically decreasing).
+
+STRICT FORMAT \u2014 Gate thresholds MUST be numeric. Symbolic values like "full", "partial", "escalating" are NOT allowed. Every gate MUST follow this exact pattern:
+- STATUS_NAME: field_name >= <number>
+
+VALID examples:
+- BEST_STATUS: integration_level >= 90
+- GOOD_STATUS: integration_level >= 60
+- WARN_STATUS: monster_rage >= 40
+- BAD_STATUS: monster_rage >= 70
+- WORST_STATUS: josie_endangerment >= 90
+
+INVALID examples (these WILL cause parse failures):
+- BEST_STATUS: integration = full
+- GOOD_STATUS: integration = partial
+- BEST_STATUS: true_integration_state == "complete"
+
+Rules:
+- All gate thresholds must be NUMERIC values (integers or decimals)
+- The field_name must reference a declared State variable or Outcome
+- Operators: >=, <=, >, <, ==, !=
+- Status names should be uppercase with underscores
+- Thresholds must be monotonically decreasing from best to worst status
+
+# Outcomes
+H2 sub-sections defining computed outcomes:
+## outcome_id
+- type: number | enum | boolean
+- range: 0-100 (for numbers)
+- display: percentage | integer | decimal
+- label: Human Label
+- primary: true (for the main metric)
+`.trim();
+async function buildSystemPrompt() {
+  const derivationWorld = await loadDerivationWorld();
+  const invariantLines = derivationWorld.split("\n").filter((l) => l.trim().startsWith("- `")).map((l) => {
+    const match = l.match(/^-\s+`([^`]+)`\s*[—–-]\s*(.+?)(?:\s*\([^)]+\))?\s*$/);
+    return match ? `- ${match[2].trim()}` : null;
+  }).filter(Boolean);
+  return `You are a governance document synthesizer for NeuroVerse OS.
+
+Your task: Given arbitrary markdown source material, synthesize a valid .nv-world.md governance document.
+
+${NV_WORLD_SPEC}
+
+## Synthesis Constraints (from DerivationWorld)
+
+You MUST follow these constraints:
+${invariantLines.join("\n")}
+
+## Critical Rules
+
+1. Output ONLY the .nv-world.md document. No preamble, no explanation, no trailing commentary.
+2. Do not wrap the output in a code fence.
+3. Every invariant derived from explicit source statements must be marked (structural, immutable).
+4. Every invariant you infer that is not directly stated in the source must be marked (operational, immutable).
+5. All state variables, rules, and invariants must trace to concepts present in the input.
+6. Do not invent governance domains beyond what the source material covers.
+7. Every rule must have a When trigger line and a Then effect line.
+8. Gate thresholds must be monotonically decreasing from best to worst status.
+9. The frontmatter must include world_id, name, and version.
+10. Rule descriptions must be a single sentence.
+
+## Syntax Precision (CRITICAL)
+
+The output is parsed by a deterministic regex parser. If the syntax is wrong, the parse FAILS.
+
+INVARIANTS: Every invariant bullet MUST use backtick-wrapped IDs:
+  CORRECT: - \\\`my_invariant_id\\\` \u2014 Description (structural, immutable)
+  WRONG:   - my_invariant_id \u2014 Description
+
+GATES: Every gate MUST use NUMERIC thresholds:
+  CORRECT: - THRIVING: score >= 80
+  WRONG:   - THRIVING: state = optimal
+
+TRIGGERS: Every trigger MUST end with [state] or [assumption]:
+  CORRECT: When score < 25 [state]
+  WRONG:   When score < 25
+
+EFFECTS: Every effect MUST use a recognized operator:
+  CORRECT: Then score *= 0.50, active = false
+  WRONG:   Then score decreases by half`;
+}
+function buildUserPrompt(concatenatedMarkdown) {
+  return `Synthesize a valid .nv-world.md under DerivationWorld constraints from the following source material.
+
+Output ONLY the .nv-world.md content. Start with the --- frontmatter delimiter.
+
+Source material:
+
+${concatenatedMarkdown}`;
+}
+
+// src/engine/derive-engine.ts
+function extractWorldMarkdown(raw) {
+  let content = raw.trim();
+  const fenceMatch = content.match(/```(?:markdown|md)?\s*\n([\s\S]*?)```/);
+  if (fenceMatch) {
+    content = fenceMatch[1].trim();
+  }
+  const sentinelMatch = content.match(
+    /(?:BEGIN NV WORLD|BEGIN_NV_WORLD)[\s\n]*([\s\S]*?)[\s\n]*(?:END NV WORLD|END_NV_WORLD)/i
+  );
+  if (sentinelMatch) {
+    content = sentinelMatch[1].trim();
+  }
+  if (!content.startsWith("---")) {
+    const fmIndex = content.indexOf("---\n");
+    if (fmIndex >= 0) {
+      content = content.slice(fmIndex);
+    }
+  }
+  if (!content.startsWith("---") && /^# /m.test(content)) {
+    const generated = generateFrontmatter(content);
+    content = generated + "\n" + content;
+  }
+  if (!content.startsWith("---")) return null;
+  const fmEnd = content.indexOf("---", 3);
+  if (fmEnd === -1) return null;
+  const frontmatter = content.slice(3, fmEnd);
+  if (!frontmatter.includes("world_id:")) return null;
+  return content;
+}
+function generateFrontmatter(content) {
+  let name = "Derived World";
+  const thesisMatch = content.match(/^# Thesis\s*\n+(.+)/m);
+  if (thesisMatch) {
+    const firstSentence = thesisMatch[1].replace(/[.!?].*$/, "").trim();
+    if (firstSentence.length >= 3 && firstSentence.length <= 60) {
+      name = firstSentence;
+    }
+  }
+  const worldId = name.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, "_").slice(0, 50);
+  return [
+    "---",
+    `world_id: ${worldId}`,
+    `name: ${name}`,
+    "version: 0.1",
+    "runtime_mode: simulation",
+    "---"
+  ].join("\n");
+}
+var GATES = [
+  { status: "FAITHFUL", threshold: 0.85 },
+  { status: "USABLE", threshold: 0.6 },
+  { status: "REVIEWABLE", threshold: 0.4 },
+  { status: "SUSPECT", threshold: 0.15 },
+  { status: "DERIVATION_REJECTED", threshold: 0 }
+];
+function classifyGate(errors, warnings, sectionCount) {
+  const maxSections = 7;
+  const completeness = sectionCount / maxSections;
+  const fidelity = errors === 0 ? Math.max(0, completeness - warnings * 0.05) : 0;
+  for (const gate of GATES) {
+    if (fidelity >= gate.threshold) return gate.status;
+  }
+  return "DERIVATION_REJECTED";
+}
+async function deriveWorld(options) {
+  const startTime = performance.now();
+  const sources = await collectMarkdownSources(options.inputPath);
+  if (sources.length === 0) {
+    throw new DeriveInputError("No markdown files found in input path");
+  }
+  const concatenated = concatenateSources(sources);
+  const systemPrompt = await buildSystemPrompt();
+  const userPrompt = buildUserPrompt(concatenated);
+  if (options.dryRun) {
+    return {
+      result: {
+        success: true,
+        outputPath: options.outputPath,
+        sectionsDetected: [],
+        validationErrors: 0,
+        validationWarnings: 0,
+        findings: [],
+        gate: "DRY_RUN",
+        durationMs: performance.now() - startTime
+      },
+      exitCode: 0,
+      dryRunOutput: { systemPrompt, userPrompt }
+    };
+  }
+  const savedConfig = await loadConfig();
+  const config = {
+    provider: options.providerOverride?.provider ?? savedConfig?.provider ?? "",
+    model: options.providerOverride?.model ?? savedConfig?.model ?? "",
+    apiKey: options.providerOverride?.apiKey ?? savedConfig?.apiKey ?? "",
+    endpoint: options.providerOverride?.endpoint ?? savedConfig?.endpoint ?? null
+  };
+  if (!config.apiKey) {
+    throw new DeriveProviderError("No API key configured. Run: neuroverse configure-ai");
+  }
+  if (!config.model) {
+    throw new DeriveProviderError("No model configured. Run: neuroverse configure-ai");
+  }
+  const provider = createProvider(config);
+  let rawResponse;
+  try {
+    rawResponse = await provider.complete(systemPrompt, userPrompt);
+  } catch (e) {
+    throw new DeriveProviderError(`AI provider failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const extracted = extractWorldMarkdown(rawResponse);
+  if (!extracted) {
+    throw new DeriveProviderError(
+      "Could not extract valid .nv-world.md from AI response. Response must contain frontmatter with world_id."
+    );
+  }
+  const { normalized, fixCount, report: normReport } = normalizeWorldMarkdown(extracted);
+  const { world, issues } = parseWorldMarkdown(normalized);
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  const sectionsDetected = world ? Object.keys(world).filter((k) => {
+    const val = world[k];
+    if (Array.isArray(val)) return val.length > 0;
+    if (typeof val === "string") return val.length > 0;
+    return !!val;
+  }) : [];
+  if (world && options.validate) {
+    try {
+      const { world: worldDef } = emitWorldDefinition(world);
+      const report = validateWorld(worldDef);
+      for (const finding of report.findings) {
+        if (finding.severity === "error" || finding.severity === "warning") {
+          issues.push({
+            line: 0,
+            section: `Validate:${finding.category}`,
+            message: finding.message,
+            severity: finding.severity
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const allErrors = issues.filter((i) => i.severity === "error");
+  const allWarnings = issues.filter((i) => i.severity === "warning");
+  const gate = classifyGate(allErrors.length, allWarnings.length, sectionsDetected.length);
+  const findings = issues.filter((i) => i.severity === "error" || i.severity === "warning").map((i) => ({
+    severity: i.severity,
+    section: i.section,
+    message: i.message,
+    line: i.line
+  }));
+  let output = normalized;
+  if (findings.length > 0 || fixCount > 0) {
+    const lines = [`<!-- DERIVATION STATUS: ${gate}`];
+    if (fixCount > 0) {
+      const details = [];
+      if (normReport.invariantIds > 0) details.push(`${normReport.invariantIds} invariant ID(s) wrapped`);
+      if (normReport.gateThresholds > 0) details.push(`${normReport.gateThresholds} gate threshold(s) converted`);
+      if (normReport.triggerTags > 0) details.push(`${normReport.triggerTags} trigger(s) tagged with [state]`);
+      lines.push(``, `Normalizer: ${fixCount} fix(es) applied`);
+      for (const d of details) lines.push(`  - ${d}`);
+    }
+    const errs = findings.filter((f) => f.severity === "error");
+    const warns = findings.filter((f) => f.severity === "warning");
+    if (errs.length > 0) {
+      lines.push("", "Errors:");
+      for (const f of errs) lines.push(`- [${f.section}] ${f.message}`);
+    }
+    if (warns.length > 0) {
+      lines.push("", "Warnings:");
+      for (const f of warns) lines.push(`- [${f.section}] ${f.message}`);
+    }
+    lines.push("-->", "");
+    output = lines.join("\n") + normalized;
+  }
+  await writeFile(options.outputPath, output, "utf-8");
+  const hasErrors = allErrors.length > 0;
+  return {
+    result: {
+      success: !hasErrors,
+      outputPath: options.outputPath,
+      sectionsDetected,
+      validationErrors: allErrors.length,
+      validationWarnings: allWarnings.length,
+      findings,
+      gate,
+      normalization: fixCount > 0 ? {
+        fixCount: normReport.fixCount,
+        invariantIds: normReport.invariantIds,
+        gateThresholds: normReport.gateThresholds,
+        triggerTags: normReport.triggerTags
+      } : void 0,
+      durationMs: performance.now() - startTime
+    },
+    exitCode: hasErrors ? 1 : 0
+  };
+}
+var DeriveInputError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeriveInputError";
+  }
+};
+var DeriveProviderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeriveProviderError";
+  }
+};
+
+export {
+  normalizeWorldMarkdown,
+  extractWorldMarkdown,
+  deriveWorld,
+  DeriveInputError,
+  DeriveProviderError
+};