@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/task-conflict-inspection.js

@@ -2,8 +2,9 @@ import { classifyLoadedWorkState, readWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
 import { readLockInfo, classifyLockStaleness } from "./task-lock.js";
 import { validateStateLedgerCoherence } from "./events.js";
+import { ledgerEventAt, ledgerEventsOfTypes } from "./ledger-event-collection.js";
 import { currentRepositoryFingerprint } from "./repository.js";
-import { collectTaskClaimEvidence, classifyTaskClaimState } from "./task-claim-state.js";
+import { withTaskClaimEvidence, classifyTaskClaimState } from "./task-claim-state.js";
 
 export const TASK_CONFLICT_CLASSIFICATIONS = Object.freeze([
   "ACTIVE",
@@ -55,13 +56,37 @@ function checkCount(state, status) {
 }
 
 function lastMeaningfulActivity(state, events) {
-  const candidates = [
-    ...(state?.lastUpdated ? [{ at: state.lastUpdated, type: "WORK_STATE_UPDATED" }] : []),
-    ...events
-      .filter((event) => MEANINGFUL_ACTIVITY_EVENTS.has(event.event))
-      .map((event) => ({ at: event.at, type: event.event })),
-  ].filter((candidate) => Number.isFinite(Date.parse(candidate.at)));
-  return candidates.sort((left, right) => Date.parse(right.at) - Date.parse(left.at))[0] ?? null;
+  let latest = state?.lastUpdated && Number.isFinite(Date.parse(state.lastUpdated))
+    ? { at: state.lastUpdated, type: "WORK_STATE_UPDATED" }
+    : null;
+  for (const event of ledgerEventsOfTypes(events, [...MEANINGFUL_ACTIVITY_EVENTS])) {
+    const timestamp = Date.parse(event.at);
+    if (Number.isFinite(timestamp) && (!latest || timestamp > Date.parse(latest.at))) {
+      latest = { at: event.at, type: event.event };
+    }
+  }
+  return latest;
+}
+
+function isInitialTaskLedger(events, taskId) {
+  return events.length >= 2
+    && ledgerEventAt(events, 0)?.taskId === taskId
+    && ledgerEventAt(events, 0)?.event === "TASK_RECEIVED"
+    && ledgerEventAt(events, 1)?.taskId === taskId
+    && ledgerEventAt(events, 1)?.event === "TRANSACTION_COMMITTED"
+    && ledgerEventAt(events, 1)?.details?.operation === "task-create"
+    && !events.slice(2).some((event) => [
+      "CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY", "EXECUTION_STARTED",
+      "VERIFICATION_STARTED", "VERIFICATION_RECORDED", "REVIEW_STARTED", "COMPLETION_VALIDATED",
+      "TASK_RECOVERY_RECORDED", "OPERATOR_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED",
+    ].includes(event.event));
+}
+
+function deriveEarlyPhase(events, taskId) {
+  if (!isInitialTaskLedger(events, taskId)) return null;
+  return events.some((event) => event.event === "DISCOVERY_STARTED")
+    ? "DISCOVERING"
+    : "RECEIVED";
 }
 
 /**
@@ -97,6 +122,7 @@ export function classifyConflictEvidence(evidence, {
     totalChecks,
     verificationEvidenceCount,
     recoveryStatus,
+    earlyPhase,
   } = evidence;
 
   if (!ledgerValid) {
@@ -107,10 +133,11 @@ export function classifyConflictEvidence(evidence, {
     };
   }
   const KNOWN_PHASES = new Set([
-    "RECEIVED", "DISCOVERING", "CONTRACT_READY", "ROUTED", "DESIGNING", "PLANNED",
+    "RECEIVED", "DISCOVERING", "CONTRACT_READY", "ROUTED", "DESIGNING", "PLANNED", "BLOCKED",
     ...POST_EXECUTION_PHASES,
   ]);
-  if (!phase || !KNOWN_PHASES.has(phase)) {
+  const effectivePhase = phase ?? earlyPhase;
+  if (!effectivePhase || !KNOWN_PHASES.has(effectivePhase)) {
     return {
       classification: "INCONSISTENT",
       reasonCodes: ["E_PHASE_UNKNOWN"],
@@ -151,7 +178,7 @@ export function classifyConflictEvidence(evidence, {
     };
   }
 
-  if (phase === "COMPLETE") {
+  if (effectivePhase === "COMPLETE") {
     return {
       classification: "COMPLETE",
       reasonCodes: ["TASK_COMPLETE"],
@@ -175,7 +202,7 @@ export function classifyConflictEvidence(evidence, {
     };
   }
 
-  if (POST_EXECUTION_PHASES.has(phase)) {
+  if (POST_EXECUTION_PHASES.has(effectivePhase)) {
     if (staleOnlyRepositoryDrift) {
       return {
         classification: "RECOVERABLE",
@@ -224,98 +251,102 @@ export async function inspectTaskConflictState(target, {
   now = Date.now(),
   ignoredLockId = null,
 } = {}) {
-  const [lockInfo, stateResult, ownershipEvidence] = await Promise.all([
-    readLockInfo(target, taskId),
-    readWorkState(target, { packageRoot, taskId })
-      .then((value) => ({ value, error: null }))
-      .catch((error) => ({ value: null, error })),
-    collectTaskClaimEvidence(target, { packageRoot, taskId }),
-  ]);
-  const claimProjection = classifyTaskClaimState(ownershipEvidence);
-  const state = stateResult.value;
-  const recovery = claimProjection.recovery;
-
-  const lockClassification = ignoredLockId && lockInfo?.lockId === ignoredLockId
-    ? { status: "NONE", stale: false }
-    : classifyLockStaleness(lockInfo, now);
-
-  let freshness = null;
-  if (state) {
-    try {
-      freshness = await classifyLoadedWorkState({
-        target,
-        state,
-        contractFile: taskArtifactPath(taskId, "contract"),
-      });
-    } catch {
-      freshness = { status: "UNKNOWN", reasons: ["E_STATE_UNREADABLE"] };
+  return withTaskClaimEvidence(target, { packageRoot, taskId }, async ownershipEvidence => {
+    const [lockInfo, stateResult] = await Promise.all([
+      readLockInfo(target, taskId),
+      readWorkState(target, { packageRoot, taskId })
+        .then((value) => ({ value, error: null }))
+        .catch((error) => ({ value: null, error })),
+    ]);
+    const claimProjection = classifyTaskClaimState(ownershipEvidence);
+    const state = stateResult.value;
+    const recovery = claimProjection.recovery;
+
+    const lockClassification = ignoredLockId && lockInfo?.lockId === ignoredLockId
+      ? { status: "NONE", stale: false }
+      : classifyLockStaleness(lockInfo, now);
+
+    let freshness = null;
+    if (state) {
+      try {
+        freshness = await classifyLoadedWorkState({
+          target,
+          state,
+          contractFile: taskArtifactPath(taskId, "contract"),
+        });
+      } catch {
+        freshness = { status: "UNKNOWN", reasons: ["E_STATE_UNREADABLE"] };
+      }
     }
-  }
 
-  // Reuse the ownership snapshot's already-validated ledger; no second full
-  // ledger parse inside this immutable inspection.
-  const coherenceErrors = ownershipEvidence.state && ownershipEvidence.ledger
-    ? validateStateLedgerCoherence(ownershipEvidence.state, ownershipEvidence.ledger.events)
-    : [];
-  const ledgerValid = ownershipEvidence.ledger.valid && coherenceErrors.length === 0;
-  const ledgerEvents = ownershipEvidence.ledger.events;
-  const ledgerErrors = [...ownershipEvidence.ledger.errors, ...coherenceErrors];
-
-  const repository = await currentRepositoryFingerprint(target);
-  const meaningfulActivity = lastMeaningfulActivity(state, ledgerEvents);
-  const recoveryConsistencyErrors = claimProjection.ownershipErrors ?? claimProjection.errors ?? [];
-  const healthReasonCodes = [
-    ...(stateResult.error ? ["E_STATE_UNREADABLE"] : []),
-    ...(claimProjection.ownershipValid === false
-      ? claimProjection.reasonCodes
-      : []),
-  ];
-
-  const evidence = {
-    healthy: healthReasonCodes.length === 0,
-    healthReasonCodes,
-    descriptorHealthy: true,
-    phase: state?.phase ?? null,
-    lastUpdated: state?.lastUpdated ?? null,
-    lastMeaningfulActivityAt: meaningfulActivity?.at ?? null,
-    lastMeaningfulEventType: meaningfulActivity?.type ?? null,
-    workStateRevision: state?.revision ?? 0,
-    lockStatus: lockClassification.status,
-    lockId: lockInfo?.lockId ?? null,
-    lockExpiresAt: lockClassification.expiresAt ?? null,
-    freshnessStatus: freshness?.status ?? "UNKNOWN",
-    freshnessReasons: freshness?.reasons ?? [],
-    ledgerValid,
-    ledgerLastSeq: ledgerEvents.at(-1)?.seq ?? 0,
-    ledgerErrors,
-    recordedChecks: passedCheckCount(state),
-    passedCheckCount: passedCheckCount(state),
-    failedCheckCount: checkCount(state, "failed"),
-    blockedCheckCount: checkCount(state, "blocked"),
-    totalChecks: state?.checks?.length ?? 0,
-    verificationEvidenceCount: state?.verificationEvidence?.length ?? 0,
-    recoveryStatus: claimProjection.claimState === "RELEASED_BY_RECOVERY"
-      ? "RECOVERED"
-      : recovery?.status ?? null,
-    recoveryConsistencyErrors,
-    claimState: claimProjection.claimState,
-    historicalWriteClaims: claimProjection.historicalWriteClaims,
-    effectiveWriteClaims: claimProjection.effectiveWriteClaims,
-    mutationAllowed: claimProjection.mutationAllowed,
-    ownershipValid: claimProjection.ownershipValid,
-    ownershipErrors: recoveryConsistencyErrors,
-    repositoryBranch: repository.branch,
-    repositoryHead: repository.head,
-  };
+    // Reuse the ownership snapshot's already-validated ledger; no second full
+    // ledger parse inside this immutable inspection.
+    const coherenceErrors = ownershipEvidence.state && ownershipEvidence.ledger
+      ? validateStateLedgerCoherence(ownershipEvidence.state, ownershipEvidence.ledger.events)
+      : [];
+    const ledgerValid = ownershipEvidence.ledger.valid && coherenceErrors.length === 0;
+    const ledgerEvents = ownershipEvidence.ledger.events;
+    const ledgerErrors = [...ownershipEvidence.ledger.errors, ...coherenceErrors];
 
-  const verdict = classifyConflictEvidence(evidence, { now });
+    const repository = await currentRepositoryFingerprint(target);
+    const initialTask = !state && ledgerValid && ownershipEvidence.descriptor
+      && isInitialTaskLedger(ledgerEvents, taskId)
+      && !ownershipEvidence.recovery;
+    const meaningfulActivity = lastMeaningfulActivity(state, ledgerEvents);
+    const recoveryConsistencyErrors = claimProjection.ownershipErrors ?? claimProjection.errors ?? [];
+    const healthReasonCodes = [
+      ...(stateResult.error ? ["E_STATE_UNREADABLE"] : []),
+      ...(claimProjection.ownershipValid === false
+        ? claimProjection.reasonCodes
+        : []),
+    ];
 
-  return {
-    taskId,
-    classification: verdict.classification,
-    reasonCodes: verdict.reasonCodes,
-    recoverable: verdict.recoverable ?? false,
-    ...(verdict.recoveredBy ? { recoveredBy: verdict.recoveredBy } : {}),
-    evidence,
-  };
+    const evidence = {
+      healthy: healthReasonCodes.length === 0,
+      healthReasonCodes,
+      descriptorHealthy: true,
+      phase: state?.phase ?? (initialTask ? deriveEarlyPhase(ledgerEvents, taskId) : null),
+      lastUpdated: state?.lastUpdated ?? null,
+      lastMeaningfulActivityAt: meaningfulActivity?.at ?? null,
+      lastMeaningfulEventType: meaningfulActivity?.type ?? null,
+      workStateRevision: state?.revision ?? 0,
+      lockStatus: lockClassification.status,
+      lockId: lockInfo?.lockId ?? null,
+      lockExpiresAt: lockClassification.expiresAt ?? null,
+      freshnessStatus: freshness?.status ?? (initialTask ? "FRESH" : "UNKNOWN"),
+      freshnessReasons: freshness?.reasons ?? [],
+      ledgerValid,
+      ledgerLastSeq: ledgerEvents.at(-1)?.seq ?? 0,
+      ledgerErrors,
+      recordedChecks: passedCheckCount(state),
+      passedCheckCount: passedCheckCount(state),
+      failedCheckCount: checkCount(state, "failed"),
+      blockedCheckCount: checkCount(state, "blocked"),
+      totalChecks: state?.checks?.length ?? 0,
+      verificationEvidenceCount: state?.verificationEvidence?.length ?? 0,
+      recoveryStatus: claimProjection.claimState === "RELEASED_BY_RECOVERY"
+        ? "RECOVERED"
+        : recovery?.status ?? null,
+      recoveryConsistencyErrors,
+      claimState: claimProjection.claimState,
+      historicalWriteClaims: claimProjection.historicalWriteClaims,
+      effectiveWriteClaims: claimProjection.effectiveWriteClaims,
+      mutationAllowed: claimProjection.mutationAllowed,
+      ownershipValid: claimProjection.ownershipValid,
+      ownershipErrors: recoveryConsistencyErrors,
+      repositoryBranch: repository.branch,
+      repositoryHead: repository.head,
+    };
+
+    const verdict = classifyConflictEvidence(evidence, { now });
+
+    return {
+      taskId,
+      classification: verdict.classification,
+      reasonCodes: verdict.reasonCodes,
+      recoverable: verdict.recoverable ?? false,
+      ...(verdict.recoveredBy ? { recoveredBy: verdict.recoveredBy } : {}),
+      evidence,
+    };
+  });
 }

package/src/core/task-descriptor.js

@@ -1,5 +1,5 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
-import { readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { readJsonArtifact, readPortableJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { getPackageRoot } from "./templates.js";
 import { assertTaskDescriptorIdentity, assertTaskId, taskStorageKey } from "./task-identity.js";
@@ -7,6 +7,8 @@ import { normalizeWriteClaims } from "./task-scope.js";
 import { taskArtifactPath, TASK_STATE_ROOT } from "./task-paths.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { E_TASK_DESCRIPTOR_INVALID, E_TASK_NOT_FOUND } from "./error-codes.js";
+import { operationalArtifactExists } from "../storage/operational-context.js";
+import { withNativeReadScope } from "./native-storage.js";
 
 export const TASK_DESCRIPTOR_SCHEMA_VERSION = 1;
 
@@ -42,29 +44,34 @@ export async function validateTaskDescriptor(descriptor, packageRoot = getPackag
 }
 
 export async function readTaskDescriptor(target, taskIdOrKey, packageRoot = getPackageRoot()) {
-  // If it's a 64-char key, use it directly; otherwise derive storage key
-  const isKey = typeof taskIdOrKey === "string" && /^[a-f0-9]{64}$/.test(taskIdOrKey);
-  const relativePath = isKey
-    ? `${TASK_STATE_ROOT}/${taskIdOrKey}/task.json`
-    : taskArtifactPath(taskIdOrKey, "descriptor");
+  return withNativeReadScope(target, async () => {
+    // If it's a 64-char key, use it directly; otherwise derive storage key
+    const isKey = typeof taskIdOrKey === "string" && /^[a-f0-9]{64}$/.test(taskIdOrKey);
+    const relativePath = isKey
+      ? `${TASK_STATE_ROOT}/${taskIdOrKey}/task.json`
+      : taskArtifactPath(taskIdOrKey, "descriptor");
 
-  await assertSafePath(target, relativePath);
-  const fullPath = ensureWithin(target, relativePath);
-  if (!(await fileExists(fullPath))) {
-    const error = new Error(`Task descriptor not found: ${relativePath}`);
-    error.code = E_TASK_NOT_FOUND;
-    error.artifacts = [relativePath];
-    throw error;
-  }
+    const operationalExists = operationalArtifactExists(target, relativePath);
+    if (operationalExists === null) await assertSafePath(target, relativePath);
+    const fullPath = ensureWithin(target, relativePath);
+    if (operationalExists === false || (operationalExists === null && !(await fileExists(fullPath)))) {
+      const error = new Error(`Task descriptor not found: ${relativePath}`);
+      error.code = E_TASK_NOT_FOUND;
+      error.artifacts = [relativePath];
+      throw error;
+    }
 
-  const artifact = await readJsonArtifact(target, relativePath, "task-descriptor", packageRoot);
-  try {
-    await validateTaskDescriptor(artifact.value, packageRoot);
-  } catch (error) {
-    error.code = E_TASK_DESCRIPTOR_INVALID;
-    throw error;
-  }
-  return { ...artifact, ...artifact.value, value: artifact.value };
+    // An unselected legacy descriptor is inspection input, never writable authority.
+    const reader = operationalExists === null ? readPortableJsonArtifact : readJsonArtifact;
+    const artifact = await reader(target, relativePath, "task-descriptor", packageRoot);
+    try {
+      await validateTaskDescriptor(artifact.value, packageRoot);
+    } catch (error) {
+      error.code = E_TASK_DESCRIPTOR_INVALID;
+      throw error;
+    }
+    return { ...artifact, ...artifact.value, value: artifact.value };
+  });
 }
 
 export async function writeTaskDescriptor(target, descriptor, packageRoot = getPackageRoot(), options = {}) {