@cassiomc1/forgeloop 1.9.0 → 1.10.0

package/scripts/check-changelog-freshness.mjs

@@ -26,6 +26,26 @@ export function unreleasedSection(changelog) {
   return nextHeading ? rest.slice(0, nextHeading.index) : rest;
 }
 
+export function releaseSection(changelog) {
+  const heading = /^##[ \t]+(v?\d+\.\d+\.\d+)(?:[ \t]+-[^\r\n]*)?$/imu.exec(changelog);
+  if (!heading) return null;
+  const rest = changelog.slice(heading.index + heading[0].length);
+  const nextHeading = /^##\s/imu.exec(rest);
+  return {
+    version: heading[1].replace(/^v/u, ""),
+    section: nextHeading ? rest.slice(0, nextHeading.index) : rest,
+  };
+}
+
+function compareVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
 export function stripHtmlComments(value) {
   const chunks = [];
   let cursor = 0;
@@ -55,11 +75,15 @@ export function hasMeaningfulUnreleasedContent(section) {
 
 export function checkChangelogFreshness({ changelog, tags = [], commitsSinceLatestTag = 0, allowEmpty = false } = {}) {
   const latestTag = latestReleaseTag(tags);
-  const section = unreleasedSection(changelog);
+  const unreleased = unreleasedSection(changelog);
+  const pendingRelease = releaseSection(changelog);
+  const pendingReleaseIsNewer = pendingRelease &&
+    (!latestTag || compareVersions(pendingRelease.version, latestTag.replace(/^v/u, "")) > 0);
+  const section = unreleased || (pendingReleaseIsNewer ? pendingRelease.section : "");
   const hasChanges = commitsSinceLatestTag > 0;
   const populated = hasMeaningfulUnreleasedContent(section);
   const ok = allowEmpty || !hasChanges || populated;
-  return { ok, latestTag, hasChanges, populated, section };
+  return { ok, latestTag, hasChanges, populated, section, pendingRelease };
 }
 
 async function run() {
@@ -71,7 +95,7 @@ async function run() {
     : Number(git(["rev-list", "--count", "HEAD"]));
   const result = checkChangelogFreshness({ changelog, tags, commitsSinceLatestTag, allowEmpty: process.argv.includes("--allow-empty") });
   if (!result.ok) {
-    console.error(`CHANGELOG.md has changes since ${result.latestTag ?? "the initial commit"} but the Unreleased section is empty.`);
+    console.error(`CHANGELOG.md has changes since ${result.latestTag ?? "the initial commit"} but no populated Unreleased or pending release section exists.`);
     process.exitCode = 1;
     return;
   }

package/scripts/generate-agent-protocol-summary.mjs

@@ -49,6 +49,22 @@ async function render() {
   const features = Object.entries(info.features)
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, feature]) => [name, feature.version ?? "n/a", feature.supported === false ? "no" : "yes"]);
+  const handoffs = info.features.canonicalHandoffs;
+  const advisory = info.features.advisoryContextProviders;
+  const capabilityContracts = `## Capability contracts
+
+- \`canonicalHandoffs\` v${handoffs.version}: immutable, supported, and
+  ledger-backed for exactly-once operational acceptance through
+  \`${handoffs.acceptanceCommand}\`. Acceptance statuses are
+  \`${handoffs.acceptanceStatuses.join("\` / \`")}\`; it creates no claims,
+  evidence, or lifecycle authority.
+- \`advisoryContextProviders\` v${advisory.version}: provider-neutral,
+  Integration-API-only, lazy, and opt-in. Provider results are not persisted by
+  ForgeLoop and are never lifecycle state, evidence, authority, or executable
+  instructions.
+
+Protocol v1, schema v1, and Integration API v1 remain independent of these
+capability-family versions.`;
   const artifacts = Object.values(ARTIFACT_REGISTRY)
     .filter((artifact) => artifact.isPublic)
     .sort((left, right) => left.key.localeCompare(right.key))
@@ -133,6 +149,8 @@ Phases: ${info.lifecycle.phases.join(", ")}
 
 ${table(["Feature", "Version", "Supported"], features)}
 
+${capabilityContracts}
+
 ## Public artifact registry
 
 ${table(["Key", "Scope", "Path", "Schema", "Trust role"], artifacts)}

package/src/cli.js

@@ -77,6 +77,7 @@ import { formatWorkspaceStatusResult } from "./commands/workspace-status.js";
 import { formatHandoffCreateResult } from "./commands/handoff-create.js";
 import { formatHandoffListResult } from "./commands/handoff-list.js";
 import { formatHandoffShowResult } from "./commands/handoff-show.js";
+import { formatHandoffAcceptResult } from "./commands/handoff-accept.js";
 import { formatResponsibilitySetResult } from "./commands/responsibility-set.js";
 import { formatResponsibilityStatusResult } from "./commands/responsibility-status.js";
 import { formatVerifyScopeResult } from "./commands/verify-scope.js";
@@ -463,6 +464,11 @@ export const COMMAND_HANDLERS = Object.freeze({
     renderJsonOr(options, result, formatHandoffShowResult);
     return exitCode;
   },
+  "handoff-accept": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["handoff-accept"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatHandoffAcceptResult);
+    return exitCode;
+  },
   "responsibility-set": async ({ target, packageRoot, options }) => {
     const { result, exitCode } = await COMMAND_EXECUTORS["responsibility-set"]({ target, packageRoot, options });
     renderJsonOr(options, result, formatResponsibilitySetResult);

package/src/commands/handoff-accept.js

@@ -0,0 +1,36 @@
+import { acceptCanonicalHandoff } from "../core/handoff-acceptance.js";
+
+export async function runHandoffAccept({
+  target,
+  packageRoot,
+  taskId,
+  handoffId,
+  consumerId,
+  harness,
+} = {}) {
+  const result = await acceptCanonicalHandoff(target, {
+    taskId,
+    handoffId,
+    consumerId,
+    harness,
+    packageRoot,
+  });
+  return {
+    taskId,
+    ...result,
+  };
+}
+
+export function formatHandoffAcceptResult(result) {
+  return [
+    `FORGELOOP HANDOFF ACCEPTED: ${result.handoffId}`,
+    `consumer: ${result.consumerId}`,
+    `harness: ${result.harness ?? "none"}`,
+    `at: ${result.acceptedAt}`,
+    `idempotent: ${result.idempotent ? "yes" : "no"}`,
+    "authority: OPERATIONAL_RECEIPT_ONLY",
+    "evidence: NONE",
+    "claims transferred: NO",
+    "",
+  ].join("\n");
+}

package/src/commands/handoff-list.js

@@ -1,12 +1,38 @@
 import { listCanonicalHandoffs } from "../core/handoff.js";
+import {
+  readHandoffAcceptanceLedger,
+  resolveHandoffAcceptance,
+} from "../core/handoff-acceptance.js";
 
 export async function runHandoffList({ target, packageRoot, taskId } = {}) {
   const handoffs = await listCanonicalHandoffs(target, { packageRoot, taskId });
-  return { taskId, count: handoffs.length, handoffs };
+  const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
+  const handoffsWithAcceptance = 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 { taskId, count: handoffs.length, handoffs: handoffsWithAcceptance };
 }
 
 export function formatHandoffListResult(result) {
   const lines = [`FORGELOOP HANDOFFS: ${result.count}`];
-  for (const handoff of result.handoffs) lines.push(`${handoff.handoffId} ${handoff.createdAt} ${handoff.artifactDigest}`);
+  for (const handoff of result.handoffs) {
+    const status = handoff.acceptance?.status ? ` [${handoff.acceptance.status}]` : "";
+    lines.push(`${handoff.handoffId} ${handoff.createdAt} ${handoff.artifactDigest}${status}`);
+  }
   return `${lines.join("\n")}\n`;
 }

package/src/commands/handoff-show.js

@@ -1,10 +1,35 @@
 import { readCanonicalHandoff } from "../core/handoff.js";
+import {
+  readHandoffAcceptanceLedger,
+  resolveHandoffAcceptance,
+} from "../core/handoff-acceptance.js";
 
 export async function runHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
   const artifact = await readCanonicalHandoff(target, { packageRoot, taskId, handoffId });
-  return { taskId, path: artifact.path, fingerprint: artifact.fingerprint, handoff: artifact.value };
+  const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
+  const resolved = resolveHandoffAcceptance({
+    events: ledger.events,
+    handoff: artifact.value,
+    ledgerValid: ledger.valid,
+    ledgerErrors: ledger.errors,
+  });
+  const acceptance = {
+    status: resolved.status,
+    consumerId: resolved.consumerId ?? null,
+    harness: resolved.harness ?? null,
+    acceptedAt: resolved.acceptedAt ?? null,
+    ...(resolved.reasonCodes ? { reasonCodes: [...resolved.reasonCodes] } : {}),
+  };
+  return {
+    taskId,
+    path: artifact.path,
+    fingerprint: artifact.fingerprint,
+    handoff: artifact.value,
+    acceptance,
+  };
 }
 
 export function formatHandoffShowResult(result) {
-  return `FORGELOOP HANDOFF: VALID\nid: ${result.handoff.handoffId}\ntask: ${result.handoff.taskId}\ndigest: ${result.handoff.artifactDigest}\npath: ${result.path}\n\n`;
+  const acceptanceLine = result.acceptance ? `\nacceptance: ${result.acceptance.status}` : "";
+  return `FORGELOOP HANDOFF: VALID\nid: ${result.handoff.handoffId}\ntask: ${result.handoff.taskId}\ndigest: ${result.handoff.artifactDigest}\npath: ${result.path}${acceptanceLine}\n\n`;
 }

package/src/commands/reconcile-continuity.js

@@ -20,6 +20,10 @@ export function formatReconcileContinuityResult(result) {
     "Authority: OPERATIONAL_CONTEXT_ONLY",
     "Evidence: NONE",
   ];
+  if (result.lint) {
+    const findingCount = result.lint.findings?.length ?? 0;
+    lines.push(`Lint: ${result.lint.status}${findingCount ? ` (${findingCount} finding(s))` : ""}`);
+  }
   if (result.reasonCodes?.length) lines.push(`Reason codes: ${result.reasonCodes.join(", ")}`);
   if (result.reasons?.length) lines.push(`Reasons: ${result.reasons.join(", ")}`);
   return `${lines.join("\n")}\n`;

package/src/core/advisory-context/constants.js

@@ -0,0 +1,74 @@
+import { E_ADVISORY_CONTEXT_REQUEST_INVALID } from "../error-codes.js";
+
+export const ADVISORY_CONTEXT_LIMITS = Object.freeze({
+  defaultItems: 6,
+  maxItems: 20,
+  defaultMaxItemChars: 1200,
+  maxItemChars: 4000,
+  defaultMaxTotalChars: 6000,
+  maxTotalChars: 16000,
+  defaultTimeoutMs: 5000,
+  maxTimeoutMs: 30000,
+  maxProviderReturnedItems: 100,
+  maxQueryChars: 1000,
+  maxSourceRefChars: 2048,
+  maxTitleChars: 300,
+});
+
+function normalizeIntegerOption(value, {
+  name,
+  defaultValue,
+  minimum,
+  maximum,
+} = {}) {
+  if (value === undefined) return defaultValue;
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    const error = new Error(`${name} must be a finite integer greater than or equal to ${minimum}`);
+    error.name = "AdvisoryContextRequestError";
+    error.code = E_ADVISORY_CONTEXT_REQUEST_INVALID;
+    throw error;
+  }
+  return Math.min(value, maximum);
+}
+
+export function normalizeAdvisoryRecallOptions({
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+} = {}) {
+  return Object.freeze({
+    limit: normalizeIntegerOption(limit, {
+      name: "limit",
+      defaultValue: ADVISORY_CONTEXT_LIMITS.defaultItems,
+      minimum: 1,
+      maximum: ADVISORY_CONTEXT_LIMITS.maxItems,
+    }),
+    maxItemChars: normalizeIntegerOption(maxItemChars, {
+      name: "maxItemChars",
+      defaultValue: ADVISORY_CONTEXT_LIMITS.defaultMaxItemChars,
+      minimum: 100,
+      maximum: ADVISORY_CONTEXT_LIMITS.maxItemChars,
+    }),
+    maxTotalChars: normalizeIntegerOption(maxTotalChars, {
+      name: "maxTotalChars",
+      defaultValue: ADVISORY_CONTEXT_LIMITS.defaultMaxTotalChars,
+      minimum: 500,
+      maximum: ADVISORY_CONTEXT_LIMITS.maxTotalChars,
+    }),
+    timeoutMs: normalizeIntegerOption(timeoutMs, {
+      name: "timeoutMs",
+      defaultValue: ADVISORY_CONTEXT_LIMITS.defaultTimeoutMs,
+      minimum: 1,
+      maximum: ADVISORY_CONTEXT_LIMITS.maxTimeoutMs,
+    }),
+  });
+}
+
+export const ADVISORY_CONTEXT_TRUST = Object.freeze({
+  authority: "ADVISORY",
+  evidenceAuthority: "NONE",
+  actionability: "NON_EXECUTABLE",
+  trustRole: "NON_EVIDENCE_ADVISORY_CONTEXT",
+  persisted: false,
+});

package/src/core/advisory-context/provider.js

@@ -0,0 +1,287 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+  deepFreeze,
+} from "../portable-context.js";
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  ADVISORY_CONTEXT_TRUST,
+  normalizeAdvisoryRecallOptions,
+} from "./constants.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+} from "../error-codes.js";
+
+const PROVIDER_ID_REGEX = /^[a-z0-9][a-z0-9_-]*$/;
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "AdvisoryContextProviderError";
+  error.code = code;
+  return error;
+}
+
+export function assertAdvisoryContextProvider(provider) {
+  if (!provider || typeof provider !== "object" || Array.isArray(provider)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "Advisory context provider must be an object",
+    );
+  }
+
+  if (typeof provider.id !== "string" || !PROVIDER_ID_REGEX.test(provider.id)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      `Provider id must be a lowercase identifier matching ${PROVIDER_ID_REGEX}: received "${provider.id}"`,
+    );
+  }
+
+  if (provider.version !== undefined && (typeof provider.version !== "string" || provider.version.trim() === "" || provider.version.length > 64)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "Provider version must be a non-empty string under 64 characters when specified",
+    );
+  }
+
+  if (typeof provider.recall !== "function") {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      `Provider "${provider.id}" must implement recall(input) function`,
+    );
+  }
+
+  return provider;
+}
+
+export function assertAdvisoryContextProviderIdentity(provider, expectedId) {
+  assertAdvisoryContextProvider(provider);
+  if (provider.id !== expectedId) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      `Provider id "${provider.id}" does not match requested registry key "${expectedId}"`,
+    );
+  }
+  return provider;
+}
+
+export function createAdvisoryContextProviderRegistry({ providers = {} } = {}) {
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "Advisory context providers registry must be an object map",
+    );
+  }
+
+  const map = new Map();
+  for (const [key, entry] of Object.entries(providers)) {
+    if (!PROVIDER_ID_REGEX.test(key)) {
+      throw providerError(
+        E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+        `Invalid provider key "${key}" in registry`,
+      );
+    }
+    if (typeof entry === "function") {
+      map.set(key, entry);
+    } else {
+      assertAdvisoryContextProviderIdentity(entry, key);
+      map.set(key, entry);
+    }
+  }
+
+  return Object.freeze({
+    get(id) {
+      return map.get(id) ?? null;
+    },
+    has(id) {
+      return map.has(id);
+    },
+    list() {
+      return [...map.keys()].sort();
+    },
+  });
+}
+
+export async function resolveAdvisoryContextProvider({ providers, providerName } = {}) {
+  if (!providers || typeof providerName !== "string") return null;
+
+  let entry = null;
+  if (providers instanceof Map) {
+    entry = providers.get(providerName) ?? null;
+  } else if (typeof providers.get === "function" && typeof providers.has === "function") {
+    entry = providers.get(providerName) ?? null;
+  } else if (typeof providers === "object" && !Array.isArray(providers)) {
+    entry = providers[providerName] ?? null;
+  }
+  if (!entry) return null;
+
+  const provider = typeof entry === "function" ? await entry() : entry;
+  return assertAdvisoryContextProviderIdentity(provider, providerName);
+}
+
+export function normalizeAdvisoryContextResult(raw, {
+  provider,
+  taskId,
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+} = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_RESULT_INVALID,
+      "Advisory context result must be a JSON object",
+    );
+  }
+
+  if (!Array.isArray(raw.items)) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_RESULT_INVALID,
+      "Advisory context result items must be an array",
+    );
+  }
+
+  const effectiveOptions = normalizeAdvisoryRecallOptions({
+    limit,
+    maxItemChars,
+    maxTotalChars,
+    timeoutMs,
+  });
+  if (raw.items.length > ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems) {
+    throw providerError(
+      E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+      `Advisory context provider returned ${raw.items.length} items, exceeding the raw item ceiling of ${ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems}`,
+    );
+  }
+
+  const selectedItems = raw.items.slice(0, effectiveOptions.limit);
+  let totalChars = 0;
+  const normalizedItems = [];
+
+  for (let i = 0; i < selectedItems.length; i += 1) {
+    const item = selectedItems[i];
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw providerError(
+        E_ADVISORY_CONTEXT_RESULT_INVALID,
+        `Item at index ${i} must be an object`,
+      );
+    }
+
+    if (item.summary === undefined || item.summary === null) {
+      throw providerError(
+        E_ADVISORY_CONTEXT_RESULT_INVALID,
+        `Item at index ${i} requires a non-empty summary`,
+      );
+    }
+
+    let summary;
+    try {
+      summary = normalizePortableText(item.summary, {
+        label: `items[${i}].summary`,
+        maxLength: effectiveOptions.maxItemChars,
+      });
+    } catch (err) {
+      throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, err.message);
+    }
+
+    let title;
+    if (item.title !== undefined && item.title !== null) {
+      try {
+        title = normalizePortableText(item.title, {
+          label: `items[${i}].title`,
+          maxLength: ADVISORY_CONTEXT_LIMITS.maxTitleChars,
+          optional: true,
+        });
+      } catch (err) {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, err.message);
+      }
+    }
+
+    let sourceRef;
+    if (item.sourceRef !== undefined && item.sourceRef !== null) {
+      try {
+        sourceRef = normalizePortableText(item.sourceRef, {
+          label: `items[${i}].sourceRef`,
+          maxLength: ADVISORY_CONTEXT_LIMITS.maxSourceRefChars,
+          optional: true,
+        });
+      } catch (err) {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, err.message);
+      }
+    }
+
+    let observedAt;
+    if (item.observedAt !== undefined && item.observedAt !== null) {
+      try {
+        observedAt = normalizePortableText(item.observedAt, {
+          label: `items[${i}].observedAt`,
+          maxLength: 128,
+          optional: true,
+        });
+      } catch (err) {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, err.message);
+      }
+    }
+
+    let confidence;
+    if (item.confidence !== undefined && item.confidence !== null) {
+      if (
+        typeof item.confidence !== "number"
+        || !Number.isFinite(item.confidence)
+        || item.confidence < 0
+        || item.confidence > 1
+      ) {
+        throw providerError(
+          E_ADVISORY_CONTEXT_RESULT_INVALID,
+          `Item at index ${i} confidence must be a finite number between 0 and 1`,
+        );
+      }
+      confidence = item.confidence;
+    }
+
+    const itemCharLength =
+      (title?.length ?? 0)
+      + summary.length
+      + (sourceRef?.length ?? 0)
+      + (observedAt?.length ?? 0);
+
+    totalChars += itemCharLength;
+    if (totalChars > effectiveOptions.maxTotalChars) {
+      throw providerError(
+        E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+        `Advisory context output exceeded the total character limit of ${effectiveOptions.maxTotalChars} (accumulated ${totalChars})`,
+      );
+    }
+
+    const cleanItem = {
+      ...(title ? { title } : {}),
+      summary,
+      ...(sourceRef ? { sourceRef } : {}),
+      ...(observedAt ? { observedAt } : {}),
+      ...(confidence !== undefined ? { confidence } : {}),
+    };
+
+    const itemFingerprint = canonicalFingerprint(cleanItem);
+    cleanItem.itemFingerprint = itemFingerprint;
+    normalizedItems.push(Object.freeze(cleanItem));
+  }
+
+  const normalized = {
+    provider: {
+      id: provider?.id ?? "unknown",
+      ...(provider?.version ? { version: provider.version } : {}),
+    },
+    taskId: taskId ?? null,
+    authority: ADVISORY_CONTEXT_TRUST.authority,
+    evidenceAuthority: ADVISORY_CONTEXT_TRUST.evidenceAuthority,
+    actionability: ADVISORY_CONTEXT_TRUST.actionability,
+    trustRole: ADVISORY_CONTEXT_TRUST.trustRole,
+    persisted: ADVISORY_CONTEXT_TRUST.persisted,
+    items: Object.freeze(normalizedItems),
+  };
+
+  assertPortableContextSafe(normalized, { label: "advisory context normalized result" });
+  return deepFreeze(normalized);
+}