@cassiomc1/forgeloop 1.9.0 → 1.10.0

package/src/core/handoff-acceptance.js

@@ -0,0 +1,277 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
+import { compareRepositoryFingerprint, readCanonicalHandoff } from "./handoff.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
+import { withTaskTransaction } from "./transaction.js";
+import { getPackageRoot } from "./templates.js";
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+} from "./portable-context.js";
+import {
+  E_HANDOFF_ACCEPTANCE_UNBOUND,
+  E_HANDOFF_STALE,
+  E_HANDOFF_ALREADY_ACCEPTED,
+  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+} from "./error-codes.js";
+
+function acceptanceError(code, message) {
+  const error = new Error(message);
+  error.name = "HandoffAcceptanceError";
+  error.code = code;
+  return error;
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+export function resolveHandoffAcceptance(input = {}, legacyHandoff) {
+  const projection = Array.isArray(input)
+    ? { events: input, handoff: legacyHandoff }
+    : input;
+  const {
+    events = [],
+    handoff,
+    ledgerValid = true,
+    ledgerErrors = [],
+  } = projection ?? {};
+
+  if (ledgerValid !== true) {
+    return {
+      status: "INCONSISTENT",
+      reasonCodes: uniqueSorted(ledgerErrors.map((error) => typeof error === "string" ? error : error?.code)),
+    };
+  }
+
+  if (!handoff?.state?.workStateFingerprint) {
+    return { status: "UNBOUND" };
+  }
+
+  const acceptedEvents = (events ?? []).filter(
+    (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoff.handoffId,
+  );
+
+  if (acceptedEvents.length === 0) {
+    return { status: "OPEN" };
+  }
+
+  if (acceptedEvents.length > 1) {
+    return { status: "INCONSISTENT" };
+  }
+
+  const accepted = acceptedEvents[0];
+  if (accepted.details?.handoffDigest !== handoff.artifactDigest) {
+    return { status: "INCONSISTENT" };
+  }
+
+  return {
+    status: "ACCEPTED",
+    consumerId: accepted.details?.consumerId,
+    ...(accepted.details?.harness ? { harness: accepted.details.harness } : {}),
+    acceptedAt: accepted.at,
+  };
+}
+
+export async function readHandoffAcceptanceLedger(target, packageRoot = getPackageRoot(), { taskId } = {}) {
+  try {
+    return await validateEventLedger(target, packageRoot, { taskId });
+  } catch (error) {
+    return {
+      valid: false,
+      events: [],
+      errors: [{
+        code: error.code ?? "E_EVENT_INVALID",
+        message: error.message,
+      }],
+    };
+  }
+}
+
+export async function acceptCanonicalHandoff(target, {
+  taskId,
+  handoffId,
+  consumerId,
+  harness,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  if (!target || typeof target !== "string") {
+    throw acceptanceError("E_TARGET_REQUIRED", "target path is required");
+  }
+  if (!taskId || typeof taskId !== "string") {
+    throw acceptanceError("E_TASK_REQUIRED", "taskId is required");
+  }
+  if (!handoffId || typeof handoffId !== "string") {
+    throw acceptanceError("E_HANDOFF_INVALID", "handoffId is required");
+  }
+
+  const normalizedConsumerId = normalizePortableText(consumerId, {
+    label: "consumerId",
+    maxLength: 128,
+  });
+  assertPortableContextSafe(normalizedConsumerId, { label: "consumerId" });
+
+  const normalizedHarness = harness !== undefined
+    ? normalizePortableText(harness, {
+      label: "harness",
+      maxLength: 64,
+      optional: true,
+    })
+    : null;
+  if (normalizedHarness) {
+    assertPortableContextSafe(normalizedHarness, { label: "harness" });
+  }
+
+  return withTaskTransaction(
+    {
+      target,
+      taskId,
+      packageRoot,
+      operation: "handoff-accept",
+      recordCommitEvent: true,
+    },
+    async () => {
+      const { value: handoff } = await readCanonicalHandoff(target, {
+        taskId,
+        handoffId,
+        packageRoot,
+      });
+
+      if (!handoff.state?.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_UNBOUND,
+          "Handoff snapshot is unbound (lacks state.workStateFingerprint); create a fresh handoff",
+        );
+      }
+
+      const currentState = await readWorkState(target, { packageRoot, taskId });
+      if (!currentState) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Canonical work state is unavailable for handoff acceptance",
+        );
+      }
+
+      const currentWorkStateFingerprint = canonicalFingerprint(currentState);
+      if (currentWorkStateFingerprint !== handoff.state.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current work state has drifted from handoff workStateFingerprint",
+        );
+      }
+
+      const contract = await readContract(target, packageRoot, { taskId });
+      const route = await readPersistedRoute(target, packageRoot, { taskId });
+      try {
+        assertStateIdentity({ contract, route, state: currentState });
+      } catch (error) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          `Current canonical task artifacts are not coherent with one another: ${error.message}`,
+        );
+      }
+      if (contract.fingerprint !== handoff.state.contractFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current contract fingerprint has drifted from handoff contractFingerprint",
+        );
+      }
+      if ((route.fingerprint ?? null) !== (handoff.state.routeFingerprint ?? null)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current route fingerprint has drifted from handoff routeFingerprint",
+        );
+      }
+
+      const repositoryFingerprint = await currentRepositoryFingerprint(target);
+      if (compareRepositoryFingerprint(handoff.state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current repository branch or HEAD has drifted from handoff snapshot",
+        );
+      }
+
+      const changedPaths = await currentChangedPaths(target);
+      const currentList = [...new Set((changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      const handoffList = [...new Set((handoff.state.changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      if (JSON.stringify(currentList) !== JSON.stringify(handoffList)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current changed paths have drifted from handoff snapshot",
+        );
+      }
+
+      const ledgerResult = await validateEventLedger(target, packageRoot, { taskId });
+      if (!ledgerResult.valid) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "Task event ledger is invalid",
+        );
+      }
+
+      const events = ledgerResult.events;
+      const createdEvent = events.find(
+        (e) => e.event === "HANDOFF_CREATED" && e.details?.handoffId === handoffId,
+      );
+      if (!createdEvent || createdEvent.details?.digest !== handoff.artifactDigest) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "No matching HANDOFF_CREATED event with matching digest found in ledger",
+        );
+      }
+
+      const existingAccepted = events.filter(
+        (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoffId,
+      );
+
+      if (existingAccepted.length > 0) {
+        const prev = existingAccepted[0];
+        if (prev.details?.consumerId === normalizedConsumerId) {
+          return {
+            accepted: true,
+            idempotent: true,
+            handoffId,
+            consumerId: normalizedConsumerId,
+            harness: prev.details?.harness ?? null,
+            acceptedAt: prev.at,
+          };
+        }
+        throw acceptanceError(
+          E_HANDOFF_ALREADY_ACCEPTED,
+          `Handoff ${handoffId} has already been accepted by consumer "${prev.details?.consumerId}"`,
+        );
+      }
+
+      const eventDetails = {
+        handoffId,
+        handoffDigest: handoff.artifactDigest,
+        consumerId: normalizedConsumerId,
+        ...(normalizedHarness ? { harness: normalizedHarness } : {}),
+      };
+
+      const appended = await appendProtocolEvent(
+        target,
+        {
+          taskId,
+          event: "HANDOFF_ACCEPTED",
+          details: eventDetails,
+        },
+        packageRoot,
+        { taskId },
+      );
+
+      return {
+        accepted: true,
+        idempotent: false,
+        handoffId,
+        consumerId: normalizedConsumerId,
+        harness: normalizedHarness ?? null,
+        acceptedAt: appended.at,
+      };
+    },
+  );
+}

package/src/core/handoff.js

@@ -2,12 +2,13 @@ import { randomUUID } from "node:crypto";
 import { readdir } from "node:fs/promises";
 
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { assertSecretFree } from "./receipt.js";
+import { assertPortableContextSafe, normalizePortableText } from "./portable-context.js";
 import { appendProtocolEvent } from "./events.js";
-import { currentChangedPaths } from "./repository.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { readContinuity } from "./continuity.js";
 import { getPackageRoot } from "./templates.js";
@@ -26,12 +27,13 @@ function handoffError(code, message, artifacts = []) {
   return error;
 }
 
-function optionalText(value, label) {
+function optionalText(value, label, maxLength = 2000) {
   if (value === undefined || value === null) return null;
-  if (typeof value !== "string" || value.trim() === "") {
+  try {
+    return normalizePortableText(value, { label, maxLength, optional: true });
+  } catch (error) {
     throw handoffError("E_HANDOFF_INVALID", `${label} must be a non-empty string when provided`);
   }
-  return value;
 }
 
 function pathList(value) {
@@ -43,8 +45,22 @@ function handoffWithoutDigest(value) {
   return body;
 }
 
+export function compareRepositoryFingerprint(expected, current) {
+  const expectedUnavailable = !expected || (expected.branch === null && expected.head === null);
+  const currentUnavailable = !current || (current.branch === null && current.head === null);
+  if (expectedUnavailable && currentUnavailable) return "NOT_VERIFIED";
+  if (expectedUnavailable !== currentUnavailable) return "MISMATCH";
+  return expected.branch === current.branch && expected.head === current.head
+    ? "MATCH"
+    : "MISMATCH";
+}
+
 export function validateHandoffDigest(handoff) {
-  assertSecretFree(handoff);
+  try {
+    assertPortableContextSafe(handoff);
+  } catch (error) {
+    throw handoffError("E_HANDOFF_INVALID", error.message);
+  }
   if (typeof handoff?.artifactDigest !== "string"
     || handoff.artifactDigest !== canonicalFingerprint(handoffWithoutDigest(handoff))) {
     throw handoffError("E_HANDOFF_TAMPERED", "Handoff artifact digest does not match its canonical content");
@@ -73,17 +89,33 @@ export async function buildCanonicalHandoff(target, {
   createdAt = new Date().toISOString(),
 } = {}) {
   if (!taskId) throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "taskId is required to build a handoff");
-  const [state, contract, route, claims, changedPaths, continuity] = await Promise.all([
+  const [state, contract, route, claims, changedPaths, continuity, repositoryFingerprint] = await Promise.all([
     readWorkState(target, { packageRoot, taskId }),
     readContract(target, packageRoot, { taskId }),
     readPersistedRoute(target, packageRoot, { taskId }),
     resolveTaskClaimState(target, { packageRoot, taskId }),
     currentChangedPaths(target),
     currentContinuity(target, packageRoot, taskId),
+    currentRepositoryFingerprint(target),
   ]);
   if (!state || !contract || !route || changedPaths === null || !claims.valid) {
     throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "Canonical task state, route, claims, and changed paths are required for a handoff");
   }
+  try {
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      `Canonical task artifacts are not coherent for handoff creation: ${error.message}`,
+      error.artifacts ?? [],
+    );
+  }
+  if (compareRepositoryFingerprint(state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      "Canonical repository fingerprint has drifted from current repository state",
+    );
+  }
   const checkItems = [...(state.checks ?? [])];
   const executionRefs = pathList(checkItems.map((check) => check.executionRef).filter(Boolean));
   const checkIds = pathList(checkItems.map((check) => check.id).filter(Boolean));
@@ -101,9 +133,10 @@ export async function buildCanonicalHandoff(target, {
       phase: WORK_PHASES.includes(state.phase) ? state.phase : "UNKNOWN",
       revision: state.revision ?? 0,
       verificationCycle: state.verificationCycle ?? 1,
+      workStateFingerprint: canonicalFingerprint(state),
       contractFingerprint: contract.fingerprint,
       routeFingerprint: route.fingerprint ?? null,
-      repositoryFingerprint: state.repositoryFingerprint ?? { branch: null, head: null },
+      repositoryFingerprint,
       writeClaims: pathList(claims.effectiveWriteClaims ?? []),
       changedPaths: pathList(changedPaths),
     },

package/src/core/integration-invocation-policy.js

@@ -42,7 +42,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "record-terminal-result", "complete",
   "record-intervention", "record-hypothesis-disposition",
   "usage-record",
-  "workspace-bind", "handoff-create", "responsibility-set", "verify-scope", "attestation-create",
+  "workspace-bind", "handoff-create", "handoff-accept", "responsibility-set", "verify-scope", "attestation-create",
 ]));
 
 const STATIC_RISK_CLASSES = Object.freeze({
@@ -189,10 +189,27 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         explicitRebinding: false,
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,

package/src/core/integration-resources.js

@@ -14,6 +14,7 @@ import { readJsonArtifact } from "./artifacts.js";
 import { taskDirectory } from "./task-paths.js";
 import { resolveWorkspaceBindingStatus } from "./workspace-binding.js";
 import { listCanonicalHandoffs } from "./handoff.js";
+import { readHandoffAcceptanceLedger, resolveHandoffAcceptance } from "./handoff-acceptance.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
@@ -196,7 +197,26 @@ export async function readForgeLoopIntegrationResource(uri, {
   }
   if (uri === "task/handoffs") {
     const handoffs = await listCanonicalHandoffs(projectPath, { packageRoot, taskId });
-    return { uri, taskId, data: { taskId, count: handoffs.length, handoffs } };
+    const ledger = await readHandoffAcceptanceLedger(projectPath, packageRoot, { taskId });
+    const projectedHandoffs = handoffs.map((handoff) => {
+      const resolved = resolveHandoffAcceptance({
+        events: ledger.events,
+        handoff,
+        ledgerValid: ledger.valid,
+        ledgerErrors: ledger.errors,
+      });
+      return {
+        ...handoff,
+        acceptance: {
+          status: resolved.status,
+          consumerId: resolved.consumerId ?? null,
+          harness: resolved.harness ?? null,
+          acceptedAt: resolved.acceptedAt ?? null,
+          ...(resolved.reasonCodes ? { reasonCodes: [...resolved.reasonCodes] } : {}),
+        },
+      };
+    });
+    return { uri, taskId, data: { taskId, count: projectedHandoffs.length, handoffs: projectedHandoffs } };
   }
   if (uri === "task/responsibility") {
     return { uri, taskId, data: await resolveResponsibilityStatus(projectPath, { packageRoot, taskId }) };

package/src/core/portable-context.js

@@ -0,0 +1,103 @@
+import { assertJsonLimits } from "./json-safety.js";
+import { assertSecretFree } from "./receipt.js";
+import { E_PORTABLE_CONTEXT_INVALID } from "./error-codes.js";
+
+export class PortableContextError extends Error {
+  constructor(message, { code = E_PORTABLE_CONTEXT_INVALID, cause } = {}) {
+    super(message, cause !== undefined ? { cause } : undefined);
+    this.name = "PortableContextError";
+    this.code = code;
+  }
+}
+
+const PORTABLE_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /(?:^|\s)(?:sk|ghp|glpat|xox[baprs])-[-_a-z0-9]{8,}/i,
+  /(?:AKIA|ASIA)[A-Z0-9]{12,}/,
+  /(?:bearer\s+[-_a-z0-9\.]{4,})/i,
+  /(?:authorization:\s*bearer)/i,
+];
+
+function containsSecretPattern(str) {
+  return PORTABLE_SECRET_PATTERNS.some((pattern) => pattern.test(str));
+}
+
+function checkObjectForSecrets(value, location = "$") {
+  if (typeof value === "string") {
+    if (containsSecretPattern(value)) {
+      throw new Error(`${location}: secret-like value is not allowed`);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => checkObjectForSecrets(item, `${location}[${index}]`));
+  } else {
+    for (const [key, child] of Object.entries(value)) {
+      checkObjectForSecrets(child, `${location}.${key}`);
+    }
+  }
+}
+
+export function normalizePortableText(
+  value,
+  {
+    label = "portable text",
+    maxLength,
+    optional = false,
+  } = {},
+) {
+  if (value === undefined || value === null) {
+    if (optional) return null;
+    throw new PortableContextError(`${label} is required`);
+  }
+
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new PortableContextError(`${label} must be a non-empty string`);
+  }
+
+  if (typeof maxLength === "number" && value.length > maxLength) {
+    throw new PortableContextError(`${label} exceeds the ${maxLength}-character limit`);
+  }
+
+  if (/\p{Cc}/u.test(value)) {
+    throw new PortableContextError(`${label} contains control characters`);
+  }
+
+  return value;
+}
+
+export function assertPortableContextSafe(
+  value,
+  {
+    label = "portable context",
+  } = {},
+) {
+  try {
+    assertJsonLimits(value, label);
+    assertSecretFree(value);
+    checkObjectForSecrets(value, label);
+    return value;
+  } catch (error) {
+    if (error.code === E_PORTABLE_CONTEXT_INVALID) {
+      throw error;
+    }
+    throw new PortableContextError(
+      `${label} failed safety verification: ${error.message}`,
+      { code: E_PORTABLE_CONTEXT_INVALID, cause: error },
+    );
+  }
+}
+
+export function deepFreeze(object) {
+  if (object === null || typeof object !== "object" || Object.isFrozen(object)) {
+    return object;
+  }
+  Object.freeze(object);
+  for (const value of Object.values(object)) {
+    if (value !== null && typeof value === "object") {
+      deepFreeze(value);
+    }
+  }
+  return object;
+}

package/src/core/protocol-info.js

@@ -160,11 +160,27 @@ export function protocolInfo({ packageVersion = null } = {}) {
         rebinding: "EXPLICIT_ONLY",
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
-        actorControlledIntent: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,

package/src/core/runtime-context.js

@@ -4,6 +4,8 @@ import {
   normalizeVerificationExecutionPolicy,
 } from "./verification-execution.js";
 import { STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN } from "./structural-quality/constants.js";
+import { E_ADVISORY_CONTEXT_PROVIDER_INVALID } from "./error-codes.js";
+import { assertAdvisoryContextProviderIdentity } from "./advisory-context/provider.js";
 
 export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
 
@@ -132,5 +134,34 @@ export function createForgeLoopContext(options = {}) {
     }
     context.structuralQualityProviders = Object.freeze(providers);
   }
+  if (options?.advisoryContextProviders !== undefined) {
+    const configured = options.advisoryContextProviders instanceof Map
+      ? Object.fromEntries(options.advisoryContextProviders.entries())
+      : options.advisoryContextProviders;
+    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+      const error = new Error("advisoryContextProviders must be an object or Map");
+      error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+      throw error;
+    }
+    const providers = {};
+    for (const [id, provider] of Object.entries(configured)) {
+      if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) {
+        const error = new Error(`Invalid advisory-context provider ID: ${id}`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function"
+        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
+        const error = new Error(`Advisory-context provider ${id} must be an object or factory`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function") {
+        assertAdvisoryContextProviderIdentity(provider, id);
+      }
+      providers[id] = provider;
+    }
+    context.advisoryContextProviders = Object.freeze(providers);
+  }
   return Object.freeze(context);
 }