omp-conductor 0.17.0 → 0.18.0

package/src/config.ts

@@ -17,15 +17,20 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import {
+  ARM_PROOFS,
   AUTHORITY_HOLDERS,
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   CONFIG_VERSION,
+  DEFAULT_ARM_PROOF,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_POLICY,
+  DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
   LEGACY_RELEASE_POLICIES,
@@ -35,6 +40,9 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   INTERRUPT_CATEGORIES,
   DIGEST_CADENCES,
   WEEKDAYS,
@@ -51,10 +59,13 @@ import {
   type ReleaseRequirement,
   type ReportScope,
   type ReportingPolicy,
+  type ReviewPolicy,
+  type ReviewStrictness,
   type Weekday,
   type WeeklyAvailability,
   type RepoTarget,
   type ResolvedGrants,
+  type ArmProof,
 } from "./types.ts";
 import {
   AUTHORITY_HOLDER_LIST,
@@ -68,6 +79,7 @@ import {
   ORCHESTRATOR_MODE_LIST,
   RELEASE_REQUIREMENT_LIST,
   RELEASE_SHAPE_LIST,
+  REVIEW_STRICTNESS_LIST,
   REPORT_SCOPE_LIST,
   WEEKDAY_LIST,
   quoteList,
@@ -95,10 +107,13 @@ const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
  * Used when a project omits `stateLabels`. Namespaced so a human scanning the
  * tracker can tell dispatcher-written labels from their own.
  */
-const DEFAULT_STATE_LABELS: ProjectConfig["stateLabels"] = {
+export const DEFAULT_STATE_LABELS: ProjectConfig["stateLabels"] = {
   inProgress: "agent:in-progress",
   blocked: "agent:blocked",
   failed: "agent:failed",
+  // The operator's park gesture (#507): unnamed by design — it is theirs, and
+  // the operator adds it by hand until setup grows a confirm step (slice 2).
+  backlog: "backlog",
 };
 
 /**
@@ -313,6 +328,34 @@ export function resolvePolicy(p: ProjectConfig): ProjectPolicy {
   return clonePolicy(p.policy ?? DEFAULT_PROJECT_POLICY);
 }
 
+/**
+ * How this project's `arm` proves a human just approved arming (#613),
+ * complete.
+ *
+ * The loader always materialises `arm` (finalizeProject), so this is only ever
+ * the fallback for a `ProjectConfig` that never went through it — a hand-built
+ * one in a test, or a config written before the key existed. Absent resolves
+ * to {@link DEFAULT_ARM_PROOF} (`challenge`): the authenticated round-trip,
+ * which is the behaviour every existing install already has.
+ */
+export function resolveArmProof(p: ProjectConfig): ArmProof {
+  return p.arm?.proof === "claim-only" ? "claim-only" : DEFAULT_ARM_PROOF;
+}
+
+/**
+ * The project's review policy (#678), complete.
+ *
+ * The loader always materialises `review` (finalizeProject), so this is only
+ * ever the fallback for a `ProjectConfig` that never went through it — a
+ * hand-built one in a test, or a config written before the key existed.
+ * Absent resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration
+ * default every existing install deterministically upgrades to. A fresh object
+ * each call, so mutating the result cannot reach the config it came from.
+ */
+export function resolveReview(p: ProjectConfig): ReviewPolicy {
+  return { ...(p.review ?? DEFAULT_REVIEW_POLICY) };
+}
+
 /**
  * A policy with no array shared with its source.
  *
@@ -835,12 +878,21 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
       return `reporting.availability must be an object`;
     }
     if (rel.length === 1 && relStr === "escalation") return `escalation must be an object`;
+    if (rel.length === 1 && relStr === "arm") {
+      return `arm must be an object with a "proof" of ${ARM_PROOF_LIST}`;
+    }
     if (rel.length === 1 && relStr === "authority") {
       return `authority must be an object with "merge", "release" and "promotion" of ${AUTHORITY_HOLDER_LIST}`;
     }
     if (rel.length === 1 && relStr === "policy") {
       return `policy must be an object with "merge" and "release" sections`;
     }
+    if (rel.length === 1 && relStr === "review") {
+      return `review must be an object with "strictness" and "maxRounds"`;
+    }
+    if (rel.length === 2 && rel[0] === "review" && rel[1] === "maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     if (rel.length === 2 && relStr === "policy") return `${pathStr} must be an object`;
     if (rel.length === 1 && relStr === "caps") return `caps must be an object`;
     if (rel.length === 2 && relStr === "caps" && rel[1] === "planUsage") {
@@ -891,6 +943,7 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   if (issue.code === "unrecognized_keys") {
     const keys = (issue.keys ?? []).join(", ");
     if (pathStr === "policy") return `policy has unknown key(s): ${keys} — expected "merge" or "release"`;
+    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness" and "maxRounds"`;
     if (pathStr === "policy.merge") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_MERGE_KEYS}`;
     if (pathStr === "policy.release") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_RELEASE_KEYS}`;
     if (pathStr === "caps.planUsage") {
@@ -940,6 +993,9 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
 
   // Regex / custom-message failures carry the finding in issue.message.
   if (issue.code === "too_small") {
+    if (pathStr === "review.maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     // Empty array (reporting.interruptOn, availability.days) has its own line.
     if (parentOf(rel) === "reporting.interruptOn") return `reporting.interruptOn must name at least one category`;
     if (pathStr === "reporting.availability.days") return `reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`;
@@ -955,6 +1011,9 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   }
 
   if (issue.code === "too_big") {
+    if (pathStr === "review.maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     if (rel.length === 2 && rel[0] === "caps") return capProblem(rel[1] as string, found());
     if (pathStr === "caps.planUsage.maxUsedFraction") {
       return `caps.planUsage.maxUsedFraction must be a fraction between 0 and 1 (0.85 holds at 85% of the allowance), found ${found()}`;
@@ -995,6 +1054,9 @@ function capProblem(key: string, found: string): string {
 const POLICY_MERGE_KEYS = quoteList(Object.keys(clonePolicy(DEFAULT_PROJECT_POLICY).merge));
 const POLICY_RELEASE_KEYS = quoteList(Object.keys(clonePolicy(DEFAULT_PROJECT_POLICY).release));
 
+/** The closed `arm.proof` vocabulary, for the not-an-object wording. */
+const ARM_PROOF_LIST = quoteList(ARM_PROOFS);
+
 // ---------------------------------------------------------------------------
 // residue: cross-field coherence, migrations, defaults, path expansion
 // ---------------------------------------------------------------------------
@@ -1062,6 +1124,7 @@ function finalizeProject(
 
   const stateLabels = p["stateLabels"] as Raw | undefined;
   const escalation = finalizeEscalation(p["escalation"] as Raw | undefined);
+  const arm = finalizeArm(p["arm"] as Raw | undefined);
   const authority = finalizeAuthority(p["authority"] as Raw | undefined);
   const releasePolicy = finalizeReleasePolicy(p["releasePolicy"], label, problems);
   const strandedTagRepos =
@@ -1077,6 +1140,7 @@ function finalizeProject(
     );
   }
   const policy = finalizePolicy(p["policy"], label, problems);
+  const review = finalizeReview(p["review"] as Raw | undefined);
   const caps = reconcileCaps(p["caps"], `${label}: caps`, problems, legacyCaps);
   const reporting = finalizeReporting(p["reporting"], label, problems);
   const recoveryMerges = (p["recoveryMerges"] as RecoveryMergeAuthorization[] | undefined)?.map(
@@ -1175,6 +1239,7 @@ function finalizeProject(
       inProgress: pickString(stateLabels?.["inProgress"], DEFAULT_STATE_LABELS.inProgress),
       blocked: pickString(stateLabels?.["blocked"], DEFAULT_STATE_LABELS.blocked),
       failed: pickString(stateLabels?.["failed"], DEFAULT_STATE_LABELS.failed),
+      backlog: pickString(stateLabels?.["backlog"], DEFAULT_STATE_LABELS.backlog),
     },
     routing: { labelPrefix, repos },
     caps,
@@ -1183,6 +1248,8 @@ function finalizeProject(
     ...(modelFallbackThreshold === undefined ? {} : { modelFallbackThreshold }),
     ...(effectiveOmpSettings === undefined ? {} : { ompSettings: effectiveOmpSettings }),
     escalation,
+    arm,
+    review,
     authority,
     releasePolicy,
     policy,
@@ -1194,6 +1261,35 @@ function finalizeProject(
   };
 }
 
+/**
+ * The project's arming gate (#613), complete. A config written before the key
+ * existed — or one that never answered — materialises as `challenge`, the
+ * authenticated round-trip every existing install already runs, so an upgrade
+ * changes no behaviour. zod has already rejected anything that is not a
+ * `"challenge"` / `"claim-only"` string, so this only fills the absent case.
+ */
+function finalizeArm(parsed: Raw | undefined): ProjectConfig["arm"] {
+  if (parsed === undefined) return { proof: DEFAULT_ARM_PROOF };
+  return { proof: (parsed["proof"] as ArmProof | undefined) ?? DEFAULT_ARM_PROOF };
+}
+
+/**
+ * The project's review policy (#678), complete. A config written before the
+ * key existed — or one that never answered — materialises as
+ * {@link DEFAULT_REVIEW_POLICY}, the documented migration default, so an
+ * upgrade changes no existing project's behaviour beyond what its operators
+ * then choose in setup. zod has already rejected anything outside the
+ * strictness vocabulary or the validated round range, so this only fills the
+ * absent-case default.
+ */
+function finalizeReview(parsed: Raw | undefined): ProjectConfig["review"] {
+  if (parsed === undefined) return { ...DEFAULT_REVIEW_POLICY };
+  return {
+    strictness: (parsed["strictness"] as ReviewStrictness | undefined) ?? DEFAULT_REVIEW_STRICTNESS,
+    maxRounds: (parsed["maxRounds"] as number | undefined) ?? DEFAULT_REVIEW_MAX_ROUNDS,
+  };
+}
+
 function finalizeEscalation(parsed: Raw | undefined): ProjectConfig["escalation"] {
   if (parsed === undefined) {
     return { fallbackToIssueComment: true, orchestrator: "embedded" };