@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/src/core/continuity-reconciliation.js

@@ -0,0 +1,224 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { assertContinuitySemantics, readContinuity } from "./continuity.js";
+import { WORK_TRANSITIONS } from "./protocol.js";
+
+const RECONCILIATION_CODE = "E_CONTINUITY_RECONCILIATION_REQUIRED";
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function pathCoveredByHint(changedPath, hint) {
+  const normalizedPath = String(changedPath).replaceAll("\\", "/").replace(/^\.\//, "");
+  const normalizedHint = String(hint).replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+  return normalizedPath === normalizedHint || normalizedPath.startsWith(`${normalizedHint}/`);
+}
+
+function compareChangedPaths(changedPaths, hints) {
+  if (!Array.isArray(changedPaths)) return "NOT_VERIFIED";
+  if (!Array.isArray(hints) || hints.length === 0) return changedPaths.length === 0 ? "MATCH" : "MISMATCH";
+  const matched = hints.filter((hint) => changedPaths.some((changedPath) => pathCoveredByHint(changedPath, hint))).length;
+  if (matched === hints.length) return "MATCH";
+  if (matched > 0) return "PARTIAL";
+  return "MISMATCH";
+}
+
+function compareRepository(saved, current) {
+  const savedUnavailable = !saved || (saved.branch === null && saved.head === null);
+  const currentUnavailable = !current || (current.branch === null && current.head === null);
+  if (savedUnavailable && currentUnavailable) return "NOT_VERIFIED";
+  if (!saved || !current) return "NOT_VERIFIED";
+  return saved.branch === current.branch && saved.head === current.head ? "MATCH" : "MISMATCH";
+}
+
+function phaseReachable(from, to) {
+  if (from === to) return true;
+  if (to === "BLOCKED" && from !== "COMPLETE") return true;
+  if (from === "BLOCKED") return false;
+  const queue = [from];
+  const visited = new Set(queue);
+  while (queue.length > 0) {
+    const phase = queue.shift();
+    for (const next of WORK_TRANSITIONS[phase] ?? []) {
+      if (next === to) return true;
+      if (!visited.has(next)) {
+        visited.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return false;
+}
+
+function baseResult(classification, overrides = {}) {
+  return {
+    classification,
+    taskMatches: overrides.taskMatches ?? null,
+    workStateMatches: overrides.workStateMatches ?? null,
+    contractMatches: overrides.contractMatches ?? null,
+    phaseMatches: overrides.phaseMatches ?? null,
+    repositoryComparison: overrides.repositoryComparison ?? "NOT_VERIFIED",
+    changedPathComparison: overrides.changedPathComparison ?? "NOT_VERIFIED",
+    reasonCodes: uniqueSorted(overrides.reasonCodes ?? []),
+    reasons: uniqueSorted(overrides.reasons ?? []),
+    authority: "OPERATIONAL_CONTEXT_ONLY",
+    evidenceAuthority: "NONE",
+  };
+}
+
+export function classifyContinuity({
+  continuity,
+  state,
+  contractFingerprint,
+  repositoryFingerprint,
+  changedPaths,
+} = {}) {
+  if (!continuity) {
+    return baseResult("ABSENT", { reasons: ["CONTINUITY_ABSENT"] });
+  }
+
+  let value;
+  try {
+    value = assertContinuitySemantics(continuity);
+  } catch (error) {
+    return baseResult("INVALID", {
+      reasonCodes: [error.code ?? "E_CONTINUITY_INVALID"],
+      reasons: [error.message],
+    });
+  }
+
+  if (!state || typeof state !== "object") {
+    return baseResult("INCONSISTENT", {
+      reasonCodes: ["E_CONTINUITY_STATE_MISSING"],
+      reasons: ["CONTINUITY_STATE_MISSING"],
+    });
+  }
+
+  if (state.phase === "COMPLETE") {
+    return baseResult("NOT_APPLICABLE", {
+      taskMatches: value.taskId === state.taskId,
+      phaseMatches: value.phase === state.phase,
+      reasons: ["CONTINUITY_NOT_APPLICABLE_AFTER_COMPLETE"],
+    });
+  }
+
+  const taskMatches = value.taskId === state.taskId;
+  const workStateMatches = value.workStateFingerprint === canonicalFingerprint(state);
+  const expectedContract = contractFingerprint ?? state.contractFingerprint ?? null;
+  const contractMatches = value.contractFingerprint === state.contractFingerprint
+    && (expectedContract === null || value.contractFingerprint === expectedContract);
+  const phaseMatches = value.phase === state.phase;
+  const repositoryComparison = compareRepository(value.repositoryFingerprint, repositoryFingerprint);
+  const changedPathComparison = compareChangedPaths(changedPaths, value.changedAreas);
+
+  const inconsistentCodes = [];
+  const inconsistentReasons = [];
+  if (!taskMatches) {
+    inconsistentCodes.push("E_CONTINUITY_TASK_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_TASK_MISMATCH");
+  }
+  if (!contractMatches) {
+    inconsistentCodes.push("E_CONTINUITY_CONTRACT_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_CONTRACT_MISMATCH");
+  }
+  if (!phaseMatches && !phaseReachable(value.phase, state.phase)) {
+    inconsistentCodes.push("E_CONTINUITY_PHASE_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_PHASE_MISMATCH");
+  }
+  if (inconsistentCodes.length > 0) {
+    return baseResult("INCONSISTENT", {
+      taskMatches,
+      workStateMatches,
+      contractMatches,
+      phaseMatches,
+      repositoryComparison,
+      changedPathComparison,
+      reasonCodes: inconsistentCodes,
+      reasons: inconsistentReasons,
+    });
+  }
+
+  const reconciliationReasons = [];
+  if (!workStateMatches) reconciliationReasons.push("CONTINUITY_WORK_STATE_CHANGED");
+  if (!phaseMatches) reconciliationReasons.push("CONTINUITY_PHASE_CHANGED");
+  if (repositoryComparison === "MISMATCH") reconciliationReasons.push("CONTINUITY_REPOSITORY_CHANGED");
+  if (["PARTIAL", "MISMATCH"].includes(changedPathComparison)) {
+    reconciliationReasons.push("CONTINUITY_CHANGED_PATHS_DIFFER");
+  }
+
+  if (reconciliationReasons.length > 0) {
+    return baseResult("RECONCILIATION_REQUIRED", {
+      taskMatches,
+      workStateMatches,
+      contractMatches,
+      phaseMatches,
+      repositoryComparison,
+      changedPathComparison,
+      reasonCodes: [RECONCILIATION_CODE],
+      reasons: reconciliationReasons,
+    });
+  }
+
+  return baseResult("FRESH", {
+    taskMatches,
+    workStateMatches,
+    contractMatches,
+    phaseMatches,
+    repositoryComparison,
+    changedPathComparison,
+  });
+}
+
+export async function reconcileContinuity({ target, packageRoot } = {}) {
+  const [{ readWorkState }, { readContract }, repository] = await Promise.all([
+    import("./work-state.js"),
+    import("./contract.js"),
+    import("./repository.js"),
+  ]);
+
+  const state = await readWorkState(target, packageRoot);
+  let continuityArtifact;
+  try {
+    continuityArtifact = await readContinuity(target, packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      return { ...classifyContinuity({ continuity: null, state }), path: ".forgeloop/continuity.json", present: false };
+    }
+    return {
+      ...baseResult("INVALID", {
+        reasonCodes: [error.code ?? "E_CONTINUITY_INVALID"],
+        reasons: [error.message],
+      }),
+      path: ".forgeloop/continuity.json",
+      present: true,
+      error: error.message,
+    };
+  }
+
+  let contractFingerprint = null;
+  try {
+    const contract = await readContract(target, packageRoot);
+    contractFingerprint = contract.fingerprint;
+  } catch {
+    contractFingerprint = null;
+  }
+
+  const [repositoryFingerprint, changedPaths] = await Promise.all([
+    repository.currentRepositoryFingerprint(target),
+    repository.currentChangedPaths(target),
+  ]);
+
+  return {
+    ...classifyContinuity({
+      continuity: continuityArtifact.value,
+      state,
+      contractFingerprint,
+      repositoryFingerprint,
+      changedPaths,
+    }),
+    path: continuityArtifact.path,
+    present: true,
+    fingerprint: continuityArtifact.fingerprint,
+    continuity: continuityArtifact.value,
+  };
+}

package/src/core/continuity.js

@@ -0,0 +1,245 @@
+import { unlink } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  ARTIFACT_PATHS,
+  canonicalFingerprint,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "./artifacts.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { PROTOCOL_VERSION, WORK_PHASES } from "./protocol.js";
+import { assertSecretFree } from "./receipt.js";
+import { getPackageRoot } from "./templates.js";
+
+export const CONTINUITY_PATH = ARTIFACT_PATHS.continuity;
+export const CONTINUITY_SCHEMA_VERSION = 1;
+
+const LIMITS = Object.freeze({
+  taskId: 128,
+  id: 128,
+  summary: 1000,
+  path: 1024,
+  resumeNote: 2000,
+  remainingWork: 40,
+  knownIssues: 40,
+  changedAreas: 80,
+  inspectFirst: 40,
+});
+
+function continuityError(code, message, artifacts = [CONTINUITY_PATH]) {
+  const error = new Error(message);
+  error.name = "ContinuityError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function nonEmptyString(value, label, maxLength) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a non-empty string`);
+  }
+  if (value.length > maxLength) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxLength}-character limit`);
+  }
+  if (/\p{Cc}/u.test(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} contains control characters`);
+  }
+  return value;
+}
+
+function fingerprint(value, label) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a lowercase SHA-256 fingerprint`);
+  }
+  return value;
+}
+
+function normalizeProjectPath(value, label) {
+  nonEmptyString(value, label, LIMITS.path);
+  const portable = value.replaceAll("\\", "/");
+  if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must remain a relative project path`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must not escape the task target`);
+  }
+  return normalized.replace(/^\.\//, "");
+}
+
+function normalizeWorkItem(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be an object`);
+  }
+  const keys = Object.keys(value).sort();
+  if (keys.some((key) => !["id", "summary"].includes(key))) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} contains an unsupported field`);
+  }
+  return {
+    id: nonEmptyString(value.id, `${label}.id`, LIMITS.id),
+    summary: nonEmptyString(value.summary, `${label}.summary`, LIMITS.summary),
+  };
+}
+
+function normalizeWorkItems(value, label, maxItems) {
+  if (!Array.isArray(value)) throw continuityError("E_CONTINUITY_INVALID", `${label} must be an array`);
+  if (value.length > maxItems) throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxItems}-item limit`);
+  const items = value.map((item, index) => normalizeWorkItem(item, `${label}[${index}]`));
+  if (new Set(items.map((item) => item.id)).size !== items.length) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must not contain duplicate ids`);
+  }
+  return items;
+}
+
+function normalizePaths(value, label, maxItems) {
+  if (!Array.isArray(value)) throw continuityError("E_CONTINUITY_INVALID", `${label} must be an array`);
+  if (value.length > maxItems) throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxItems}-item limit`);
+  const paths = value.map((item, index) => normalizeProjectPath(item, `${label}[${index}]`));
+  if (new Set(paths).size !== paths.length) throw continuityError("E_CONTINUITY_INVALID", `${label} must not contain duplicate paths`);
+  return paths;
+}
+
+function normalizeRepositoryFingerprint(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", "repositoryFingerprint must be an object");
+  }
+  if (Object.keys(value).some((key) => !["branch", "head"].includes(key))) {
+    throw continuityError("E_CONTINUITY_INVALID", "repositoryFingerprint contains an unsupported field");
+  }
+  for (const key of ["branch", "head"]) {
+    if (value[key] !== null && typeof value[key] !== "string") {
+      throw continuityError("E_CONTINUITY_INVALID", `repositoryFingerprint.${key} must be a string or null`);
+    }
+  }
+  return { branch: value.branch ?? null, head: value.head ?? null };
+}
+
+const CONTINUITY_FIELDS = new Set([
+  "schemaVersion",
+  "protocolVersion",
+  "taskId",
+  "workStateFingerprint",
+  "contractFingerprint",
+  "phase",
+  "verificationCycle",
+  "repositoryFingerprint",
+  "updatedAt",
+  "currentFocus",
+  "remainingWork",
+  "knownIssues",
+  "changedAreas",
+  "inspectFirst",
+  "resumeNote",
+]);
+
+export function assertContinuitySemantics(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw continuityError("E_CONTINUITY_INVALID", "Continuity must be a JSON object");
+  }
+  const unknownField = Object.keys(input).find((key) => !CONTINUITY_FIELDS.has(key));
+  if (unknownField) {
+    throw continuityError("E_CONTINUITY_INVALID", `Continuity contains unsupported field: ${unknownField}`);
+  }
+  if (input.schemaVersion !== CONTINUITY_SCHEMA_VERSION || input.protocolVersion !== PROTOCOL_VERSION) {
+    throw continuityError("E_CONTINUITY_SCHEMA_UNSUPPORTED", "Unsupported continuity schema or protocol version");
+  }
+  if (!WORK_PHASES.includes(input.phase)) {
+    throw continuityError("E_CONTINUITY_INVALID", `Unknown continuity phase: ${input.phase}`);
+  }
+  if (input.verificationCycle !== undefined
+    && (!Number.isInteger(input.verificationCycle) || input.verificationCycle < 1)) {
+    throw continuityError("E_CONTINUITY_INVALID", "verificationCycle must be a positive integer");
+  }
+  const normalized = {
+    schemaVersion: CONTINUITY_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: nonEmptyString(input.taskId, "taskId", LIMITS.taskId),
+    workStateFingerprint: fingerprint(input.workStateFingerprint, "workStateFingerprint"),
+    contractFingerprint: fingerprint(input.contractFingerprint, "contractFingerprint"),
+    phase: input.phase,
+    ...(input.verificationCycle !== undefined ? { verificationCycle: input.verificationCycle } : {}),
+    repositoryFingerprint: normalizeRepositoryFingerprint(input.repositoryFingerprint),
+    updatedAt: nonEmptyString(input.updatedAt, "updatedAt", 128),
+    ...(input.currentFocus !== undefined ? { currentFocus: normalizeWorkItem(input.currentFocus, "currentFocus") } : {}),
+    remainingWork: normalizeWorkItems(input.remainingWork, "remainingWork", LIMITS.remainingWork),
+    knownIssues: normalizeWorkItems(input.knownIssues, "knownIssues", LIMITS.knownIssues),
+    changedAreas: normalizePaths(input.changedAreas, "changedAreas", LIMITS.changedAreas),
+    inspectFirst: normalizePaths(input.inspectFirst, "inspectFirst", LIMITS.inspectFirst),
+    ...(input.resumeNote !== undefined
+      ? { resumeNote: nonEmptyString(input.resumeNote, "resumeNote", LIMITS.resumeNote) }
+      : {}),
+  };
+  assertSecretFree(normalized);
+  return normalized;
+}
+
+export function createContinuity(input) {
+  return assertContinuitySemantics({
+    schemaVersion: input.schemaVersion ?? CONTINUITY_SCHEMA_VERSION,
+    protocolVersion: input.protocolVersion ?? PROTOCOL_VERSION,
+    ...structuredClone(input),
+  });
+}
+
+export async function readContinuity(target, packageRoot = getPackageRoot()) {
+  const artifact = await readJsonArtifact(target, CONTINUITY_PATH, "continuity", packageRoot);
+  return { ...artifact, value: assertContinuitySemantics(artifact.value) };
+}
+
+export async function writeContinuity(target, operationalInput = {}, options = {}) {
+  const packageRoot = options.packageRoot ?? getPackageRoot();
+  let state = options.state;
+  if (!state) {
+    const { readWorkState } = await import("./work-state.js");
+    state = await readWorkState(target, packageRoot);
+  }
+  if (!state) throw continuityError("E_CONTINUITY_STATE_MISSING", "Cannot record continuity without work state", [ARTIFACT_PATHS.state]);
+
+  let contract = options.contract;
+  if (!contract) {
+    const { readContract } = await import("./contract.js");
+    contract = await readContract(target, packageRoot);
+  }
+  const currentContractFingerprint = contract?.fingerprint
+    ?? (contract ? canonicalFingerprint(contract.value ?? contract) : null);
+  if (!currentContractFingerprint) {
+    throw continuityError("E_CONTINUITY_CONTRACT_MISMATCH", "Cannot bind continuity to the current contract", [ARTIFACT_PATHS.contract]);
+  }
+  if (state.contractFingerprint !== currentContractFingerprint) {
+    throw continuityError(
+      "E_CONTINUITY_CONTRACT_MISMATCH",
+      "Work state contract fingerprint does not match the current contract",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+    );
+  }
+  const value = createContinuity({
+    taskId: state.taskId,
+    workStateFingerprint: canonicalFingerprint(state),
+    contractFingerprint: state.contractFingerprint,
+    phase: state.phase,
+    ...(state.verificationCycle !== undefined ? { verificationCycle: state.verificationCycle } : {}),
+    repositoryFingerprint: options.repositoryFingerprint ?? await (async () => {
+      const { currentRepositoryFingerprint } = await import("./repository.js");
+      return currentRepositoryFingerprint(target);
+    })(),
+    updatedAt: options.now ?? new Date().toISOString(),
+    ...(operationalInput.currentFocus !== undefined ? { currentFocus: operationalInput.currentFocus } : {}),
+    remainingWork: operationalInput.remainingWork ?? [],
+    knownIssues: operationalInput.knownIssues ?? [],
+    changedAreas: operationalInput.changedAreas ?? [],
+    inspectFirst: operationalInput.inspectFirst ?? [],
+    ...(operationalInput.resumeNote !== undefined ? { resumeNote: operationalInput.resumeNote } : {}),
+  });
+  return writeJsonArtifact(target, CONTINUITY_PATH, value, "continuity", packageRoot, {
+    dryRun: options.dryRun ?? false,
+  });
+}
+
+export async function clearContinuity(target) {
+  await assertSafePath(target, CONTINUITY_PATH);
+  const artifactPath = ensureWithin(target, CONTINUITY_PATH);
+  if (!(await fileExists(artifactPath))) return { removed: false, path: CONTINUITY_PATH };
+  await unlink(artifactPath);
+  return { removed: true, path: CONTINUITY_PATH };
+}

package/src/core/evidence-readiness.js

@@ -1,6 +1,24 @@
 import { sha256 } from "./manifest.js";
 import { validateVerificationAuthority } from "./verification-capability.js";
 
+export const E_COMMAND_PROVENANCE_UNATTESTED = "E_COMMAND_PROVENANCE_UNATTESTED";
+
+export function validateCommandProvenance(check) {
+  if (check?.kind !== "command" || check.evidenceKind !== "OBSERVED") {
+    return { valid: true, error: null };
+  }
+  if (check.provenance !== "FORGELOOP_EXECUTED" || typeof check.executionRef !== "string" || check.executionRef.trim() === "") {
+    return {
+      valid: false,
+      error: {
+        code: E_COMMAND_PROVENANCE_UNATTESTED,
+        message: "Observed command evidence requires a ForgeLoop execution artifact",
+      },
+    };
+  }
+  return { valid: true, error: null };
+}
+
 export const REQUIREMENT_TYPES = Object.freeze([
   "PRODUCT",
   "VERIFICATION",
@@ -256,6 +274,8 @@ function componentStatus(check, requirement, allChecks = [], options = {}) {
         item?.requirementId === child.id || item?.requirement === child.text
       )).at(-1);
       if (matchingComp) {
+        const provenance = validateCommandProvenance(matchingComp);
+        if (!provenance.valid) return { ...matchingComp, status: "failed", reasonCode: provenance.error.code };
         const auth = validateVerificationAuthority(matchingComp, options);
         if (!auth.valid) return { ...matchingComp, status: "failed", reasonCode: auth.error.code };
         return matchingComp;
@@ -264,6 +284,8 @@ function componentStatus(check, requirement, allChecks = [], options = {}) {
     const childCandidates = allChecks.filter((candidate) => matchesRequirement(candidate, child));
     const childCheck = latestAuthoritativeCheck(childCandidates);
     if (childCheck) {
+      const provenance = validateCommandProvenance(childCheck);
+      if (!provenance.valid) return { ...childCheck, status: "failed", reasonCode: provenance.error.code };
       const auth = validateVerificationAuthority(childCheck, options);
       if (!auth.valid) return { ...childCheck, status: "failed", reasonCode: auth.error.code };
     }
@@ -314,7 +336,10 @@ export function evaluateRequiredEvidence({
     }
     const candidates = checks.filter((check) => matchesRequirement(check, requirement));
     const check = latestAuthoritativeCheck(candidates);
-    const auth = check ? validateVerificationAuthority(check, authOptions) : { valid: true };
+    const provenance = check ? validateCommandProvenance(check) : { valid: true };
+    const auth = provenance.valid
+      ? (check ? validateVerificationAuthority(check, authOptions) : { valid: true })
+      : provenance;
     const compound = componentStatus(check, requirement, checks, authOptions);
     if (!auth.valid) {
       result.invalid.push({ ...requirement, reasonCode: auth.error.code });