owlrunkit 0.18.0 → 0.18.1

package/scripts/runkit-contract/schemas/usage-mode-recommendation-v1.schema.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/usage-mode-recommendation-v1.json",
+  "title": "OwlCoda RunKit Usage Mode Recommendation V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "requestedMode",
+    "recommendedMode",
+    "continuity",
+    "assurance",
+    "triggerReasons",
+    "rejectedLighterModes",
+    "estimatedOverhead",
+    "nextCommand",
+    "downgrade",
+    "authorityBoundary",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitUsageModeRecommendationV1" },
+    "status": { "enum": ["mode_recommended", "mode_status"] },
+    "requestedMode": { "enum": ["auto", "off", "light", "managed", "formal"] },
+    "recommendedMode": { "enum": ["off", "light", "managed", "formal"] },
+    "continuity": { "enum": ["none", "project_driver"] },
+    "assurance": { "enum": ["none", "quick", "formal"] },
+    "triggerReasons": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "rejectedLighterModes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["mode", "reasonCodes"],
+        "properties": {
+          "mode": { "enum": ["off", "light", "managed"] },
+          "reasonCodes": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "estimatedOverhead": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["additionalSteps", "evidenceArtifacts"],
+      "properties": {
+        "additionalSteps": { "type": "integer", "minimum": 0 },
+        "evidenceArtifacts": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "nextCommand": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "string", "minLength": 1 }
+      ]
+    },
+    "downgrade": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allowed", "reasonCodes"],
+      "properties": {
+        "allowed": { "type": "boolean" },
+        "reasonCodes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "authorityBoundary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authorizationGranted", "git", "release", "deployment", "production", "business"],
+      "properties": {
+        "authorizationGranted": { "const": false },
+        "git": { "const": false },
+        "release": { "const": false },
+        "deployment": { "const": false },
+        "production": { "const": false },
+        "business": { "const": false }
+      }
+    },
+    "authorizationGranted": { "const": false },
+    "preferenceSource": { "const": "default_auto" },
+    "persistedPreference": { "type": "null" }
+  },
+  "examples": [
+    {
+      "schemaVersion": "OwlCodaRunKitUsageModeRecommendationV1",
+      "status": "mode_recommended",
+      "requestedMode": "auto",
+      "recommendedMode": "managed",
+      "continuity": "project_driver",
+      "assurance": "quick",
+      "triggerReasons": ["cross_session_continuity", "single_bounded_verification"],
+      "rejectedLighterModes": [
+        {
+          "mode": "off",
+          "reasonCodes": ["cross_session_continuity", "single_bounded_verification"]
+        },
+        {
+          "mode": "light",
+          "reasonCodes": ["cross_session_continuity", "single_bounded_verification"]
+        }
+      ],
+      "estimatedOverhead": {
+        "additionalSteps": 3,
+        "evidenceArtifacts": 2
+      },
+      "nextCommand": "owlrunkit project status --workspace '.'",
+      "downgrade": {
+        "allowed": true,
+        "reasonCodes": []
+      },
+      "authorityBoundary": {
+        "authorizationGranted": false,
+        "git": false,
+        "release": false,
+        "deployment": false,
+        "production": false,
+        "business": false
+      },
+      "authorizationGranted": false
+    }
+  ]
+}

package/scripts/runkit-contract/templates/assurance-request.json

@@ -6,6 +6,12 @@
   "longRunning": false,
   "interruptionRecovery": false,
   "dirtyParallelWorkspace": false,
+  "irreversibleChange": false,
+  "rollbackUncertain": false,
+  "permissionSensitive": false,
+  "securitySensitive": false,
+  "fundsAtRisk": false,
+  "schemaOrDataMigration": false,
   "exactCommandCount": 1,
   "writerCount": 0,
   "riskCategories": [],

package/scripts/runkit-contract/usage-mode.mjs

@@ -0,0 +1,229 @@
+const USER_MODES = new Set(["auto", "off", "light", "managed", "formal"]);
+
+const BOOLEAN_FACTS = [
+  "needsDurableEvidence",
+  "mayMutateProject",
+  "externalSideEffects",
+  "crossSession",
+  "longRunning",
+  "interruptionRecovery",
+  "dirtyParallelWorkspace",
+  "irreversibleChange",
+  "rollbackUncertain",
+  "permissionSensitive",
+  "securitySensitive",
+  "fundsAtRisk",
+  "schemaOrDataMigration",
+  "needsFormalAcceptance",
+];
+
+const MATERIAL_RISK_CATEGORIES = new Map([
+  ["destructive", "risk_destructive"],
+  ["foreign_write", "risk_foreign_write"],
+  ["funds", "funds_at_risk"],
+  ["migration", "schema_or_data_migration"],
+]);
+
+const KNOWN_RISK_CATEGORIES = new Set([
+  "backtest",
+  "deployment",
+  "destructive",
+  "foreign_write",
+  "funds",
+  "integration",
+  "migration",
+  "production",
+  "release",
+]);
+
+const AUTHORITY_BOUNDARY = Object.freeze({
+  authorizationGranted: false,
+  git: false,
+  release: false,
+  deployment: false,
+  production: false,
+  business: false,
+});
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}
+
+function requireFacts(input) {
+  if (!USER_MODES.has(input?.requestedMode)) {
+    throw new Error("requestedMode must be auto, off, light, managed, or formal");
+  }
+  for (const field of BOOLEAN_FACTS) {
+    if (typeof input[field] !== "boolean") throw new Error(`${field} must be boolean`);
+  }
+  for (const field of ["exactCommandCount", "writerCount"]) {
+    if (!Number.isSafeInteger(input[field]) || input[field] < 0) {
+      throw new Error(`${field} must be a non-negative safe integer`);
+    }
+  }
+  if (!Array.isArray(input.riskCategories)
+    || !input.riskCategories.every((value) => typeof value === "string")) {
+    throw new Error("riskCategories must be an array of strings");
+  }
+  if (input.riskCategories.some((value) => !KNOWN_RISK_CATEGORIES.has(value))) {
+    throw new Error("riskCategories contains an unknown category");
+  }
+}
+
+function formalReasonCodes(input) {
+  return uniqueSorted([
+    ...(input.writerCount > 1 ? ["multiple_writers"] : []),
+    ...(input.permissionSensitive ? ["permission_sensitive"] : []),
+    ...(input.securitySensitive ? ["security_sensitive"] : []),
+    ...(input.fundsAtRisk ? ["funds_at_risk"] : []),
+    ...(input.irreversibleChange ? ["irreversible_change"] : []),
+    ...(input.rollbackUncertain ? ["rollback_uncertain"] : []),
+    ...(input.schemaOrDataMigration ? ["schema_or_data_migration"] : []),
+    ...(input.needsFormalAcceptance ? ["formal_acceptance_required"] : []),
+    ...input.riskCategories
+      .filter((category) => MATERIAL_RISK_CATEGORIES.has(category))
+      .map((category) => MATERIAL_RISK_CATEGORIES.get(category)),
+  ]);
+}
+
+function continuityReasonCodes(input) {
+  return uniqueSorted([
+    ...(input.crossSession ? ["cross_session_continuity"] : []),
+    ...(input.longRunning ? ["long_running_continuity"] : []),
+    ...(input.interruptionRecovery ? ["interruption_recovery_continuity"] : []),
+    ...(input.dirtyParallelWorkspace ? ["dirty_workspace_continuity"] : []),
+    ...(input.writerCount > 1 ? ["multi_writer_continuity"] : []),
+  ]);
+}
+
+function estimateOverhead(continuity, assurance) {
+  const continuitySteps = continuity === "project_driver" ? 2 : 0;
+  const assuranceSteps = assurance === "quick" ? 1 : assurance === "formal" ? 3 : 0;
+  const continuityArtifacts = continuity === "project_driver" ? 1 : 0;
+  const assuranceArtifacts = assurance === "quick" ? 1 : assurance === "formal" ? 4 : 0;
+  return {
+    additionalSteps: continuitySteps + assuranceSteps,
+    evidenceArtifacts: continuityArtifacts + assuranceArtifacts,
+  };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function nextCommand({ workspaceRoot, continuity, assurance }) {
+  const workspace = shellQuote(workspaceRoot ?? ".");
+  if (assurance === "formal") {
+    return `owlrunkit formal start --workspace ${workspace}`;
+  }
+  if (continuity === "project_driver") {
+    return `owlrunkit project status --workspace ${workspace}`;
+  }
+  if (assurance === "quick") {
+    return `owlrunkit quick-verify --workspace ${workspace} -- <command> [args...]`;
+  }
+  return null;
+}
+
+function rejectedModes(recommendedMode, reasonCodes) {
+  const lighter = {
+    off: [],
+    light: ["off"],
+    managed: ["off", "light"],
+    formal: ["off", "light", "managed"],
+  }[recommendedMode];
+  return lighter.map((mode) => ({ mode, reasonCodes }));
+}
+
+export function recommendUsageModeV1(input) {
+  requireFacts(input);
+  const forcedFormalReasons = formalReasonCodes(input);
+  const continuityReasons = continuityReasonCodes(input);
+  const requestedMode = input.requestedMode;
+
+  let continuity = "none";
+  let assurance = "none";
+  const triggerReasons = [];
+
+  if (requestedMode === "managed" || (requestedMode === "auto" && continuityReasons.length > 0)) {
+    continuity = "project_driver";
+    triggerReasons.push(...(continuityReasons.length > 0 ? continuityReasons : ["managed_mode_requested"]));
+  }
+
+  if (forcedFormalReasons.length > 0) {
+    assurance = "formal";
+    if (continuityReasons.length > 0) continuity = "project_driver";
+    triggerReasons.push(...forcedFormalReasons);
+  } else if (requestedMode === "formal") {
+    assurance = "formal";
+    triggerReasons.push("formal_mode_requested");
+  } else if (requestedMode === "light") {
+    assurance = "quick";
+    triggerReasons.push("light_mode_requested");
+  } else if (requestedMode !== "off" && input.needsDurableEvidence) {
+    if (input.exactCommandCount === 1) {
+      assurance = "quick";
+      triggerReasons.push("single_bounded_verification");
+    } else {
+      triggerReasons.push("quick_exact_command_required");
+    }
+  } else if (requestedMode === "off") {
+    triggerReasons.push("off_mode_requested");
+  } else {
+    triggerReasons.push("durable_evidence_not_required");
+  }
+
+  const recommendedMode = assurance === "formal"
+    ? "formal"
+    : continuity === "project_driver"
+      ? "managed"
+      : assurance === "quick"
+        ? "light"
+        : "off";
+  const blockingReasons = forcedFormalReasons.length > 0
+    ? forcedFormalReasons
+    : uniqueSorted(triggerReasons);
+  const downgradeAllowed = forcedFormalReasons.length === 0;
+
+  return {
+    schemaVersion: "OwlCodaRunKitUsageModeRecommendationV1",
+    status: "mode_recommended",
+    requestedMode,
+    recommendedMode,
+    continuity,
+    assurance,
+    triggerReasons: uniqueSorted(triggerReasons),
+    rejectedLighterModes: rejectedModes(recommendedMode, blockingReasons),
+    estimatedOverhead: estimateOverhead(continuity, assurance),
+    nextCommand: nextCommand({ workspaceRoot: input.workspaceRoot, continuity, assurance }),
+    downgrade: {
+      allowed: downgradeAllowed,
+      reasonCodes: downgradeAllowed ? [] : forcedFormalReasons,
+    },
+    authorityBoundary: { ...AUTHORITY_BOUNDARY },
+    authorizationGranted: false,
+  };
+}
+
+export function formatUsageModeHumanV1(result) {
+  const triggers = result.triggerReasons.length > 0
+    ? result.triggerReasons.join(", ")
+    : "none";
+  const rejected = result.rejectedLighterModes.length > 0
+    ? result.rejectedLighterModes
+      .map((entry) => `${entry.mode} (${entry.reasonCodes.join(", ")})`)
+      .join("; ")
+    : "none";
+  return [
+    `Recommended mode: ${result.recommendedMode}`,
+    `Continuity: ${result.continuity}`,
+    `Assurance: ${result.assurance}`,
+    `Why: ${triggers}`,
+    `Rejected lighter modes: ${rejected}`,
+    `Estimated overhead: ${result.estimatedOverhead.additionalSteps} steps, ${result.estimatedOverhead.evidenceArtifacts} evidence artifacts`,
+    `Next command: ${result.nextCommand ?? "none"}`,
+    `User downgrade allowed: ${result.downgrade.allowed ? "yes" : "no"}`,
+    "Authority: no Git, release, deployment, production, or business authorization granted.",
+    "",
+  ].join("\n");
+}