@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/bin/modules/flow/state.ts

@@ -0,0 +1,351 @@
+import {
+  FLOW_SCHEMA_VERSION,
+  FlowError,
+  REVIEW_NECESSITY_TIERS,
+  TERMINAL_STATES,
+  canonicalJson,
+  deepClone,
+  isRecord,
+  normalizeSha,
+  isoNow,
+} from "./common";
+import { normalizeAcceptanceManifest } from "./acceptance";
+import { repositoryBindingIdentity } from "./state-policy";
+
+export {
+  repositoryBindingIdentity,
+  requireRepositoryBindingMatch,
+  validatePostMergeReleasePolicy,
+} from "./state-policy";
+export {
+  isCurrentClearWave,
+  reviewConvergenceStarted,
+  reviewTier,
+} from "./state-review";
+
+export const PR_REF_PATTERN =
+  /^(?:PR#\d+|[^\s/]+\/[^\s#]+#\d+|https?:\/\/[^\s]+\/pulls?\/\d+)$/;
+export const POST_MERGE_FINALITY_STATUSES = {
+  target_ci: new Set(["passed"]),
+  release: new Set(["published", "not-applicable"]),
+};
+
+export function defaultReviewState(): Record<string, unknown> {
+  return {
+    next_epoch: 1,
+    pr_ref: null,
+    pr_base_sha: null,
+    pr_head_sha: null,
+    pr_bound_at: null,
+    base_ref: null,
+    base_ref_identity: null,
+    pr_base_ref_identity: null,
+    authorization_message_ids: [],
+    terra_authorization_message_ids: [],
+    active_epoch_id: null,
+    active_wave_id: null,
+    epochs: [],
+    waves: {},
+    cumulative: {
+      finding_to_group: {},
+      blocker_fingerprints: [],
+      invariants: [],
+      coverage_lanes: [],
+      conflicts: [],
+      conflict_dispositions: [],
+    },
+  };
+}
+
+export function pendingReviewAssessment(): Record<string, unknown> {
+  return {
+    tier: null,
+    reason: null,
+    assessed_at: null,
+    assessed_head_sha: null,
+    source: "pending",
+  };
+}
+
+export function migratedReviewAssessment(): Record<string, unknown> {
+  return {
+    tier: 3,
+    reason: "Migrated from the pre-tier mandatory direct review contract.",
+    assessed_at: null,
+    assessed_head_sha: null,
+    source: "pre-tier-migration",
+  };
+}
+
+export function reviewModeForTier(tier: number | null): string {
+  if (tier === null) return "assessment-required";
+  if (tier === 1) return "not-required";
+  if (tier === 2) return "advisory";
+  return `mandatory-tier-${tier}`;
+}
+
+export function normalizePostMergeEvidence(
+  payload: unknown,
+): Record<string, unknown> {
+  if (
+    !isRecord(payload) ||
+    Object.keys(payload).length !== 6 ||
+    typeof payload.pr_ref !== "string" ||
+    !PR_REF_PATTERN.test(payload.pr_ref.trim()) ||
+    !isRecord(payload.finality)
+  )
+    throw new FlowError(
+      "post-merge evidence does not match the required schema",
+    );
+  const mergedAt =
+    typeof payload.merged_at === "string" ? payload.merged_at.trim() : "";
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      mergedAt,
+    ) ||
+    Number.isNaN(Date.parse(mergedAt))
+  )
+    throw new FlowError("post-merge merged_at is invalid");
+  if (Object.keys(payload.finality).length !== 2)
+    throw new FlowError("post-merge finality is invalid");
+  const finality: Record<string, Record<string, unknown>> = {};
+  for (const surface of ["target_ci", "release"] as const) {
+    const fact = payload.finality[surface];
+    if (!isRecord(fact))
+      throw new FlowError(`post-merge finality.${surface} is invalid`);
+    const status =
+      fact.status === "not_applicable" ? "not-applicable" : fact.status;
+    if (
+      typeof status !== "string" ||
+      !POST_MERGE_FINALITY_STATUSES[surface].has(status)
+    )
+      throw new FlowError(`post-merge finality.${surface} is not terminal`);
+    finality[surface] = {
+      ...fact,
+      status,
+      bound_sha: normalizeSha(fact.bound_sha, `finality.${surface}.bound_sha`),
+    };
+    if (fact.run_id !== undefined && typeof fact.run_id !== "string")
+      throw new FlowError(`post-merge finality.${surface}.run_id is invalid`);
+    if (surface === "release" && status === "not-applicable") {
+      const policy = fact.policy_evidence;
+      if (fact.release_expected !== false || !isRecord(policy))
+        throw new FlowError(
+          "post-merge release not-applicable requires policy evidence",
+        );
+      if (!repositoryBindingIdentity(policy.repository))
+        throw new FlowError("post-merge release policy repository is invalid");
+      for (const field of ["target_branch", "policy_locator", "reason"]) {
+        if (typeof policy[field] !== "string" || !policy[field].trim())
+          throw new FlowError(`post-merge release policy ${field} is invalid`);
+      }
+      if (
+        normalizeSha(policy.merge_sha, "release policy merge_sha") !==
+        finality[surface].bound_sha
+      )
+        throw new FlowError(
+          "post-merge release policy must bind the merge SHA",
+        );
+    } else if (
+      surface === "release" &&
+      "release_expected" in fact &&
+      fact.release_expected !== true
+    ) {
+      throw new FlowError(
+        "post-merge release finality conflicts with release_expected",
+      );
+    }
+  }
+  const mergeSha = normalizeSha(payload.merge_sha, "post-merge merge_sha");
+  if (Object.values(finality).some((fact) => fact.bound_sha !== mergeSha))
+    throw new FlowError("post-merge finality facts must bind the merge SHA");
+  return {
+    pr_ref: payload.pr_ref.trim(),
+    head_sha: normalizeSha(payload.head_sha, "post-merge head_sha"),
+    base_sha: normalizeSha(payload.base_sha, "post-merge base_sha"),
+    merge_sha: mergeSha,
+    merged_at: mergedAt,
+    finality,
+  };
+}
+
+export function normalizeLedger(input: unknown): Record<string, unknown> {
+  if (!isRecord(input)) throw new FlowError("ledger payload is invalid");
+  if (input.flow_type === "initiative") return input;
+  const payload = input;
+  const rawVersion = payload.schema_version ?? 1;
+  if (
+    typeof rawVersion !== "number" ||
+    !Number.isInteger(rawVersion) ||
+    ![5, 6, FLOW_SCHEMA_VERSION].includes(rawVersion)
+  )
+    throw new FlowError(
+      "flow receipt supports only schema v5/v6 migration or schema v7",
+    );
+  const version = rawVersion;
+  if (version === 5) {
+    if (
+      payload.state !== "active" &&
+      !(typeof payload.state === "string" && TERMINAL_STATES.has(payload.state))
+    )
+      throw new FlowError("schema v5 receipt state is invalid");
+    if (payload.state !== "active") return payload;
+    if (payload.review !== undefined && payload.legacy_review === undefined)
+      payload.legacy_review = deepClone(payload.review);
+    if (
+      payload.review_assessment !== undefined &&
+      payload.legacy_review_assessment === undefined
+    )
+      payload.legacy_review_assessment = deepClone(payload.review_assessment);
+    const legacyReview = isRecord(payload.legacy_review)
+      ? payload.legacy_review
+      : undefined;
+    payload.legacy_compatibility = true;
+    payload.legacy_schema_version = version;
+    payload.schema_version = FLOW_SCHEMA_VERSION;
+    payload.review = defaultReviewState();
+    for (const key of [
+      "pr_ref",
+      "pr_base_sha",
+      "pr_head_sha",
+      "pr_bound_at",
+      "pr_base_ref_identity",
+      "base_ref",
+      "base_ref_identity",
+    ])
+      if (legacyReview && Object.hasOwn(legacyReview, key))
+        (payload.review as Record<string, unknown>)[key] = legacyReview[key];
+    payload.review_assessment = migratedReviewAssessment();
+  } else if (version === 6) {
+    payload.review_assessment ??= pendingReviewAssessment();
+    payload.legacy_compatibility = true;
+    payload.legacy_schema_version = version;
+    payload.schema_version = FLOW_SCHEMA_VERSION;
+    payload.repository_binding ??= null;
+    payload.provider_facts ??= null;
+  } else {
+    payload.review_assessment ??= pendingReviewAssessment();
+    payload.repository_binding ??= null;
+    payload.provider_facts ??= null;
+  }
+  const assessment = payload.review_assessment;
+  if (!isRecord(assessment))
+    throw new FlowError("ledger review assessment is invalid");
+  const tier = assessment.tier;
+  if (
+    tier !== null &&
+    (typeof tier !== "number" || !REVIEW_NECESSITY_TIERS.has(tier))
+  )
+    throw new FlowError("ledger review assessment tier is invalid");
+  if (tier === null) {
+    if (
+      assessment.reason !== null ||
+      assessment.assessed_at !== null ||
+      assessment.assessed_head_sha !== null ||
+      assessment.source !== "pending"
+    )
+      throw new FlowError("pending review assessment is invalid");
+  } else if (typeof assessment.reason !== "string" || !assessment.reason.trim())
+    throw new FlowError("recorded review assessment reason is invalid");
+  else if (assessment.source === "pre-tier-migration") {
+    if (canonicalJson(assessment) !== canonicalJson(migratedReviewAssessment()))
+      throw new FlowError("migrated review assessment is invalid");
+  } else {
+    if (
+      assessment.source !== "agent-assessment" ||
+      typeof assessment.assessed_at !== "string" ||
+      !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+        assessment.assessed_at,
+      ) ||
+      Number.isNaN(Date.parse(assessment.assessed_at)) ||
+      typeof assessment.assessed_head_sha !== "string" ||
+      !/^[0-9a-f]{40}$/.test(assessment.assessed_head_sha)
+    )
+      throw new FlowError("recorded review assessment is invalid");
+  }
+  payload.review_mode = reviewModeForTier(tier as number | null);
+  payload.acceptance_required = true;
+  payload.acceptance_manifest ??= null;
+  payload.phase_acceptance_evidence ??= [];
+  if (!Array.isArray(payload.phase_acceptance_evidence))
+    throw new FlowError("phase acceptance evidence is invalid");
+  if (payload.acceptance_manifest)
+    payload.acceptance_manifest = normalizeAcceptanceManifest(
+      payload.acceptance_manifest,
+    );
+  if (payload.review !== undefined && !isRecord(payload.review))
+    throw new FlowError("ledger review state is invalid");
+  const review = isRecord(payload.review) ? payload.review : {};
+  const defaults = defaultReviewState();
+  for (const [key, value] of Object.entries(defaults))
+    review[key] ??= deepClone(value);
+  payload.review = review;
+  payload.receipts ??= [];
+  payload.events ??= [];
+  if (!Array.isArray(payload.receipts) || !Array.isArray(payload.events))
+    throw new FlowError("ledger receipts or events are invalid");
+  payload.convergence ??= {
+    state: "pending",
+    round: 0,
+    repair_round: 0,
+    diagnostic_used: false,
+    blockers: [],
+  };
+  if (!isRecord(payload.convergence))
+    throw new FlowError("ledger convergence state is invalid");
+  return payload;
+}
+
+export function projectStatusPayload(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(projectStatusPayload);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(
+        ([key]) =>
+          !(key.startsWith("validation") && key.endsWith("_scope")) &&
+          !(key.startsWith("full_") && key.includes("validation")),
+      )
+      .map(([key, item]) => [key, projectStatusPayload(item)]),
+  );
+}
+
+export function initialLedger(
+  runId: string,
+  flowType: string,
+  baseSha: string,
+  headSha: string,
+  manifest: unknown,
+  prRef?: string,
+): Record<string, unknown> {
+  const review = defaultReviewState();
+  review.pr_ref = prRef?.trim() || null;
+  return {
+    schema_version: FLOW_SCHEMA_VERSION,
+    run_id: runId,
+    flow_type: flowType,
+    base_sha: baseSha,
+    head_sha: headSha,
+    state: "active",
+    created_at: isoNow(),
+    updated_at: isoNow(),
+    command_budget_seconds: 1800,
+    retry_budget_per_identity: 1,
+    convergence: {
+      state: "pending",
+      round: 0,
+      repair_round: 0,
+      diagnostic_used: false,
+      blockers: [],
+    },
+    review,
+    acceptance_manifest: manifest,
+    acceptance_required: true,
+    receipts: [],
+    events: [],
+    review_assessment: pendingReviewAssessment(),
+    review_mode: "assessment-required",
+    repository_binding: null,
+    provider_facts: null,
+  };
+}

package/toolkit/skills/bin/modules/flow/storage.ts

@@ -0,0 +1,228 @@
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { systemClock } from "../core/clock";
+import { tryLockFile } from "../core/security_file";
+import { FlowError, canonicalJson, sha256Bytes } from "./common";
+
+export interface StableBytes {
+  bytes: Uint8Array;
+  identity: string;
+}
+
+function sleepSync(milliseconds: number): void {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, milliseconds);
+}
+
+export function ensureDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+
+export function withExclusiveLock<T>(
+  path: string,
+  callback: () => T,
+  timeoutMs = 30_000,
+  createIfMissing = true,
+  expectedParentIdentity?: { dev: number; ino: number },
+  expectedFileIdentity?: { dev: number; ino: number },
+): T {
+  if (createIfMissing) ensureDirectory(dirname(path));
+  const started = Date.now();
+  while (true) {
+    const lock = tryLockFile(
+      path,
+      createIfMissing,
+      expectedParentIdentity,
+      expectedFileIdentity,
+    );
+    if (lock !== null) {
+      try {
+        return callback();
+      } finally {
+        lock.release();
+      }
+    }
+    if (Date.now() - started >= timeoutMs)
+      throw new FlowError("flow state lock timed out");
+    sleepSync(10);
+  }
+}
+
+export async function withExclusiveLockAsync<T>(
+  path: string,
+  callback: () => Promise<T>,
+  timeoutMs = 30_000,
+): Promise<T> {
+  ensureDirectory(dirname(path));
+  const started = Date.now();
+  while (true) {
+    const lock = tryLockFile(path);
+    if (lock !== null) {
+      try {
+        return await callback();
+      } finally {
+        lock.release();
+      }
+    }
+    if (Date.now() - started >= timeoutMs)
+      throw new FlowError("flow state lock timed out");
+    await systemClock.sleep(10);
+  }
+}
+
+export function atomicWriteBytes(path: string, bytes: Uint8Array): void {
+  ensureDirectory(dirname(path));
+  const temporary = join(
+    dirname(path),
+    `.${path.split("/").at(-1) ?? "state"}.${randomUUID()}.tmp`,
+  );
+  const fd = openSync(temporary, "w", 0o600);
+  try {
+    writeFileSync(fd, bytes);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(temporary, path);
+  } catch (error) {
+    if (existsSync(temporary)) unlinkSync(temporary);
+    throw error;
+  }
+}
+
+export function atomicWriteJson(path: string, value: unknown): void {
+  atomicWriteBytes(path, Buffer.from(prettyJson(value), "utf8"));
+}
+
+function sortJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, item]) => [key, sortJson(item)]),
+  );
+}
+
+export function readJson(path: string, errorMessage: string): unknown {
+  try {
+    return JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        stableFileBytes(path, errorMessage),
+      ),
+    );
+  } catch (error) {
+    throw new FlowError(errorMessage, { cause: error });
+  }
+}
+
+export function stableFileBytes(path: string, label: string): Uint8Array {
+  const noFollow = constants.O_NOFOLLOW;
+  if (typeof noFollow !== "number")
+    throw new FlowError(`${label} cannot be read without no-follow support`);
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | noFollow);
+    const before = fstatSync(fd);
+    const bytes = readFileSync(fd);
+    const after = fstatSync(fd);
+    if (
+      before.dev !== after.dev ||
+      before.ino !== after.ino ||
+      before.size !== after.size ||
+      Math.trunc(before.mtimeMs * 1_000_000) !==
+        Math.trunc(after.mtimeMs * 1_000_000) ||
+      Math.trunc(before.ctimeMs * 1_000_000) !==
+        Math.trunc(after.ctimeMs * 1_000_000)
+    )
+      throw new FlowError(`${label} changed while being read`);
+    return new Uint8Array(bytes);
+  } catch (error) {
+    if (error instanceof FlowError) throw error;
+    throw new FlowError(`${label} cannot be read`, { cause: error });
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function stableFileDigest(path: string, label: string): string {
+  return sha256Bytes(stableFileBytes(path, label));
+}
+
+export function archiveImmutable(
+  path: string,
+  bytes: Uint8Array,
+  label: string,
+): void {
+  ensureDirectory(dirname(path));
+  if (existsSync(path)) {
+    const current = stableFileBytes(path, label);
+    if (Buffer.compare(Buffer.from(current), Buffer.from(bytes)) !== 0) {
+      throw new FlowError(`${label} already exists with different content`);
+    }
+    return;
+  }
+  atomicWriteBytes(path, bytes);
+}
+
+export function readText(path: string, label: string): string {
+  return new TextDecoder("utf-8", { fatal: true }).decode(
+    stableFileBytes(path, label),
+  );
+}
+
+export function canonicalText(value: unknown): string {
+  return `${canonicalJson(value)}\n`;
+}
+
+export function prettyJson(value: unknown): string {
+  const text = `${JSON.stringify(sortJson(value), null, 2)}\n`;
+  return text.replace(/[^\x00-\x7f]/g, (char) => {
+    const code = char.charCodeAt(0).toString(16).padStart(4, "0");
+    return `\\u${code}`;
+  });
+}
+
+export function archiveBytes(
+  path: string,
+  bytes: Uint8Array,
+  label: string,
+): void {
+  ensureDirectory(dirname(path));
+  const temporary = join(
+    dirname(path),
+    `.${path.split("/").at(-1) ?? "archive"}.${randomUUID()}.tmp`,
+  );
+  const fd = openSync(temporary, "w", 0o600);
+  try {
+    writeFileSync(fd, bytes);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    linkSync(temporary, path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const current = stableFileBytes(path, label);
+    if (Buffer.compare(Buffer.from(current), Buffer.from(bytes)) !== 0)
+      throw new FlowError(`${label} already exists with different content`);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}

package/toolkit/skills/bin/modules/flow/validation-input.ts

@@ -0,0 +1,28 @@
+import { FlowError, stableHash } from "./common";
+
+export function normalizeInputPaths(paths: string[]): string[] {
+  return [...new Set(paths.map((path) => path.trim().replace(/^(\.\/)+/, "")))]
+    .map((path) => {
+      if (!path || path.startsWith("/") || path.split("/").includes(".."))
+        throw new FlowError(
+          "validation input paths must be repository-relative without '..'",
+        );
+      return path;
+    })
+    .sort();
+}
+
+export function validationProofKey(
+  command: string,
+  toolchain: string,
+  declaredInput: string,
+  paths: string[],
+): string {
+  return stableHash({
+    kind: "validation",
+    command,
+    toolchain,
+    declared_input_scope: declaredInput,
+    declared_input_paths: normalizeInputPaths(paths),
+  });
+}