@cassiomc1/forgeloop 0.1.1 → 0.1.3

package/src/core/completion-artifacts.js

@@ -0,0 +1,321 @@
+import {
+  ARTIFACT_PATHS,
+  canonicalFingerprint,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { completionEvidenceForGuides } from "./guide-metadata.js";
+import { createCheck } from "./checks.js";
+import { createEvidence } from "./evidence.js";
+import { coverageForRequirements } from "./coverage.js";
+import { assertCompletionRelationships } from "./completion-relationships.js";
+import { evaluatePreflight } from "./preflight.js";
+import { currentChangedPaths } from "./repository.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { createReceipt, validateReceipt } from "./receipt.js";
+import { readWorkState, writeWorkState } from "./work-state.js";
+import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
+
+function artifactError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw artifactError("E_CHECK_INVALID", `${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+async function readCurrentReceipt(target, packageRoot) {
+  try {
+    return await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      throw artifactError(
+        "E_RECEIPT_MISSING",
+        "Execution receipt is missing; run forgeloop prepare-completion first",
+        [ARTIFACT_PATHS.receipt],
+      );
+    }
+    throw error;
+  }
+}
+
+async function readOptionalConfig(target, packageRoot) {
+  try {
+    return (await readJsonArtifact(target, ARTIFACT_PATHS.config, "config", packageRoot)).value;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return {};
+    throw error;
+  }
+}
+
+export async function requiredEvidenceForTarget({ target, contract, route, packageRoot, additionalEvidence = [] }) {
+  const config = await readOptionalConfig(target, packageRoot);
+  const guideEvidence = await completionEvidenceForGuides(route.value.guides, packageRoot);
+  return [...new Set([
+    ...(contract.value.successCriteria ?? []),
+    ...guideEvidence,
+    ...(config.requiredEvidence ?? []),
+    ...additionalEvidence,
+  ])].sort();
+}
+
+export async function prepareCompletion({ target, packageRoot }) {
+  const contract = await readContract(target, packageRoot);
+  const route = await readPersistedRoute(target, packageRoot);
+  const state = await readWorkState(target, packageRoot);
+  if (!state) {
+    throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [ARTIFACT_PATHS.state]);
+  }
+  if (hasExecutionStarted(state.phase)) {
+    await assertExecutionPrerequisites({ target, state, packageRoot });
+  }
+
+  let existing = null;
+  try {
+    existing = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+    await validateReceipt(existing.value, packageRoot);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  const requiredEvidence = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  const existingValue = existing?.value ?? {};
+  assertCompletionRelationships({
+    contract,
+    route,
+    state,
+    receipt: existingValue.taskId ? existingValue : null,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
+  const changedPaths = existing
+    ? [...(existingValue.changedPaths ?? [])]
+    : (await currentChangedPaths(target) ?? []);
+  const checks = existing ? [...existingValue.checks] : [...state.checks];
+  const evidence = existing ? [...(existingValue.evidence ?? [])] : [...state.verificationEvidence];
+  const receipt = await createReceipt({
+    ...existingValue,
+    taskId: contract.value.taskId,
+    contractFingerprint: contract.fingerprint,
+    routeFingerprint: route.fingerprint,
+    stateFingerprint: canonicalFingerprint(state),
+    status: existingValue.status ?? "in-progress",
+    taskStatus: existingValue.taskStatus ?? "in-progress",
+    verificationStatus: existingValue.verificationStatus ?? "not-verified",
+    publicationStatus: existingValue.publicationStatus ?? "local-only",
+    productionReadiness: existingValue.productionReadiness ?? "not-verified",
+    selectedGuides: [...route.value.guides],
+    changedPaths,
+    checks,
+    evidence,
+    evidenceCoverage: coverageForRequirements(requiredEvidence, checks),
+    review: existingValue.review ?? { status: "not-run", independent: false },
+    limitations: [...(existingValue.limitations ?? [])],
+    publication: existingValue.publication ?? {
+      committed: false,
+      pushed: false,
+      pullRequest: null,
+      deployed: false,
+    },
+  }, packageRoot);
+  const written = await writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.receipt,
+    receipt,
+    "execution-receipt",
+    packageRoot,
+  );
+  return {
+    path: written.path,
+    receipt: written.value,
+    requiredEvidence,
+    changedPaths,
+  };
+}
+
+function mergeByCheckId(checks, nextCheck) {
+  const next = [...checks];
+  const index = next.findIndex((item) => item?.schemaVersion === 1 && item.id === nextCheck.id);
+  if (index >= 0) next[index] = nextCheck;
+  else next.push(nextCheck);
+  return next;
+}
+
+function appendUniqueEvidence(evidence, nextEvidence) {
+  const exists = evidence.some((item) => item.kind === nextEvidence.kind
+    && item.source === nextEvidence.source
+    && item.result === nextEvidence.result
+    && JSON.stringify(item.details ?? null) === JSON.stringify(nextEvidence.details ?? null));
+  return exists ? [...evidence] : [...evidence, nextEvidence];
+}
+
+export async function recordCheck({
+  target,
+  packageRoot,
+  id,
+  kind = "command",
+  requirement,
+  status,
+  evidenceKind,
+  command,
+  result,
+  exitCode,
+  details,
+}) {
+  requiredString(id, "check id");
+  requiredString(kind, "check kind");
+  requiredString(requirement, "check requirement");
+  requiredString(status, "check status");
+  requiredString(evidenceKind, "evidence kind");
+  if (command !== undefined && typeof command !== "string") {
+    throw artifactError("E_CHECK_INVALID", "command must be a string when supplied");
+  }
+  if (result !== undefined && typeof result !== "string") {
+    throw artifactError("E_CHECK_INVALID", "result must be a string when supplied");
+  }
+  if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
+    throw artifactError("E_CHECK_INVALID", "check details must be a JSON object");
+  }
+  if ((typeof command !== "string" || command.trim() === "")
+    && (typeof result !== "string" || result.trim() === "")) {
+    throw artifactError("E_CHECK_INVALID", "record-check requires --command or --result");
+  }
+
+  const state = await readWorkState(target, packageRoot);
+  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a check", [ARTIFACT_PATHS.state]);
+  if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
+    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a check in ${state.phase}`, [ARTIFACT_PATHS.state]);
+  }
+  if (state.phase !== "VERIFYING") {
+    throw artifactError(
+      "E_PHASE_PREREQUISITE_MISSING",
+      `record-check requires VERIFYING before review; found ${state.phase}`,
+      [ARTIFACT_PATHS.state],
+    );
+  }
+  await assertExecutionPrerequisites({ target, state, packageRoot });
+
+  const existingReceipt = await readCurrentReceipt(target, packageRoot);
+  await validateReceipt(existingReceipt.value, packageRoot);
+  const source = command?.trim() || `check:${id}`;
+  const recordedResult = result?.trim() || `recorded command: ${command.trim()}`;
+  const check = createCheck({
+    id,
+    kind,
+    requirement,
+    status,
+    evidenceKind,
+    source,
+    ...(exitCode === undefined ? {} : { exitCode }),
+    details: {
+      ...(command === undefined ? {} : { command }),
+      ...(result === undefined ? {} : { result }),
+      ...(details === undefined ? {} : details),
+    },
+  });
+  const evidence = createEvidence({
+    kind: evidenceKind,
+    source,
+    result: recordedResult,
+    ...(details === undefined ? {} : { details: structuredClone(details) }),
+  });
+
+  const checks = mergeByCheckId(existingReceipt.value.checks ?? [], check);
+  const evidenceList = appendUniqueEvidence(existingReceipt.value.evidence ?? [], evidence);
+  const contract = await readContract(target, packageRoot);
+  const route = await readPersistedRoute(target, packageRoot);
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  const requiredEvidence = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  assertCompletionRelationships({
+    contract,
+    route,
+    state,
+    receipt: existingReceipt.value,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw artifactError(first.code, first.message, [ARTIFACT_PATHS.events]);
+  }
+  if (!ledger.events.some((event) => event.taskId === state.taskId && event.event === "VERIFICATION_STARTED")) {
+    throw artifactError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "record-check requires VERIFICATION_STARTED in the current task ledger",
+      [ARTIFACT_PATHS.events],
+    );
+  }
+  const coverage = coverageForRequirements(requiredEvidence, checks);
+  const nextState = {
+    ...state,
+    checks,
+    verificationEvidence: appendUniqueEvidence(state.verificationEvidence ?? [], evidence),
+    evidenceCoverage: coverage,
+    lastUpdated: new Date().toISOString(),
+  };
+  const nextReceipt = await createReceipt({
+    ...existingReceipt.value,
+    checks,
+    evidence: evidenceList,
+    evidenceCoverage: coverage,
+    stateFingerprint: canonicalFingerprint(nextState),
+  }, packageRoot);
+
+  assertCompletionRelationships({
+    contract,
+    route,
+    state: nextState,
+    receipt: nextReceipt,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
+
+  await writeWorkState(target, nextState, { packageRoot });
+  const written = await writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.receipt,
+    nextReceipt,
+    "execution-receipt",
+    packageRoot,
+  );
+  const event = await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: "VERIFICATION_RECORDED",
+    details: {
+      checkId: check.id,
+      requirement: check.requirement,
+      status: check.status,
+      evidenceKind: check.evidenceKind,
+    },
+  }, packageRoot);
+  return {
+    path: written.path,
+    receipt: written.value,
+    check,
+    evidence,
+    coverage,
+    event,
+  };
+}

package/src/core/completion-relationships.js

@@ -0,0 +1,141 @@
+import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
+import { assertCheckList, requiredChecksSatisfied } from "./checks.js";
+import { assertCoverageList, coverageForRequirements } from "./coverage.js";
+import { assertEvidenceList } from "./evidence.js";
+
+function issue(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+function sameValue(left, right) {
+  return canonicalFingerprint(left) === canonicalFingerprint(right);
+}
+
+function addAssertion(errors, assertion, code, artifacts) {
+  try {
+    assertion();
+  } catch (error) {
+    errors.push(issue(code, error.message, artifacts));
+  }
+}
+
+export function stateIdentityErrors({
+  contract,
+  route,
+  state,
+} = {}) {
+  const errors = [];
+  const contractValue = contract?.value ?? contract;
+  const contractFingerprint = contract?.fingerprint;
+  if (contractValue && state && contractValue.taskId !== state.taskId) {
+    errors.push(issue("E_STATE_TASK_MISMATCH", "Work state does not belong to the current contract task", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+  }
+  if (contractFingerprint && state && state.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_CONTRACT_STALE", "Work state does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+  }
+  if (contractFingerprint && route && route.value.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route]));
+  }
+  if (route && state && route.value.contractFingerprint !== undefined
+    && route.value.contractFingerprint !== state.contractFingerprint) {
+    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the work state contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  if (route && state && (state.routeFingerprint !== route.fingerprint || !sameValue(state.selectedGuides, route.value.guides))) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Work state does not match the persisted route identity", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  return errors;
+}
+
+export function assertStateIdentity(input) {
+  const errors = stateIdentityErrors(input);
+  if (errors.length === 0) return;
+  const first = errors[0];
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  throw error;
+}
+
+export function completionRelationshipErrors({
+  contract,
+  route,
+  state,
+  receipt,
+  requiredEvidence = [],
+  requireReceiptStateFingerprint = true,
+  requireRequiredChecks = true,
+} = {}) {
+  const errors = stateIdentityErrors({ contract, route, state });
+  const contractValue = contract?.value ?? contract;
+  const contractFingerprint = contract?.fingerprint;
+  if (contractValue && receipt && contractValue.taskId !== receipt.taskId) {
+    errors.push(issue("E_RECEIPT_TASK_MISMATCH", "Execution receipt does not belong to the current contract task", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
+  }
+  if (route && receipt && (receipt.routeFingerprint !== route.fingerprint || !sameValue(receipt.selectedGuides, route.value.guides))) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Execution receipt does not match the persisted route identity", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
+  }
+  if (contractFingerprint && receipt && receipt.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_RECEIPT_CONTRACT_MISMATCH", "Execution receipt does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
+  }
+
+  if (state) {
+    addAssertion(errors, () => assertCheckList(state.checks, "work-state.checks"), "E_CHECK_INVALID", [ARTIFACT_PATHS.state]);
+    addAssertion(errors, () => assertEvidenceList(state.verificationEvidence, "work-state.verificationEvidence"), "E_EVIDENCE_INVALID", [ARTIFACT_PATHS.state]);
+  }
+  if (receipt) {
+    addAssertion(errors, () => assertCheckList(receipt.checks, "receipt.checks"), "E_CHECK_INVALID", [ARTIFACT_PATHS.receipt]);
+    addAssertion(errors, () => assertEvidenceList(receipt.evidence ?? [], "receipt.evidence"), "E_EVIDENCE_INVALID", [ARTIFACT_PATHS.receipt]);
+    if (requireRequiredChecks) {
+      for (const error of requiredChecksSatisfied(receipt.checks, requiredEvidence)) {
+        errors.push(issue(error.code, error.message, [ARTIFACT_PATHS.receipt]));
+      }
+    }
+  }
+
+  const expectedCoverage = state ? coverageForRequirements(requiredEvidence, state.checks) : [];
+  if (state?.evidenceCoverage !== undefined) {
+    addAssertion(errors, () => assertCoverageList(state.evidenceCoverage, "work-state.evidenceCoverage"), "E_EVIDENCE_COVERAGE_INVALID", [ARTIFACT_PATHS.state]);
+    if (!sameValue(state.evidenceCoverage, expectedCoverage)) {
+      errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Work state evidence coverage does not match its checks", [ARTIFACT_PATHS.state]));
+    }
+  }
+  if (receipt) {
+    if (receipt.evidenceCoverage === undefined) {
+      errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Execution receipt requires evidence coverage", [ARTIFACT_PATHS.receipt]));
+    } else {
+      addAssertion(errors, () => assertCoverageList(receipt.evidenceCoverage, "receipt.evidenceCoverage"), "E_EVIDENCE_COVERAGE_INVALID", [ARTIFACT_PATHS.receipt]);
+      if (!sameValue(receipt.evidenceCoverage, expectedCoverage)) {
+        errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Execution receipt evidence coverage does not match current checks", [ARTIFACT_PATHS.receipt]));
+      }
+    }
+  }
+
+  if (state && receipt) {
+    if (requireReceiptStateFingerprint && receipt.stateFingerprint === undefined) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    } else if (receipt.stateFingerprint !== undefined && receipt.stateFingerprint !== canonicalFingerprint(state)) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt does not match the recorded work state", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+    if (!sameValue(state.checks, receipt.checks)) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt checks diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+    if (!sameValue(state.verificationEvidence, receipt.evidence ?? [])) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt evidence diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+    if (state.evidenceCoverage !== undefined && receipt.evidenceCoverage !== undefined
+      && !sameValue(state.evidenceCoverage, receipt.evidenceCoverage)) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt coverage diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+  }
+  return errors;
+}
+
+export function assertCompletionRelationships(input) {
+  const errors = completionRelationshipErrors(input);
+  if (errors.length === 0) return;
+  const first = errors[0];
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  throw error;
+}