mirai-graph 1.3.0 → 1.5.0

package/packages/cli/validate-technology-course.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  canonicalBytes,
+  compileTechnologyCourse,
+  reconcileTechnologyCourse,
+  verifyTechnologyCourse,
+} = require("../project-technology/technology-course");
+
+const root = path.resolve(__dirname, "../..");
+const fixture = JSON.parse(fs.readFileSync(path.join(root, "examples/executable-technology-course/technology.json"), "utf8"));
+
+function compile(options = {}) {
+  return compileTechnologyCourse(root, { technology: fixture, audience: "staff", ...options });
+}
+
+const full = compile();
+assert.equal(full.status, "success");
+assert.deepEqual(full.course_pack.scenario_ids, ["scenario.full_release", "scenario.recovery_preparation"]);
+assert.deepEqual(full.course_pack.sections.map((item) => item.technology_node_id), [
+  "operation.inventory", "operation.backup", "operation.validate", "operation.promote",
+]);
+
+const partial = compile({ scenarioIds: ["scenario.recovery_preparation"] });
+assert.equal(partial.status, "success");
+assert.deepEqual(partial.course_pack.sections.map((item) => item.technology_node_id), ["operation.inventory", "operation.backup"]);
+assert.equal(partial.course_pack.course_pack_digest, compile({ scenarioIds: ["scenario.recovery_preparation"] }).course_pack.course_pack_digest);
+assert.equal(verifyTechnologyCourse(root, { coursePack: partial.course_pack }).status, "success");
+assert.equal(verifyTechnologyCourse(root, { coursePack: partial }).status, "success");
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), "mirai-course-"));
+const technologyFile = path.join(temp, "technology.json");
+fs.writeFileSync(technologyFile, canonicalBytes(fixture));
+const fromFile = compileTechnologyCourse(root, { technologyFile, scenarioIds: ["scenario.recovery_preparation"], audience: "staff" });
+assert.equal(fromFile.course_pack.course_pack_digest, partial.course_pack.course_pack_digest);
+
+const editorial = JSON.parse(JSON.stringify(partial.course_pack));
+editorial.sections[0].title = "Understand the current state";
+const editorialResult = reconcileTechnologyCourse(root, { coursePack: partial.course_pack, projection: editorial });
+assert.equal(editorialResult.status, "success");
+assert.equal(editorialResult.editorial_changes.length, 1);
+assert.equal(editorialResult.canonical_write_allowed, false);
+
+const semantic = JSON.parse(JSON.stringify(partial.course_pack));
+semantic.sections[1].check_refs = [];
+const semanticResult = reconcileTechnologyCourse(root, { coursePack: partial.course_pack, projection: semantic });
+assert.equal(semanticResult.status, "needs_decision");
+assert.equal(semanticResult.semantic_proposals.length, 1);
+assert.equal(semanticResult.canonical_write_allowed, false);
+
+const stale = JSON.parse(JSON.stringify(partial.course_pack));
+stale.course_pack_digest = `sha256:${"0".repeat(64)}`;
+assert.equal(reconcileTechnologyCourse(root, { coursePack: partial.course_pack, projection: stale }).status, "blocked");
+
+for (const mutate of [
+  (item) => { item.operations[1].prerequisites = ["operation.unknown"]; },
+  (item) => { item.operations[0].prerequisites = ["operation.backup"]; },
+  (item) => { item.operations.push(JSON.parse(JSON.stringify(item.operations[0]))); },
+  (item) => { item.scenarios[0].operation_ids = ["operation.unknown"]; },
+]) {
+  const invalid = JSON.parse(JSON.stringify(fixture)); mutate(invalid);
+  assert.equal(compileTechnologyCourse(root, { technology: invalid }).status, "blocked");
+}
+
+const tampered = JSON.parse(JSON.stringify(partial.course_pack));
+tampered.sections[0].summary = "Tampered";
+assert.equal(verifyTechnologyCourse(root, { coursePack: tampered }).status, "blocked");
+
+const secret = JSON.parse(JSON.stringify(partial.course_pack));
+secret.sections[0].token = "forbidden";
+assert.equal(verifyTechnologyCourse(root, { coursePack: secret }).status, "blocked");
+
+assert.deepEqual(fs.readdirSync(temp).sort(), ["technology.json"]);
+fs.rmSync(temp, { recursive: true, force: true });
+console.log("technology course validation: PASS");

package/packages/project-technology/index.js

@@ -16,6 +16,7 @@ const {
 const traversal = require("./context-traversal");
 const continuity = require("./continuity");
 const artifacts = require("./artifact-release");
+const technologyCourse = require("./technology-course");
 
 const CONTRACT_VERSION = "1.0.0";
 const EXTENSION_KEY = "mirai.project_technology";
@@ -35,7 +36,7 @@ const TARGET_EXPORT_KEYS = new Set([
   "schema_version", "target_id", "semantic_digest", "provider_revision",
   "decision_refs", "goal_binding", "requirement_bindings", "constraint_ids",
   "non_goal_ids", "deferred_boundary_ids", "allowed_change_scope",
-  "architecture_contract", "execution_contract_digest",
+  "architecture_contract", "execution_contract_digest", "provider_graph_id",
 ]);
 const SECRET_PARTS = [".env", "credential", "secret", "token", "password", "private-key", "id_rsa", ".pem", ".p12"];
 const EXCLUDED_PARTS = new Set([".git", ".mirai-graph", ".simai", "node_modules", "vendor", "dist", "build", "coverage", "generated"]);
@@ -424,6 +425,7 @@ function readExport(filePath) {
   try { payload = JSON.parse(bytes.toString("utf8").replace(/^\uFEFF/, "")); } catch (_) { return { export: {}, blockers: ["provider_export_invalid"] }; }
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { export: {}, blockers: ["provider_export_invalid"] };
   if (Object.keys(payload).some((key) => !TARGET_EXPORT_KEYS.has(key))) blockers.push("provider_export_not_bounded");
+  if (Object.hasOwn(payload, "provider_graph_id") && (typeof payload.provider_graph_id !== "string" || !REF_RE.test(payload.provider_graph_id))) blockers.push("provider_graph_id_invalid");
   const identity = bindingValues(payload); blockers.push(...identity.blockers);
   const executionFields = [
     "decision_refs", "goal_binding", "requirement_bindings", "constraint_ids",
@@ -434,7 +436,7 @@ function readExport(filePath) {
   const digest = sha256(canonicalBytes(normalized.contract));
   if (!payload.execution_contract_digest) blockers.push("provider_execution_contract_digest_missing");
   else if (payload.execution_contract_digest !== digest) blockers.push("provider_execution_contract_digest_mismatch");
-  return { export: { schema_version: "1.0.0", ...identity.values, ...normalized.contract, execution_contract_digest: digest }, blockers: [...new Set(blockers)].sort(), raw_sha256: sha256(bytes) };
+  return { export: { schema_version: "1.0.0", ...identity.values, ...normalized.contract, execution_contract_digest: digest, ...(payload.provider_graph_id ? { provider_graph_id: payload.provider_graph_id } : {}) }, blockers: [...new Set(blockers)].sort(), raw_sha256: sha256(bytes) };
 }
 
 function trackedFiles(repo) {
@@ -452,7 +454,42 @@ function safeTrackedFile(relative) {
 
 function inventory(repo) {
   const entries = [];
-  for (const relative of trackedFiles(repo).filter(safeTrackedFile).sort()) {
+  const blockers = [];
+  let files = trackedFiles(repo);
+  const revision = git(repo, "rev-parse", "HEAD") || null;
+  if (!revision) {
+    if (fs.existsSync(path.join(repo, ".git"))) blockers.push("inventory_git_unavailable");
+    else {
+      // Ordinary folders and immutable distributions have no Git index. Use
+      // only explicitly declared graph/raw sources, never scan arbitrary data.
+      const graph = readManifest(repo).manifest?.graph || {};
+      const refs = ["graph.json", ...(graph.source_of_truth || []), ...(graph.objects || []),
+        ...(graph.relations || []), ...(graph.schemas || []), ...(graph.raw_sources || [])];
+      const found = new Set();
+      const visited = new Set();
+      function collect(relative) {
+        if (typeof relative !== "string" || !relative || path.isAbsolute(relative) || relative.includes("\\") || relative.includes(":") || relative.split("/").includes("..") || /[?*\[\]]/.test(relative)) {
+          blockers.push("inventory_declared_source_unsafe_or_unsupported"); return;
+        }
+        if (!safeTrackedFile(relative)) return;
+        if (visited.has(relative)) return;
+        visited.add(relative);
+        if (visited.size > 10000) { blockers.push("inventory_declared_source_budget_exceeded"); return; }
+        const absolute = path.join(repo, relative);
+        if (!fs.existsSync(absolute)) { blockers.push("inventory_declared_source_missing"); return; }
+        if (fs.lstatSync(absolute).isSymbolicLink() || !fs.realpathSync(absolute).startsWith(`${fs.realpathSync(repo)}${path.sep}`)) {
+          blockers.push("inventory_declared_source_unsafe_or_unsupported"); return;
+        }
+        if (fs.statSync(absolute).isDirectory()) {
+          for (const name of fs.readdirSync(absolute).sort()) collect(`${relative.replace(/\/$/, "")}/${name}`);
+        } else if (fs.statSync(absolute).isFile()) found.add(relative);
+        else blockers.push("inventory_declared_source_unsafe_or_unsupported");
+      }
+      refs.forEach(collect);
+      files = [...found];
+    }
+  }
+  for (const relative of files.filter(safeTrackedFile).sort()) {
     const absolute = path.join(repo, relative);
     if (!fs.existsSync(absolute) || fs.lstatSync(absolute).isSymbolicLink() || !fs.statSync(absolute).isFile()) continue;
     const bytes = fs.readFileSync(absolute);
@@ -461,10 +498,11 @@ function inventory(repo) {
   const payload = {
     schema_version: "1.0.0",
     repository_id: readManifest(repo).manifest?.id || path.basename(repo),
-    revision: git(repo, "rev-parse", "HEAD") || null,
+    revision,
     files: entries,
   };
   payload.inventory_digest = sha256(canonicalBytes(payload), true);
+  if (blockers.length) payload.blockers = [...new Set(blockers)].sort();
   return payload;
 }
 
@@ -520,6 +558,7 @@ function targetBindingStatus(repo, options = {}) {
     provider_export_sha256: binding.provider_export_sha256 || null,
     execution_contract: Object.fromEntries(["decision_refs", "goal_binding", "requirement_bindings", "constraint_ids", "non_goal_ids", "deferred_boundary_ids", "allowed_change_scope", "architecture_contract"].map((key) => [key, exported.export[key]])),
     execution_contract_digest: exported.export.execution_contract_digest || null,
+    provider_graph_id: exported.export.provider_graph_id || null,
     blockers: [...new Set(blockers)].sort(),
     next_action: blockers.length ? "refresh or repair the exact provider binding" : "none",
   };
@@ -534,7 +573,7 @@ function status(repoArg, options = {}) {
   try { if (fs.existsSync(path.join(root, INVENTORY_FILE))) stored = readJson(path.join(root, INVENTORY_FILE)); } catch (_) { /* stale */ }
   const current = inventory(repo);
   const freshness = stored && stored.inventory_digest === current.inventory_digest ? "current" : stored ? "stale" : "missing";
-  const blockers = [...manifestState.blockers, ...ext.blockers];
+  const blockers = [...manifestState.blockers, ...ext.blockers, ...(current.blockers || [])];
   if (!stored && legacyRuntimeState(repo).present) blockers.push("project_technology_host_state_migration_required");
   if (ext.contract && ext.contract.enabled === false) blockers.push("project_technology_disabled");
   if (freshness !== "current") blockers.push(`project_technology_inventory_${freshness}`);
@@ -579,6 +618,8 @@ function enable(repoArg, options = {}) {
   const repo = normalizeRepo(repoArg);
   const manifestState = readManifest(repo);
   if (!manifestState.manifest || manifestState.blockers.length) return result("enable", "transactional", "fail", { blockers: manifestState.blockers, next_action: "repair graph.json" });
+  const inventoryPreflight = inventory(repo);
+  if (inventoryPreflight.blockers?.length) return result("enable", "transactional", "blocked", { blockers: inventoryPreflight.blockers, next_action: "repair declared graph sources" });
   const manifest = structuredClone(manifestState.manifest);
   const extensions = { ...(manifest.extensions || {}) };
   const legacy = extensions[LEGACY_EXTENSION_KEY];
@@ -616,7 +657,7 @@ function sync(repoArg, options = {}) {
   const repo = normalizeRepo(repoArg);
   const manifestState = readManifest(repo);
   const ext = extensionState(manifestState.manifest);
-  const blockers = [...manifestState.blockers, ...ext.blockers];
+  const blockers = [...manifestState.blockers, ...ext.blockers, ...(inventory(repo).blockers || [])];
   const hostRoot = runtimeRoot(repo, manifestState.manifest, options);
   if (legacyRuntimeState(repo).present && !fs.existsSync(path.join(hostRoot, INVENTORY_FILE))) blockers.push("project_technology_host_state_migration_required");
   if (!ext.contract || ext.legacy || ext.contract.enabled !== true) blockers.push("project_technology_not_enabled");
@@ -660,7 +701,7 @@ function provide(repoArg, options = {}) {
   blockers.push(...target.blockers);
   if (blockers.length) return result("provide", "transactional", "fail", { blockers: [...new Set(blockers)].sort(), next_action: "repair the accepted target contract" });
   const executionContractDigest = sha256(canonicalBytes(target.contract));
-  const payload = { schema_version: "1.0.0", ...identity.values, ...target.contract, execution_contract_digest: executionContractDigest };
+  const payload = { schema_version: "1.0.0", ...identity.values, ...target.contract, execution_contract_digest: executionContractDigest, provider_graph_id: manifestState.manifest.id };
   const changed = atomicWrite(path.join(repo, EXPORT_FILE), canonicalBytes(payload));
   return result("provide", "transactional", "success", { changed, export_ref: EXPORT_FILE, target_binding: payload });
 }
@@ -670,6 +711,32 @@ function providerRootFor(exportPath) {
   return completed.status === 0 ? completed.stdout.trim() : null;
 }
 
+// This is explicit consumer trust, NOT an assertion read from the provider.
+// The caller must obtain it from authenticated, checksum-bound release metadata.
+// Keeping it out of the export prevents an archive from authenticating itself.
+function archiveProviderIdentity(source, exported, anchor) {
+  const fail = code => ({ blockers: [code], ancestors: [] });
+  if (!anchor || typeof anchor !== "object" || Array.isArray(anchor)) return fail("provider_archive_trust_invalid");
+  const keys = ["exportSha256", "graphId", "providerRevision", "ancestorRevisions"];
+  if (Object.keys(anchor).some(key => !keys.includes(key)) || keys.some(key => !Object.hasOwn(anchor, key))) return fail("provider_archive_trust_invalid");
+  if (!/^[0-9a-f]{64}$/.test(anchor.exportSha256 || "") ||
+      typeof anchor.graphId !== "string" || !REF_RE.test(anchor.graphId) ||
+      !REVISION_RE.test(anchor.providerRevision || "") ||
+      !Array.isArray(anchor.ancestorRevisions) || anchor.ancestorRevisions.length > 4096 ||
+      anchor.ancestorRevisions.some(rev => typeof rev !== "string" || !REVISION_RE.test(rev) || rev === anchor.providerRevision) ||
+      new Set(anchor.ancestorRevisions).size !== anchor.ancestorRevisions.length) return fail("provider_archive_trust_invalid");
+  try {
+    // Parent aliases such as macOS /var are allowed; the exact bytes are pinned.
+    if (fs.lstatSync(source).isSymbolicLink()) return fail("provider_archive_source_unsafe");
+    if (!fs.statSync(source).isFile() || fs.statSync(source).size > 1024 * 1024) return fail("provider_archive_source_unsafe");
+    const bytes = fs.readFileSync(source);
+    if (sha256(bytes) !== anchor.exportSha256 || canonicalBytes(JSON.parse(bytes)) !== canonicalBytes(exported)) return fail("provider_archive_export_digest_mismatch");
+  } catch (_) { return fail("provider_archive_source_unsafe"); }
+  if (exported.provider_graph_id !== anchor.graphId) return fail("provider_archive_graph_mismatch");
+  if (exported.provider_revision !== anchor.providerRevision) return fail("provider_archive_revision_mismatch");
+  return { blockers: [], ancestors: anchor.ancestorRevisions };
+}
+
 function connect(repoArg, options = {}) {
   const repo = normalizeRepo(repoArg);
   const source = path.resolve(String(options.source || ""));
@@ -680,14 +747,20 @@ function connect(repoArg, options = {}) {
   const blockers = [...identity.blockers, ...read.blockers, ...manifestState.blockers, ...ext.blockers];
   if (!ext.contract || ext.legacy || ext.contract.enabled !== true) blockers.push("project_technology_not_enabled");
   for (const key of Object.keys(identity.values)) if (read.export[key] !== identity.values[key]) blockers.push(`${key}_mismatch`);
-  const providerRoot = providerRootFor(source);
-  if (!providerRoot) blockers.push("provider_revision_order_unverifiable");
+  const archiveRequested = Object.hasOwn(options, "providerArchive");
+  const archive = archiveRequested ? archiveProviderIdentity(source, read.export, options.providerArchive) : null;
+  const providerRoot = archiveRequested ? null : providerRootFor(source);
+  if (archive) blockers.push(...archive.blockers);
+  else if (!providerRoot) blockers.push("provider_revision_order_unverifiable");
   else if (git(providerRoot, "rev-parse", "HEAD").toLowerCase() !== identity.values.provider_revision) blockers.push("provider_revision_does_not_match_head");
   const root = runtimeRoot(repo, manifestState.manifest, options);
   const currentPath = path.join(root, BINDING_FILE);
   let current = null;
   try { if (fs.existsSync(currentPath)) current = readJson(currentPath); } catch (_) { blockers.push("current_target_binding_invalid"); }
   if (current) {
+    const currentExport = targetBindingStatus(repo, options);
+    const existingGraphId = currentExport.provider_graph_id;
+    if (existingGraphId && existingGraphId !== read.export.provider_graph_id) blockers.push("target_provider_graph_conflict");
     if (!options.refreshBinding) {
       const same = Object.keys(identity.values).every((key) => current[key] === identity.values[key]);
       if (!same) blockers.push("target_provider_conflict", "target_provider_refresh_required");
@@ -702,7 +775,9 @@ function connect(repoArg, options = {}) {
       const currentState = targetBindingStatus(repo, options);
       if (currentState.status !== "ready") blockers.push(...currentState.blockers);
       if (currentState.execution_contract_digest !== read.export.execution_contract_digest) blockers.push("provider_execution_contract_refresh_mismatch");
-      if (!providerRoot) blockers.push("provider_revision_order_unverifiable");
+      if (archive) {
+        if (current.provider_revision !== identity.values.provider_revision && !archive.ancestors.includes(current.provider_revision)) blockers.push("provider_revision_not_forward");
+      } else if (!providerRoot) blockers.push("provider_revision_order_unverifiable");
       else {
         if (current.provider_revision !== identity.values.provider_revision) {
           const ancestry = spawnSync("git", ["-C", providerRoot, "merge-base", "--is-ancestor", current.provider_revision, identity.values.provider_revision]);
@@ -767,7 +842,40 @@ function repair(repoArg, options = {}) {
   return sync(repo, options);
 }
 
+function verifyProviderExport(repoArg, options = {}) {
+  const repo = normalizeRepo(repoArg);
+  const source = path.resolve(options.source || path.join(repo, EXPORT_FILE));
+  const exported = readExport(source);
+  const manifestState = readManifest(repo);
+  const ext = extensionState(manifestState.manifest);
+  const identity = bindingValues(exported.export);
+  const blockers = [...exported.blockers, ...manifestState.blockers, ...ext.blockers, ...identity.blockers];
+  if (options.significantWork) blockers.push("provider_export_verification_is_not_execution_authority");
+  if (!trackedFiles(repo).includes("graph.json") || spawnSync("git", ["diff", "--quiet", "HEAD", "--", "graph.json"], { cwd: repo }).status !== 0) blockers.push("provider_manifest_not_revision_bound");
+  if (!source.startsWith(`${repo}${path.sep}`)) blockers.push("provider_export_outside_repository");
+  if (ext.contract?.enabled !== true || ext.legacy) blockers.push("project_technology_not_enabled");
+  const head = git(repo, "rev-parse", "HEAD");
+  if (head !== identity.values.provider_revision) blockers.push("provider_revision_does_not_match_head");
+  if (exported.export.provider_graph_id !== manifestState.manifest?.id) blockers.push("provider_archive_graph_mismatch");
+  const target = targetContract(repo, identity.values.target_id, identity.values.semantic_digest, manifestState.manifest);
+  blockers.push(...target.blockers);
+  if (sha256(canonicalBytes(target.contract)) !== exported.export.execution_contract_digest) blockers.push("provider_execution_contract_source_mismatch");
+  // Bound supported ancestry; deeper histories need a narrower supported
+  // release window rather than unbounded metadata in every consumer.
+  const history = git(repo, "rev-list", "--max-count=4098", "HEAD").split("\n").filter(Boolean);
+  if (history[0] !== head || history.length > 4097) blockers.push("provider_archive_ancestry_unverifiable_or_too_large");
+  return result("verify", "read_only", blockers.length ? "blocked" : "success", {
+    blockers: [...new Set(blockers)].sort(),
+    provider_archive: blockers.length ? null : {
+      exportSha256: exported.raw_sha256, graphId: manifestState.manifest.id,
+      providerRevision: head, ancestorRevisions: history.slice(1),
+    },
+    next_action: blockers.length ? "repair the canonical provider export before packaging" : "seal this anchor in authenticated release metadata",
+  });
+}
+
 function verify(repoArg, options = {}) {
+  if (options.source) return verifyProviderExport(repoArg, options);
   const state = status(repoArg, options);
   const blockers = [...state.blockers];
   const repo = normalizeRepo(repoArg);
@@ -790,6 +898,7 @@ function verify(repoArg, options = {}) {
 
 function execute(operation, repoArg, options = {}) {
   if (operation === "artifact") return artifacts.executeArtifact(repoArg, options);
+  if (operation === "course") return technologyCourse.executeCourse(repoArg, options);
   const readOnly = { explain, status, plan, verify, context };
   if (readOnly[operation]) return readOnly[operation](repoArg, options);
   const transactional = { enable, sync, connect, disconnect, provide, disable, repair };
@@ -807,6 +916,7 @@ module.exports = {
   compareArtifactReleases: artifacts.compareArtifactReleases,
   connect,
   compileContext: traversal.compileContext,
+  compileTechnologyCourse: technologyCourse.compileTechnologyCourse,
   context,
   createArtifactRelease: artifacts.createArtifactRelease,
   discoverContext: traversal.discoverContext,
@@ -820,16 +930,20 @@ module.exports = {
   inventory,
   inspectArtifactBundle: artifacts.inspectArtifactBundle,
   normalizeExecutionContract,
+  normalizeTechnology: technologyCourse.normalizeTechnology,
   continuity,
   plan,
   provide,
   readExport,
+  reconcileTechnologyCourse: technologyCourse.reconcileTechnologyCourse,
   repair,
   sha256,
   status,
   sync,
   targetBindingStatus,
   verify,
+  verifyProviderExport,
   verifyArtifactRelease: artifacts.verifyArtifactRelease,
+  verifyTechnologyCourse: technologyCourse.verifyTechnologyCourse,
   verifyContext: traversal.verifyContext,
 };

package/packages/project-technology/technology-course.js

@@ -0,0 +1,282 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:/@?=+*-]{1,255}$/;
+const ACTIVE_LIFECYCLES = new Set(["reviewed", "accepted", "active"]);
+const SECRET_MARKERS = ["password", "secret", "token", "cookie", "private_key", "totp", ".env"];
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+}
+
+function canonicalBytes(value) {
+  return `${JSON.stringify(sortValue(value), null, 2)}\n`;
+}
+
+function sha256(value, prefix = true) {
+  const digest = crypto.createHash("sha256").update(Buffer.from(String(value))).digest("hex");
+  return prefix ? `sha256:${digest}` : digest;
+}
+
+function result(action, status, extra = {}) {
+  return {
+    schema_version: "1.0.0",
+    operation_id: `mirai.project_technology.course.${action}`,
+    operation_mode: "read_only",
+    status,
+    changed: false,
+    blockers: [],
+    warnings: [],
+    next_action: "none",
+    ...extra,
+  };
+}
+
+function readJson(file) {
+  const absolute = path.resolve(file);
+  if (!fs.existsSync(absolute) || fs.lstatSync(absolute).isSymbolicLink()) throw new Error("unsafe_or_missing_json_input");
+  return JSON.parse(fs.readFileSync(absolute, "utf8").replace(/^\uFEFF/, ""));
+}
+
+function unwrapCoursePack(value) {
+  return value && typeof value === "object" && !Array.isArray(value) && value.course_pack
+    ? value.course_pack
+    : value;
+}
+
+function uniqueStrings(value, field, blockers, required = true) {
+  if (!Array.isArray(value) || (required && value.length === 0)) {
+    blockers.push(`technology_${field}_empty`);
+    return [];
+  }
+  const output = [];
+  for (const item of value) {
+    if (typeof item !== "string" || !SAFE_ID.test(item)) blockers.push(`technology_${field}_unsafe`);
+    else output.push(item);
+  }
+  return [...new Set(output)];
+}
+
+function normalizeTechnology(input) {
+  const blockers = [];
+  if (!input || typeof input !== "object" || Array.isArray(input)) return { technology: {}, blockers: ["technology_contract_missing"] };
+  const technology = {
+    schema_version: String(input.schema_version || "1.0.0"),
+    id: String(input.id || ""),
+    title: String(input.title || ""),
+    owner: String(input.owner || ""),
+    outcome: String(input.outcome || ""),
+    lifecycle: String(input.lifecycle || ""),
+    version: String(input.version || ""),
+    source_refs: uniqueStrings(input.source_refs || [], "source_refs", blockers),
+    projection_refs: uniqueStrings(input.projection_refs || [], "projection_refs", blockers, false),
+  };
+  for (const field of ["id", "owner"]) if (!SAFE_ID.test(technology[field])) blockers.push(`technology_${field}_missing_or_unsafe`);
+  for (const field of ["title", "outcome", "version"]) if (!technology[field].trim()) blockers.push(`technology_${field}_missing`);
+  if (!ACTIVE_LIFECYCLES.has(technology.lifecycle)) blockers.push("technology_lifecycle_not_executable");
+
+  const operationIds = new Set();
+  technology.operations = [];
+  if (!Array.isArray(input.operations) || input.operations.length === 0) blockers.push("technology_operations_empty");
+  else for (const raw of input.operations) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) { blockers.push("technology_operation_invalid"); continue; }
+    const operation = {
+      id: String(raw.id || ""), title: String(raw.title || ""), summary: String(raw.summary || ""),
+      owner: String(raw.owner || ""), capability_ref: String(raw.capability_ref || ""),
+      prerequisites: uniqueStrings(raw.prerequisites || [], "operation_prerequisites", blockers, false),
+      input_refs: uniqueStrings(raw.input_refs || [], "operation_input_refs", blockers, false),
+      output_refs: uniqueStrings(raw.output_refs || [], "operation_output_refs", blockers),
+      check_refs: uniqueStrings(raw.check_refs || [], "operation_check_refs", blockers),
+      stop_condition_refs: uniqueStrings(raw.stop_condition_refs || [], "operation_stop_condition_refs", blockers, false),
+      rollback_refs: uniqueStrings(raw.rollback_refs || [], "operation_rollback_refs", blockers, false),
+      source_refs: uniqueStrings(raw.source_refs || [], "operation_source_refs", blockers),
+      instructional_refs: uniqueStrings(raw.instructional_refs || [], "operation_instructional_refs", blockers, false),
+      applicability: Array.isArray(raw.applicability) ? [...new Set(raw.applicability.map(String))].sort() : [],
+      negative_boundaries: Array.isArray(raw.negative_boundaries) ? [...new Set(raw.negative_boundaries.map(String))].sort() : [],
+    };
+    for (const field of ["id", "owner", "capability_ref"]) if (!SAFE_ID.test(operation[field])) blockers.push(`technology_operation_${field}_missing_or_unsafe`);
+    if (!operation.title || !operation.summary) blockers.push("technology_operation_explanation_missing");
+    if (operationIds.has(operation.id)) blockers.push("technology_operation_duplicate");
+    operationIds.add(operation.id); technology.operations.push(operation);
+  }
+
+  technology.scenarios = [];
+  if (!Array.isArray(input.scenarios) || input.scenarios.length === 0) blockers.push("technology_scenarios_empty");
+  else {
+    const scenarioIds = new Set();
+    for (const raw of input.scenarios) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) { blockers.push("technology_scenario_invalid"); continue; }
+      const scenario = {
+        id: String(raw.id || ""), title: String(raw.title || ""), outcome: String(raw.outcome || ""),
+        operation_ids: uniqueStrings(raw.operation_ids || [], "scenario_operation_ids", blockers),
+        required_inputs: uniqueStrings(raw.required_inputs || [], "scenario_required_inputs", blockers, false),
+        audience: Array.isArray(raw.audience) ? [...new Set(raw.audience.map(String))].sort() : [],
+      };
+      if (!SAFE_ID.test(scenario.id)) blockers.push("technology_scenario_id_missing_or_unsafe");
+      if (!scenario.title || !scenario.outcome) blockers.push("technology_scenario_explanation_missing");
+      if (scenarioIds.has(scenario.id)) blockers.push("technology_scenario_duplicate");
+      scenarioIds.add(scenario.id);
+      for (const id of scenario.operation_ids) if (!operationIds.has(id)) blockers.push("technology_scenario_operation_unknown");
+      technology.scenarios.push(scenario);
+    }
+  }
+  for (const operation of technology.operations) for (const dependency of operation.prerequisites) if (!operationIds.has(dependency)) blockers.push("technology_operation_prerequisite_unknown");
+
+  const visiting = new Set(); const visited = new Set(); const byId = new Map(technology.operations.map((item) => [item.id, item]));
+  function visit(id) {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+    for (const dependency of (byId.get(id) || {}).prerequisites || []) if (visit(dependency)) return true;
+    visiting.delete(id); visited.add(id); return false;
+  }
+  if ([...byId.keys()].some(visit)) blockers.push("technology_required_dependency_cycle");
+  return { technology, blockers: [...new Set(blockers)].sort() };
+}
+
+function technologyDigest(technology) {
+  return sha256(canonicalBytes(technology));
+}
+
+function resolveClosure(operations, selectedIds, blockers) {
+  const byId = new Map(operations.map((item) => [item.id, item]));
+  const output = []; const seen = new Set();
+  function add(id) {
+    if (seen.has(id)) return;
+    const operation = byId.get(id);
+    if (!operation) { blockers.push("course_required_operation_missing"); return; }
+    for (const dependency of operation.prerequisites) add(dependency);
+    seen.add(id); output.push(operation);
+  }
+  for (const id of selectedIds) add(id);
+  return output;
+}
+
+function compileTechnologyCourse(repository, options = {}) {
+  let raw;
+  try { raw = options.technology || readJson(options.technologyFile); }
+  catch (error) { return result("compile", "blocked", { blockers: [String(error.message || error)], next_action: "provide a valid executable technology contract" }); }
+  const normalized = normalizeTechnology(raw);
+  const blockers = [...normalized.blockers];
+  if (blockers.length) return result("compile", "blocked", { blockers, next_action: "repair the executable technology contract" });
+  const scenarioIds = options.scenarioIds && options.scenarioIds.length ? options.scenarioIds : normalized.technology.scenarios.map((item) => item.id);
+  const scenarios = normalized.technology.scenarios.filter((item) => scenarioIds.includes(item.id));
+  if (scenarios.length !== new Set(scenarioIds).size) blockers.push("course_scenario_unknown");
+  const selectedOperationIds = scenarios.flatMap((item) => item.operation_ids);
+  const operations = resolveClosure(normalized.technology.operations, selectedOperationIds, blockers);
+  const audience = String(options.audience || "learner");
+  if (!SAFE_ID.test(audience)) blockers.push("course_audience_unsafe");
+  if (blockers.length) return result("compile", "blocked", { blockers: [...new Set(blockers)].sort(), next_action: "repair the technology or course selection" });
+  const technology_digest = technologyDigest(normalized.technology);
+  const packBase = {
+    schema_version: "1.0.0",
+    technology_id: normalized.technology.id,
+    technology_title: normalized.technology.title,
+    technology_outcome: normalized.technology.outcome,
+    technology_version: normalized.technology.version,
+    technology_digest,
+    audience,
+    scenario_ids: scenarios.map((item) => item.id),
+    source_refs: normalized.technology.source_refs,
+    source_revisions: options.sourceRevisions || {},
+    scenarios,
+    sections: operations.map((item, index) => ({
+      order: index + 1,
+      technology_node_id: item.id,
+      title: item.title,
+      summary: item.summary,
+      owner: item.owner,
+      capability_ref: item.capability_ref,
+      prerequisite_ids: item.prerequisites,
+      input_refs: item.input_refs,
+      output_refs: item.output_refs,
+      check_refs: item.check_refs,
+      stop_condition_refs: item.stop_condition_refs,
+      rollback_refs: item.rollback_refs,
+      source_refs: item.source_refs,
+      instructional_refs: item.instructional_refs,
+    })),
+    exercises: options.exercises || [],
+    checks: [...new Set(operations.flatMap((item) => item.check_refs))].sort(),
+    omissions: [],
+    limitations: [],
+  };
+  const context = { ...packBase, course_pack_digest: sha256(canonicalBytes(packBase)) };
+  return result("compile", "success", { repository: path.resolve(repository || "."), course_pack: context });
+}
+
+function verifyTechnologyCourse(repository, options = {}) {
+  let pack;
+  try { pack = unwrapCoursePack(options.coursePack || readJson(options.coursePackFile)); }
+  catch (error) { return result("verify", "blocked", { blockers: [String(error.message || error)] }); }
+  const blockers = [];
+  const digest = pack.course_pack_digest;
+  const base = { ...pack }; delete base.course_pack_digest;
+  if (digest !== sha256(canonicalBytes(base))) blockers.push("course_pack_digest_mismatch");
+  if (!Array.isArray(pack.sections) || pack.sections.length === 0) blockers.push("course_sections_empty");
+  const ids = new Set();
+  for (const section of pack.sections || []) {
+    if (!SAFE_ID.test(String(section.technology_node_id || ""))) blockers.push("course_section_identity_missing");
+    if (ids.has(section.technology_node_id)) blockers.push("course_section_duplicate");
+    ids.add(section.technology_node_id);
+    if (!section.title || !section.summary || !section.owner || !section.capability_ref) blockers.push("course_section_incomplete");
+  }
+  const serialized = JSON.stringify(pack).toLowerCase();
+  for (const marker of SECRET_MARKERS) if (serialized.includes(`\"${marker}\":`)) blockers.push("course_pack_secret_field_forbidden");
+  return result("verify", blockers.length ? "blocked" : "success", { blockers: [...new Set(blockers)].sort(), course_pack_digest: digest, next_action: blockers.length ? "recompile the course from current accepted technology" : "none" });
+}
+
+function reconcileTechnologyCourse(repository, options = {}) {
+  let pack; let projection;
+  try {
+    pack = unwrapCoursePack(options.coursePack || readJson(options.coursePackFile));
+    projection = options.projection || readJson(options.projectionFile);
+  } catch (error) { return result("reconcile", "blocked", { blockers: [String(error.message || error)] }); }
+  const verified = verifyTechnologyCourse(repository, { coursePack: pack });
+  if (verified.status !== "success") return result("reconcile", "blocked", { blockers: verified.blockers, next_action: verified.next_action });
+  if (projection.course_pack_digest !== pack.course_pack_digest) return result("reconcile", "blocked", { blockers: ["course_projection_source_stale"], next_action: "re-export the projection or explicitly reconcile against its source pack" });
+  const base = new Map(pack.sections.map((item) => [item.technology_node_id, item]));
+  const seen = new Set(); const changes = [];
+  for (const current of projection.sections || []) {
+    const id = current.technology_node_id;
+    if (!base.has(id)) { changes.push({ type: "semantic_proposal", technology_node_id: id || null, reason: "course_section_added" }); continue; }
+    seen.add(id); const previous = base.get(id);
+    const semanticFields = ["owner", "capability_ref", "prerequisite_ids", "input_refs", "output_refs", "check_refs", "stop_condition_refs", "rollback_refs", "source_refs"];
+    const semantic = semanticFields.some((field) => canonicalBytes(previous[field] || null) !== canonicalBytes(current[field] || null));
+    const editorial = previous.title !== current.title || previous.summary !== current.summary || canonicalBytes(previous.instructional_refs || []) !== canonicalBytes(current.instructional_refs || []);
+    if (semantic) changes.push({ type: "semantic_proposal", technology_node_id: id, reason: "executable_contract_changed" });
+    else if (editorial) changes.push({ type: "editorial", technology_node_id: id, reason: "instructional_projection_changed" });
+  }
+  for (const id of base.keys()) if (!seen.has(id)) changes.push({ type: "semantic_proposal", technology_node_id: id, reason: "required_course_section_removed" });
+  const semantic = changes.filter((item) => item.type === "semantic_proposal");
+  return result("reconcile", semantic.length ? "needs_decision" : "success", {
+    changes,
+    semantic_proposals: semantic,
+    editorial_changes: changes.filter((item) => item.type === "editorial"),
+    canonical_write_allowed: false,
+    next_action: semantic.length ? "send semantic proposals to the technology owners" : changes.length ? "apply editorial changes through the documentation owner" : "none",
+  });
+}
+
+function executeCourse(repository, options = {}) {
+  const action = options.courseAction;
+  if (action === "compile") return compileTechnologyCourse(repository, options);
+  if (action === "verify") return verifyTechnologyCourse(repository, options);
+  if (action === "reconcile") return reconcileTechnologyCourse(repository, options);
+  return result(String(action || "unknown"), "fail", { blockers: ["unsupported_technology_course_action"] });
+}
+
+module.exports = {
+  canonicalBytes,
+  compileTechnologyCourse,
+  executeCourse,
+  normalizeTechnology,
+  reconcileTechnologyCourse,
+  technologyDigest,
+  verifyTechnologyCourse,
+};