@neuroverseos/governance 0.4.0 → 0.4.1

package/dist/chunk-3S5AD4AB.js

@@ -0,0 +1,421 @@
+import {
+  GovernanceBlockedError,
+  buildEngineOptions,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  evaluateGuard
+} from "./chunk-ZAF6JH23.js";
+import {
+  loadWorld
+} from "./chunk-I4RTIMLX.js";
+
+// src/adapters/github.ts
+var GitHubGovernanceBlockedError = class extends GovernanceBlockedError {
+  action;
+  constructor(verdict, action) {
+    super(verdict, `[NeuroVerse] GitHub action blocked: ${action.action} on ${action.repository}`);
+    this.name = "GitHubGovernanceBlockedError";
+    this.action = action;
+  }
+};
+function extractBranch(ref) {
+  if (!ref) return void 0;
+  if (ref.startsWith("refs/heads/")) return ref.slice("refs/heads/".length);
+  if (ref.startsWith("refs/tags/")) return ref.slice("refs/tags/".length);
+  return ref;
+}
+function isProtectedBranch(branch, protectedBranches) {
+  if (!branch) return false;
+  return protectedBranches.some(
+    (pb) => branch === pb || branch.startsWith(`${pb}/`)
+  );
+}
+function defaultMapAction(action, protectedBranches, restrictedActors) {
+  const branch = action.branch ?? extractBranch(action.ref);
+  const isProtected = isProtectedBranch(branch, protectedBranches);
+  const isRestricted = action.actor ? restrictedActors.some((ra) => action.actor === ra || action.actor?.endsWith("[bot]")) : false;
+  let actionCategory = "other";
+  const act = action.action.toLowerCase();
+  if (act.includes("read") || act.includes("get") || act.includes("list") || act.includes("view")) {
+    actionCategory = "read";
+  } else if (act.includes("delete") || act.includes("remove") || act.includes("close")) {
+    actionCategory = "delete";
+  } else if (act.includes("deploy") || act.includes("run") || act.includes("execute") || act.includes("merge")) {
+    actionCategory = "network";
+  } else if (act.includes("create") || act.includes("push") || act.includes("write") || act.includes("update") || act.includes("edit")) {
+    actionCategory = "write";
+  } else if (act.includes("comment") || act.includes("review") || act.includes("notify")) {
+    actionCategory = "other";
+  }
+  return {
+    intent: action.action,
+    tool: "github",
+    scope: `${action.repository}${branch ? `@${branch}` : ""}`,
+    actionCategory,
+    direction: "input",
+    args: {
+      repository: action.repository,
+      ref: action.ref,
+      branch,
+      actor: action.actor,
+      protected_branch: isProtected,
+      restricted_actor: isRestricted,
+      ...action.metadata
+    }
+  };
+}
+function defaultMapWebhook(eventType, payload) {
+  const repo = payload.repository;
+  const repoFullName = repo?.full_name ?? "unknown/unknown";
+  const sender = payload.sender;
+  const actor = sender?.login ?? void 0;
+  const webhookAction = payload.action;
+  switch (eventType) {
+    case "push": {
+      const ref = payload.ref;
+      const branch = extractBranch(ref);
+      const forced = payload.forced;
+      return {
+        action: forced ? "force_push" : `push_to_${branch ?? "branch"}`,
+        repository: repoFullName,
+        ref,
+        branch,
+        actor,
+        metadata: {
+          forced: forced ?? false,
+          commits_count: payload.commits?.length ?? 0,
+          head_commit: payload.head_commit?.id
+        }
+      };
+    }
+    case "pull_request": {
+      const pr = payload.pull_request;
+      const base = pr?.base;
+      const baseBranch = base?.ref;
+      const prNumber = pr?.number;
+      const merged = pr?.merged;
+      const labels = pr?.labels?.map((l) => l.name) ?? [];
+      let action = `pull_request_${webhookAction ?? "unknown"}`;
+      if (webhookAction === "closed" && merged) {
+        action = "merge_pull_request";
+      }
+      return {
+        action,
+        repository: repoFullName,
+        branch: baseBranch,
+        actor,
+        metadata: {
+          pr_number: prNumber,
+          labels,
+          merged: merged ?? false,
+          draft: pr?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "release": {
+      const release = payload.release;
+      return {
+        action: `release_${webhookAction ?? "published"}`,
+        repository: repoFullName,
+        ref: release?.tag_name ? `refs/tags/${release.tag_name}` : void 0,
+        actor,
+        metadata: {
+          tag: release?.tag_name,
+          prerelease: release?.prerelease ?? false,
+          draft: release?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "deployment":
+    case "deployment_status": {
+      const deployment = payload.deployment ?? payload;
+      return {
+        action: eventType === "deployment" ? "create_deployment" : "deployment_status_update",
+        repository: repoFullName,
+        ref: deployment.ref,
+        actor,
+        metadata: {
+          environment: deployment.environment,
+          status: payload.deployment_status?.state,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "workflow_run": {
+      const run = payload.workflow_run;
+      return {
+        action: `workflow_${webhookAction ?? "completed"}`,
+        repository: repoFullName,
+        branch: run?.head_branch,
+        actor,
+        metadata: {
+          workflow_name: run?.name,
+          conclusion: run?.conclusion,
+          status: run?.status,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issues": {
+      const issue = payload.issue;
+      return {
+        action: `issue_${webhookAction ?? "opened"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: issue?.number,
+          labels: issue?.labels?.map((l) => l.name) ?? [],
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issue_comment": {
+      return {
+        action: `issue_comment_${webhookAction ?? "created"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: payload.issue?.number,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "delete": {
+      return {
+        action: `delete_${payload.ref_type ?? "ref"}`,
+        repository: repoFullName,
+        ref: payload.ref,
+        actor,
+        metadata: {
+          ref_type: payload.ref_type
+        }
+      };
+    }
+    default: {
+      return {
+        action: webhookAction ? `${eventType}_${webhookAction}` : eventType,
+        repository: repoFullName,
+        actor,
+        metadata: { webhook_action: webhookAction }
+      };
+    }
+  }
+}
+var GitHubGovernor = class {
+  world;
+  options;
+  engineOptions;
+  activePlan;
+  protectedBranches;
+  restrictedActors;
+  mapFn;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.protectedBranches = options.protectedBranches ?? ["main", "master", "production"];
+    this.restrictedActors = options.restrictedActors ?? [];
+    this.mapFn = options.mapAction ?? ((action) => defaultMapAction(action, this.protectedBranches, this.restrictedActors));
+  }
+  /**
+   * Evaluate a GitHub action against governance rules.
+   * Returns a full result with verdict, event, and the original action.
+   */
+  evaluate(action) {
+    const event = this.mapFn(action);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    this.options.onEvaluate?.(verdict, event, action);
+    if (verdict.status === "ALLOW") {
+      trackPlanProgress(event, this, this.options);
+    }
+    return { verdict, event, action };
+  }
+  /**
+   * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+   * Use this as a gate before executing GitHub API calls.
+   */
+  enforce(action) {
+    const result = this.evaluate(action);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /**
+   * Check if pushing to a branch is allowed.
+   * Convenience method for the most common governance check.
+   */
+  canPush(repository, branch, actor) {
+    return this.evaluate({
+      action: `push_to_${branch}`,
+      repository,
+      ref: `refs/heads/${branch}`,
+      branch,
+      actor
+    }).verdict;
+  }
+  /**
+   * Check if merging a PR is allowed.
+   */
+  canMerge(repository, targetBranch, prNumber, actor, labels) {
+    return this.evaluate({
+      action: "merge_pull_request",
+      repository,
+      branch: targetBranch,
+      actor,
+      metadata: { pr_number: prNumber, labels: labels ?? [] }
+    }).verdict;
+  }
+  /**
+   * Check if creating a release is allowed.
+   */
+  canRelease(repository, tag, actor, prerelease) {
+    return this.evaluate({
+      action: "release_published",
+      repository,
+      ref: `refs/tags/${tag}`,
+      actor,
+      metadata: { tag, prerelease: prerelease ?? false }
+    }).verdict;
+  }
+  /**
+   * Check if deploying to an environment is allowed.
+   */
+  canDeploy(repository, environment, ref, actor) {
+    return this.evaluate({
+      action: "create_deployment",
+      repository,
+      ref,
+      actor,
+      metadata: { environment }
+    }).verdict;
+  }
+};
+var GitHubWebhookHandler = class {
+  governor;
+  mapWebhookFn;
+  webhookSecret;
+  constructor(world, options = {}) {
+    this.governor = new GitHubGovernor(world, options);
+    this.mapWebhookFn = options.mapWebhook ?? defaultMapWebhook;
+    this.webhookSecret = options.webhookSecret;
+  }
+  /**
+   * Evaluate a webhook payload.
+   *
+   * @param eventType - The X-GitHub-Event header value
+   * @param payload - The parsed webhook body
+   */
+  evaluate(eventType, payload) {
+    const action = this.mapWebhookFn(eventType, payload);
+    const result = this.governor.evaluate(action);
+    return {
+      verdict: result.verdict,
+      event: result.event,
+      webhookEvent: eventType,
+      webhookAction: payload.action
+    };
+  }
+  /**
+   * Evaluate and enforce — throws on BLOCK/PAUSE.
+   */
+  enforce(eventType, payload) {
+    const result = this.evaluate(eventType, payload);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      const action = this.mapWebhookFn(eventType, payload);
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /** Access the underlying governor for direct action evaluation. */
+  getGovernor() {
+    return this.governor;
+  }
+  /** Get the configured webhook secret (for signature verification in your server). */
+  getWebhookSecret() {
+    return this.webhookSecret;
+  }
+};
+function formatForActions(verdict) {
+  const status = verdict.status === "ALLOW" ? "allowed" : verdict.status === "BLOCK" ? "blocked" : "paused";
+  const reason = verdict.reason ?? "";
+  const ruleId = verdict.ruleId ?? "";
+  const lines = [
+    `governance_status=${status}`,
+    `verdict_status=${verdict.status}`,
+    `reason=${reason}`,
+    `rule_id=${ruleId}`
+  ].join("\n");
+  return {
+    governance_status: status,
+    verdict_status: verdict.status,
+    reason,
+    rule_id: ruleId,
+    outputLines: lines
+  };
+}
+function formatPRComment(verdict, action) {
+  const icon = verdict.status === "ALLOW" ? "\u2705" : verdict.status === "BLOCK" ? "\u{1F6AB}" : "\u23F8\uFE0F";
+  const status = verdict.status;
+  let body = `## ${icon} Governance: ${status}
+
+`;
+  body += `**Action:** \`${action.action}\`
+`;
+  body += `**Repository:** \`${action.repository}\`
+`;
+  if (action.branch) {
+    body += `**Branch:** \`${action.branch}\`
+`;
+  }
+  if (action.actor) {
+    body += `**Actor:** \`${action.actor}\`
+`;
+  }
+  body += "\n";
+  if (verdict.reason) {
+    body += `**Reason:** ${verdict.reason}
+`;
+  }
+  if (verdict.ruleId) {
+    body += `**Rule:** \`${verdict.ruleId}\`
+`;
+  }
+  if (verdict.evidence?.invariantsSatisfied < verdict.evidence?.invariantsTotal) {
+    body += `**Invariants:** ${verdict.evidence.invariantsSatisfied}/${verdict.evidence.invariantsTotal} satisfied
+`;
+  }
+  body += "\n---\n*Evaluated by [NeuroVerse Governance](https://github.com/NeuroverseOS/neuroverseos-governance)*";
+  return body;
+}
+async function createGitHubGovernor(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubGovernor(world, options);
+}
+function createGitHubGovernorFromWorld(world, options) {
+  return new GitHubGovernor(world, options);
+}
+async function createGitHubWebhookHandler(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubWebhookHandler(world, options);
+}
+function createGitHubWebhookHandlerFromWorld(world, options) {
+  return new GitHubWebhookHandler(world, options);
+}
+
+export {
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
+  formatForActions,
+  formatPRComment,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld
+};

package/dist/{chunk-V4FZHJQX.js → chunk-A7SHG75T.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/openclaw.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {

package/dist/{chunk-JKGPSFGH.js → chunk-AV7XJJWK.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/runtime/govern.ts
 function actionToGuardEvent(action) {

package/dist/{chunk-Y6WXAPKY.js → chunk-DA5MHFRR.js}

@@ -1,6 +1,6 @@
 import {
   simulateWorld
-} from "./chunk-7QIAF377.js";
+} from "./chunk-CYDMUJVZ.js";
 import {
   validateWorld
 } from "./chunk-7P3S7MAY.js";

package/dist/{chunk-7D7PZLB7.js → chunk-FS2UUJJO.js}

@@ -35,7 +35,7 @@ async function addGuard(worldDir, input) {
   };
   config.guards.push(guard);
   await writeFile(guardsPath, JSON.stringify(config, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-C4D3VPP3.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {
@@ -83,7 +83,7 @@ async function addRule(worldDir, input) {
   };
   const rulePath = join(rulesDir, `rule-${ruleNum}.json`);
   await writeFile(rulePath, JSON.stringify(rule, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-C4D3VPP3.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {
@@ -118,7 +118,7 @@ async function addInvariant(worldDir, input) {
   };
   config.invariants.push(invariant);
   await writeFile(invariantsPath, JSON.stringify(config, null, 2) + "\n");
-  const { loadWorldFromDirectory } = await import("./world-loader-C4D3VPP3.js");
+  const { loadWorldFromDirectory } = await import("./world-loader-YTYFOP7D.js");
   const world = await loadWorldFromDirectory(worldDir);
   const report = validateWorld(world);
   return {

package/dist/{chunk-TD5GKIHP.js → chunk-FVOGUCB6.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/openai.ts
 var GovernanceBlockedError2 = class extends GovernanceBlockedError {

package/dist/{chunk-APU4OZIP.js → chunk-GTPV2XGO.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/worlds/mentraos-intent-taxonomy.ts
 var MENTRA_INTENT_TAXONOMY = [
@@ -632,6 +632,7 @@ var MentraGovernedExecutor = class {
   _userRules;
   _emergencyOverride = false;
   _emergencyActivatedAt = null;
+  _spatialSession = null;
   constructor(world, options = {}, userRules = DEFAULT_USER_RULES) {
     this.world = world;
     this.options = options;
@@ -688,13 +689,36 @@ var MentraGovernedExecutor = class {
   get emergencyActivatedAt() {
     return this._emergencyActivatedAt;
   }
+  // ── Spatial Governance (optional) ────────────────────────────────────────
+  /**
+   * Attach a spatial session to this executor.
+   *
+   * When attached, intents are evaluated against the spatial context
+   * (zone rules + handshake rules) AFTER user rules but BEFORE
+   * hardware and platform checks. This is Layer 1.5.
+   *
+   * Pass null to detach (e.g., when leaving a zone).
+   */
+  setSpatialSession(session) {
+    this._spatialSession = session;
+  }
+  /** Whether a spatial session is currently active */
+  get hasSpatialSession() {
+    return this._spatialSession !== null;
+  }
+  /** Get the current spatial session description */
+  get spatialDescription() {
+    return this._spatialSession?.description ?? null;
+  }
   /**
    * Evaluate an intent against user rules + platform world.
    *
    * Three-layer evaluation:
-   *   0. Emergency override — if active, skip governance (layers 1 + 3),
+   *   0. Emergency override — if active, skip governance (layers 1 + 1.5 + 3),
    *      but STILL enforce platform constraints (layer 2)
    *   1. User rules check — personal governance override, can BLOCK or PAUSE
+   *   1.5. Spatial governance — zone + handshake rules (optional, temporary)
+   *      ↑ ONLY ACTIVE when a spatial session is attached
    *   2. Hardware capability check — validates glasses support
    *      ↑ THIS IS A PLATFORM CONSTRAINT — never overridden
    *   3. Platform guard engine — full world rule evaluation
@@ -725,6 +749,47 @@ var MentraGovernedExecutor = class {
         return result2;
       }
     }
+    if (!this._emergencyOverride && this._spatialSession) {
+      const spatialResult = this._spatialSession.evaluate(intent);
+      if (!spatialResult.allowed && !spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "BLOCK",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: false,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onBlock?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+      if (spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "PAUSE",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: true,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onPause?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+    }
     if (intentDef && glassesModel && !intentDef.supported_glasses.includes(glassesModel)) {
       const verdict2 = {
         status: "BLOCK",

package/dist/{chunk-BXLTEUS4.js → chunk-I4RTIMLX.js}

@@ -96,8 +96,8 @@ async function loadBundledWorld(name = DEFAULT_BUNDLED_WORLD) {
   const { join, dirname } = await import("path");
   const { existsSync } = await import("fs");
   const { fileURLToPath } = await import("url");
-  const { parseWorldMarkdown } = await import("./bootstrap-parser-LBLGVEMU.js");
-  const { emitWorldDefinition } = await import("./bootstrap-emitter-GIMOJFOC.js");
+  const { parseWorldMarkdown } = await import("./engine/bootstrap-parser.js");
+  const { emitWorldDefinition } = await import("./engine/bootstrap-emitter.js");
   const filename = `${name}.nv-world.md`;
   let packageRoot;
   try {

package/dist/{chunk-5JUZ4HL7.js → chunk-J2IZBHXJ.js}

@@ -5,14 +5,14 @@ import {
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
+import {
+  loadWorld
+} from "./chunk-I4RTIMLX.js";
 import {
   advancePlan,
   evaluatePlan,
   getPlanProgress
 } from "./chunk-QLPTHTVB.js";
-import {
-  loadWorld
-} from "./chunk-BXLTEUS4.js";
 
 // src/runtime/mcp-server.ts
 import { execSync } from "child_process";

package/dist/{chunk-YNYCQECH.js → chunk-QMVQ6KPL.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorldFromDirectory
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/autoresearch.ts
 var AutoresearchGovernor = class {

package/dist/{chunk-25XHSTPT.js → chunk-RDA7ISWC.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/express.ts
 function methodToCategory(method) {

package/dist/{chunk-DWHUZUEY.js → chunk-YJ34R5NB.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-ZAF6JH23.js";
 import {
   loadWorld
-} from "./chunk-BXLTEUS4.js";
+} from "./chunk-I4RTIMLX.js";
 
 // src/engine/tool-classifier.ts
 var TOOL_CATEGORY_MAP = {

package/dist/{chunk-UTH7OXTM.js → chunk-ZEIT2QLM.js}

@@ -7,14 +7,14 @@ import {
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
+import {
+  loadWorld
+} from "./chunk-I4RTIMLX.js";
 import {
   advancePlan,
   evaluatePlan,
   getPlanProgress
 } from "./chunk-QLPTHTVB.js";
-import {
-  loadWorld
-} from "./chunk-BXLTEUS4.js";
 
 // src/runtime/session.ts
 async function defaultToolExecutor(name, args) {