@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/command-input.js

@@ -14,6 +14,195 @@ function validateSearchCommandInput(command, options, help) {
   }
 }
 
+function validatePolicyInput(command, options) {
+  if (command === "policy" && !options.policy) throw inputError("policy requires a name");
+  if (command !== "policy" && options.policy) throw inputError(`Policy name is not valid for ${command}`);
+}
+
+function validateContractBootstrapRepairMigrationInput(command, options) {
+  if (command !== "task-migrate-contract-bootstrap-repair") return;
+  if (!options.taskId) throw inputError("task-migrate-contract-bootstrap-repair requires --task");
+  if (!options.acknowledgeMigration) throw inputError("task-migrate-contract-bootstrap-repair requires --acknowledge-migration");
+}
+
+function validateTaskCreationInput(command, options, help = false) {
+  if (help) return;
+  if (command === "bundle" && !options.taskId) throw inputError("bundle requires --task");
+  if (command === "task-create" && !options.taskId) throw inputError("task-create requires --task");
+  if (!["task-create", "contract-create", "contract-revise"].includes(command) && (options.preset || options.preview)) {
+    throw inputError(`preset/preview options are not valid for ${command}`);
+  }
+  if (command === "task-create" && options.preview && !options.preset && !options.contractFile) {
+    throw inputError("task-create --preview requires --preset or --contract-file");
+  }
+  if (command === "task-create" && options.preset && options.contractFile) {
+    throw inputError("task-create accepts either --preset or --contract-file, not both");
+  }
+  if (command === "contract-create" && !options.taskId) throw inputError("contract-create requires --task");
+  if (command === "contract-create" && !options.preset && !options.contractFile) throw inputError("contract-create requires --preset or --contract-file");
+  if (command === "contract-create" && options.preset && options.contractFile) throw inputError("contract-create accepts either --preset or --contract-file, not both");
+  if (command === "contract-revise" && !options.taskId) throw inputError("contract-revise requires --task");
+  if (command === "contract-revise" && !options.preset && !options.contractFile) throw inputError("contract-revise requires --preset or --contract-file");
+  if (command === "contract-revise" && options.preset && options.contractFile) throw inputError("contract-revise accepts either --preset or --contract-file, not both");
+  if (command === "task-repair-contract-bootstrap" && !options.taskId) throw inputError("task-repair-contract-bootstrap requires --task");
+  if (command === "task-repair-contract-bootstrap" && !options.acknowledgeRepair) throw inputError("task-repair-contract-bootstrap requires --acknowledge-repair");
+  validateContractBootstrapRepairMigrationInput(command, options);
+  const hasTaskListFilter = Boolean(
+    options.phase
+      || options.active
+      || (options.limit !== undefined && options.limit !== null)
+      || (options.offset !== undefined && options.offset !== null && options.offset !== 0),
+  );
+  if (command !== "task-list" && hasTaskListFilter) {
+    throw inputError(`task-list filters are not valid for ${command}`);
+  }
+}
+
+function validateGateRecordInput(command, options, help) {
+  if (command !== "gate-record" || help) return;
+  if (!options.taskId) throw inputError("gate-record requires --task");
+  if (!options.gate) throw inputError("gate-record requires --gate");
+  if (!["satisfied", "unverified", "blocked"].includes(options.gateStatus)) {
+    throw inputError("gate-record --status must be satisfied, unverified, or blocked");
+  }
+}
+
+function validateExecutionProfileInput(command, options) {
+  if (options.executionProfile !== null && options.executionProfile !== undefined) {
+    if (command !== "route") throw inputError(`executionProfile is not valid for ${command}`);
+    if (!EXECUTION_PROFILE_REQUESTS.includes(options.executionProfile)) {
+      throw inputError(`route --execution-profile must be one of ${EXECUTION_PROFILE_REQUESTS.join(", ")}`);
+    }
+  }
+}
+
+function validateUsageInput(command, options, help) {
+  if (command === "usage-record" && !help) {
+    if (!options.taskId) throw inputError("usage-record requires --task");
+    if ((options.usageSource ?? "ACTOR_REPORTED") !== "ACTOR_REPORTED") {
+      throw inputError("usage-record accepts only --source ACTOR_REPORTED");
+    }
+  }
+  if (command === "efficiency" && !help && !options.taskId) {
+    throw inputError("efficiency requires --task");
+  }
+}
+
+function validateQualityInput(command, options, help) {
+  if (["quality-baseline", "quality-verify", "quality-status"].includes(command) && !help && !options.taskId) {
+    throw inputError(`${command} requires --task`);
+  }
+  if (["quality-baseline", "quality-verify"].includes(command) && !help
+    && options.timeoutMs !== null && options.timeoutMs !== undefined
+    && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 0 || options.timeoutMs > 300000)) {
+    throw inputError(`${command} --timeout-ms must be between 0 and 300000`);
+  }
+}
+
+function validateProfileAndUsageInput(command, options, help) {
+  validateExecutionProfileInput(command, options);
+  validateUsageInput(command, options, help);
+  validateQualityInput(command, options, help);
+  if (command !== "quality-baseline" && options.replace === true) throw inputError("--replace is only valid for quality-baseline");
+  if (command !== "usage-record" && options.usageSource !== undefined && options.usageSource !== "ACTOR_REPORTED") {
+    throw inputError(`usageSource is not valid for ${command}`);
+  }
+}
+
+function validateOutputInput(command, options) {
+  if (options.compact === true && !["next", "task-show"].includes(command)) {
+    throw inputError(`compact output is not valid for ${command}`);
+  }
+  if (command !== "next" && options.explain === true) throw inputError(`explain output is not valid for ${command}`);
+}
+
+const TASK_SELECTOR_COMMANDS = new Set([
+  "context-plan",
+  "model-route",
+  "semantic-plan",
+  "test-utility",
+  "checkpoint-revalidate",
+  "workspace-bind",
+  "workspace-status",
+  "handoff-create",
+  "handoff-list",
+  "handoff-show",
+  "handoff-accept",
+  "responsibility-set",
+  "responsibility-status",
+  "verify-scope",
+  "attestation-create",
+  "attestation-status",
+  "attestation-verify",
+]);
+
+function validateRequiredTaskSelector(command, options, help) {
+  if (TASK_SELECTOR_COMMANDS.has(command) && !help && !options.taskId) {
+    throw inputError(`${command} requires --task`);
+  }
+}
+
+function validateHandoffShowInput(command, options, help) {
+  if (command === "handoff-show" && !help && !options.handoffId) throw inputError("handoff-show requires --id");
+}
+
+function validateHandoffAcceptInput(command, options, help) {
+  if (command !== "handoff-accept" || help) return;
+  if (!options.handoffId) throw inputError("handoff-accept requires --handoff");
+  if (!options.consumerId) throw inputError("handoff-accept requires --consumer-id");
+}
+
+function validateResponsibilityInput(command, options, help) {
+  if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
+    throw inputError("responsibility-set requires --label");
+  }
+}
+
+function validateVerificationScopeInput(command, options, help) {
+  if (command !== "verify-scope" || help) return;
+  const mode = String(options.verificationScopeMode ?? "AUTO").toUpperCase();
+  if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(mode)) throw inputError("verify-scope --mode must be AUTO, CHANGED, CLAIMED, or FULL");
+}
+
+function validateAttestationRangeInput(command, options, help) {
+  if (command !== "attestation-verify-range" || help) return;
+  if (!options.baseRevision) throw inputError("attestation-verify-range requires --base");
+  if (!options.headRevision) throw inputError("attestation-verify-range requires --head");
+}
+
+function validateTaskSelectorsInput(command, options, help) {
+  validateRequiredTaskSelector(command, options, help);
+  validateHandoffShowInput(command, options, help);
+  validateHandoffAcceptInput(command, options, help);
+  validateResponsibilityInput(command, options, help);
+  validateVerificationScopeInput(command, options, help);
+  validateAttestationRangeInput(command, options, help);
+}
+
+function validateRecordCheckInput(options) {
+  if (!options.checkId) throw inputError("record-check requires --id");
+  if (!options.checkRequirement) throw inputError("record-check requires --requirement");
+  if (!options.checkStatus) throw inputError("record-check requires --status");
+  if (!options.checkEvidenceKind) throw inputError("record-check requires --evidence-kind");
+  if (!options.checkCommand && !options.checkResult) throw inputError("record-check requires --command or --result");
+}
+
+function validateCommandCheckInput(options, command) {
+  if (!options.checkId) throw inputError(`${command} requires --id`);
+  if (!options.checkRequirement) throw inputError(`${command} requires --requirement`);
+  if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
+    || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
+    throw inputError(`${command} accepts only --id, --requirement, --details,${command === "run-check" ? " --timeout-ms, --scope-ref," : ""} and -- <argv>`);
+  }
+  if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) throw inputError(`${command} requires -- followed by an exact command argv`);
+}
+
+function validateCheckInput(command, options, help) {
+  if (help) return;
+  if (command === "record-check") validateRecordCheckInput(options);
+  if (command === "run-check" || command === "reconcile-closure") validateCommandCheckInput(options, command);
+}
+
 /**
  * Transport-neutral option defaults shared by the CLI parser and the
  * programmatic command runtime so every executor observes the same
@@ -25,6 +214,7 @@ export function defaultCommandInputValues() {
     dryRun: false,
     json: false,
     compact: false,
+    explain: false,
     strict: false,
     fix: false,
     adopt: [],
@@ -44,6 +234,8 @@ export function defaultCommandInputValues() {
     assetPath: null,
     binaryPath: null,
     force: false,
+    acknowledgeRepair: false,
+    acknowledgeMigration: false,
     workType: null,
     surfaces: [],
     risks: [],
@@ -64,6 +256,19 @@ export function defaultCommandInputValues() {
     to: null,
     file: null,
     contractFile: null,
+    preset: null,
+    gate: null,
+    gateStatus: null,
+    gateArtifacts: [],
+    gateDecisions: [],
+    gateUnknowns: [],
+    gateAssumptions: [],
+    gateEvidenceFile: null,
+    preview: false,
+    phase: null,
+    active: false,
+    limit: null,
+    offset: 0,
     routeFile: null,
     stateFile: null,
     receiptFile: null,
@@ -128,110 +333,15 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   const options = input ?? {};
   if (!command) return;
 
-  if (command === "policy" && !options.policy) {
-    throw inputError("policy requires a name");
-  }
-  if (command !== "policy" && options.policy) {
-    throw inputError(`Policy name is not valid for ${command}`);
-  }
-  if (command === "bundle" && !options.taskId) {
-    throw inputError("bundle requires --task");
-  }
-  if (command === "task-create" && !options.taskId) {
-    throw inputError("task-create requires --task");
-  }
+  validatePolicyInput(command, options);
+  validateTaskCreationInput(command, options, help);
+  validateGateRecordInput(command, options, help);
   validateSearchCommandInput(command, options, help);
-  if (options.executionProfile !== null && options.executionProfile !== undefined) {
-    if (command !== "route") throw inputError(`executionProfile is not valid for ${command}`);
-    if (!EXECUTION_PROFILE_REQUESTS.includes(options.executionProfile)) {
-      throw inputError(`route --execution-profile must be one of ${EXECUTION_PROFILE_REQUESTS.join(", ")}`);
-    }
-  }
-  if (command === "usage-record" && !help) {
-    if (!options.taskId) throw inputError("usage-record requires --task");
-    if ((options.usageSource ?? "ACTOR_REPORTED") !== "ACTOR_REPORTED") {
-      throw inputError("usage-record accepts only --source ACTOR_REPORTED");
-    }
-  }
-  if (command === "efficiency" && !help && !options.taskId) {
-    throw inputError("efficiency requires --task");
-  }
-  if (["quality-baseline", "quality-verify", "quality-status"].includes(command) && !help && !options.taskId) {
-    throw inputError(`${command} requires --task`);
-  }
-  if (["quality-baseline", "quality-verify"].includes(command) && !help
-    && options.timeoutMs !== null && options.timeoutMs !== undefined
-    && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 0 || options.timeoutMs > 300000)) {
-    throw inputError(`${command} --timeout-ms must be between 0 and 300000`);
-  }
-  if (command !== "quality-baseline" && options.replace === true) {
-    throw inputError(`--replace is only valid for quality-baseline`);
-  }
-  if (command !== "usage-record" && options.usageSource !== undefined && options.usageSource !== "ACTOR_REPORTED") {
-    throw inputError(`usageSource is not valid for ${command}`);
-  }
-  if (options.compact === true && !["next", "task-show"].includes(command)) {
-    throw inputError(`compact output is not valid for ${command}`);
-  }
-  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "handoff-accept", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
-    && !options.taskId) {
-    throw inputError(`${command} requires --task`);
-  }
-  if (command === "handoff-show" && !help && !options.handoffId) {
-    throw inputError("handoff-show requires --id");
-  }
-  if (command === "handoff-accept" && !help) {
-    if (!options.handoffId) {
-      throw inputError("handoff-accept requires --handoff");
-    }
-    if (!options.consumerId) {
-      throw inputError("handoff-accept requires --consumer-id");
-    }
-  }
-  if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
-    throw inputError("responsibility-set requires --label");
-  }
-  if (command === "verify-scope" && !help) {
-    const mode = String(options.verificationScopeMode ?? "AUTO").toUpperCase();
-    if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(mode)) {
-      throw inputError("verify-scope --mode must be AUTO, CHANGED, CLAIMED, or FULL");
-    }
-  }
-  if (command === "attestation-verify-range" && !help) {
-    if (!options.baseRevision) throw inputError("attestation-verify-range requires --base");
-    if (!options.headRevision) throw inputError("attestation-verify-range requires --head");
-  }
+  validateProfileAndUsageInput(command, options, help);
+  validateOutputInput(command, options);
+  validateTaskSelectorsInput(command, options, help);
 
   validateContinuityOptions(command, options);
 
-  if (command === "record-check" && !help) {
-    if (!options.checkId) throw inputError("record-check requires --id");
-    if (!options.checkRequirement) throw inputError("record-check requires --requirement");
-    if (!options.checkStatus) throw inputError("record-check requires --status");
-    if (!options.checkEvidenceKind) throw inputError("record-check requires --evidence-kind");
-    if (!options.checkCommand && !options.checkResult) throw inputError("record-check requires --command or --result");
-  }
-  if (command === "run-check" && !help) {
-    if (!options.checkId) throw inputError("run-check requires --id");
-    if (!options.checkRequirement) throw inputError("run-check requires --requirement");
-    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
-      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw inputError("run-check accepts only --id, --requirement, --details, --timeout-ms, --scope-ref, and -- <argv>");
-    }
-    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
-      throw inputError("run-check requires -- followed by an exact command argv");
-    }
-  }
-  if (command === "reconcile-closure" && !help) {
-    if (!options.taskId) throw inputError("reconcile-closure requires --task");
-    if (!options.checkId) throw inputError("reconcile-closure requires --id");
-    if (!options.checkRequirement) throw inputError("reconcile-closure requires --requirement");
-    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
-      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw inputError("reconcile-closure accepts only --id, --requirement, --details, and -- <argv>");
-    }
-    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
-      throw inputError("reconcile-closure requires -- followed by an exact command argv");
-    }
-  }
+  validateCheckInput(command, options, help);
 }

package/src/core/completion-artifacts.js

@@ -18,7 +18,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
-import { normalizeRequirements } from "./evidence-readiness.js";
+import { normalizeRequirements, terminalRequirementsForContract } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
 import { readExecutionArtifact, validateExecutionBinding } from "./execution.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
@@ -478,10 +478,15 @@ export async function assertRecordCheckPrerequisites({
   const requested = normalizeRequirements(requiredEvidence).find((item) => (
     item.id === requirement || item.text === requirement
   ));
-  if (requested?.terminalOwned && status === "passed" && evidenceKind === "OBSERVED") {
+  const terminalRequested = terminalRequirementsForContract(contract.value, {
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  }).find((item) => (
+    item.id === requirement || item.text === requirement
+  ));
+  if ((requested?.terminalOwned || terminalRequested) && status === "passed" && evidenceKind === "OBSERVED") {
     throw artifactError(
       "E_FUTURE_LIFECYCLE_EVIDENCE",
-      `Terminal-owned requirement cannot be recorded before its authoritative result: ${requested.text}`,
+      `Terminal-owned requirement cannot be recorded before its authoritative result: ${(requested ?? terminalRequested).text}`,
       [stateRel, eventsRel],
     );
   }
@@ -827,8 +832,12 @@ export async function recordTerminalResult({
     additionalEvidence: preflight.policy?.requiredEvidence ?? [],
   });
 
-  const normalized = normalizeRequirements(requiredEvidence);
-  const requested = normalized.find((item) => (
+  const terminalRequirements = terminalRequirementsForContract(contract.value, {
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  const requested = terminalRequirements.find((item) => (
+    item.id === requirement || item.text === requirement
+  )) ?? normalizeRequirements(requiredEvidence).find((item) => (
     item.id === requirement || item.text === requirement
   ));
 

package/src/core/completion.js

@@ -10,7 +10,7 @@ import { completionRelationshipErrors } from "./completion-relationships.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { evaluateStartExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
-import { evaluateTerminalRequirements } from "./evidence-readiness.js";
+import { evaluateTerminalRequirements, terminalRequirementsForContract } from "./evidence-readiness.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath, taskCodeManifestPath } from "./task-paths.js";
 import { detectPolicyCapability, evaluateTargetPolicy } from "./policy-engine.js";
 import { listActions } from "./actions.js";
@@ -500,12 +500,10 @@ export async function evaluateCompletion({
   const publication = receiptValue ? publicationStatus(receiptValue) : "not-published";
 
   if (contract) {
-    const allContractReqs = [
-      ...(contract.value.verification ?? []),
-      ...(contract.value.successCriteria ?? []),
-    ];
     const terminalEval = evaluateTerminalRequirements({
-      requirements: allContractReqs,
+      requirements: terminalRequirementsForContract(contract.value, {
+        additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+      }),
       receipt: receiptValue,
     });
     for (const termErr of terminalEval.errors) {

package/src/core/config.js

@@ -4,6 +4,7 @@ import { E_ATTESTATION_CONFIGURATION_INVALID } from "./error-codes.js";
 import { normalizeVerificationConfiguration } from "./verification-scope-capability.js";
 import { EXECUTION_PROFILE_REQUESTS } from "./execution-profile.js";
 import { normalizeStructuralQualityConfig } from "./structural-quality/policy.js";
+import { normalizeDecisionPolicy } from "./decision/policy.js";
 
 export const CONFIG_SCHEMA_VERSION = 1;
 export const COMPLIANCE_MODES = Object.freeze(["advisory", "standard", "strict"]);
@@ -82,6 +83,7 @@ export function createConfig(input = {}) {
     executionProfile = input.executionProfile;
   }
   const structuralQuality = normalizeStructuralQualityConfig(input.structuralQuality);
+  const decisionEngine = normalizeDecisionPolicy(input.decisionEngine);
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
@@ -93,6 +95,7 @@ export function createConfig(input = {}) {
     ...(attestation ? { attestation } : {}),
     ...(executionProfile ? { executionProfile } : {}),
     ...(structuralQuality !== undefined ? { structuralQuality } : {}),
+    decisionEngine,
   };
 }
 

package/src/core/context-compiler/budget.js

@@ -0,0 +1,9 @@
+export const CONTEXT_BUDGETS = Object.freeze({
+  light: Object.freeze({ maxItems: 12, maxChars: 24_000 }),
+  balanced: Object.freeze({ maxItems: 32, maxChars: 64_000 }),
+  full: Object.freeze({ maxItems: 96, maxChars: 160_000 }),
+});
+
+export function contextBudget(profile = "balanced") {
+  return CONTEXT_BUDGETS[profile] ?? CONTEXT_BUDGETS.balanced;
+}

package/src/core/context-compiler/candidates.js

@@ -0,0 +1,39 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { buildDecisionState } from "../decision/state-builder.js";
+
+const INJECTION_PATTERN = /(ignore|disregard|override)\s+(?:all|previous|forge|system|developer)|exfiltrat|reveal\s+(?:the|all)\s+(?:secret|token|key)|execute\s+(?:this|the)\s+command/i;
+
+export function normalizeContextCandidate(input = {}) {
+  const safe = buildDecisionState({
+    id: input.id ?? null,
+    sourceRef: input.sourceRef ?? null,
+    kind: input.kind ?? "UNKNOWN",
+    summary: input.summary ?? "",
+    required: input.required === true,
+    mandatory: input.mandatory === true,
+    risk: input.risk ?? "NORMAL",
+    trust: input.trust ?? "UNTRUSTED",
+  });
+  const summary = typeof safe.summary === "string" ? safe.summary : "";
+  const id = typeof safe.id === "string" && safe.id ? safe.id : `candidate-${canonicalFingerprint(safe).slice(0, 16)}`;
+  return {
+    ...safe,
+    id,
+    summary,
+    chars: summary.length,
+    promptInjection: INJECTION_PATTERN.test(summary),
+  };
+}
+
+export function normalizeContextCandidates(candidates = []) {
+  const seen = new Set();
+  const normalized = [];
+  for (const candidate of candidates) {
+    const value = normalizeContextCandidate(candidate);
+    const identity = `${value.id}:${value.sourceRef ?? ""}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    normalized.push(value);
+  }
+  return normalized;
+}

package/src/core/context-compiler/compiler.js

@@ -0,0 +1,63 @@
+import { contextBudget } from "./budget.js";
+import { normalizeContextCandidates } from "./candidates.js";
+import { contextPlanFingerprint } from "./fingerprint.js";
+import { canonicalFingerprint } from "../artifacts.js";
+import { assertContextCompilerPolicy, candidatePriority } from "./policy.js";
+import { contextPlanResult } from "./result.js";
+
+function orderCandidates(candidates, rankedIds = []) {
+  const ranks = new Map(rankedIds.map((id, index) => [id, rankedIds.length - index]));
+  return [...candidates].sort((a, b) => (b.mandatory - a.mandatory)
+    || (b.required - a.required)
+    || ((ranks.get(b.id) ?? 0) - (ranks.get(a.id) ?? 0))
+    || (candidatePriority(b) - candidatePriority(a))
+    || a.id.localeCompare(b.id));
+}
+
+export function compileContext({ candidates = [], profile = "balanced", mandatoryIds = [], semanticRanker = null } = {}) {
+  const policy = assertContextCompilerPolicy({ profile, mandatoryIds });
+  const normalized = normalizeContextCandidates(candidates);
+  const candidateSetFingerprint = canonicalFingerprint(normalized.map((candidate) => ({
+    id: candidate.id,
+    sourceRef: candidate.sourceRef,
+    summary: candidate.summary,
+    required: candidate.required,
+    mandatory: candidate.mandatory,
+  })));
+  const mandatory = new Set(policy.mandatoryIds);
+  const marked = normalized.map((candidate) => ({ ...candidate, mandatory: candidate.mandatory || mandatory.has(candidate.id) }));
+  const semantic = typeof semanticRanker === "function" ? semanticRanker(marked.filter((item) => !item.promptInjection).map((item) => ({ id: item.id, summary: item.summary }))) : [];
+  const rankedIds = Array.isArray(semantic) ? semantic : (semantic?.rankedIds ?? []);
+  const excludedIds = new Set(Array.isArray(semantic) ? [] : (semantic?.excludedIds ?? []));
+  const ordered = orderCandidates(marked, Array.isArray(rankedIds) ? rankedIds : []);
+  const budget = contextBudget(profile);
+  const selected = [];
+  const omitted = [];
+  let chars = 0;
+  for (const candidate of ordered) {
+    const mustKeep = candidate.mandatory || candidate.required;
+    if (excludedIds.has(candidate.id) && !mustKeep) {
+      omitted.push(candidate);
+      continue;
+    }
+    const fits = selected.length < budget.maxItems && chars + candidate.chars <= budget.maxChars;
+    if (fits || mustKeep) {
+      selected.push(candidate);
+      chars += candidate.chars;
+    } else omitted.push(candidate);
+  }
+  const promptInjectionIds = marked.filter((item) => item.promptInjection).map((item) => item.id).sort();
+  const result = contextPlanResult({
+    profile,
+    candidates: marked,
+    selected,
+    omitted,
+    mandatoryIds: [...new Set([...policy.mandatoryIds, ...marked.filter((item) => item.mandatory).map((item) => item.id)])].sort(),
+    promptInjectionIds,
+    fingerprint: null,
+    budget,
+    candidateSetFingerprint,
+  });
+  result.decisionFingerprint = contextPlanFingerprint(result);
+  return result;
+}

package/src/core/context-compiler/fingerprint.js

@@ -0,0 +1,11 @@
+import { canonicalFingerprint } from "../artifacts.js";
+
+export function contextPlanFingerprint(plan) {
+  return canonicalFingerprint({
+    profile: plan.profile,
+    selectedIds: plan.selected.map((item) => item.id),
+    omittedIds: plan.omitted.map((item) => item.id),
+    mandatoryIds: plan.mandatoryIds,
+    promptInjectionIds: plan.promptInjectionIds,
+  });
+}

package/src/core/context-compiler/policy.js

@@ -0,0 +1,13 @@
+import { decisionError, DECISION_ERROR_CODES } from "../decision/errors.js";
+
+const RISK_ORDER = Object.freeze({ CRITICAL: 4, HIGH: 3, NORMAL: 2, LOW: 1 });
+
+export function assertContextCompilerPolicy({ profile = "balanced", mandatoryIds = [] } = {}) {
+  if (!["light", "balanced", "full"].includes(profile)) throw decisionError(DECISION_ERROR_CODES.POLICY_INVALID, "Context compiler profile is invalid.");
+  if (!Array.isArray(mandatoryIds) || mandatoryIds.some((id) => typeof id !== "string" || !id)) throw decisionError(DECISION_ERROR_CODES.POLICY_INVALID, "Context compiler mandatory IDs are invalid.");
+  return { profile, mandatoryIds: [...new Set(mandatoryIds)] };
+}
+
+export function candidatePriority(candidate) {
+  return (candidate.mandatory || candidate.required ? 100 : 0) + (candidate.promptInjection ? -50 : 0) + (RISK_ORDER[candidate.risk] ?? 0);
+}

package/src/core/context-compiler/result.js

@@ -0,0 +1,23 @@
+export function contextPlanResult({ profile, candidates, selected, omitted, mandatoryIds, promptInjectionIds, fingerprint, budget, candidateSetFingerprint }) {
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    profile,
+    budget,
+    candidateItems: candidates.length,
+    selectedItems: selected.length,
+    candidateChars: candidates.reduce((total, item) => total + item.chars, 0),
+    selectedChars: selected.reduce((total, item) => total + item.chars, 0),
+    selected,
+    omitted,
+    mandatoryIds,
+    promptInjectionIds,
+    candidateSetFingerprint,
+    tokenUsage: { inputTokens: null, outputTokens: null, reportedBy: "UNKNOWN" },
+    decisionFingerprint: fingerprint,
+    authority: "SEMANTIC_DECISION",
+    evidenceAuthority: "NONE",
+    lifecycleAuthority: false,
+    completionAuthority: false,
+  };
+}