@cassiomc1/forgeloop 0.1.0 → 0.1.2

package/src/cli.js

@@ -14,11 +14,22 @@ import { formatRouteResult, runRoute } from "./commands/route.js";
 import { runValidateReceipt } from "./commands/validate-receipt.js";
 import { formatValidateProtocolResult, runValidateProtocol } from "./commands/validate-protocol.js";
 import { runUpdate } from "./commands/update.js";
+import { formatActivateResult, runActivate } from "./commands/activate.js";
+import { formatAdvanceResult, runAdvance } from "./commands/advance.js";
+import { formatPreflightResult, runPreflight } from "./commands/preflight.js";
+import { formatCompleteResult, runComplete } from "./commands/complete.js";
+import { formatAuditResult, runAudit } from "./commands/audit.js";
+import { formatReportResult, runReport } from "./commands/report.js";
+import { formatPolicyResult, runPolicy } from "./commands/policy.js";
+import { formatBundleResult, runBundle } from "./commands/bundle.js";
+import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
+import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
+import { ARTIFACT_PATHS } from "./core/artifacts.js";
 
 function usage(command = null) {
-  const commands = "init|doctor|update|route|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
+  const commands = "init|doctor|update|activate|route|preflight|advance|prepare-completion|record-check|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
   const options = ["  --path <directory>  target project directory (default: current directory)"];
   if (!command || command === "init" || command === "update") {
     options.push("  --dry-run           show planned writes without changing files");
@@ -37,9 +48,21 @@ function usage(command = null) {
     options.push("  --executable-change declare executable/configuration change");
     options.push("  --json              emit route result as JSON");
   }
-  if (!command || ["inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
+  if (!command || command === "advance") {
+    options.push("  --to <phase>        destination workflow phase");
+  }
+  if (!command || ["activate", "advance", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
     options.push("  --json              emit structured output as JSON");
   }
+  if (!command || ["preflight", "complete", "audit", "report"].includes(command)) {
+    options.push("  --strict            require strict protocol compliance");
+  }
+  if (!command || command === "policy") {
+    options.push("  <name>              policy pack name");
+  }
+  if (!command || command === "bundle") {
+    options.push("  --task <id>         task ID to export as a portable bundle");
+  }
   if (!command || ["status", "inspect", "validate-protocol"].includes(command)) {
     options.push("  --contract-file <path>  current JSON contract used for freshness comparison");
   }
@@ -53,6 +76,17 @@ function usage(command = null) {
   if (!command || command === "validate-receipt") {
     options.push("  --file <path>       receipt file relative to target");
   }
+  if (!command || command === "record-check") {
+    options.push("  --id <id>            stable check identifier");
+    options.push("  --kind <kind>        check kind (default: command)");
+    options.push("  --requirement <id>   completion requirement covered by the check");
+    options.push("  --status <status>    passed, failed, blocked, or not-run");
+    options.push("  --evidence-kind <kind> OBSERVED, INFERRED, NOT_VERIFIED, or BLOCKED");
+    options.push("  --command <text>     command already run by the agent (recorded only)");
+    options.push("  --result <text>      observed result supplied by the agent");
+    options.push("  --exit-code <number> observed process exit code");
+    options.push("  --details <json>     additional structured check details");
+  }
   options.push("  --version           show the installed package version");
   options.push("  --help              show this help");
 
@@ -72,6 +106,7 @@ export function parseArgs(argv) {
     platforms: [],
     behaviorChange: false,
     executableChange: false,
+    to: null,
     file: null,
     contractFile: null,
     routeFile: null,
@@ -79,6 +114,17 @@ export function parseArgs(argv) {
     receiptFile: null,
     taskBriefFiles: [],
     delegatedResultFiles: [],
+    checkId: null,
+    checkKind: null,
+    checkRequirement: null,
+    checkStatus: null,
+    checkEvidenceKind: null,
+    checkCommand: null,
+    checkResult: null,
+    checkExitCode: null,
+    checkDetails: null,
+    policy: null,
+    task: null,
     help: false,
     version: false,
   };
@@ -86,7 +132,7 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (["init", "doctor", "update", "route", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
+    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "prepare-completion", "record-check", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
       if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
       command = argument;
     } else if (argument === "--help" || argument === "-h") {
@@ -126,6 +172,16 @@ export function parseArgs(argv) {
       options.behaviorChange = true;
     } else if (argument === "--executable-change") {
       options.executableChange = true;
+    } else if (argument === "--to") {
+      const phase = argv[index + 1];
+      if (!phase || phase.startsWith("-")) throw new Error("--to requires a phase");
+      options.to = phase;
+      index += 1;
+    } else if (argument === "--task") {
+      const task = argv[index + 1];
+      if (!task || task.startsWith("-")) throw new Error("--task requires an ID");
+      options.task = task;
+      index += 1;
     } else if (argument === "--file") {
       const file = argv[index + 1];
       if (!file || file.startsWith("-")) throw new Error("--file requires a path");
@@ -153,6 +209,59 @@ export function parseArgs(argv) {
       if (!file || file.startsWith("-")) throw new Error("--delegated-result-file requires a path");
       options.delegatedResultFiles.push(file);
       index += 1;
+    } else if (argument === "--id") {
+      const id = argv[index + 1];
+      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
+      options.checkId = id;
+      index += 1;
+    } else if (argument === "--kind") {
+      const kind = argv[index + 1];
+      if (!kind || kind.startsWith("-")) throw new Error("--kind requires a check kind");
+      options.checkKind = kind;
+      index += 1;
+    } else if (argument === "--requirement") {
+      const requirement = argv[index + 1];
+      if (!requirement || requirement.startsWith("-")) throw new Error("--requirement requires an evidence target");
+      options.checkRequirement = requirement;
+      index += 1;
+    } else if (argument === "--status") {
+      const status = argv[index + 1];
+      if (!status || status.startsWith("-")) throw new Error("--status requires a check status");
+      options.checkStatus = status;
+      index += 1;
+    } else if (argument === "--evidence-kind") {
+      const evidenceKind = argv[index + 1];
+      if (!evidenceKind || evidenceKind.startsWith("-")) throw new Error("--evidence-kind requires an evidence kind");
+      options.checkEvidenceKind = evidenceKind;
+      index += 1;
+    } else if (argument === "--command") {
+      const commandText = argv[index + 1];
+      if (!commandText || commandText.startsWith("-")) throw new Error("--command requires recorded text");
+      options.checkCommand = commandText;
+      index += 1;
+    } else if (argument === "--result") {
+      const resultText = argv[index + 1];
+      if (!resultText || resultText.startsWith("-")) throw new Error("--result requires recorded text");
+      options.checkResult = resultText;
+      index += 1;
+    } else if (argument === "--exit-code") {
+      const exitCode = argv[index + 1];
+      if (!exitCode || exitCode.startsWith("-")) throw new Error("--exit-code requires a non-negative integer");
+      if (!/^\d+$/.test(exitCode)) throw new Error("--exit-code requires a non-negative integer");
+      options.checkExitCode = Number(exitCode);
+      index += 1;
+    } else if (argument === "--details") {
+      const details = argv[index + 1];
+      if (!details || details.startsWith("-")) throw new Error("--details requires a JSON object");
+      try {
+        options.checkDetails = JSON.parse(details);
+      } catch {
+        throw new Error("--details must be valid JSON");
+      }
+      if (!options.checkDetails || typeof options.checkDetails !== "object" || Array.isArray(options.checkDetails)) {
+        throw new Error("--details must be a JSON object");
+      }
+      index += 1;
     } else if (argument === "--path") {
       options.path = argv[index + 1];
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
@@ -162,6 +271,8 @@ export function parseArgs(argv) {
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
     } else if (argument === "--version" || argument === "-v") {
       options.version = true;
+    } else if (!argument.startsWith("-") && command === "policy" && !options.policy) {
+      options.policy = argument;
     } else if (!argument.startsWith("-") && !command) {
       command = argument;
     } else {
@@ -171,7 +282,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
+  const jsonCommands = ["doctor", "route", "activate", "advance", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
   if (!jsonCommands.includes(command) && options.json) {
     throw new Error(`Option --json is not valid for ${command}`);
   }
@@ -181,7 +292,7 @@ export function parseArgs(argv) {
   ].includes(command) && options.dryRun) {
     throw new Error(`Option --dry-run is not valid for ${command}`);
   }
-  if (command !== "doctor" && options.strict) {
+  if (!["doctor", "preflight", "complete", "audit", "report"].includes(command) && options.strict) {
     throw new Error(`Option --strict is not valid for ${command}`);
   }
   if (command !== "doctor" && options.adopt.length > 0) {
@@ -190,6 +301,21 @@ export function parseArgs(argv) {
   if (command !== "route" && (options.work || options.surfaces.length || options.risks.length || options.platforms.length || options.behaviorChange || options.executableChange)) {
     throw new Error(`Route options are not valid for ${command}`);
   }
+  if (command !== "advance" && options.to) {
+    throw new Error(`Option --to is not valid for ${command}`);
+  }
+  if (command === "policy" && !options.policy) {
+    throw new Error("policy requires a name");
+  }
+  if (command !== "policy" && options.policy) {
+    throw new Error(`Policy name is not valid for ${command}`);
+  }
+  if (command === "bundle" && !options.task) {
+    throw new Error("bundle requires --task");
+  }
+  if (command !== "bundle" && options.task) {
+    throw new Error(`--task is not valid for ${command}`);
+  }
   if (command !== "validate-receipt" && options.file) {
     throw new Error(`Option --file is not valid for ${command}`);
   }
@@ -199,6 +325,27 @@ export function parseArgs(argv) {
   if (command !== "validate-protocol" && (options.routeFile || options.stateFile || options.receiptFile || options.taskBriefFiles.length > 0 || options.delegatedResultFiles.length > 0)) {
     throw new Error(`Protocol artifact options are not valid for ${command}`);
   }
+  const checkOptions = [
+    options.checkId,
+    options.checkKind,
+    options.checkRequirement,
+    options.checkStatus,
+    options.checkEvidenceKind,
+    options.checkCommand,
+    options.checkResult,
+    options.checkExitCode,
+    options.checkDetails,
+  ];
+  if (command !== "record-check" && checkOptions.some((value) => value !== null)) {
+    throw new Error(`Check recording options are not valid for ${command}`);
+  }
+  if (command === "record-check" && !options.help) {
+    if (!options.checkId) throw new Error("record-check requires --id");
+    if (!options.checkRequirement) throw new Error("record-check requires --requirement");
+    if (!options.checkStatus) throw new Error("record-check requires --status");
+    if (!options.checkEvidenceKind) throw new Error("record-check requires --evidence-kind");
+    if (!options.checkCommand && !options.checkResult) throw new Error("record-check requires --command or --result");
+  }
   return { command, options };
 }
 
@@ -257,7 +404,9 @@ export async function main(argv = process.argv.slice(2)) {
     }
 
     if (command === "route") {
-      const result = runRoute({
+      const result = await runRoute({
+        target,
+        packageRoot,
         workType: options.work,
         surfaces: options.surfaces,
         risks: options.risks,
@@ -269,6 +418,78 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === "activate") {
+      const result = await runActivate({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatActivateResult(result));
+      return 0;
+    }
+
+    if (command === "preflight") {
+      const result = await runPreflight({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPreflightResult(result));
+      return result.status === "READY" ? 0 : 1;
+    }
+
+    if (command === "advance") {
+      const result = await runAdvance({ target, packageRoot, to: options.to });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatAdvanceResult(result));
+      return 0;
+    }
+
+    if (command === "prepare-completion") {
+      const result = await runPrepareCompletion({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
+      return 0;
+    }
+
+    if (command === "record-check") {
+      const result = await runRecordCheck({
+        target,
+        packageRoot,
+        id: options.checkId,
+        kind: options.checkKind ?? "command",
+        requirement: options.checkRequirement,
+        status: options.checkStatus,
+        evidenceKind: options.checkEvidenceKind,
+        command: options.checkCommand,
+        result: options.checkResult,
+        exitCode: options.checkExitCode,
+        details: options.checkDetails ?? undefined,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
+      return 0;
+    }
+
+    if (command === "complete") {
+      const result = await runComplete({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));
+      return result.status === "VALID" ? 0 : 1;
+    }
+
+    if (command === "audit") {
+      const result = await runAudit({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatAuditResult(result));
+      return result.status === "VALID" ? 0 : 1;
+    }
+
+    if (command === "report") {
+      const result = await runReport({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatReportResult(result));
+      return result.verdict === "VALID" ? 0 : 1;
+    }
+
+    if (command === "policy") {
+      const result = await runPolicy({ target, packageRoot, name: options.policy });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
+      return 0;
+    }
+
+    if (command === "bundle") {
+      const result = await runBundle({ target, packageRoot, taskId: options.task });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatBundleResult(result));
+      return 0;
+    }
+
     if (command === "inspect") {
       const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile });
       console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
@@ -285,9 +506,9 @@ export async function main(argv = process.argv.slice(2)) {
       const result = await runValidateProtocol({
         target,
         packageRoot,
-        routeFile: options.routeFile,
-        stateFile: options.stateFile,
-        receiptFile: options.receiptFile,
+        stateFile: options.stateFile ?? ARTIFACT_PATHS.state,
+        receiptFile: options.receiptFile ?? ARTIFACT_PATHS.receipt,
+        routeFile: options.routeFile ?? ARTIFACT_PATHS.route,
         contractFile: options.contractFile,
         taskBriefFiles: options.taskBriefFiles,
         delegatedResultFiles: options.delegatedResultFiles,

package/src/commands/activate.js

@@ -0,0 +1,11 @@
+import { activateSession } from "../core/activation.js";
+
+export { activateSession };
+
+export async function runActivate({ target, packageRoot }) {
+  return activateSession(target, packageRoot);
+}
+
+export function formatActivateResult(result) {
+  return `activated: ${result.activationMarker}\nsession: ${result.sessionId}\n`;
+}

package/src/commands/advance.js

@@ -0,0 +1,12 @@
+import { advanceWorkState } from "../core/phase.js";
+
+export { advanceWorkState };
+
+export async function runAdvance({ target, packageRoot, to }) {
+  if (!to) throw new Error("--to is required for advance");
+  return advanceWorkState(target, to, { packageRoot });
+}
+
+export function formatAdvanceResult(result) {
+  return `phase: ${result.phase}\nprevious: ${result.previousPhase ?? "none"}\n`;
+}

package/src/commands/audit.js

@@ -0,0 +1,12 @@
+import { evaluateAudit } from "../core/audit.js";
+
+export { evaluateAudit as runAudit };
+
+export function formatAuditResult(result) {
+  const lines = [`FORGELOOP AUDIT: ${result.status}`];
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/bundle.js

@@ -0,0 +1,10 @@
+import { exportTaskBundle } from "../core/bundles.js";
+
+export async function runBundle({ target, packageRoot, taskId }) {
+  if (!taskId) throw new Error("--task is required for bundle");
+  return exportTaskBundle(target, taskId, packageRoot);
+}
+
+export function formatBundleResult(result) {
+  return `bundle: ${result.taskId}\npath: ${result.path}\nartifacts: ${result.artifacts.join(", ")}\n`;
+}

package/src/commands/complete.js

@@ -0,0 +1,18 @@
+import { runComplete as evaluateAndComplete } from "../core/completion.js";
+
+export { evaluateAndComplete as runComplete };
+
+export function formatCompleteResult(result) {
+  const lines = [`FORGELOOP COMPLETE: ${result.status}`];
+  if (result.status === "VALID") {
+    lines.push(`TASK: ${result.taskStatus}`);
+    lines.push(`VERIFICATION: ${result.verificationStatus}`);
+    lines.push(`PUBLICATION: ${result.publicationStatus}`);
+    lines.push(`PRODUCTION_READINESS: ${result.productionReadiness}`);
+  }
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/policy.js

@@ -0,0 +1,19 @@
+import { createConfig, writeConfig } from "../core/config.js";
+import { getPolicy, validatePolicy } from "../core/policies.js";
+
+export async function runPolicy({ target, packageRoot, name }) {
+  const policy = getPolicy(name);
+  await validatePolicy(policy, packageRoot);
+  const config = createConfig({
+    complianceMode: policy.complianceMode,
+    policy: policy.name,
+    requiredGates: policy.requiredGates,
+    requiredEvidence: policy.requiredEvidence,
+  });
+  await writeConfig(target, config, packageRoot);
+  return { policy, config };
+}
+
+export function formatPolicyResult(result) {
+  return `policy: ${result.policy.name}\nmode: ${result.policy.complianceMode}\n`;
+}

package/src/commands/preflight.js

@@ -0,0 +1,12 @@
+import { runPreflight as evaluateAndPersistPreflight } from "../core/preflight.js";
+
+export { evaluateAndPersistPreflight as runPreflight };
+
+export function formatPreflightResult(result) {
+  const lines = [`FORGELOOP PREFLIGHT: ${result.status}`];
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/prepare-completion.js

@@ -0,0 +1,18 @@
+import { prepareCompletion as prepareCompletionArtifacts } from "../core/completion-artifacts.js";
+
+export { prepareCompletionArtifacts as prepareCompletion };
+
+export async function runPrepareCompletion({ target, packageRoot }) {
+  return prepareCompletionArtifacts({ target, packageRoot });
+}
+
+export function formatPrepareCompletionResult(result) {
+  return [
+    "FORGELOOP COMPLETION PREPARED",
+    `receipt: ${result.path}`,
+    `task: ${result.receipt.taskId}`,
+    `required evidence: ${result.requiredEvidence.length}`,
+    `changed paths: ${result.changedPaths.length}`,
+    "",
+  ].join("\n");
+}

package/src/commands/record-check.js

@@ -0,0 +1,20 @@
+import { recordCheck as recordCheckArtifact } from "../core/completion-artifacts.js";
+
+export { recordCheckArtifact as recordCheck };
+
+export async function runRecordCheck(input) {
+  return recordCheckArtifact(input);
+}
+
+export function formatRecordCheckResult(result) {
+  return [
+    "FORGELOOP CHECK RECORDED",
+    `id: ${result.check.id}`,
+    `requirement: ${result.check.requirement}`,
+    `status: ${result.check.status}`,
+    `evidence: ${result.evidence.kind}`,
+    `coverage: ${result.coverage.find((item) => item.requirement === result.check.requirement)?.status ?? "NOT_VERIFIED"}`,
+    `receipt: ${result.path}`,
+    "",
+  ].join("\n");
+}

package/src/commands/report.js

@@ -0,0 +1,10 @@
+import { evaluateReport } from "../core/report.js";
+
+export { evaluateReport as runReport };
+
+export function formatReportResult(result) {
+  const lines = ["ForgeLoop Compliance"];
+  for (const item of result.sections) lines.push(`${item.label.padEnd(20)} ${item.status}`);
+  lines.push(`\nVERDICT: ${result.verdict}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/route.js

@@ -1,7 +1,9 @@
 import { evaluateRoute } from "../core/router.js";
+import { persistRoute } from "../core/route-artifact.js";
+import { readContract } from "../core/contract.js";
 
-export function runRoute({ workType, surfaces, risks, platforms, behaviorChange, executableChange }) {
-  return evaluateRoute({
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange }) {
+  const route = evaluateRoute({
     workType,
     surfaces,
     risks,
@@ -9,6 +11,16 @@ export function runRoute({ workType, surfaces, risks, platforms, behaviorChange,
     behaviorChange,
     executableChange,
   });
+  if (target && packageRoot) {
+    let contractFingerprint;
+    try {
+      contractFingerprint = (await readContract(target, packageRoot)).fingerprint;
+    } catch {
+      contractFingerprint = undefined;
+    }
+    await persistRoute(target, route, packageRoot, { contractFingerprint });
+  }
+  return route;
 }
 
 export function formatRouteResult(result) {

package/src/commands/validate-receipt.js

@@ -1,19 +1,20 @@
 import { assertSafePath, ensureWithin, readBytes } from "../core/filesystem.js";
 import { validateReceipt } from "../core/receipt.js";
 import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
+import { ARTIFACT_PATHS } from "../core/artifacts.js";
 
 export async function runValidateReceipt({ target, packageRoot, file }) {
-  if (!file) throw new Error("--file is required for validate-receipt");
-  await assertSafePath(target, file);
-  const receiptPath = ensureWithin(target, file);
+  const relativeFile = file ?? ARTIFACT_PATHS.receipt;
+  await assertSafePath(target, relativeFile);
+  const receiptPath = ensureWithin(target, relativeFile);
   let receipt;
   try {
     const bytes = await readBytes(receiptPath);
-    assertJsonBytes(bytes, file);
+    assertJsonBytes(bytes, relativeFile);
     receipt = JSON.parse(bytes.toString("utf8"));
-    assertJsonLimits(receipt, file);
+    assertJsonLimits(receipt, relativeFile);
   } catch (error) {
-    throw new Error(`Unable to parse receipt ${file}: ${error.message}`);
+    throw new Error(`Unable to parse receipt ${relativeFile}: ${error.message}`);
   }
   return validateReceipt(receipt, packageRoot);
 }

package/src/core/activation.js

@@ -0,0 +1,16 @@
+import { randomUUID } from "node:crypto";
+
+import { ARTIFACT_PATHS, writeJsonArtifact } from "./artifacts.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+export async function activateSession(target, packageRoot, options = {}) {
+  const value = {
+    schemaVersion: 1,
+    protocolVersion: PROTOCOL_VERSION,
+    sessionId: randomUUID(),
+    activationMarker: `forgeloop-${randomUUID()}`,
+    createdAt: options.createdAt ?? new Date().toISOString(),
+  };
+  const written = await writeJsonArtifact(target, ARTIFACT_PATHS.session, value, "activation", packageRoot, options);
+  return written.value;
+}