@granular-software/sdk 0.4.36 → 0.4.37

package/dist/cli/index.js

@@ -1194,8 +1194,8 @@ var require_command = __commonJS({
   "../../node_modules/commander/lib/command.js"(exports) {
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
-    var path6 = __require("path");
-    var fs7 = __require("fs");
+    var path7 = __require("path");
+    var fs8 = __require("fs");
     var process10 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -2175,7 +2175,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs7.existsSync(executableFile)) return;
+        if (fs8.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2193,11 +2193,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path6.resolve(baseDir, baseName);
-          if (fs7.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path6.extname(baseName))) return void 0;
+          const localBin = path7.resolve(baseDir, baseName);
+          if (fs8.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path7.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs7.existsSync(`${localBin}${ext}`)
+            (ext) => fs8.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2209,21 +2209,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs7.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs8.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path6.resolve(
-            path6.dirname(resolvedScriptPath),
+          executableDir = path7.resolve(
+            path7.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path6.basename(
+            const legacyName = path7.basename(
               this._scriptPath,
-              path6.extname(this._scriptPath)
+              path7.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2234,7 +2234,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path6.extname(executableFile));
+        launchWithNode = sourceExt.includes(path7.extname(executableFile));
         let proc;
         if (process10.platform !== "win32") {
           if (launchWithNode) {
@@ -3081,7 +3081,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path6.basename(filename, path6.extname(filename));
+        this._name = path7.basename(filename, path7.extname(filename));
         return this;
       }
       /**
@@ -3095,9 +3095,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path7) {
-        if (path7 === void 0) return this._executableDir;
-        this._executableDir = path7;
+      executableDir(path8) {
+        if (path8 === void 0) return this._executableDir;
+        this._executableDir = path8;
         return this;
       }
       /**
@@ -3440,8 +3440,8 @@ var require_package = __commonJS({
 // ../../node_modules/dotenv/lib/main.js
 var require_main = __commonJS({
   "../../node_modules/dotenv/lib/main.js"(exports, module) {
-    var fs7 = __require("fs");
-    var path6 = __require("path");
+    var fs8 = __require("fs");
+    var path7 = __require("path");
     var os2 = __require("os");
     var crypto2 = __require("crypto");
     var packageJson = require_package();
@@ -3549,7 +3549,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs7.existsSync(filepath)) {
+            if (fs8.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -3557,15 +3557,15 @@ var require_main = __commonJS({
           possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
         }
       } else {
-        possibleVaultPath = path6.resolve(process.cwd(), ".env.vault");
+        possibleVaultPath = path7.resolve(process.cwd(), ".env.vault");
       }
-      if (fs7.existsSync(possibleVaultPath)) {
+      if (fs8.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
     }
     function _resolveHome(envPath) {
-      return envPath[0] === "~" ? path6.join(os2.homedir(), envPath.slice(1)) : envPath;
+      return envPath[0] === "~" ? path7.join(os2.homedir(), envPath.slice(1)) : envPath;
     }
     function _configVault(options) {
       const debug = Boolean(options && options.debug);
@@ -3582,7 +3582,7 @@ var require_main = __commonJS({
       return { parsed };
     }
     function configDotenv(options) {
-      const dotenvPath = path6.resolve(process.cwd(), ".env");
+      const dotenvPath = path7.resolve(process.cwd(), ".env");
       let encoding = "utf8";
       const debug = Boolean(options && options.debug);
       const quiet = options && "quiet" in options ? options.quiet : true;
@@ -3606,13 +3606,13 @@ var require_main = __commonJS({
       }
       let lastError;
       const parsedAll = {};
-      for (const path7 of optionPaths) {
+      for (const path8 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs7.readFileSync(path7, { encoding }));
+          const parsed = DotenvModule.parse(fs8.readFileSync(path8, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
-            _debug(`Failed to load ${path7} ${e.message}`);
+            _debug(`Failed to load ${path8} ${e.message}`);
           }
           lastError = e;
         }
@@ -3627,8 +3627,8 @@ var require_main = __commonJS({
         const shortPaths = [];
         for (const filePath of optionPaths) {
           try {
-            const relative = path6.relative(process.cwd(), filePath);
-            shortPaths.push(relative);
+            const relative2 = path7.relative(process.cwd(), filePath);
+            shortPaths.push(relative2);
           } catch (e) {
             if (debug) {
               _debug(`Failed to load ${filePath} ${e.message}`);
@@ -5561,7 +5561,7 @@ var LIBRARY_TEMPLATE = {
     userId: "reader_demo",
     name: "Mina Reader",
     email: "mina@example.com",
-    permissions: ["default"]
+    permissions: ["allow-all"]
   },
   seedRecords: [
     {
@@ -5937,7 +5937,7 @@ var SUPPORT_TEMPLATE = {
     userId: "support_demo",
     name: "Taylor Support",
     email: "taylor@example.com",
-    permissions: ["default"]
+    permissions: ["allow-all"]
   },
   seedRecords: [
     {
@@ -6253,7 +6253,7 @@ var DELIVERY_TEMPLATE = {
     userId: "delivery_demo",
     name: "Alex Delivery",
     email: "alex@example.com",
-    permissions: ["default"]
+    permissions: ["allow-all"]
   },
   seedRecords: [
     {
@@ -6769,10 +6769,839 @@ return {
 `;
 }
 
+// ../policy-engine/src/index.ts
+var DECISIONS = /* @__PURE__ */ new Set(["allow", "confirm", "deny"]);
+var BUILTIN_PROFILE_NAMES = ["allow-all", "confirm-all", "deny-all"];
+function getBuiltinPermissionProfiles() {
+  return [
+    {
+      schemaVersion: 1,
+      name: "allow-all",
+      label: "Allow all",
+      description: "Every declared action is visible unless a manifest policy denies it.",
+      source: "builtin",
+      defaults: { actionPolicy: "allow" },
+      policies: [],
+      actions: []
+    },
+    {
+      schemaVersion: 1,
+      name: "confirm-all",
+      label: "Confirm all",
+      description: "Every declared action requires user confirmation before execution.",
+      source: "builtin",
+      defaults: { actionPolicy: "confirm" },
+      policies: [],
+      actions: []
+    },
+    {
+      schemaVersion: 1,
+      name: "deny-all",
+      label: "Deny all",
+      description: "No declared action is invocable.",
+      source: "builtin",
+      defaults: { actionPolicy: "deny" },
+      policies: [],
+      actions: []
+    }
+  ];
+}
+function stableStringify(value) {
+  return JSON.stringify(sortJson(value));
+}
+async function digestJson(value) {
+  const payload = stableStringify(value);
+  const cryptoLike = globalThis.crypto;
+  if (cryptoLike?.subtle) {
+    const data = new TextEncoder().encode(payload);
+    const hash2 = await cryptoLike.subtle.digest("SHA-256", data);
+    const hex = Array.from(new Uint8Array(hash2)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `sha256:${hex}`;
+  }
+  let hash = 2166136261;
+  for (let index = 0; index < payload.length; index += 1) {
+    hash ^= payload.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortJson(child)])
+    );
+  }
+  return value;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeProfileName(name) {
+  if (typeof name !== "string") return null;
+  const trimmed = name.trim();
+  if (!/^[a-z0-9][a-z0-9._-]{1,63}$/.test(trimmed)) return null;
+  return trimmed;
+}
+function normalizeDecision(value) {
+  return DECISIONS.has(value) ? value : null;
+}
+function normalizePath(value) {
+  if (Array.isArray(value)) {
+    return value.map((part) => String(part)).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.includes(".") ? value.split(".").filter(Boolean) : [value];
+  }
+  return [];
+}
+function firstDefinedValue(spec) {
+  if ("value" in spec) return spec.value;
+  if ("stringValue" in spec) return spec.stringValue;
+  if ("numberValue" in spec) return spec.numberValue;
+  if ("booleanValue" in spec) return spec.booleanValue;
+  if ("state" in spec) return spec.state;
+  return void 0;
+}
+function normalizeCondition(input) {
+  if (input === void 0 || input === null) return { kind: "always" };
+  if (!isRecord(input)) {
+    throw new Error("Policy condition must be an object");
+  }
+  if (Array.isArray(input.all)) {
+    return {
+      kind: "all",
+      conditions: input.all.map((item) => normalizeCondition(item))
+    };
+  }
+  if (Array.isArray(input.any)) {
+    return {
+      kind: "any",
+      conditions: input.any.map((item) => normalizeCondition(item))
+    };
+  }
+  if (input.not !== void 0) {
+    return { kind: "not", condition: normalizeCondition(input.not) };
+  }
+  for (const source of ["input", "object", "stateMachine"]) {
+    const raw = input[source];
+    if (!isRecord(raw)) continue;
+    const operator = raw.operator;
+    if (operator !== "eq" && operator !== "neq" && operator !== "gt" && operator !== "gte" && operator !== "lt" && operator !== "lte" && operator !== "contains" && operator !== "not_contains" && operator !== "starts_with" && operator !== "ends_with" && operator !== "exists") {
+      throw new Error(`Unsupported policy operator: ${String(operator)}`);
+    }
+    if (source === "stateMachine") {
+      const machine = typeof raw.machine === "string" ? raw.machine : "";
+      if (!machine) throw new Error("stateMachine condition requires machine");
+      return {
+        kind: "predicate",
+        source,
+        path: [machine],
+        machine,
+        operator,
+        value: firstDefinedValue(raw)
+      };
+    }
+    const path7 = normalizePath(raw.path ?? raw.field ?? raw.input);
+    if (path7.length === 0) {
+      throw new Error(`${source} condition requires a path`);
+    }
+    return {
+      kind: "predicate",
+      source,
+      path: path7,
+      operator,
+      value: firstDefinedValue(raw)
+    };
+  }
+  throw new Error(
+    "Policy condition must contain all, any, not, input, object, or stateMachine"
+  );
+}
+function readPath(root, path7) {
+  let current = root;
+  for (const part of path7) {
+    if (!isRecord(current) && !Array.isArray(current)) {
+      return { exists: false, value: void 0 };
+    }
+    if (!(part in current)) {
+      return { exists: false, value: void 0 };
+    }
+    current = current[part];
+  }
+  return { exists: true, value: current };
+}
+function evaluateCondition(condition, context) {
+  switch (condition.kind) {
+    case "always":
+      return true;
+    case "all":
+      return condition.conditions.every(
+        (child) => evaluateCondition(child, context)
+      );
+    case "any":
+      return condition.conditions.some(
+        (child) => evaluateCondition(child, context)
+      );
+    case "not":
+      return !evaluateCondition(condition.condition, context);
+    case "predicate":
+      return evaluatePredicate(condition, context);
+  }
+}
+function evaluatePredicate(predicate, context) {
+  const target = predicate.source === "input" ? context.input : predicate.source === "object" ? context.object : context.stateMachines;
+  const { exists, value } = readPath(target || {}, predicate.path);
+  if (predicate.operator === "exists") return exists;
+  if (!exists) return false;
+  const expected = predicate.value;
+  switch (predicate.operator) {
+    case "eq":
+      return value === expected;
+    case "neq":
+      return value !== expected;
+    case "gt":
+      return typeof value === "number" && typeof expected === "number" && value > expected;
+    case "gte":
+      return typeof value === "number" && typeof expected === "number" && value >= expected;
+    case "lt":
+      return typeof value === "number" && typeof expected === "number" && value < expected;
+    case "lte":
+      return typeof value === "number" && typeof expected === "number" && value <= expected;
+    case "contains":
+      return Array.isArray(value) ? value.includes(expected) : typeof value === "string" && typeof expected === "string" && value.includes(expected);
+    case "not_contains":
+      return Array.isArray(value) ? !value.includes(expected) : typeof value === "string" && typeof expected === "string" && !value.includes(expected);
+    case "starts_with":
+      return typeof value === "string" && typeof expected === "string" && value.startsWith(expected);
+    case "ends_with":
+      return typeof value === "string" && typeof expected === "string" && value.endsWith(expected);
+  }
+}
+function matchRule(rule, context) {
+  if (!evaluateCondition(rule.condition, context)) return null;
+  return {
+    id: rule.id,
+    outcome: rule.outcome,
+    origin: rule.origin,
+    reason: rule.reason,
+    summary: rule.summary
+  };
+}
+function evaluatePolicies(input) {
+  const context = input.context || {};
+  const manifestRules = input.manifestRules || [];
+  const profileRules = input.profileRules || [];
+  const defaultActionPolicy = input.defaultActionPolicy || "deny";
+  const buckets = [
+    {
+      outcome: "deny",
+      rules: manifestRules.filter((rule) => rule.outcome === "deny")
+    },
+    {
+      outcome: "deny",
+      rules: profileRules.filter((rule) => rule.outcome === "deny")
+    },
+    {
+      outcome: "confirm",
+      rules: manifestRules.filter((rule) => rule.outcome === "confirm")
+    },
+    {
+      outcome: "confirm",
+      rules: profileRules.filter((rule) => rule.outcome === "confirm")
+    },
+    {
+      outcome: "allow",
+      rules: profileRules.filter((rule) => rule.outcome === "allow")
+    }
+  ];
+  for (const bucket of buckets) {
+    const matches = bucket.rules.map((rule) => matchRule(rule, context)).filter((match) => match !== null);
+    if (matches.length > 0) return { outcome: bucket.outcome, matches };
+  }
+  return {
+    outcome: defaultActionPolicy,
+    matches: defaultActionPolicy === "deny" ? [] : [
+      {
+        id: `profile-default-${defaultActionPolicy}`,
+        outcome: defaultActionPolicy,
+        origin: {
+          kind: "permissionProfile",
+          profileName: "active",
+          source: "permissionProfile"
+        },
+        summary: `Profile default policy is ${defaultActionPolicy}`
+      }
+    ]
+  };
+}
+function ruleSummary(outcome, reason, condition) {
+  if (reason) return reason;
+  if (condition.kind === "always") return `${capitalize(outcome)} always`;
+  return `${capitalize(outcome)} when ${summarizeCondition(condition)}`;
+}
+function capitalize(value) {
+  return value.slice(0, 1).toUpperCase() + value.slice(1);
+}
+function summarizeCondition(condition) {
+  switch (condition.kind) {
+    case "always":
+      return "always";
+    case "all":
+      return condition.conditions.map(summarizeCondition).join(" and ");
+    case "any":
+      return condition.conditions.map(summarizeCondition).join(" or ");
+    case "not":
+      return `not (${summarizeCondition(condition.condition)})`;
+    case "predicate": {
+      const path7 = condition.source === "stateMachine" ? `stateMachine.${condition.machine || condition.path.join(".")}` : `${condition.source}.${condition.path.join(".")}`;
+      if (condition.operator === "exists") return `${path7} exists`;
+      return `${path7} ${condition.operator} ${String(condition.value)}`;
+    }
+  }
+}
+function makeRule(input) {
+  const condition = input.condition || { kind: "always" };
+  return {
+    ...input,
+    condition,
+    summary: ruleSummary(input.outcome, input.reason, condition)
+  };
+}
+function actionIdentity(action, on) {
+  return on ? `${on}:${action}` : `global:${action}`;
+}
+function normalizeAttachedClass(value) {
+  if (!value) return null;
+  if (!value.startsWith("@")) return value;
+  const slashIndex = value.indexOf("/");
+  return slashIndex === -1 ? value : value.slice(slashIndex + 1);
+}
+function resolveEffectReference(effects2, action, on) {
+  const normalizedOn = normalizeAttachedClass(on);
+  const matches = effects2.filter((effect) => {
+    if (effect.name !== action) return false;
+    const attachedClass = normalizeAttachedClass(effect.attachedClass);
+    return normalizedOn ? attachedClass === normalizedOn : !attachedClass;
+  });
+  if (matches.length === 1) return matches[0];
+  if (!normalizedOn) {
+    const byName = effects2.filter((effect) => effect.name === action);
+    if (byName.length > 1) {
+      const classes = byName.map(
+        (effect) => normalizeAttachedClass(effect.attachedClass) || "global"
+      ).join(", ");
+      throw new Error(
+        `Action "${action}" exists on ${classes}. Add "on" to disambiguate.`
+      );
+    }
+  }
+  if (matches.length > 1) {
+    throw new Error(`Action "${action}" on "${String(on)}" is ambiguous.`);
+  }
+  throw new Error(
+    on ? `Action "${action}" on "${on}" was not found.` : `Global action "${action}" was not found.`
+  );
+}
+function manifestPolicyRulesForEffect(effect, manifestId) {
+  const policies = isRecord(effect.metamodels?.policies) ? effect.metamodels?.policies : null;
+  if (!policies) return [];
+  const rules = [];
+  const add2 = (outcome, specs, prefix) => {
+    if (!Array.isArray(specs)) return;
+    specs.forEach((spec, index) => {
+      if (!isRecord(spec)) {
+        throw new Error(
+          `Manifest policy ${prefix}[${index}] for ${effect.effectKey} must be an object`
+        );
+      }
+      const condition = normalizeCondition(spec.when);
+      rules.push(
+        makeRule({
+          id: typeof spec.id === "string" ? spec.id : `manifest-${prefix}-${effect.effectKey}-${index + 1}`,
+          origin: { kind: "manifest", manifestId, effectKey: effect.effectKey },
+          outcome,
+          reason: typeof spec.reason === "string" ? spec.reason : void 0,
+          condition
+        })
+      );
+    });
+  };
+  add2("deny", policies.denyWhen, "denyWhen");
+  add2("confirm", policies.confirmWhen, "confirmWhen");
+  add2("allow", policies.allowWhen, "allowWhen");
+  return rules;
+}
+function inputSchemaHasField(effect, path7) {
+  if (path7.length === 0) return false;
+  const properties = isRecord(effect.inputSchema?.properties) ? effect.inputSchema?.properties : {};
+  return path7[0] in properties;
+}
+function validateLimitBands(effect, action, warnings) {
+  const limits = action.limits || [];
+  const byInput = /* @__PURE__ */ new Map();
+  limits.forEach((limit, index) => {
+    const path7 = normalizePath(limit.input);
+    if (path7.length === 0) {
+      throw new Error(`Limit ${index + 1} on ${action.action} requires input`);
+    }
+    if (!inputSchemaHasField(effect, path7)) {
+      throw new Error(
+        `Limit ${index + 1} on ${action.action} references unsupported input field "${path7.join(".")}"`
+      );
+    }
+    if (!normalizeDecision(limit.decision)) {
+      throw new Error(
+        `Limit ${index + 1} on ${action.action} has invalid decision`
+      );
+    }
+    if (limit.upTo === void 0 === (limit.above === void 0)) {
+      throw new Error(
+        `Limit ${index + 1} on ${action.action} must define exactly one of upTo or above`
+      );
+    }
+    if (limit.reason === void 0) {
+      warnings.push(`Limit ${index + 1} on ${action.action} has no reason`);
+    }
+    const key = path7.join(".");
+    byInput.set(key, [...byInput.get(key) || [], limit]);
+  });
+  for (const [input, bands] of byInput.entries()) {
+    const thresholds = /* @__PURE__ */ new Set();
+    let previousUpTo = -Infinity;
+    for (const band of bands) {
+      const value = band.upTo ?? band.above;
+      const key = `${band.upTo === void 0 ? "above" : "upTo"}:${value}`;
+      if (thresholds.has(key)) {
+        throw new Error(
+          `Duplicate limit threshold ${key} for input "${input}"`
+        );
+      }
+      thresholds.add(key);
+      if (band.upTo !== void 0) {
+        if (band.upTo < previousUpTo) {
+          throw new Error(`Unordered limit bands for input "${input}"`);
+        }
+        previousUpTo = band.upTo;
+      }
+    }
+  }
+}
+function compileProfileActionRules(input) {
+  const { profile, action, effect, warnings } = input;
+  const origin = {
+    kind: "permissionProfile",
+    profileName: action.ownerProfileName || profile.name,
+    source: profile.source || "permissionProfile"
+  };
+  const rules = [];
+  const baseId = action.id || `${profile.name}-${effect.effectKey}`;
+  if (action.allow === "always") {
+    rules.push(
+      makeRule({
+        id: `${baseId}-allow`,
+        origin,
+        outcome: "allow",
+        reason: action.reason
+      })
+    );
+  }
+  if (action.confirm === "always") {
+    rules.push(
+      makeRule({
+        id: `${baseId}-confirm`,
+        origin,
+        outcome: "confirm",
+        reason: action.reason
+      })
+    );
+  }
+  if (action.deny === "always") {
+    rules.push(
+      makeRule({
+        id: `${baseId}-deny`,
+        origin,
+        outcome: "deny",
+        reason: action.reason
+      })
+    );
+  }
+  const addConditional = (outcome, specs, suffix) => {
+    (specs || []).forEach((spec, index) => {
+      rules.push(
+        makeRule({
+          id: spec.id || `${baseId}-${suffix}-${index + 1}`,
+          origin,
+          outcome,
+          reason: spec.reason,
+          condition: normalizeCondition(spec.when)
+        })
+      );
+    });
+  };
+  addConditional("allow", action.allowWhen, "allowWhen");
+  addConditional("confirm", action.confirmWhen, "confirmWhen");
+  addConditional("deny", action.denyWhen, "denyWhen");
+  validateLimitBands(effect, action, warnings);
+  const previousUpToByInput = /* @__PURE__ */ new Map();
+  (action.limits || []).forEach((limit, index) => {
+    const path7 = normalizePath(limit.input);
+    const pathKey = path7.join(".");
+    const lowerBound = previousUpToByInput.get(pathKey);
+    const upperCondition = {
+      kind: "predicate",
+      source: "input",
+      path: path7,
+      operator: limit.upTo !== void 0 ? "lte" : "gt",
+      value: limit.upTo ?? limit.above
+    };
+    const condition = lowerBound !== void 0 && limit.upTo !== void 0 ? {
+      kind: "all",
+      conditions: [
+        {
+          kind: "predicate",
+          source: "input",
+          path: path7,
+          operator: "gt",
+          value: lowerBound
+        },
+        upperCondition
+      ]
+    } : upperCondition;
+    rules.push(
+      makeRule({
+        id: limit.id || `${baseId}-limit-${index + 1}`,
+        origin,
+        outcome: limit.decision,
+        reason: limit.reason,
+        condition
+      })
+    );
+    if (limit.upTo !== void 0) previousUpToByInput.set(pathKey, limit.upTo);
+  });
+  return rules;
+}
+function flattenProfiles(profiles, errors) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const profile of profiles) {
+    const name = normalizeProfileName(profile.name);
+    if (!name) {
+      errors.push(`Invalid permission profile name: ${String(profile.name)}`);
+      continue;
+    }
+    if (byName.has(name)) {
+      errors.push(`Duplicate permission profile name: ${name}`);
+      continue;
+    }
+    byName.set(name, {
+      ...profile,
+      name,
+      defaultsOwnerName: profile.defaultsOwnerName || name,
+      policies: (profile.policies || []).map((policy) => ({
+        ...policy,
+        ownerProfileName: policy.ownerProfileName || name
+      })),
+      actions: (profile.actions || []).map((action) => ({
+        ...action,
+        ownerProfileName: action.ownerProfileName || name
+      }))
+    });
+  }
+  const flattening = /* @__PURE__ */ new Set();
+  const flattened = /* @__PURE__ */ new Map();
+  const flatten = (name, depth) => {
+    if (depth > 5) {
+      errors.push(`Permission profile inheritance depth exceeds 5 at ${name}`);
+      return null;
+    }
+    const existing = flattened.get(name);
+    if (existing) return existing;
+    const profile = byName.get(name);
+    if (!profile) {
+      errors.push(`Missing parent permission profile: ${name}`);
+      return null;
+    }
+    if (flattening.has(name)) {
+      errors.push(`Permission profile inheritance cycle detected at ${name}`);
+      return null;
+    }
+    flattening.add(name);
+    let result = profile;
+    if (profile.extends) {
+      if (profile.defaults !== void 0) {
+        errors.push(
+          `Permission profile "${name}" extends "${profile.extends}" and cannot define defaults`
+        );
+      }
+      const parent = flatten(profile.extends, depth + 1);
+      if (parent) {
+        const actionMap = /* @__PURE__ */ new Map();
+        for (const action of parent.actions || []) {
+          actionMap.set(actionIdentity(action.action, action.on), action);
+        }
+        for (const action of profile.actions || []) {
+          actionMap.set(actionIdentity(action.action, action.on), action);
+        }
+        result = {
+          ...profile,
+          defaults: parent.defaults,
+          defaultsOwnerName: parent.defaultsOwnerName || parent.name,
+          policies: [...parent.policies || [], ...profile.policies || []],
+          actions: [...actionMap.values()]
+        };
+      }
+    }
+    flattening.delete(name);
+    flattened.set(name, result);
+    return result;
+  };
+  for (const name of byName.keys()) flatten(name, 0);
+  return [...flattened.values()];
+}
+function compileProfile(input) {
+  const { profile, effects: effects2, manifestRules, warnings } = input;
+  const defaultActionPolicy = normalizeDecision(profile.defaults?.actionPolicy) || "deny";
+  const actionRules = {};
+  const addRules = (effectKey, rules) => {
+    if (rules.length === 0) return;
+    actionRules[effectKey] = [...actionRules[effectKey] || [], ...rules];
+  };
+  for (const policy of profile.policies || []) {
+    const outcome = normalizeDecision(policy.outcome || policy.decision);
+    if (!outcome)
+      throw new Error(
+        `Profile "${profile.name}" has a policy with invalid decision`
+      );
+    const condition = normalizeCondition(policy.when);
+    const targetEffects = policy.action ? [resolveEffectReference(effects2, policy.action, policy.on)] : effects2;
+    for (const effect of targetEffects) {
+      addRules(effect.effectKey, [
+        makeRule({
+          id: policy.id || `${profile.name}-${effect.effectKey}-profile-policy`,
+          origin: {
+            kind: "permissionProfile",
+            profileName: policy.ownerProfileName || profile.name,
+            source: profile.source || "permissionProfile"
+          },
+          outcome,
+          reason: policy.reason,
+          condition
+        })
+      ]);
+    }
+  }
+  for (const action of profile.actions || []) {
+    const effect = resolveEffectReference(effects2, action.action, action.on);
+    addRules(
+      effect.effectKey,
+      compileProfileActionRules({ profile, action, effect, warnings })
+    );
+  }
+  const actionVisibility = effects2.filter((effect) => {
+    const rules = actionRules[effect.effectKey] || [];
+    const denyVisibilityRules = [
+      ...manifestRules[effect.effectKey] || [],
+      ...rules
+    ];
+    if (denyVisibilityRules.some(
+      (rule) => rule.outcome === "deny" && rule.condition.kind === "always"
+    )) {
+      return false;
+    }
+    if (defaultActionPolicy === "allow" || defaultActionPolicy === "confirm")
+      return true;
+    return denyVisibilityRules.some(
+      (rule) => rule.outcome === "allow" || rule.outcome === "confirm"
+    );
+  }).map((effect) => effect.effectKey).sort();
+  const summaries = Object.entries(actionRules).flatMap(
+    ([effectKey, rules]) => rules.map((rule) => `${effectKey}: ${rule.summary}`)
+  ).sort();
+  return {
+    name: profile.name,
+    label: profile.label,
+    description: profile.description,
+    source: profile.source || "permissionProfile",
+    sourcePath: profile.sourcePath,
+    defaultActionPolicy,
+    defaultActionPolicyOwner: profile.defaultsOwnerName || profile.name,
+    digest: "",
+    actionRules,
+    actionVisibility,
+    summaries,
+    flattened: profile
+  };
+}
+function normalizeSourceProfiles(sources) {
+  const sourceProfiles = (sources || []).filter((profile) => isRecord(profile)).map((profile) => ({
+    ...profile,
+    source: profile.source || "permissionProfile"
+  }));
+  const nonBuiltin = sourceProfiles.filter(
+    (profile) => !BUILTIN_PROFILE_NAMES.includes(
+      profile.name
+    )
+  );
+  return [...getBuiltinPermissionProfiles(), ...nonBuiltin];
+}
+async function compilePolicyBundle(input) {
+  const errors = [];
+  const warnings = [];
+  const effects2 = [...input.effects].sort(
+    (left, right) => left.effectKey.localeCompare(right.effectKey)
+  );
+  const profiles = flattenProfiles(
+    normalizeSourceProfiles(input.profileSources),
+    errors
+  );
+  const manifestRules = {};
+  for (const effect of effects2) {
+    try {
+      const rules = manifestPolicyRulesForEffect(effect, input.manifestId);
+      if (rules.length > 0) manifestRules[effect.effectKey] = rules;
+    } catch (error2) {
+      errors.push(String(error2 instanceof Error ? error2.message : error2));
+    }
+  }
+  const compiledProfiles = {};
+  for (const profile of profiles) {
+    try {
+      const defaultActionPolicy = profile.defaults?.actionPolicy;
+      if (defaultActionPolicy !== void 0 && !normalizeDecision(defaultActionPolicy)) {
+        throw new Error(
+          `Permission profile "${profile.name}" has invalid defaults.actionPolicy`
+        );
+      }
+      const compiled = compileProfile({
+        profile,
+        effects: effects2,
+        manifestRules,
+        warnings
+      });
+      compiled.digest = await digestJson({
+        profile: compiled.flattened,
+        actionRules: compiled.actionRules,
+        defaultActionPolicy: compiled.defaultActionPolicy
+      });
+      compiledProfiles[profile.name] = compiled;
+    } catch (error2) {
+      errors.push(String(error2 instanceof Error ? error2.message : error2));
+    }
+  }
+  const permissionProfilesDigest = await digestJson(
+    Object.values(compiledProfiles).map((profile) => ({
+      name: profile.name,
+      digest: profile.digest,
+      source: profile.source
+    }))
+  );
+  const bundleWithoutDigest = {
+    schemaVersion: 1,
+    buildId: input.buildId,
+    sandboxId: input.sandboxId,
+    manifestDigest: input.manifestDigest,
+    permissionProfilesDigest,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    effects: effects2.map((effect) => ({
+      effectKey: effect.effectKey,
+      name: effect.name,
+      attachedClass: normalizeAttachedClass(effect.attachedClass),
+      isStatic: effect.isStatic === true
+    })),
+    manifestRules,
+    profiles: compiledProfiles
+  };
+  const bundleDigest = await digestJson(bundleWithoutDigest);
+  return {
+    bundle: { ...bundleWithoutDigest, bundleDigest },
+    errors,
+    warnings
+  };
+}
+function evaluateCompiledPolicyBundle(input) {
+  const profile = input.bundle.profiles[input.profileName];
+  if (!profile) {
+    return {
+      outcome: "deny",
+      matches: [
+        {
+          id: "missing-profile",
+          outcome: "deny",
+          origin: {
+            kind: "permissionProfile",
+            profileName: input.profileName,
+            source: "permissionProfile"
+          },
+          reason: `Permission profile "${input.profileName}" does not exist in this version`,
+          summary: `Permission profile "${input.profileName}" does not exist in this version`
+        }
+      ]
+    };
+  }
+  if (!profile.actionVisibility.includes(input.effectKey)) {
+    return {
+      outcome: "deny",
+      matches: [
+        {
+          id: "action-not-visible",
+          outcome: "deny",
+          origin: {
+            kind: "permissionProfile",
+            profileName: input.profileName,
+            source: profile.source
+          },
+          reason: `Action ${input.effectKey} is not visible for ${input.profileName}`,
+          summary: `Action ${input.effectKey} is not visible for ${input.profileName}`
+        }
+      ]
+    };
+  }
+  const decision = evaluatePolicies({
+    manifestRules: input.bundle.manifestRules[input.effectKey] || [],
+    profileRules: profile.actionRules[input.effectKey] || [],
+    defaultActionPolicy: profile.defaultActionPolicy,
+    context: input.context
+  });
+  return {
+    outcome: decision.outcome,
+    matches: decision.matches.map(
+      (match) => match.id === `profile-default-${decision.outcome}` ? {
+        ...match,
+        origin: {
+          kind: "permissionProfile",
+          profileName: profile.name,
+          source: profile.source
+        }
+      } : match
+    )
+  };
+}
+function extractManifestEffects(manifest) {
+  const effects2 = [];
+  for (const volume of manifest.volumes || []) {
+    for (const operation of volume.operations || []) {
+      const effect = operation.withEffect;
+      if (!effect?.name) continue;
+      const attachedClass = normalizeAttachedClass(effect.attachedClass);
+      const effectKey = attachedClass ? effect.isStatic ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}` : `global:${effect.name}`;
+      effects2.push({
+        effectKey,
+        name: effect.name,
+        attachedClass,
+        isStatic: effect.isStatic === true,
+        inputSchema: effect.inputSchema || null,
+        metamodels: effect.metamodels || null
+      });
+    }
+  }
+  return effects2;
+}
+
 // src/cli/config.ts
 var MANIFEST_FILE = "granular.json";
 var RC_FILE = ".granularrc";
 var ENV_LOCAL_FILE = ".env.local";
+var PERMISSIONS_DIR = "permissions";
 function getProjectRoot() {
   return process.cwd();
 }
@@ -6785,6 +7614,9 @@ function getRcPath() {
 function getEnvLocalPath() {
   return path3__namespace.join(getProjectRoot(), ENV_LOCAL_FILE);
 }
+function getPermissionsDir() {
+  return path3__namespace.join(getProjectRoot(), PERMISSIONS_DIR);
+}
 function readManifestFile() {
   const filePath = getManifestPath();
   if (!fs__namespace.existsSync(filePath)) return null;
@@ -6799,6 +7631,40 @@ function writeManifestFile(project) {
   const filePath = getManifestPath();
   fs__namespace.writeFileSync(filePath, JSON.stringify(project, null, 2) + "\n", "utf-8");
 }
+function ensureBuiltinPermissionFiles() {
+  const permissionsDir = getPermissionsDir();
+  if (!fs__namespace.existsSync(permissionsDir)) {
+    fs__namespace.mkdirSync(permissionsDir, { recursive: true });
+  }
+  for (const profile of getBuiltinPermissionProfiles()) {
+    const filePath = path3__namespace.join(permissionsDir, `${profile.name}.json`);
+    if (!fs__namespace.existsSync(filePath)) {
+      fs__namespace.writeFileSync(filePath, JSON.stringify(profile, null, 2) + "\n", "utf-8");
+    }
+  }
+}
+function readPermissionProfileFiles() {
+  const permissionsDir = getPermissionsDir();
+  if (!fs__namespace.existsSync(permissionsDir)) {
+    return getBuiltinPermissionProfiles();
+  }
+  const profiles = [];
+  const entries = fs__namespace.readdirSync(permissionsDir).filter((entry) => entry.endsWith(".json")).sort();
+  for (const entry of entries) {
+    const filePath = path3__namespace.join(permissionsDir, entry);
+    const raw = fs__namespace.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    profiles.push({
+      ...parsed,
+      name: parsed.name || entry.replace(/\.json$/, ""),
+      sourcePath: path3__namespace.relative(getProjectRoot(), filePath)
+    });
+  }
+  if (profiles.length === 0) {
+    return getBuiltinPermissionProfiles();
+  }
+  return profiles;
+}
 function manifestExists() {
   return fs__namespace.existsSync(getManifestPath());
 }
@@ -6926,8 +7792,8 @@ var ApiClient = class {
     this.apiKey = resolveAuthTokenForApiUrl(apiKey, apiUrl);
     this.baseUrl = apiUrl.replace("wss://", "https://").replace("ws://", "http://").replace(/\/ws$/, "");
   }
-  async request(path6, options = {}) {
-    const url = `${this.baseUrl}${path6}`;
+  async request(path7, options = {}) {
+    const url = `${this.baseUrl}${path7}`;
     const response = await fetch(url, {
       ...options,
       headers: {
@@ -7098,31 +7964,52 @@ var ApiClient = class {
   }
   // ── Permission Profiles ──
   async createPermissionProfile(sandboxId, data) {
+    const profile = {
+      ...data.rules,
+      schemaVersion: 1,
+      name: data.name
+    };
+    const result = await this.syncPermissionProfileSources(sandboxId, [profile]);
+    const synced = result.items?.find((item) => item.name === data.name) || result.items?.[0];
+    if (!synced) {
+      throw new Error(`Permission profile source sync did not return ${data.name}`);
+    }
+    return synced;
+  }
+  async ensureDefaultProfile(sandboxId) {
+    return await this.createPermissionProfile(sandboxId, {
+      name: "allow-all",
+      rules: {
+        schemaVersion: 1,
+        name: "allow-all",
+        description: "Every declared action is visible unless a manifest policy denies it.",
+        defaults: { actionPolicy: "allow" },
+        actions: []
+      }
+    });
+  }
+  async syncPermissionProfileSources(sandboxId, profiles) {
     return this.request(
-      `/control/sandboxes/${sandboxId}/permission-profiles`,
+      `/control/sandboxes/${sandboxId}/permission-profile-sources`,
       {
-        method: "POST",
-        body: JSON.stringify(data)
+        method: "PUT",
+        body: JSON.stringify({ profiles })
       }
     );
   }
-  async ensureDefaultProfile(sandboxId) {
-    try {
-      return await this.createPermissionProfile(sandboxId, {
-        name: "default",
-        rules: {
-          effects: { allow: ["*"] },
-          resources: { allow: ["*"] }
-        }
-      });
-    } catch {
-      const profiles = await this.request(
-        `/control/sandboxes/${sandboxId}/permission-profiles`
-      );
-      const existing = profiles.items.find((p) => p.name === "default");
-      if (existing) return existing;
-      throw new Error("Could not create or find default permission profile");
-    }
+  async getVersionPolicies(versionId) {
+    return this.request(`/control/ontology-versions/${versionId}/policies`);
+  }
+  async getVersionPermissionProfiles(versionId) {
+    return this.request(
+      `/control/ontology-versions/${versionId}/permission-profiles`
+    );
+  }
+  async evaluateVersionPolicy(versionId, request) {
+    return this.request(`/control/builds/${versionId}/policies/evaluate`, {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
   }
   // ── Subjects ──
   async createSubject(identityId, name) {
@@ -9521,8 +10408,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path6, errorMaps, issueData } = params;
-  const fullPath = [...path6, ...issueData.path || []];
+  const { data, path: path7, errorMaps, issueData } = params;
+  const fullPath = [...path7, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -9638,11 +10525,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path6, key) {
+  constructor(parent, value, path7, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path6;
+    this._path = path7;
     this._key = key;
   }
   get path() {
@@ -13148,6 +14035,67 @@ external_exports.object({
   transitions: external_exports.array(StateMachineTransitionSchema),
   finalStates: external_exports.array(external_exports.string()).optional()
 }).strict();
+var POLICY_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "contains",
+  "not_contains",
+  "starts_with",
+  "ends_with",
+  "exists"
+];
+var PolicyPredicateSchema = external_exports.object({
+  path: external_exports.union([external_exports.string(), external_exports.array(external_exports.string())]).optional(),
+  field: external_exports.string().optional(),
+  input: external_exports.string().optional(),
+  operator: external_exports.enum([...POLICY_OPERATORS]),
+  stringValue: external_exports.string().optional(),
+  numberValue: external_exports.number().optional(),
+  booleanValue: external_exports.boolean().optional(),
+  value: external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]).optional()
+}).strict();
+var PolicyStateMachinePredicateSchema = external_exports.object({
+  machine: external_exports.string().min(1),
+  operator: external_exports.enum([...POLICY_OPERATORS]),
+  state: external_exports.string().optional(),
+  stringValue: external_exports.string().optional()
+}).strict();
+var PolicyConditionSchema = external_exports.lazy(
+  () => external_exports.object({
+    all: external_exports.array(PolicyConditionSchema).optional(),
+    any: external_exports.array(PolicyConditionSchema).optional(),
+    not: PolicyConditionSchema.optional(),
+    input: PolicyPredicateSchema.optional(),
+    object: PolicyPredicateSchema.optional(),
+    stateMachine: PolicyStateMachinePredicateSchema.optional()
+  }).strict().refine(
+    (data) => [
+      data.all,
+      data.any,
+      data.not,
+      data.input,
+      data.object,
+      data.stateMachine
+    ].filter((value) => value !== void 0).length === 1,
+    {
+      message: "Policy condition must define exactly one of all, any, not, input, object, or stateMachine"
+    }
+  )
+);
+var PolicyRuleSchema = external_exports.object({
+  id: external_exports.string().min(1).optional(),
+  reason: external_exports.string().optional(),
+  when: PolicyConditionSchema
+}).strict();
+var PoliciesSchema = external_exports.object({
+  allowWhen: external_exports.array(PolicyRuleSchema).optional(),
+  confirmWhen: external_exports.array(PolicyRuleSchema).optional(),
+  denyWhen: external_exports.array(PolicyRuleSchema).optional()
+}).strict();
 external_exports.object({
   postCondition: external_exports.union([
     external_exports.string(),
@@ -13177,7 +14125,8 @@ external_exports.object({
       reason: external_exports.string().optional(),
       mode: external_exports.string().optional()
     }).strict()
-  ]).optional()
+  ]).optional(),
+  policies: PoliciesSchema.optional()
 }).strict();
 
 // ../metamodel-core/src/index.ts
@@ -14046,6 +14995,54 @@ var noteMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// ../metamodel-policy/src/index.ts
+function escapeGraphqlString(value) {
+  return JSON.stringify(value);
+}
+function buildPolicyMutations(effectKey, spec) {
+  const policies = spec.policies;
+  if (!policies) return [];
+  const mutations = [];
+  const addRules = (key, outcome) => {
+    const rules = policies[key] || [];
+    rules.forEach((rule, index) => {
+      const condition = normalizeCondition(rule.when);
+      const summary = rule.reason || summarizeCondition(condition);
+      const id = rule.id || `${effectKey}:${outcome}:${index + 1}`;
+      mutations.push({
+        label: `set policy ${outcome} on ${effectKey}`,
+        query: `mutation { set_policy_rule(effect_key: ${escapeGraphqlString(effectKey)}, policy_id: ${escapeGraphqlString(id)}, outcome: ${escapeGraphqlString(outcome)}, reason: ${escapeGraphqlString(summary)}, condition_json: ${escapeGraphqlString(JSON.stringify(condition))}) }`
+      });
+    });
+  };
+  addRules("allowWhen", "allow");
+  addRules("confirmWhen", "confirm");
+  addRules("denyWhen", "deny");
+  return mutations;
+}
+var policyMetamodelPackage = defineMetamodelPackage({
+  id: "policy",
+  manifest: {
+    buildEffectMutations: buildPolicyMutations
+  },
+  summary: {
+    selections: {
+      methodFields: ["policies"]
+    },
+    readMethodSummary(rawMethod) {
+      return rawMethod.policies ? { metamodels: { policies: rawMethod.policies } } : {};
+    }
+  },
+  docs: {
+    effectRows: [
+      {
+        key: "policies",
+        description: "Universal effect policies with allowWhen, confirmWhen, and denyWhen structural conditions."
+      }
+    ]
+  }
+});
+
 // ../metamodel-required/src/index.ts
 function buildRequiredFieldMutations(fieldPath, required) {
   if (!required) return [];
@@ -14820,7 +15817,8 @@ var DEFAULT_METAMODEL_PACKAGES = [
   searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
-  effectBehaviorsMetamodelPackage
+  effectBehaviorsMetamodelPackage,
+  policyMetamodelPackage
 ];
 var DEFAULT_METAMODEL_REGISTRY = createMetamodelRegistry(
   DEFAULT_METAMODEL_PACKAGES
@@ -15126,7 +16124,112 @@ Example:
 
 **Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.ontology(sandboxId).effects.registerMany([...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
 
-**Permissions:** \`openEnvironment({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
+**Permissions:** \`openEnvironment({ permissions: [...] })\` assigns one permission profile for the environment/session. Profile files live in \`permissions/*.json\`, are synced by \`granular build\` / \`granular deploy\`, are compiled into the ontology version, and decide whether each generated action is visible, allowed, confirmed, or denied.
+
+### Manifest logic policies
+
+Use \`withEffect.metamodels.policies\` for product-wide guardrails that apply to every profile. Manifest policies are strongest for rules such as \u201Clocked objects cannot be changed\u201D or \u201Cexternal payments need confirmation.\u201D
+
+\`\`\`json
+{
+  "withEffect": {
+    "name": "approve_ticket",
+    "attachedClass": "ticket",
+    "inputSchema": { "type": "object", "properties": { "note": { "type": "string" } } },
+    "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" } } },
+    "metamodels": {
+      "policies": {
+        "denyWhen": [
+          {
+            "id": "locked-ticket-deny",
+            "reason": "Locked tickets cannot be approved",
+            "when": {
+              "object": { "path": "locked", "operator": "eq", "booleanValue": true }
+            }
+          }
+        ],
+        "confirmWhen": [
+          {
+            "id": "high-risk-confirm",
+            "reason": "High-risk active tickets require confirmation",
+            "when": {
+              "all": [
+                { "object": { "path": "risk_score", "operator": "gt", "numberValue": 50 } },
+                { "stateMachine": { "machine": "lifecycle", "operator": "eq", "stringValue": "active" } }
+              ]
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+\`\`\`
+
+### Permission profile files
+
+Each file under \`permissions/\` defines one role/profile. Built-ins are \`allow-all\`, \`confirm-all\`, and \`deny-all\`; \`granular init\` and \`granular pull\` materialize them as files.
+
+\`\`\`json
+{
+  "schemaVersion": 1,
+  "name": "reviewer",
+  "description": "Reviewer can comment and conditionally approve tickets",
+  "defaults": { "actionPolicy": "deny" },
+  "policies": [
+    {
+      "id": "reviewer-low-risk-allow",
+      "action": "approve_ticket",
+      "on": "ticket",
+      "decision": "allow",
+      "reason": "Active low-risk tickets can be approved by reviewers",
+      "when": {
+        "all": [
+          { "object": { "path": "risk_score", "operator": "lte", "numberValue": 50 } },
+          { "stateMachine": { "machine": "lifecycle", "operator": "eq", "stringValue": "active" } },
+          { "not": { "object": { "path": "locked", "operator": "eq", "booleanValue": true } } }
+        ]
+      }
+    }
+  ],
+  "actions": [
+    {
+      "action": "comment_ticket",
+      "on": "ticket",
+      "allow": "always",
+      "reason": "Reviewers can comment on tickets"
+    }
+  ]
+}
+\`\`\`
+
+Profile rules:
+
+- \`defaults.actionPolicy\` is \`allow\`, \`confirm\`, or \`deny\`; omitted means \`deny\`.
+- \`policies[]\` can target one action with \`action\` + optional \`on\`, or all declared actions if \`action\` is omitted.
+- \`actions[]\` supports \`allow: "always"\`, \`confirm: "always"\`, \`deny: "always"\`, \`allowWhen\`, \`confirmWhen\`, \`denyWhen\`, and numeric \`limits\`.
+- \`limits\` is a shorthand over numeric input fields: \`{ "input": "amount", "upTo": 500, "decision": "allow" }\` and \`{ "input": "amount", "above": 5000, "decision": "deny" }\`.
+- \`extends\` inherits exactly one parent profile. A child profile cannot define its own \`defaults\`; it can add rules and override action rules by the same \`{ action, on }\`.
+
+Condition sources:
+
+- \`input\`: the action input passed by job code.
+- \`object\`: fields on the target object for instance effects.
+- \`stateMachine\`: current state of a workflow attached to the target object.
+- Logical composition: \`all\`, \`any\`, and \`not\`.
+
+Decision precedence is deterministic: manifest \`deny\`, profile \`deny\`, manifest/profile \`confirm\`, profile \`allow\`, then the profile default. Runtime blocks \`deny\` before provider invocation and asks a human confirmation for \`confirm\`.
+
+Useful commands:
+
+\`\`\`bash
+granular permissions validate
+granular permissions preview --profile reviewer --action approve_ticket --on ticket \\
+  --input '{"note":"ok"}' \\
+  --object '{"risk_score":40,"locked":false}' \\
+  --state-machines '{"lifecycle":"active"}'
+granular build
+\`\`\`
 
 ### Effect metamodels
 
@@ -15247,6 +16350,8 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 | \`granular build\` | Upload \`granular.json\`, create or reuse the matching ontology version, and run the build (**validation**). |
 | \`granular deploy\` | Push the current revision, build it, and update \`dev\`. |
 | \`granular deploy --prod\` | If the current version is already on \`dev\`, also point \`prod\` to it. Otherwise build it, then point both \`dev\` and \`prod\` to it. |
+| \`granular permissions validate\` | Validate \`permissions/*.json\` against local \`granular.json\`, including action references, inheritance, limits, and conditions. |
+| \`granular permissions preview --profile <name> --action <name> [--on <class>] [--input '{}'] [--object '{}'] [--state-machines '{}'] [--version-id <id>]\` | Preview the exact \`allow\` / \`confirm\` / \`deny\` decision locally or against a compiled version. |
 | \`granular version current --json\` | Resolve the latest/current ontology version for agent workflows. |
 | \`granular version diff\` | Show the semantic diff between ontology versions. |
 | \`granular tag move\` | Move \`dev\`, \`prod\`, or another tag to a chosen version. |
@@ -15261,7 +16366,7 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 | \`granular graphql --query '...' --json\` | Run a GraphQL query or mutation against the live graph. |
 | \`granular effects list/diff --json\` | Inspect declared versus live ready effects. |
 | \`granular job run --file ./job.ts --json\` | Execute a real runtime job from the terminal or CI. |
-| \`granular pull <version>\` | Pull the manifest for a specific ontology version. |
+| \`granular pull <version>\` | Pull the manifest and versioned \`permissions/*.json\` files for a specific ontology version. |
 | \`granular login\`, \`granular whoami\`, \`granular status --verbose --json\` | Auth, config, and project info. |
 
 ---
@@ -15428,7 +16533,7 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push(`  ontology: '${meta.sandboxId}',`);
   lines.push(`  tag: 'dev',`);
   lines.push(`  userId: 'your_app_user_id',`);
-  lines.push(`  permissions: ['default'],`);
+  lines.push(`  permissions: ['allow-all'],`);
   lines.push(`});`);
   lines.push("```");
   lines.push("");
@@ -15978,7 +17083,7 @@ Use this when proving that the ontology works in real runtime conditions.
 
 - Load \`GRANULAR_API_KEY\` from environment when running unattended tests.
 - Read the ontology id from \`.granularrc\` if the repo uses \`granular init\`.
-- Connect with \`new Granular({ apiKey }).connect({ ontology, environment: 'dev', userId, permissions: ['default'] })\`.
+- Connect with \`new Granular({ apiKey }).connect({ ontology, environment: 'dev', userId, permissions: ['allow-all'] })\`.
 - Assert on real behavior rather than giant snapshots.
 
 # What to verify
@@ -16725,9 +17830,11 @@ async function initCommand(projectName, options) {
   }
   const project = createDefaultManifest(name, templateId);
   writeManifestFile(project);
+  ensureBuiltinPermissionFiles();
   success(
     `Created ${brand.bold("granular.json")} with the ${template.label} starter ontology`
   );
+  success(`Created ${brand.bold("permissions/")} with built-in profiles`);
   writeRcFile({
     sandboxId: sandbox.sandboxId,
     sandboxName: sandbox.name,
@@ -17060,8 +18167,32 @@ async function loginCommand(options = {}) {
   dim("API key saved to .env.local (used by CLI and SDK examples)");
   console.log();
 }
-
-// src/cli/commands/pull.ts
+function cleanPermissionProfile(profile) {
+  const {
+    source,
+    sourcePath,
+    defaultsOwnerName,
+    ...rest
+  } = profile;
+  return rest;
+}
+function writePermissionProfileFiles(profiles) {
+  const permissionsDir = getPermissionsDir();
+  fs__namespace.mkdirSync(permissionsDir, { recursive: true });
+  const written = [];
+  for (const profile of profiles) {
+    if (!profile?.name) continue;
+    const fileName = `${profile.name}.json`;
+    const filePath = path3__namespace.join(permissionsDir, fileName);
+    fs__namespace.writeFileSync(
+      filePath,
+      JSON.stringify(cleanPermissionProfile(profile), null, 2) + "\n",
+      "utf-8"
+    );
+    written.push(path3__namespace.join("permissions", fileName));
+  }
+  return written.sort();
+}
 async function pullCommand(versionId) {
   printHeader();
   const config = resolveConfig({ requireApiKey: true });
@@ -17085,13 +18216,18 @@ async function pullCommand(versionId) {
       manifest: full.content
     };
     writeManifestFile(project);
+    spin.text = "  Downloading permission profile files...";
+    const profileVersions = await api.getVersionPermissionProfiles(versionId);
+    const pulledProfiles = (profileVersions.items || []).map((item) => item.profile).filter((profile) => Boolean(profile?.name));
+    const writtenProfiles = writePermissionProfileFiles(pulledProfiles);
     spin.succeed("  Manifest pulled successfully.");
     console.log();
     keyValue({
       "Manifest ID": full.manifestId,
       "Source Version": versionId,
       "Version": targetVersionLabel,
-      "Written to": "granular.json"
+      "Written to": "granular.json",
+      "Permission profiles": writtenProfiles.length > 0 ? writtenProfiles.join(", ") : "none"
     });
     console.log();
   } catch (err) {
@@ -17110,6 +18246,28 @@ async function buildCommand() {
   }
   const api = new ApiClient(config.apiKey, config.apiUrl);
   const manifest = config.project.manifest;
+  const permissionProfiles = readPermissionProfileFiles();
+  const localPolicyValidation = await compilePolicyBundle({
+    sandboxId: config.sandboxId,
+    manifestDigest: void 0,
+    effects: extractManifestEffects(manifest),
+    profileSources: permissionProfiles
+  });
+  if (localPolicyValidation.errors.length > 0) {
+    error("Permission policy validation failed:");
+    for (const error2 of localPolicyValidation.errors) {
+      error(`  ${error2}`);
+    }
+    process.exit(1);
+  }
+  const syncingProfiles = spinner(`Syncing ${permissionProfiles.length} permission profile file(s)...`);
+  try {
+    const result = await api.syncPermissionProfileSources(config.sandboxId, permissionProfiles);
+    syncingProfiles.succeed(`  Permission profiles synced: ${brand.secondary(result.digest)}`);
+  } catch (err) {
+    syncingProfiles.fail(`  Failed to sync permission profiles: ${err.message}`);
+    process.exit(1);
+  }
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
   let uploadedManifest;
   try {
@@ -17184,6 +18342,25 @@ async function deployCommand(options = {}) {
   step(options.prod ? "Deploy to dev and prod" : "Deploy to dev", `Sandbox ${config.sandboxId}`);
   console.log();
   const manifest = config.project.manifest;
+  const permissionProfiles = readPermissionProfileFiles();
+  const localPolicyValidation = await compilePolicyBundle({
+    sandboxId: config.sandboxId,
+    effects: extractManifestEffects(manifest),
+    profileSources: permissionProfiles
+  });
+  if (localPolicyValidation.errors.length > 0) {
+    error("Permission policy validation failed:");
+    for (const error2 of localPolicyValidation.errors) error(`  ${error2}`);
+    process.exit(1);
+  }
+  const syncingProfiles = spinner(`Syncing ${permissionProfiles.length} permission profile file(s)...`);
+  try {
+    const result = await api.syncPermissionProfileSources(config.sandboxId, permissionProfiles);
+    syncingProfiles.succeed(`  Permission profiles synced: ${brand.secondary(result.digest)}`);
+  } catch (err) {
+    syncingProfiles.fail(`  Failed to sync permission profiles: ${err.message}`);
+    process.exit(1);
+  }
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
   let uploadedManifest;
   try {
@@ -17726,11 +18903,22 @@ var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
 var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
 var MAX_TIMER_DELAY_MS = 2147483647;
 var DEBUG_WS = process.env.GRANULAR_DEBUG_WS === "1";
+var DEFAULT_RPC_TIMEOUT_MS = 3e4;
+var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
   }
 }
+function rpcTimeoutMsForMethod(method) {
+  switch (method) {
+    case "domain.fetchPackagePart":
+    case "domain.getSummary":
+      return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
+    default:
+      return DEFAULT_RPC_TIMEOUT_MS;
+  }
+}
 var WSClient = class {
   ws = null;
   url;
@@ -18155,13 +19343,14 @@ var WSClient = class {
     return new Promise((resolve2, reject) => {
       this.messageQueue.push({ resolve: resolve2, reject, id });
       this.ws.send(JSON.stringify(request));
+      const timeoutMs = rpcTimeoutMsForMethod(method);
       setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
           this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
           reject(new Error(`RPC timeout: ${method}`));
         }
-      }, 3e4);
+      }, timeoutMs);
     });
   }
   async handleIncomingRpc(request) {
@@ -18275,10 +19464,48 @@ function normalizePromptText(value) {
 function extractPromptTokens(value) {
   return normalizePromptText(value).split(/\s+/).map((token) => token.trim()).filter((token) => token.length > 0);
 }
+function parseJsonPromptChoiceOption(option) {
+  const trimmed = option.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return asRecord(parsed);
+  } catch {
+    return null;
+  }
+}
+function normalizePromptChoiceOption(option) {
+  if (typeof option === "string") {
+    const record2 = parseJsonPromptChoiceOption(option);
+    if (!record2) {
+      return { value: option, label: option };
+    }
+    const value2 = typeof record2.value === "string" ? record2.value : typeof record2.id === "string" ? record2.id : typeof record2.label === "string" ? record2.label : JSON.stringify(record2);
+    return {
+      value: value2,
+      label: typeof record2.label === "string" ? record2.label : value2,
+      description: typeof record2.description === "string" ? record2.description : void 0
+    };
+  }
+  const record = option;
+  if (!record) {
+    return { value: "", label: "" };
+  }
+  const nestedJson = (typeof record.value === "string" ? parseJsonPromptChoiceOption(record.value) : null) || (typeof record.label === "string" ? parseJsonPromptChoiceOption(record.label) : null);
+  if (nestedJson) {
+    return normalizePromptChoiceOption(nestedJson);
+  }
+  const value = typeof record.value === "string" ? record.value : typeof record.label === "string" ? record.label : JSON.stringify(record);
+  return {
+    value,
+    label: typeof record.label === "string" ? record.label : value,
+    description: typeof record.description === "string" ? record.description : void 0
+  };
+}
 function scorePromptChoiceMatch(answer, answerTokens, option) {
-  const value = typeof option === "string" ? option : typeof option?.value === "string" ? option.value : "";
-  const label = typeof option === "string" ? option : typeof option?.label === "string" ? option.label : "";
-  const description = typeof option === "string" ? "" : typeof option?.description === "string" ? option.description : "";
+  const choice = normalizePromptChoiceOption(option);
+  const { value, label } = choice;
+  const description = choice.description || "";
   const haystack = normalizePromptText([value, label, description].filter(Boolean).join(" "));
   if (!haystack) return { score: 0, resolvedValue: value || label || null };
   let score = 0;
@@ -18314,7 +19541,9 @@ function normalizePrompt(rawValue) {
     type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
-    options: Array.isArray(source.options) ? source.options : void 0,
+    options: Array.isArray(source.options) ? source.options.map(
+      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(option) : option
+    ) : void 0,
     defaultValue: source.defaultValue,
     placeholder: typeof source.placeholder === "string" ? source.placeholder : void 0,
     allowEmpty: typeof source.allowEmpty === "boolean" ? source.allowEmpty : void 0,
@@ -18342,6 +19571,22 @@ function resolvePromptAnswer(prompt3, answer) {
 }
 
 // src/session.ts
+var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
+function withPromptTranscriptTimeout(promise) {
+  let timeout = null;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timeout = setTimeout(() => {
+        reject(new Error("Timed out appending prompt answer transcript."));
+      }, PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS);
+    })
+  ]).finally(() => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  });
+}
 var Session = class {
   client;
   clientId;
@@ -18358,6 +19603,8 @@ var Session = class {
   lastKnownTools = /* @__PURE__ */ new Map();
   /** Last seen live prompts, keyed by prompt id, for answer normalization */
   promptCache = /* @__PURE__ */ new Map();
+  /** Prompt ids locally answered before the document sync catches up. */
+  hiddenPromptIds = /* @__PURE__ */ new Set();
   constructor(client, clientId) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
@@ -18493,8 +19740,9 @@ var Session = class {
    * `effect.invoke` RPC back to the sandbox effect host, where the registered handlers
    * execute locally and return the result to the sandbox.
    */
-  async submitJob(code, domainRevision) {
-    let revision = domainRevision || this.currentDomainRevision || this.extractDomainRevisionFromDoc(this.client.doc) || void 0;
+  async submitJob(code, domainRevisionOrOptions) {
+    const options = typeof domainRevisionOrOptions === "string" ? { domainRevision: domainRevisionOrOptions } : domainRevisionOrOptions || {};
+    let revision = options.domainRevision || this.currentDomainRevision || this.extractDomainRevisionFromDoc(this.client.doc) || void 0;
     if (!revision) {
       try {
         const summary = await this.getDomain();
@@ -18509,7 +19757,9 @@ var Session = class {
     }
     const result = await this.client.call("job.submit", {
       domainRevision: revision,
-      code
+      code,
+      metadata: options.metadata,
+      agent: options.agent
     });
     if (!result.jobId) {
       throw new Error("Failed to submit job: no jobId returned");
@@ -18550,25 +19800,39 @@ var Session = class {
     const prompt3 = this.promptCache.get(promptId);
     const resolvedAnswer = resolvePromptAnswer(prompt3, answer);
     this.promptCache.delete(promptId);
-    await this.client.call("prompt.answer", {
-      promptId,
-      answer: resolvedAnswer,
-      value: resolvedAnswer
-    });
+    this.hiddenPromptIds.add(promptId);
+    try {
+      await this.client.call("prompt.answer", {
+        promptId,
+        answer: resolvedAnswer,
+        value: resolvedAnswer
+      });
+    } catch (error2) {
+      this.hiddenPromptIds.delete(promptId);
+      if (prompt3) {
+        this.promptCache.set(promptId, prompt3);
+      }
+      throw error2;
+    }
     try {
       const content = this.stringifyConversationValue(resolvedAnswer);
       if (content.trim()) {
-        await this.appendConversationMessage({
-          role: "user",
-          content,
-          promptId
-        });
+        await withPromptTranscriptTimeout(
+          this.appendConversationMessage({
+            role: "user",
+            content,
+            promptId
+          })
+        );
       }
     } catch {
     }
   }
   async appendConversationMessage(input) {
-    return this.client.call("conversation.append", input);
+    return this.client.call(
+      "conversation.append",
+      input
+    );
   }
   /**
    * Get the current list of available effects.
@@ -18577,9 +19841,53 @@ var Session = class {
   getEffects() {
     const doc = this.client.doc;
     const toolMap = /* @__PURE__ */ new Map();
-    const domainPkg = doc.domain?.packages?.domain;
-    if (domainPkg?.tools && Array.isArray(domainPkg.tools)) {
-      for (const tool of domainPkg.tools) {
+    const domainPackages = doc.domain?.packages;
+    const packageCandidates = domainPackages && typeof domainPackages === "object" ? [
+      domainPackages.domain,
+      domainPackages["@sandbox/domain"],
+      ...Object.values(domainPackages)
+    ].filter(Boolean) : [];
+    for (const domainPkg of packageCandidates) {
+      if (domainPkg?.tools && Array.isArray(domainPkg.tools)) {
+        for (const tool of domainPkg.tools) {
+          if (!tool?.name || toolMap.has(tool.name)) continue;
+          toolMap.set(tool.name, {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            className: tool.className || void 0,
+            static: tool.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+      if (!domainPkg?.classes || typeof domainPkg.classes !== "object") {
+        continue;
+      }
+      for (const [className, classDef] of Object.entries(
+        domainPkg.classes
+      )) {
+        const methods = Array.isArray(classDef?.methods) ? classDef.methods : [];
+        for (const method of methods) {
+          if (!method?.name || toolMap.has(method.name)) continue;
+          toolMap.set(method.name, {
+            name: method.name,
+            description: method.description,
+            inputSchema: method.inputSchema,
+            outputSchema: method.outputSchema,
+            className: method.className || classDef?.name || className,
+            static: method.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+    }
+    const legacyDomainPkg = doc.domain?.packages?.domain;
+    if (legacyDomainPkg?.tools && Array.isArray(legacyDomainPkg.tools)) {
+      for (const tool of legacyDomainPkg.tools) {
         if (!tool?.name) continue;
         toolMap.set(tool.name, {
           name: tool.name,
@@ -18593,6 +19901,27 @@ var Session = class {
         });
       }
     }
+    if (legacyDomainPkg?.classes && typeof legacyDomainPkg.classes === "object") {
+      for (const [className, classDef] of Object.entries(
+        legacyDomainPkg.classes
+      )) {
+        const methods = Array.isArray(classDef?.methods) ? classDef.methods : [];
+        for (const method of methods) {
+          if (!method?.name || toolMap.has(method.name)) continue;
+          toolMap.set(method.name, {
+            name: method.name,
+            description: method.description,
+            inputSchema: method.inputSchema,
+            outputSchema: method.outputSchema,
+            className: method.className || classDef?.name || className,
+            static: method.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+    }
+    const hasPolicyFilteredDomainTools = toolMap.size > 0;
     const catalogs = doc.catalog?.rawToolCatalogs || {};
     for (const [clientId, catalog] of Object.entries(catalogs)) {
       const cat = catalog;
@@ -18600,6 +19929,7 @@ var Session = class {
       for (const tool of cat.tools) {
         if (!tool?.name) continue;
         const existing = toolMap.get(tool.name);
+        if (hasPolicyFilteredDomainTools && !existing) continue;
         if (existing?.publishedAt && cat.publishedAt && existing.publishedAt > cat.publishedAt)
           continue;
         const isLocal = clientId === this.clientId;
@@ -18619,6 +19949,24 @@ var Session = class {
     }
     return Array.from(toolMap.values());
   }
+  /**
+   * Return the currently open prompt payloads known to this session.
+   *
+   * These come from live `prompt` / `prompt.request` websocket events and
+   * preserve the exact shape used by `answerPrompt(...)`.
+   */
+  getPrompts() {
+    return Array.from(this.promptCache.values()).map((prompt3) => ({
+      ...prompt3,
+      options: Array.isArray(prompt3.options) ? prompt3.options.map(
+        (option) => typeof option === "string" ? option : { ...option }
+      ) : void 0,
+      metadata: prompt3.metadata ? { ...prompt3.metadata } : void 0
+    }));
+  }
+  getHiddenPromptIds() {
+    return Array.from(this.hiddenPromptIds);
+  }
   /**
    * Backwards-compatible alias for `getEffects()`.
    */
@@ -18718,11 +20066,7 @@ var Session = class {
       if (!normalizedDocs) {
         return normalizedTypes;
       }
-      return [
-        normalizedTypes,
-        "Generated usage notes from ./sandbox-tools docs:",
-        normalizedDocs
-      ].join("\n\n");
+      return [normalizedTypes, "[Docs]", normalizedDocs].join("\n\n");
     }
     if (normalizedDocs) {
       return normalizedDocs;
@@ -18944,6 +20288,7 @@ import { ${allImports} } from "./sandbox-tools";
     const emitPrompt = (payload) => {
       const prompt3 = normalizePrompt(payload);
       if (!prompt3) return;
+      this.hiddenPromptIds.delete(prompt3.id);
       this.promptCache.set(prompt3.id, prompt3);
       this.emit("prompt", prompt3);
     };
@@ -19126,6 +20471,7 @@ var JobImplementation = class {
   eventListeners = /* @__PURE__ */ new Map();
   bufferedAgentMessages = [];
   bufferedAgentMessageIds = /* @__PURE__ */ new Set();
+  resultSettled = false;
   metadata;
   constructor(id, client, initialState) {
     this.id = id;
@@ -19150,7 +20496,9 @@ var JobImplementation = class {
         if (execData.error) {
           this.finalize("failed", void 0, execData.error);
         } else {
-          this.finalize("succeeded", execData.result);
+          this.finalize("succeeded", execData.result, void 0, {
+            hasResult: Object.prototype.hasOwnProperty.call(execData, "result")
+          });
         }
         this.emit("status", this.status);
       }
@@ -19186,9 +20534,6 @@ var JobImplementation = class {
       if (normalizedStatus === "failed" || normalizedStatus === "timeout" || normalizedStatus === "canceled") {
         this.finalize(normalizedStatus);
       }
-      if (normalizedStatus === "succeeded") {
-        this.finalize("succeeded");
-      }
       this.emit("status", normalizedStatus);
     });
     this.client.on(`job.${id}.stdout`, (line) => {
@@ -19208,7 +20553,7 @@ var JobImplementation = class {
       this.emit("stderr", line);
     });
     this.client.on(`job.${id}.result`, (result) => {
-      this.finalize("succeeded", result);
+      this.finalize("succeeded", result, void 0, { hasResult: true });
     });
     this.client.on(`job.${id}.error`, (error2) => {
       this.finalize("failed", void 0, error2);
@@ -19229,7 +20574,9 @@ var JobImplementation = class {
     this.client.on("job.completed", (data) => {
       const jobData = data;
       if (jobData.jobId === id) {
-        this.finalize("succeeded", jobData.result);
+        this.finalize("succeeded", jobData.result, void 0, {
+          hasResult: true
+        });
         this.emit("status", this.status);
       }
     });
@@ -19354,7 +20701,7 @@ var JobImplementation = class {
       this.metadata.status = "running";
     }
   }
-  finalize(status, result, error2) {
+  finalize(status, result, error2, options = {}) {
     if (!this.metadata.startedAt) {
       this.metadata.startedAt = Date.now();
     }
@@ -19362,14 +20709,18 @@ var JobImplementation = class {
     this.metadata.status = status;
     this.metadata.completedAt = this.metadata.completedAt || Date.now();
     this.metadata.durationMs = this.metadata.completedAt - this.metadata.startedAt;
-    if (result !== void 0) {
+    if (!this.resultSettled && (options.hasResult || result !== void 0)) {
       this.metadata.result = sanitizeFeedbackValue(result);
+      this.resultSettled = true;
       this._resolveResult(result);
     }
-    if (error2 !== void 0) {
-      const message = error2 instanceof Error ? error2.message : String(error2);
+    if (!this.resultSettled && (error2 !== void 0 || status === "failed" || status === "timeout" || status === "canceled")) {
+      const fallbackError = new Error(`Job ${this.id} ${status}.`);
+      const cause = error2 ?? fallbackError;
+      const message = cause instanceof Error ? cause.message : String(cause);
       this.metadata.error = truncateFeedbackString(message);
-      this._rejectResult(error2);
+      this.resultSettled = true;
+      this._rejectResult(cause);
     }
   }
   upsertToolCall(next) {
@@ -19452,6 +20803,17 @@ function humanTextFromStdout(stdout) {
   }
   return null;
 }
+function responseTextFromAgentMessages(agentMessages) {
+  for (const message of [...agentMessages].reverse()) {
+    const record = asRecord2(message);
+    if (!record) continue;
+    for (const key of RESPONSE_KEYS) {
+      const normalized = normalizeText(record[key]);
+      if (normalized) return normalized;
+    }
+  }
+  return null;
+}
 function pushString(target, value) {
   if (typeof value === "string" && value.trim()) {
     target.add(value.trim());
@@ -19477,6 +20839,41 @@ function collectReferencesFromRecord(record, refs) {
   for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
     pushStringArray(refs.variableNames, record[key]);
 }
+function stringValue(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+function findEntryPathForRecord(record, heap) {
+  const directPath = stringValue(record, ["entryPath", "path"]);
+  if (directPath && heap.entriesByPath?.[directPath]) {
+    return directPath;
+  }
+  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
+  if (!id) {
+    return null;
+  }
+  const className = stringValue(record, [
+    "className",
+    "_className",
+    "__className",
+    "prototype",
+    "type"
+  ]);
+  const entries = Object.values(heap.entriesByPath || {});
+  const exact = entries.find(
+    (entry) => entry.id === id && (!className || entry.className === className || entry.prototypes?.includes(className))
+  );
+  if (exact?.path) {
+    return exact.path;
+  }
+  const idOnlyMatches = entries.filter((entry) => entry.id === id);
+  return idOnlyMatches.length === 1 ? idOnlyMatches[0].path : null;
+}
 function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
   if (value === null || value === void 0 || depth > 4 || seen.has(value))
     return;
@@ -19497,6 +20894,8 @@ function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__
   const record = asRecord2(value);
   if (!record) return;
   seen.add(value);
+  const entryPath = findEntryPathForRecord(record, heap);
+  if (entryPath) refs.entryPaths.add(entryPath);
   collectReferencesFromRecord(record, refs);
   for (const key of UI_CONTAINER_KEYS) {
     const nested = asRecord2(record[key]);
@@ -19594,8 +20993,8 @@ function getJobRelatedLists(heap, jobId) {
 function entriesFromLists(lists, heap) {
   const entries = [];
   for (const list of lists) {
-    for (const path6 of list.paths || []) {
-      const entry = heap.entriesByPath?.[path6];
+    for (const path7 of list.paths || []) {
+      const entry = heap.entriesByPath?.[path7];
       if (entry) entries.push(entry);
     }
   }
@@ -19605,6 +21004,7 @@ function resolveJobPresentation({
   jobId,
   result,
   stdout = [],
+  agentMessages = [],
   sessionHeap,
   allowExplicitArtifacts = true
 }) {
@@ -19621,7 +21021,7 @@ function resolveJobPresentation({
     [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
   );
   const referencedEntries = sortEntries(
-    [...refs.entryPaths].map((path6) => sessionHeap.entriesByPath?.[path6]).filter((entry) => Boolean(entry))
+    [...refs.entryPaths].map((path7) => sessionHeap.entriesByPath?.[path7]).filter((entry) => Boolean(entry))
   );
   const jobLists = getJobRelatedLists(sessionHeap, jobId);
   const jobEntries = getJobRelatedEntries(sessionHeap, jobId);
@@ -19637,7 +21037,7 @@ function resolveJobPresentation({
   const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
   const lists = hasExplicitArtifacts ? explicitLists : jobLists;
   const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
-  const responseText = extractResponseText(result, stdout) || fallbackResponseText(entries, lists);
+  const responseText = extractResponseText(result, stdout) || responseTextFromAgentMessages(agentMessages) || fallbackResponseText(entries, lists);
   return {
     responseText,
     entries,
@@ -20172,6 +21572,12 @@ var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT = 3;
 var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS = 1e3;
 var LOCAL_CONTROL_REQUEST_RETRY_COUNT = 4;
 var LOCAL_CONTROL_REQUEST_RETRY_DELAY_MS = 500;
+var SESSION_DATA_REQUEST_RETRY_COUNT = 4;
+var SESSION_DATA_REQUEST_RETRY_DELAY_MS = 500;
+var EFFECT_HOST_CONNECT_TIMEOUT_MS = 15e3;
+var EFFECT_CATALOG_SYNC_TIMEOUT_MS = 3e4;
+var EFFECT_CATALOG_SYNC_RETRY_COUNT = 3;
+var EFFECT_CATALOG_SYNC_RETRY_DELAY_MS = 1e3;
 function planRecordObjectsChunks(records, batchSize) {
   const total = records.length;
   const size = Math.max(1, Math.min(batchSize, total));
@@ -20186,6 +21592,19 @@ function planRecordObjectsChunks(records, batchSize) {
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
+function withTimeout(promise, timeoutMs, label) {
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  });
+}
 function isLocalControlUrl(url) {
   try {
     const parsed = new URL(url);
@@ -20199,7 +21618,19 @@ function isRetryableLocalWorkerRestart(status, body, url) {
 }
 function isRetryableRecordObjectsError(error2) {
   const message = error2 instanceof Error ? error2.message : String(error2);
-  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(
+  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out|bad gateway|too many requests|gateway timeout|control plane api error \((?:429|500|502|503|504)\)|graphql api error \((?:429|500|502|503|504)\)|failed to record batch/i.test(
+    message
+  );
+}
+function isRetryableEffectRegistrationError(error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return /timed out|websocket disconnected|websocket not connected|rpc timeout|worker restarted mid-request|network connection lost|bad gateway|gateway timeout|too many requests|(?:control plane|granular|graphql) api error \((?:429|500|502|503|504)\)/i.test(
+    message
+  );
+}
+function isRetryableSessionDataError(error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return /network connection lost|worker restarted mid-request|econnreset|socket connection was closed unexpectedly|bad gateway|gateway timeout|service unavailable|session data api error \((?:429|500|502|503|504)\)/i.test(
     message
   );
 }
@@ -20221,16 +21652,28 @@ function computeEffectRegistrationKey(effect) {
     effect.versionSelector
   )}`;
 }
-function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
-  const url = new URL(apiUrl);
-  if (url.pathname.endsWith("/granular/ws/connect")) {
+function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId, effectHostUrl) {
+  const overrideUrl = effectHostUrl || process.env.GRANULAR_EFFECT_HOST_URL || process.env.EFFECT_HOST_URL;
+  const api = new URL(apiUrl);
+  const localRuntimeBase = process.env.RUNTIME_ORCHESTRATOR_URL || (isLocalControlUrl(apiUrl) ? `${api.protocol}//${api.hostname}:8791` : "");
+  const url = new URL(overrideUrl || localRuntimeBase || apiUrl);
+  if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  } else if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  }
+  if (!overrideUrl && isLocalControlUrl(apiUrl) && api.pathname.endsWith("/granular")) {
+    url.pathname = "/granular/orchestrator/effects/connect";
+  } else if (url.pathname.endsWith("/granular/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/granular")) {
-    url.pathname = `${url.pathname.replace(/\/$/, "")}/effects/connect`;
+    url.pathname = isLocalControlUrl(url.toString()) ? "/granular/orchestrator/effects/connect" : `${url.pathname.replace(/\/$/, "")}/effects/connect`;
   } else if (url.pathname.endsWith("/v2/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/v2/ws")) {
     url.pathname = url.pathname.replace(/\/ws$/, "/effects/connect");
+  } else if (url.pathname === "/" && isLocalControlUrl(url.toString()) && (url.port === "8791" || !overrideUrl && Boolean(localRuntimeBase))) {
+    url.pathname = "/granular/orchestrator/effects/connect";
   } else if (url.pathname.endsWith("/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/ws")) {
@@ -20265,6 +21708,79 @@ function normalizeHeapSnapshot(raw) {
     updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
+function normalizeGraphPathSegment(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function extractRecordIdFromGraphPath(path7, className) {
+  const normalizedPrefix = `${normalizeGraphPathSegment(className)}_`;
+  if (path7.startsWith(normalizedPrefix)) {
+    return path7.slice(normalizedPrefix.length);
+  }
+  const legacyPrefix = `${className}_`;
+  if (path7.startsWith(legacyPrefix)) {
+    return path7.slice(legacyPrefix.length);
+  }
+  return path7;
+}
+function toRecordSearchResult(className, node) {
+  const path7 = typeof node.path === "string" ? node.path : "";
+  if (!path7) return null;
+  const fields = Array.isArray(node.submodels) ? node.submodels.flatMap(
+    (submodel) => {
+      const name = typeof submodel?.label === "string" && submodel.label.trim() ? submodel.label : typeof submodel?.path === "string" ? submodel.path.split(":").pop() || submodel.path : "";
+      if (!name) return [];
+      if (typeof submodel.string_value === "string") {
+        return [{ name, type: "string", value: submodel.string_value }];
+      }
+      if (typeof submodel.number_value === "number") {
+        return [{ name, type: "number", value: submodel.number_value }];
+      }
+      if (typeof submodel.boolean_value === "boolean") {
+        return [
+          {
+            name,
+            type: "boolean",
+            value: submodel.boolean_value
+          }
+        ];
+      }
+      return [];
+    }
+  ) : [];
+  return {
+    path: path7,
+    className,
+    id: extractRecordIdFromGraphPath(path7, className),
+    label: typeof node.label === "string" && node.label.trim() ? node.label : extractRecordIdFromGraphPath(path7, className),
+    description: typeof node.description === "string" && node.description.trim() ? node.description : null,
+    fields
+  };
+}
+function normalizeRecordSearchText(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function rankRecordSearchResult(result, query, index) {
+  const normalizedQuery = normalizeRecordSearchText(query);
+  if (!normalizedQuery) {
+    return index;
+  }
+  const label = normalizeRecordSearchText(result.label || "");
+  const id = normalizeRecordSearchText(result.id || "");
+  const path7 = normalizeRecordSearchText(result.path || "");
+  const className = normalizeRecordSearchText(result.className || "");
+  const searchable = [label, id, path7, className].filter(Boolean);
+  if (label === normalizedQuery) return index;
+  if (id === normalizedQuery || path7 === normalizedQuery) return 100 + index;
+  if (label.startsWith(normalizedQuery)) return 200 + index;
+  if (searchable.some((value) => value.startsWith(normalizedQuery))) {
+    return 300 + index;
+  }
+  if (label.includes(normalizedQuery)) return 400 + index;
+  if (searchable.some((value) => value.includes(normalizedQuery))) {
+    return 500 + index;
+  }
+  return 900 + index;
+}
 function deriveRuntimeBaseUrl(apiEndpoint) {
   try {
     const endpoint = new URL(apiEndpoint);
@@ -20353,7 +21869,7 @@ function normalizeEnvironmentData(environment) {
     setup: normalizeEnvironmentSetupSummary(environment.setup)
   };
 }
-var Environment = class {
+var Environment = class _Environment {
   granular;
   envData;
   _apiKey;
@@ -20528,9 +22044,9 @@ var Environment = class {
   getRuntimeBaseUrl() {
     return deriveRuntimeBaseUrl(this._apiEndpoint);
   }
-  async controlPlaneRequest(path6, options = {}) {
+  async controlPlaneRequest(path7, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
-    const url = `${runtimeBase}${path6}`;
+    const url = `${runtimeBase}${path7}`;
     const response = await fetch(url, {
       ...options,
       headers: {
@@ -20548,28 +22064,30 @@ var Environment = class {
     return response.json();
   }
   // ==================== ID ↔ GRAPH PATH MAPPING ====================
+  static normalizeGraphPathSegment(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  }
   /**
-   * Convert a class name + real-world ID into a unique graph path.
-   *
-   * Two objects of *different* classes may share the same real-world ID,
-   * so the graph path must incorporate the class to guarantee uniqueness.
-   *
-   * Format: `{className}_{id}` — deterministic, human-readable.
+   * Convert a class name + application record ID into Granular's graph path.
    *
-   * **Convention**: class names should be simple identifiers without
-   * underscores (e.g. `author`, `book`).  This ensures the prefix is
-   * unambiguously parseable by `extractIdFromGraphPath`.
+   * This mirrors the record-write path normalization used by the control plane.
+   * Keep the original customer/system ID in `real_id`; graph paths are stable
+   * internal addresses, not the source of truth for business identity.
    */
   static toGraphPath(className, id) {
-    return `${className}_${id}`;
+    return `${_Environment.normalizeGraphPathSegment(className)}_${_Environment.normalizeGraphPathSegment(id)}`;
   }
   /**
-   * Extract the real-world ID from a graph path, given the class name.
+   * Best-effort extraction of an ID-like suffix from a graph path.
    *
-   * Strips the `{className}_` prefix. Returns the raw path if the
-   * expected prefix is not found.
+   * Prefer the record's `real_id` field whenever exact customer/system IDs
+   * matter, because graph path normalization is intentionally lossy.
    */
   static extractIdFromGraphPath(graphPath, className) {
+    const normalizedPrefix = `${_Environment.normalizeGraphPathSegment(className)}_`;
+    if (graphPath.startsWith(normalizedPrefix)) {
+      return graphPath.substring(normalizedPrefix.length);
+    }
     const prefix = `${className}_`;
     return graphPath.startsWith(prefix) ? graphPath.substring(prefix.length) : graphPath;
   }
@@ -20616,6 +22134,62 @@ var Environment = class {
     }
     return response.json();
   }
+  async searchRecords(query, options = {}) {
+    const normalizedQuery = query.replace(/\s+/g, " ").trim();
+    const limit = Math.max(1, Math.min(50, Math.floor(options.limit ?? 12)));
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const response = await this.graphql(
+      `
+        query RecordMentionSearch(
+          $query: String
+          $limit: Int
+          $offset: Int
+          $classNames: [String!]
+        ) {
+          record_search(
+            query: $query
+            limit: $limit
+            offset: $offset
+            class_names: $classNames
+          ) {
+            className
+            model {
+              path
+              label
+              description
+              submodels {
+                path
+                label
+                string_value
+                number_value
+                boolean_value
+              }
+            }
+          }
+        }
+      `,
+      {
+        query: normalizedQuery,
+        limit,
+        offset,
+        classNames: options.classNames?.length ? options.classNames : []
+      }
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const results = (response.data?.record_search || []).flatMap((entry) => {
+      const className = entry.className?.trim();
+      const item = className && entry.model ? toRecordSearchResult(className, entry.model) : null;
+      if (!item || seen.has(item.path)) {
+        return [];
+      }
+      seen.add(item.path);
+      return [item];
+    });
+    return results.map((result, index) => ({
+      result,
+      rank: rankRecordSearchResult(result, normalizedQuery, index)
+    })).sort((left, right) => left.rank - right.rank).map((item) => item.result).slice(0, limit);
+  }
   // ==================== RELATIONSHIP METHODS ====================
   /**
    * Define a relationship between two model types.
@@ -21381,7 +22955,8 @@ var Environment = class {
         body: JSON.stringify({
           records,
           batchSize: options.batchSize,
-          setupRunId: options.setupRunId
+          setupRunId: options.setupRunId,
+          writeMode: options.writeMode
         })
       }
     );
@@ -21433,11 +23008,13 @@ var Environment = class {
 };
 var EnvironmentSession = class extends Session {
   environment;
+  sessionDataRoutePrefix;
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
-  constructor(client, environment, clientId) {
+  constructor(client, environment, clientId, options = {}) {
     super(client, clientId);
     this.environment = environment;
+    this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
   }
   get environmentId() {
     return this.environment.environmentId;
@@ -21482,7 +23059,7 @@ var EnvironmentSession = class extends Session {
     const doc = this.document;
     return normalizeHeapSnapshot(doc?.heap);
   }
-  async sessionDataRequest(path6, query) {
+  async sessionDataRequest(path7, query, init2 = {}) {
     const searchParams = new URLSearchParams();
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== null && typeof value !== "undefined" && value !== "") {
@@ -21490,23 +23067,39 @@ var EnvironmentSession = class extends Session {
       }
     }
     const queryString = searchParams.toString();
-    const response = await fetch(
-      `${this.environment.runtimeBaseUrl}/orchestrator/ws/sessions/${encodeURIComponent(this.sessionId)}${path6}${queryString ? `?${queryString}` : ""}`,
-      {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.environment.authToken}`,
-          "Content-Type": "application/json"
+    const url = `${this.environment.runtimeBaseUrl}${this.sessionDataRoutePrefix}/${encodeURIComponent(this.sessionId)}${path7}${queryString ? `?${queryString}` : ""}`;
+    const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
+    for (let attempt = 1; attempt <= SESSION_DATA_REQUEST_RETRY_COUNT; attempt += 1) {
+      try {
+        const response = await fetch(url, {
+          method: init2.method || "GET",
+          headers: {
+            Authorization: `Bearer ${this.environment.authToken}`,
+            "Content-Type": "application/json"
+          },
+          ...typeof body === "undefined" ? {} : { body }
+        });
+        if (response.ok) {
+          return response.json();
+        }
+        const errorText = await response.text();
+        const error2 = new Error(
+          `Session data API Error (${response.status}): ${errorText}`
+        );
+        if (isLocalControlUrl(url) && isRetryableSessionDataError(error2) && attempt < SESSION_DATA_REQUEST_RETRY_COUNT) {
+          await sleep(SESSION_DATA_REQUEST_RETRY_DELAY_MS * attempt);
+          continue;
+        }
+        throw error2;
+      } catch (error2) {
+        if (isLocalControlUrl(url) && isRetryableSessionDataError(error2) && attempt < SESSION_DATA_REQUEST_RETRY_COUNT) {
+          await sleep(SESSION_DATA_REQUEST_RETRY_DELAY_MS * attempt);
+          continue;
         }
+        throw error2;
       }
-    );
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(
-        `Session data API Error (${response.status}): ${errorText}`
-      );
     }
-    return response.json();
+    throw new Error(`Session data API Error: exhausted retries for ${url}`);
   }
   async collectAllSessionItems(listPage) {
     const items = [];
@@ -21552,8 +23145,8 @@ var EnvironmentSession = class extends Session {
     return {
       entries: {
         list: (options = {}) => this.sessionDataRequest("/heap/entries", options),
-        get: (path6) => this.sessionDataRequest(
-          `/heap/entries/${encodeURIComponent(path6)}`
+        get: (path7) => this.sessionDataRequest(
+          `/heap/entries/${encodeURIComponent(path7)}`
         )
       },
       lists: {
@@ -21564,6 +23157,17 @@ var EnvironmentSession = class extends Session {
         get: (name) => this.sessionDataRequest(
           `/heap/lists/${encodeURIComponent(name)}`
         )
+      },
+      variables: {
+        list: (options = {}) => this.sessionDataRequest("/heap/variables", options),
+        get: (name) => this.sessionDataRequest(
+          `/heap/variables/${encodeURIComponent(name)}`
+        ),
+        delete: (name) => this.sessionDataRequest(
+          `/heap/variables/${encodeURIComponent(name)}`,
+          void 0,
+          { method: "DELETE" }
+        )
       }
     };
   }
@@ -21632,6 +23236,19 @@ var EnvironmentSession = class extends Session {
   async graphql(query, variables) {
     return this.environment.graphql(query, variables);
   }
+  async searchRecords(query, options = {}) {
+    return this.environment.searchRecords(query, options);
+  }
+  async mentionRecord(input) {
+    return this.sessionDataRequest(
+      "/records/mention",
+      void 0,
+      {
+        method: "POST",
+        body: input
+      }
+    );
+  }
   async defineRelationship(options) {
     return this.environment.defineRelationship(options);
   }
@@ -21779,6 +23396,7 @@ var Granular = class _Granular {
   WebSocketCtor;
   onUnexpectedClose;
   onReconnectError;
+  effectHostUrl;
   debugHttp = process.env.GRANULAR_DEBUG_HTTP === "1";
   /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
@@ -21807,6 +23425,7 @@ var Granular = class _Granular {
     this.WebSocketCtor = options.WebSocketCtor;
     this.onUnexpectedClose = options.onUnexpectedClose;
     this.onReconnectError = options.onReconnectError;
+    this.effectHostUrl = options.effectHostUrl;
     this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
   /**
@@ -21977,6 +23596,30 @@ var Granular = class _Granular {
       permissions: options.permissions || options.user?.permissions || []
     });
   }
+  /**
+   * Run a registered environment importer against an environment that was
+   * opened outside this SDK instance, for example by a delegated browser flow.
+   *
+   * This uses the same setup-run and queued record-import plumbing as
+   * `openEnvironment()`: importer stages, expected object counts, and queued
+   * import counters remain visible through `environment.setup` and
+   * `getRecordImportSummary()`.
+   */
+  async runEnvironmentImporterForEnvironment(environmentId, options = {}) {
+    const environmentData = await this.environments.get(environmentId);
+    const environment = this.bindEnvironmentHandle(environmentData);
+    const requestedOntology = options.ontology || environmentData.ontologyId || environmentData.sandboxId;
+    return this.runEnvironmentImporter(
+      {
+        environment: environmentData,
+        requestedOntology,
+        sandboxId: environmentData.sandboxId,
+        subjectId: environmentData.subjectId,
+        setupTriggerReason: options.reason || "new_environment"
+      },
+      environment
+    );
+  }
   resolveRequestedTag(options, methodName) {
     const tag2 = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
     if (!tag2) {
@@ -22220,15 +23863,25 @@ var Granular = class _Granular {
     return ontologyImporter;
   }
   async maybeRunEnvironmentImporter(resolved, environment) {
-    if (!resolved.setupTriggerReason) {
-      return;
+    const setupTriggerReason = resolved.setupTriggerReason;
+    if (!setupTriggerReason) {
+      return null;
     }
+    return this.runEnvironmentImporter(
+      {
+        ...resolved,
+        setupTriggerReason
+      },
+      environment
+    );
+  }
+  async runEnvironmentImporter(resolved, environment) {
     const importer = this.resolveEnvironmentImporter(
       resolved.requestedOntology,
       resolved.sandboxId
     );
     if (!importer) {
-      return;
+      return null;
     }
     const setupRun = await this.request(
       `/control/environments/${environment.environmentId}/setup-runs`,
@@ -22268,16 +23921,24 @@ var Granular = class _Granular {
       },
       importRecords: async (records, options) => environment.enqueueRecordImport(records, {
         batchSize: options?.batchSize,
+        writeMode: options?.writeMode,
         setupRunId
       })
     };
     try {
       await importer(importerContext);
-      await updateSetupRun({ markHookCompleted: true });
+      const completedSetupRun = await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        {
+          method: "PATCH",
+          body: JSON.stringify({ markHookCompleted: true })
+        }
+      );
       const refreshedEnvironment = await this.environments.get(
         environment.environmentId
       );
       environment.syncEnvironmentData(refreshedEnvironment);
+      return completedSetupRun;
     } catch (error2) {
       await updateSetupRun({
         status: "failed",
@@ -22325,27 +23986,45 @@ var Granular = class _Granular {
     return effects2;
   }
   serializeEffect(effect) {
-    return {
+    const serialized = {
       effectKey: computeEffectKey2(effect),
       name: effect.name,
       description: effect.description,
       inputSchema: effect.inputSchema,
-      outputSchema: effect.outputSchema,
       stability: effect.stability || "stable",
-      provenance: effect.provenance || { source: "custom" },
-      tags: effect.tags,
-      className: effect.className,
-      static: effect.static,
-      versionSelector: effect.versionSelector
+      provenance: effect.provenance || { source: "custom" }
     };
+    if (effect.outputSchema !== void 0) {
+      serialized.outputSchema = effect.outputSchema;
+    }
+    if (effect.tags !== void 0) {
+      serialized.tags = effect.tags;
+    }
+    if (effect.className !== void 0) {
+      serialized.className = effect.className;
+    }
+    if (effect.static !== void 0) {
+      serialized.static = effect.static;
+    }
+    if (effect.versionSelector !== void 0) {
+      serialized.versionSelector = effect.versionSelector;
+    }
+    if (effect.metamodels !== void 0) {
+      serialized.metamodels = effect.metamodels;
+    }
+    return serialized;
   }
   async publishSandboxEffectCatalog(host) {
     const effects2 = Array.from(
       this.getSandboxEffectMap(host.sandboxId).values()
     ).map((effect) => this.serializeEffect(effect));
-    const result = await host.wsClient.call("effects.publishCatalog", {
-      effects: effects2
-    });
+    const result = await withTimeout(
+      host.wsClient.call("effects.publishCatalog", {
+        effects: effects2
+      }),
+      EFFECT_CATALOG_SYNC_TIMEOUT_MS,
+      `effects.publishCatalog for sandbox ${host.sandboxId}`
+    );
     const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
     const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
     if (acceptedCount === 0 && rejected.length > 0) {
@@ -22364,8 +24043,26 @@ var Granular = class _Granular {
     }
   }
   async syncSandboxEffectCatalog(sandboxId) {
-    const host = await this.ensureSandboxEffectHost(sandboxId);
-    await this.publishSandboxEffectCatalog(host);
+    let lastError;
+    for (let attempt = 1; attempt <= EFFECT_CATALOG_SYNC_RETRY_COUNT; attempt += 1) {
+      try {
+        const host = await this.ensureSandboxEffectHost(sandboxId);
+        await this.publishSandboxEffectCatalog(host);
+        return;
+      } catch (error2) {
+        lastError = error2;
+        this.disconnectSandboxEffectHost(sandboxId);
+        if (attempt === EFFECT_CATALOG_SYNC_RETRY_COUNT || !isRetryableEffectRegistrationError(error2)) {
+          throw error2;
+        }
+        console.warn(
+          `[Granular] Retrying effect registration for sandbox ${sandboxId} after transient failure (${attempt}/${EFFECT_CATALOG_SYNC_RETRY_COUNT - 1} retries used):`,
+          error2
+        );
+        await sleep(EFFECT_CATALOG_SYNC_RETRY_DELAY_MS * attempt);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
   recoverEffectHost(host, error2) {
     if (host.recovering) {
@@ -22458,7 +24155,8 @@ var Granular = class _Granular {
           this.apiUrl,
           sandboxId,
           effectClientId,
-          clientId
+          clientId,
+          this.effectHostUrl
         ),
         sessionId: `effect-host:${effectClientId}`,
         token: this.apiKey,
@@ -22494,7 +24192,11 @@ var Granular = class _Granular {
       wsClient.on("disconnect", () => {
         this.stopEffectHostHeartbeat(host);
       });
-      await wsClient.connect();
+      await withTimeout(
+        wsClient.connect(),
+        EFFECT_HOST_CONNECT_TIMEOUT_MS,
+        `effect host WebSocket connect for sandbox ${sandboxId}`
+      );
       await this.synchronizeEffectHost(host);
       this.sandboxEffectHosts.set(sandboxId, host);
       return host;
@@ -22617,7 +24319,7 @@ var Granular = class _Granular {
   /**
    * Ensure a permission profile exists for a sandbox, creating it if needed.
    * If profileName matches an existing profile name, returns its ID.
-   * Otherwise, creates a new profile with default allow-all rules.
+   * Otherwise, creates a v1 source-profile file shape with an allow default.
    */
   async ensurePermissionProfile(sandboxId, profileName) {
     try {
@@ -22631,8 +24333,11 @@ var Granular = class _Granular {
     const created = await this.permissionProfiles.create(sandboxId, {
       name: profileName,
       rules: {
-        effects: { allow: ["*"] },
-        resources: { allow: ["*"] }
+        schemaVersion: 1,
+        name: profileName,
+        description: profileName === "allow-all" ? "Every declared action is visible unless a manifest policy denies it." : `Generated permission profile ${profileName}`,
+        defaults: { actionPolicy: "allow" },
+        actions: []
       }
     });
     return created.permissionProfileId;
@@ -22705,33 +24410,63 @@ var Granular = class _Granular {
    * Permission Profile management for sandboxes
    */
   get permissionProfiles() {
+    const profileSourceFromRecord = (record) => {
+      const profile = record.profile || record.rules || {};
+      return {
+        ...profile,
+        schemaVersion: profile.schemaVersion || 1,
+        name: profile.name || record.name,
+        description: profile.description || record.description
+      };
+    };
     return {
       list: async (sandboxId) => {
         const result = await this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles`
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`
         );
         return result.items;
       },
       get: async (sandboxId, profileId) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`
+        );
+        const profile = result.items.find(
+          (item) => item.permissionProfileId === profileId || item.name === profileId
         );
+        if (!profile) {
+          throw new Error(`Permission profile source not found: ${profileId}`);
+        }
+        return profile;
       },
       create: async (sandboxId, data) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles`,
+        const profile = {
+          ...data.rules,
+          schemaVersion: 1,
+          name: data.name
+        };
+        const existingProfiles = await this.permissionProfiles.list(sandboxId);
+        const profiles = [
+          ...existingProfiles.filter((existing) => existing.name !== data.name).map((existing) => profileSourceFromRecord(existing)),
+          profile
+        ];
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`,
           {
-            method: "POST",
-            body: JSON.stringify(data)
+            method: "PUT",
+            body: JSON.stringify({ profiles })
           }
         );
+        const synced = result.items.find((item) => item.name === data.name) || result.items[0];
+        if (!synced) {
+          throw new Error(
+            `Permission profile source sync did not return ${data.name}`
+          );
+        }
+        return synced;
       },
-      delete: async (sandboxId, profileId) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`,
-          {
-            method: "DELETE"
-          }
+      delete: async (_sandboxId, _profileId) => {
+        throw new Error(
+          "Permission profile sources are updated by syncing the desired source set."
         );
       }
     };
@@ -22944,8 +24679,8 @@ var Granular = class _Granular {
   /**
    * Make an authenticated API request
    */
-  async request(path6, options = {}) {
-    const url = `${this.httpUrl}${path6}`;
+  async request(path7, options = {}) {
+    const url = `${this.httpUrl}${path7}`;
     if (this.debugHttp) {
       console.log(`[SDK] Requesting: ${url}`);
     }
@@ -22989,7 +24724,7 @@ var Granular = class _Granular {
 // src/cli/commands/runtime-shared.ts
 function normalizePermissions(raw) {
   const values = raw?.split(",").map((value) => value.trim()).filter(Boolean);
-  return values && values.length > 0 ? values : ["default"];
+  return values && values.length > 0 ? values : ["allow-all"];
 }
 function createGranularClient() {
   const config = resolveConfig({ requireApiKey: true });
@@ -23049,7 +24784,7 @@ async function resolveEnvironmentData(granular, options) {
     ontology: ontologyId,
     environment: environmentName,
     userId: options.userId ?? "granular-cli",
-    permissions: options.permissions ?? ["default"]
+    permissions: options.permissions ?? ["allow-all"]
   });
   return await granular.environments.get(connection.environmentId);
 }
@@ -23089,7 +24824,7 @@ async function connectRuntime(options) {
     ontology: ontologyId,
     environment: options.environment ?? "dev",
     userId: options.userId ?? "granular-cli",
-    permissions: options.permissions ?? ["default"]
+    permissions: options.permissions ?? ["allow-all"]
   });
   const environment = await environmentHandle.createSession();
   return {
@@ -23250,13 +24985,13 @@ async function sessionCreateCommand(options) {
     printHeader();
   }
   const { granular } = createGranularClient();
-  const permissions = normalizePermissions(options.permissions);
+  const permissions2 = normalizePermissions(options.permissions);
   const envData = await resolveEnvironmentData(granular, {
     ontology: options.ontology,
     environment: requestedEnvironment,
     environmentId: options.environmentId,
     userId: options.user,
-    permissions,
+    permissions: permissions2,
     createIfMissing: true
   });
   const environment = await granular.createSession({
@@ -23581,6 +25316,101 @@ async function jobRunCommand(options) {
   );
 }
 
+// src/cli/commands/permissions.ts
+function parseJsonObject(value) {
+  if (!value) return {};
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Expected a JSON object");
+  }
+  return parsed;
+}
+function resolveEffectKey(manifest, action, on) {
+  const effects2 = extractManifestEffects(manifest);
+  const matches = effects2.filter((effect) => {
+    if (effect.name !== action) return false;
+    return on ? effect.attachedClass === on : !effect.attachedClass;
+  });
+  if (matches.length === 1) return matches[0].effectKey;
+  if (matches.length === 0) {
+    throw new Error(
+      on ? `Action "${action}" on "${on}" was not found.` : `Global action "${action}" was not found.`
+    );
+  }
+  throw new Error(`Action "${action}" is ambiguous. Add --on.`);
+}
+async function permissionsValidateCommand() {
+  const config = resolveConfig({ requireProject: true });
+  const manifest = config.project.manifest;
+  const profiles = readPermissionProfileFiles();
+  const result = await compilePolicyBundle({
+    sandboxId: config.sandboxId,
+    effects: extractManifestEffects(manifest),
+    profileSources: profiles
+  });
+  if (result.errors.length > 0) {
+    error("Permission policy validation failed:");
+    for (const error2 of result.errors) error(`  ${error2}`);
+    process.exit(1);
+  }
+  success(
+    `Validated ${Object.keys(result.bundle.profiles).length} permission profile(s).`
+  );
+  if (result.warnings.length > 0) {
+    for (const warning of result.warnings) warn(warning);
+  }
+}
+async function permissionsPreviewCommand(options) {
+  const config = resolveConfig({
+    requireApiKey: Boolean(options.versionId),
+    requireProject: true
+  });
+  if (!options.profile || !options.action) {
+    throw new Error("permissions preview requires --profile and --action");
+  }
+  const requestInput = parseJsonObject(options.input);
+  const objectContext = parseJsonObject(options.object);
+  const stateMachines = parseJsonObject(options.stateMachines);
+  const effectKey = resolveEffectKey(
+    config.project.manifest,
+    options.action,
+    options.on
+  );
+  if (options.versionId) {
+    const api = new ApiClient(config.apiKey, config.apiUrl);
+    const decision2 = await api.evaluateVersionPolicy(options.versionId, {
+      permissionProfileName: options.profile,
+      effectKey,
+      input: requestInput,
+      object: objectContext,
+      stateMachines
+    });
+    keyValue({
+      Decision: decision2.outcome,
+      Matched: (decision2.matches || []).map((match) => match.reason || match.summary || match.id).join("; ") || "none"
+    });
+    return;
+  }
+  const result = await compilePolicyBundle({
+    sandboxId: config.sandboxId,
+    effects: extractManifestEffects(config.project.manifest),
+    profileSources: readPermissionProfileFiles()
+  });
+  if (result.errors.length > 0) {
+    throw new Error(result.errors.join("; "));
+  }
+  const decision = evaluateCompiledPolicyBundle({
+    bundle: result.bundle,
+    profileName: options.profile,
+    effectKey,
+    context: { input: requestInput, object: objectContext, stateMachines }
+  });
+  keyValue({
+    Decision: decision.outcome,
+    Matched: decision.matches.map((match) => match.reason || match.summary || match.id).join("; ") || "none"
+  });
+}
+
 // src/cli/commands/version.ts
 function formatVersionLabel(versionId, versionNumber) {
   return versionNumber != null ? `v${versionNumber}` : versionId;
@@ -23822,67 +25652,130 @@ program2.hook("preAction", () => {
     process.env.GRANULAR_ENDPOINT_MODE = mode;
   }
 });
-program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").option("--template <template>", "Starter ontology template: library|support|delivery").option("--agent-docs", "Add AGENTS.md and docs/granular-manifest.md (for AI coding agents)").option("--no-agent-docs", "Skip agent documentation files").option("--cursor-hooks", "Emit optional Cursor hook files under .cursor/").option("--cursor-subagents", "Emit optional Cursor subagent files under .cursor/").option("--cursor-all", "Emit both Cursor hooks and Cursor subagents").option("--control-plane-session <sessionId>", "Attach the init flow to a control-plane onboarding session").option("--project-mode <mode>", "Onboarding context: new|existing").option("--auth-strategy <strategy>", "Onboarding context: just-me|granular-auth|existing-auth").option("--ide <ide>", "Onboarding context: cursor|codex|claude-code").option("--data-strategy <strategy>", "Onboarding context: demo|real").option("--product-summary <text>", "Onboarding context: product brief from the control plane").option("--roles-summary <text>", "Onboarding context: roles and permission notes from the control plane").action(async (projectName, opts) => {
-  try {
-    await initCommand(projectName, {
-      skipBuild: opts.skipBuild,
-      template: opts.template,
-      agentDocs: opts.agentDocs,
-      noAgentDocs: opts.noAgentDocs,
-      cursorHooks: opts.cursorHooks || opts.cursorAll,
-      cursorSubagents: opts.cursorSubagents || opts.cursorAll,
-      controlPlaneSession: opts.controlPlaneSession,
-      projectMode: opts.projectMode,
-      authStrategy: opts.authStrategy,
-      ide: opts.ide,
-      dataStrategy: opts.dataStrategy,
-      productSummary: opts.productSummary,
-      rolesSummary: opts.rolesSummary
-    });
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").option(
+  "--template <template>",
+  "Starter ontology template: library|support|delivery"
+).option(
+  "--agent-docs",
+  "Add AGENTS.md and docs/granular-manifest.md (for AI coding agents)"
+).option("--no-agent-docs", "Skip agent documentation files").option("--cursor-hooks", "Emit optional Cursor hook files under .cursor/").option(
+  "--cursor-subagents",
+  "Emit optional Cursor subagent files under .cursor/"
+).option("--cursor-all", "Emit both Cursor hooks and Cursor subagents").option(
+  "--control-plane-session <sessionId>",
+  "Attach the init flow to a control-plane onboarding session"
+).option("--project-mode <mode>", "Onboarding context: new|existing").option(
+  "--auth-strategy <strategy>",
+  "Onboarding context: just-me|granular-auth|existing-auth"
+).option("--ide <ide>", "Onboarding context: cursor|codex|claude-code").option("--data-strategy <strategy>", "Onboarding context: demo|real").option(
+  "--product-summary <text>",
+  "Onboarding context: product brief from the control plane"
+).option(
+  "--roles-summary <text>",
+  "Onboarding context: roles and permission notes from the control plane"
+).action(
+  async (projectName, opts) => {
+    try {
+      await initCommand(projectName, {
+        skipBuild: opts.skipBuild,
+        template: opts.template,
+        agentDocs: opts.agentDocs,
+        noAgentDocs: opts.noAgentDocs,
+        cursorHooks: opts.cursorHooks || opts.cursorAll,
+        cursorSubagents: opts.cursorSubagents || opts.cursorAll,
+        controlPlaneSession: opts.controlPlaneSession,
+        projectMode: opts.projectMode,
+        authStrategy: opts.authStrategy,
+        ide: opts.ide,
+        dataStrategy: opts.dataStrategy,
+        productSummary: opts.productSummary,
+        rolesSummary: opts.rolesSummary
+      });
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
-program2.command("login").description("Authenticate with Granular (browser by default)").option("--manual", "Prompt for API key instead of browser login").option("--api-key <key>", "Use a provided API key directly").option("--timeout <seconds>", "Browser auth timeout in seconds", (value) => {
-  const n = Number.parseInt(value, 10);
-  return Number.isFinite(n) ? n : 180;
-}).action(async (opts) => {
+);
+program2.command("login").description("Authenticate with Granular (browser by default)").option("--manual", "Prompt for API key instead of browser login").option("--api-key <key>", "Use a provided API key directly").option(
+  "--timeout <seconds>",
+  "Browser auth timeout in seconds",
+  (value) => {
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : 180;
+  }
+).action(
+  async (opts) => {
+    try {
+      await loginCommand({
+        manual: opts.manual,
+        apiKey: opts.apiKey,
+        timeout: opts.timeout
+      });
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
+  }
+);
+program2.command("pull <version-id>").description("Pull the manifest for a specific ontology version").action(async (versionId) => {
   try {
-    await loginCommand({
-      manual: opts.manual,
-      apiKey: opts.apiKey,
-      timeout: opts.timeout
-    });
+    await pullCommand(versionId);
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
-program2.command("pull <version-id>").description("Pull the manifest for a specific ontology version").action(async (versionId) => {
+program2.command("build").description(
+  "Create or reuse the ontology version for your current manifest, then run its build"
+).action(async () => {
   try {
-    await pullCommand(versionId);
+    await buildCommand();
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
-program2.command("build").description("Create or reuse the ontology version for your current manifest, then run its build").action(async () => {
+program2.command("deploy").description(
+  "Push the current revision to dev; use --prod to move prod there too"
+).option("--prod", "Also point prod to the current version").action(async (opts) => {
   try {
-    await buildCommand();
+    await deployCommand({ prod: opts.prod });
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
-program2.command("deploy").description("Push the current revision to dev; use --prod to move prod there too").option("--prod", "Also point prod to the current version").action(async (opts) => {
+var permissions = program2.command("permissions").description("Validate and preview permission profile files");
+permissions.command("validate").description("Validate permissions/*.json against granular.json").action(async () => {
   try {
-    await deployCommand({ prod: opts.prod });
+    await permissionsValidateCommand();
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
+permissions.command("preview").description("Preview a policy decision for a profile and action").requiredOption("--profile <profile>", "Permission profile name").requiredOption("--action <action>", "Action name").option("--on <className>", "Class name for instance/static actions").option("--input <json>", "Action input JSON object", "{}").option(
+  "--object <json>",
+  "Target object fields JSON object for object-based conditions",
+  "{}"
+).option(
+  "--state-machines <json>",
+  'Current state-machine states JSON object, e.g. {"lifecycle":"active"}',
+  "{}"
+).option(
+  "--version-id <versionId>",
+  "Evaluate against a compiled ontology version"
+).action(
+  async (opts) => {
+    try {
+      await permissionsPreviewCommand(opts);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
+  }
+);
 program2.command("status").description("Show ontology versions, dev/prod, and manifest status").option("--verbose", "Include endpoint/config details helpful for debugging").option("--json", "Print machine-readable JSON").action(async (options) => {
   try {
     await statusCommand(options);
@@ -23900,14 +25793,16 @@ version.command("current").description("Show the latest/current ontology version
     process.exit(1);
   }
 });
-version.command("diff <version-id> [against-version-id]").description("Show the semantic diff between one version and another").option("--json", "Print machine-readable JSON").action(async (versionId, againstVersionId, options) => {
-  try {
-    await versionDiffCommand(versionId, againstVersionId, options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+version.command("diff <version-id> [against-version-id]").description("Show the semantic diff between one version and another").option("--json", "Print machine-readable JSON").action(
+  async (versionId, againstVersionId, options) => {
+    try {
+      await versionDiffCommand(versionId, againstVersionId, options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
+);
 var tag = program2.command("tag").description("Inspect and move release tags such as dev and prod");
 tag.command("list").description("List tags for the current ontology").action(async () => {
   try {
@@ -23966,7 +25861,9 @@ program2.command("dev").description("Start development mode (watch + auto-rebuil
     process.exit(1);
   }
 });
-program2.command("document").description("Generate GRANULAR_SANDBOX.md (agent reference) from granular.json").action(async () => {
+program2.command("document").description(
+  "Generate GRANULAR_SANDBOX.md (agent reference) from granular.json"
+).action(async () => {
   try {
     await documentCommand();
   } catch (err) {
@@ -23974,83 +25871,232 @@ program2.command("document").description("Generate GRANULAR_SANDBOX.md (agent re
     process.exit(1);
   }
 });
-program2.command("simulate [ontology-id]").description("Open the Granular simulator in the browser for the current (or given) ontology").option("--subject-id <subjectId>", "Open the simulator preloaded for a specific subject").option("--environment <environment>", "Add an environment query parameter to the simulator URL").option("--session <sessionId>", "Add a session query parameter to the simulator URL").option("--user <userId>", "Add a user query parameter to the simulator URL").option("--print-url", "Print the simulator URL without opening a browser").action(async (sandboxId, options) => {
-  try {
-    await simulateCommand(sandboxId, options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+program2.command("simulate [ontology-id]").description(
+  "Open the Granular simulator in the browser for the current (or given) ontology"
+).option(
+  "--subject-id <subjectId>",
+  "Open the simulator preloaded for a specific subject"
+).option(
+  "--environment <environment>",
+  "Add an environment query parameter to the simulator URL"
+).option(
+  "--session <sessionId>",
+  "Add a session query parameter to the simulator URL"
+).option("--user <userId>", "Add a user query parameter to the simulator URL").option("--print-url", "Print the simulator URL without opening a browser").action(
+  async (sandboxId, options) => {
+    try {
+      await simulateCommand(sandboxId, options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
+);
 var connect = program2.command("connect").description("Run connectivity checks against a live Granular ontology");
-connect.command("test").description("Create a real session and verify connect/disconnect works").option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot to connect to", "dev").option("--user <userId>", "External user id to connect as").option("--permissions <list>", "Comma-separated permission profiles to ensure", "default").option("--json", "Print machine-readable JSON").action(async (options) => {
-  try {
-    await connectTestCommand(options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+connect.command("test").description("Create a real session and verify connect/disconnect works").option(
+  "--ontology <ontologyId>",
+  "Override the ontology id from .granularrc"
+).option(
+  "--environment <environment>",
+  "Environment slot to connect to",
+  "dev"
+).option("--user <userId>", "External user id to connect as").option(
+  "--permissions <list>",
+  "Comma-separated permission profile to ensure",
+  "allow-all"
+).option("--json", "Print machine-readable JSON").action(
+  async (options) => {
+    try {
+      await connectTestCommand(options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
-var session = program2.command("session").description("Inspect live Granular sessions and their Automerge-backed state");
+);
+var session = program2.command("session").description(
+  "Inspect live Granular sessions and their Automerge-backed state"
+);
 for (const [name, description, handler] of [
   ["heap", "Print the normalized session heap", sessionHeapCommand],
   ["doc", "Print the full session document", sessionDocCommand]
 ]) {
-  session.command(name).description(description).option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot to connect to when no session id is provided", "dev").option("--user <userId>", "External user id to connect as when no session id is provided").option("--permissions <list>", "Comma-separated permission profiles to ensure", "default").option("--session <sessionId>", "Connect to an existing session instead of creating a fresh one").option("--json", "Print machine-readable JSON").action(async (options) => {
+  session.command(name).description(description).option(
+    "--ontology <ontologyId>",
+    "Override the ontology id from .granularrc"
+  ).option(
+    "--environment <environment>",
+    "Environment slot to connect to when no session id is provided",
+    "dev"
+  ).option(
+    "--user <userId>",
+    "External user id to connect as when no session id is provided"
+  ).option(
+    "--permissions <list>",
+    "Comma-separated permission profile to ensure",
+    "allow-all"
+  ).option(
+    "--session <sessionId>",
+    "Connect to an existing session instead of creating a fresh one"
+  ).option("--json", "Print machine-readable JSON").action(
+    async (options) => {
+      try {
+        await handler(options);
+      } catch (err) {
+        error(err.message);
+        process.exit(1);
+      }
+    }
+  );
+}
+session.command("create").description(
+  "Create a new session for an existing environment or environment slot"
+).option(
+  "--ontology <ontologyId>",
+  "Override the ontology id from .granularrc"
+).option(
+  "--environment <environment>",
+  "Environment slot name to resolve when --environment-id is not provided",
+  "dev"
+).option(
+  "--environment-id <environmentId>",
+  "Create a session for this exact environment id"
+).option(
+  "--user <userId>",
+  "External user id to connect as when a named environment needs to be created"
+).option(
+  "--permissions <list>",
+  "Comma-separated permission profile to ensure when a named environment needs to be created",
+  "allow-all"
+).option("--json", "Print machine-readable JSON").action(
+  async (options) => {
     try {
-      await handler(options);
+      await sessionCreateCommand(options);
     } catch (err) {
       error(err.message);
       process.exit(1);
     }
-  });
-}
-session.command("create").description("Create a new session for an existing environment or environment slot").option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot name to resolve when --environment-id is not provided", "dev").option("--environment-id <environmentId>", "Create a session for this exact environment id").option("--user <userId>", "External user id to connect as when a named environment needs to be created").option("--permissions <list>", "Comma-separated permission profiles to ensure when a named environment needs to be created", "default").option("--json", "Print machine-readable JSON").action(async (options) => {
-  try {
-    await sessionCreateCommand(options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
   }
-});
-session.command("list").description("List indexed sessions for an environment").option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot name to resolve when --environment-id is not provided", "dev").option("--environment-id <environmentId>", "List sessions for this exact environment id").option("--status <status>", "Session status filter: active|closed|all", "active").option("--json", "Print machine-readable JSON").action(async (options) => {
-  try {
-    await sessionListCommand(options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+);
+session.command("list").description("List indexed sessions for an environment").option(
+  "--ontology <ontologyId>",
+  "Override the ontology id from .granularrc"
+).option(
+  "--environment <environment>",
+  "Environment slot name to resolve when --environment-id is not provided",
+  "dev"
+).option(
+  "--environment-id <environmentId>",
+  "List sessions for this exact environment id"
+).option(
+  "--status <status>",
+  "Session status filter: active|closed|all",
+  "active"
+).option("--json", "Print machine-readable JSON").action(
+  async (options) => {
+    try {
+      await sessionListCommand(options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
+);
 var job = program2.command("job").description("Run real Granular runtime jobs from the CLI");
-job.command("run").description("Submit a job from a file or inline code and wait for the result").option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot to connect to when no session id is provided", "dev").option("--user <userId>", "External user id to connect as when no session id is provided").option("--permissions <list>", "Comma-separated permission profiles to ensure", "default").option("--session <sessionId>", "Connect to an existing session instead of creating a fresh one").option("--file <path>", "Read the job source from a file").option("--inline <code>", "Provide the job source inline").option("--json", "Print machine-readable JSON").action(async (options) => {
-  try {
-    await jobRunCommand(options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+job.command("run").description(
+  "Submit a job from a file or inline code and wait for the result"
+).option(
+  "--ontology <ontologyId>",
+  "Override the ontology id from .granularrc"
+).option(
+  "--environment <environment>",
+  "Environment slot to connect to when no session id is provided",
+  "dev"
+).option(
+  "--user <userId>",
+  "External user id to connect as when no session id is provided"
+).option(
+  "--permissions <list>",
+  "Comma-separated permission profile to ensure",
+  "allow-all"
+).option(
+  "--session <sessionId>",
+  "Connect to an existing session instead of creating a fresh one"
+).option("--file <path>", "Read the job source from a file").option("--inline <code>", "Provide the job source inline").option("--json", "Print machine-readable JSON").action(
+  async (options) => {
+    try {
+      await jobRunCommand(options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
-program2.command("graphql").description("Execute a real GraphQL query against the current Granular environment").requiredOption("--query <query>", "GraphQL query or mutation string").option("--variables <json>", "JSON object of GraphQL variables").option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot to connect to when no session id is provided", "dev").option("--user <userId>", "External user id to connect as when no session id is provided").option("--permissions <list>", "Comma-separated permission profiles to ensure", "default").option("--session <sessionId>", "Connect to an existing session instead of creating a fresh one").option("--json", "Print machine-readable JSON").action(async (options) => {
-  try {
-    await graphqlCommand(options);
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
+);
+program2.command("graphql").description(
+  "Execute a real GraphQL query against the current Granular environment"
+).requiredOption("--query <query>", "GraphQL query or mutation string").option("--variables <json>", "JSON object of GraphQL variables").option(
+  "--ontology <ontologyId>",
+  "Override the ontology id from .granularrc"
+).option(
+  "--environment <environment>",
+  "Environment slot to connect to when no session id is provided",
+  "dev"
+).option(
+  "--user <userId>",
+  "External user id to connect as when no session id is provided"
+).option(
+  "--permissions <list>",
+  "Comma-separated permission profile to ensure",
+  "allow-all"
+).option(
+  "--session <sessionId>",
+  "Connect to an existing session instead of creating a fresh one"
+).option("--json", "Print machine-readable JSON").action(
+  async (options) => {
+    try {
+      await graphqlCommand(options);
+    } catch (err) {
+      error(err.message);
+      process.exit(1);
+    }
   }
-});
+);
 var effects = program2.command("effects").description("Inspect declared and live Granular effects for an environment");
 for (const [name, description, handler] of [
   ["list", "List the current effect catalog", effectsListCommand],
-  ["diff", "Compare declared effects to live ready handlers", effectsDiffCommand]
+  [
+    "diff",
+    "Compare declared effects to live ready handlers",
+    effectsDiffCommand
+  ]
 ]) {
-  effects.command(name).description(description).option("--ontology <ontologyId>", "Override the ontology id from .granularrc").option("--environment <environment>", "Environment slot to connect to when no session id is provided", "dev").option("--user <userId>", "External user id to connect as when no session id is provided").option("--permissions <list>", "Comma-separated permission profiles to ensure", "default").option("--session <sessionId>", "Connect to an existing session instead of creating a fresh one").option("--json", "Print machine-readable JSON").action(async (options) => {
-    try {
-      await handler(options);
-    } catch (err) {
-      error(err.message);
-      process.exit(1);
+  effects.command(name).description(description).option(
+    "--ontology <ontologyId>",
+    "Override the ontology id from .granularrc"
+  ).option(
+    "--environment <environment>",
+    "Environment slot to connect to when no session id is provided",
+    "dev"
+  ).option(
+    "--user <userId>",
+    "External user id to connect as when no session id is provided"
+  ).option(
+    "--permissions <list>",
+    "Comma-separated permission profile to ensure",
+    "allow-all"
+  ).option(
+    "--session <sessionId>",
+    "Connect to an existing session instead of creating a fresh one"
+  ).option("--json", "Print machine-readable JSON").action(
+    async (options) => {
+      try {
+        await handler(options);
+      } catch (err) {
+        error(err.message);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 void program2.parseAsync(process.argv).then(() => {
   process.exit(0);