mirai-graph 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to Mirai Graph will be documented in this file.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-08-29
+
+### Added
+
+- A domain-neutral executable-technology contract for large, ordered methods
+  whose scenarios reuse independently executable operations.
+- Deterministic Course Pack compilation with required dependency closure,
+  exact source binding and partial courses for one scenario.
+- Read-only `technology course compile`, `verify` and `reconcile` operations in
+  the public CLI and JavaScript API.
+- Universal positive and negative fixtures for course projection.
+
+### Safety Boundary
+
+- A course is a projection, not another source of truth. Reconciliation never
+  writes to the executable technology and semantic changes require an owner
+  decision.
+- Missing operations, dependency cycles, stale digests and secret fields fail
+  closed.
+- The public `graph.json` schema remains `2.0.0`; the Project Technology
+  activation contract remains `1.0.0` and no new profile is introduced.
+
 ## [1.3.0] - 2026-08-28
 
 ### Added

package/README.md

@@ -156,6 +156,23 @@ The protected files remain outside graph data. The graph keeps only safe
 identity, lineage, state, references and checksums. Mirai Graph performs
 technical integrity checks; a domain owner decides what a version means.
 
+Large operational methods can be described once as executable technologies and
+compiled into staff courses without maintaining a second semantic copy:
+
+```bash
+mirai-graph technology course compile . --technology graph/specs/technology.json
+mirai-graph technology course compile . --technology graph/specs/technology.json --scenario scenario.recovery
+mirai-graph technology course verify . --course-pack course-pack.json
+mirai-graph technology course reconcile . --course-pack course-pack.json --projection edited-course.json
+```
+
+An executable technology contains reusable operations, their prerequisites,
+inputs, outputs, stop conditions, rollback paths, checks and raw source refs.
+Scenarios select the operations needed for a complete or partial outcome.
+Compilation restores every required dependency. Reconciliation is read-only:
+editorial differences go to the documentation owner, while changed execution
+or safety rules become proposals to the technology owner.
+
 Changing operations return a preview unless `--apply` is explicit. See
 [Project Technology](standard/project-technology.md) for provider/consumer
 binding, local state and safety boundaries.

package/examples/executable-technology-course/README.md

@@ -0,0 +1,16 @@
+# Executable Technology Course
+
+This domain-neutral fixture demonstrates one accepted executable technology,
+two independently usable scenarios and a deterministic instructional course
+projection. The recovery scenario automatically includes its required
+inventory operation.
+
+```bash
+mirai-graph technology course compile . \
+  --technology examples/executable-technology-course/technology.json \
+  --scenario scenario.recovery_preparation
+```
+
+Course packs are read-only projections. Their reconciliation result can return
+editorial changes, but semantic changes remain owner proposals and never write
+back into the executable technology.

package/examples/executable-technology-course/technology.json

@@ -0,0 +1,99 @@
+{
+  "schema_version": "1.0.0",
+  "id": "technology.service_release",
+  "title": "Safe service release",
+  "owner": "role.release_owner",
+  "outcome": "A verified service version is promoted with a tested recovery path.",
+  "lifecycle": "accepted",
+  "version": "2026.08",
+  "source_refs": ["repo://example/operations/release.md"],
+  "projection_refs": ["docs://staff-course/service-release"],
+  "operations": [
+    {
+      "id": "operation.inventory",
+      "title": "Inventory the current state",
+      "summary": "Record exact versions, dependencies and available environments before change.",
+      "owner": "role.release_owner",
+      "capability_ref": "capability.release.inventory",
+      "prerequisites": [],
+      "input_refs": ["input.release_request"],
+      "output_refs": ["evidence.current_state"],
+      "check_refs": ["check.inventory_complete"],
+      "stop_condition_refs": ["stop.unknown_current_state"],
+      "rollback_refs": [],
+      "source_refs": ["repo://example/operations/inventory.md"],
+      "instructional_refs": ["lesson.inventory"],
+      "applicability": ["release", "recovery"],
+      "negative_boundaries": ["Do not mutate the environment during inventory."]
+    },
+    {
+      "id": "operation.backup",
+      "title": "Prepare recovery",
+      "summary": "Create and verify a bounded backup and rollback procedure.",
+      "owner": "role.operations",
+      "capability_ref": "capability.release.recovery",
+      "prerequisites": ["operation.inventory"],
+      "input_refs": ["evidence.current_state"],
+      "output_refs": ["evidence.backup", "procedure.rollback"],
+      "check_refs": ["check.restore_smoke"],
+      "stop_condition_refs": ["stop.restore_not_proven"],
+      "rollback_refs": ["procedure.rollback"],
+      "source_refs": ["repo://example/operations/recovery.md"],
+      "instructional_refs": ["lesson.recovery"],
+      "applicability": ["release", "recovery"],
+      "negative_boundaries": ["A backup without a restore check is not sufficient."]
+    },
+    {
+      "id": "operation.validate",
+      "title": "Validate the candidate",
+      "summary": "Run the required functional, compatibility and safety checks.",
+      "owner": "role.tester",
+      "capability_ref": "capability.release.validation",
+      "prerequisites": ["operation.inventory"],
+      "input_refs": ["input.release_candidate"],
+      "output_refs": ["evidence.validation"],
+      "check_refs": ["check.acceptance"],
+      "stop_condition_refs": ["stop.blocking_regression"],
+      "rollback_refs": [],
+      "source_refs": ["repo://example/operations/validation.md"],
+      "instructional_refs": ["lesson.validation"],
+      "applicability": ["release"],
+      "negative_boundaries": ["A green syntax check is not an outcome verdict."]
+    },
+    {
+      "id": "operation.promote",
+      "title": "Promote the accepted version",
+      "summary": "Apply the exact accepted candidate and verify the resulting identity.",
+      "owner": "role.release_owner",
+      "capability_ref": "capability.release.promotion",
+      "prerequisites": ["operation.backup", "operation.validate"],
+      "input_refs": ["evidence.backup", "evidence.validation"],
+      "output_refs": ["evidence.release_readback"],
+      "check_refs": ["check.release_identity", "check.runtime_smoke"],
+      "stop_condition_refs": ["stop.identity_mismatch"],
+      "rollback_refs": ["procedure.rollback"],
+      "source_refs": ["repo://example/operations/promotion.md"],
+      "instructional_refs": ["lesson.promotion"],
+      "applicability": ["release"],
+      "negative_boundaries": ["Do not promote a candidate that differs from the accepted identity."]
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "scenario.full_release",
+      "title": "Full release",
+      "outcome": "The accepted service version is released and verified.",
+      "operation_ids": ["operation.inventory", "operation.backup", "operation.validate", "operation.promote"],
+      "required_inputs": ["input.release_request", "input.release_candidate"],
+      "audience": ["release_manager", "operations_engineer"]
+    },
+    {
+      "id": "scenario.recovery_preparation",
+      "title": "Recovery preparation only",
+      "outcome": "A verified rollback path exists without performing a release.",
+      "operation_ids": ["operation.backup"],
+      "required_inputs": ["input.release_request"],
+      "audience": ["operations_engineer"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirai-graph",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "description": "An evolutionary graph operating model for managing the growth of complex systems.",
   "license": "MIT",
@@ -12,47 +12,14 @@
   "exports": {
     "./project-technology": "./packages/project-technology/index.js"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zabarov/mirai-graph.git"
-  },
-  "keywords": [
-    "graph",
-    "knowledge-graph",
-    "governance",
-    "complex-systems",
-    "context-engineering",
-    "ai-assisted-work"
-  ],
-  "author": "Rim Zabarov",
-  "files": [
-    "README.md",
-    "CHANGELOG.md",
-    "ROADMAP.md",
-    "LICENSE",
-    "LICENSE-DOCS",
-    "CITATION.cff",
-    "docs",
-    "standard",
-    "schemas",
-    "benchmarks",
-    "examples",
-    "packages",
-    "profiles",
-    "pilots",
-    "playground",
-    "publications",
-    "releases",
-    "templates",
-    ".github"
-  ],
   "scripts": {
-    "pretest": "npm run test:project-technology && npm run test:context-traversal && npm run test:project-continuity && npm run test:artifact-releases && npm run validate:project-technology-schemas",
+    "pretest": "npm run test:project-technology && npm run test:context-traversal && npm run test:project-continuity && npm run test:artifact-releases && npm run test:technology-courses && npm run validate:project-technology-schemas",
     "test:project-technology": "node packages/cli/validate-project-technology.js",
     "test:context-traversal": "node packages/cli/validate-context-traversal.js",
     "test:project-continuity": "node packages/cli/validate-project-continuity.js",
     "test:artifact-releases": "node packages/cli/validate-artifact-releases.js",
-    "validate:project-technology-schemas": "node -e \"const fs=require('fs'); for (const file of ['project-technology-extension.schema.json','project-technology-target-export.schema.json','context-traversal-receipt.schema.json','context-pack.schema.json']) JSON.parse(fs.readFileSync('schemas/'+file))\"",
+    "test:technology-courses": "node packages/cli/validate-technology-course.js",
+    "validate:project-technology-schemas": "node -e \"const fs=require('fs'); for (const file of ['project-technology-extension.schema.json','project-technology-target-export.schema.json','context-traversal-receipt.schema.json','context-pack.schema.json','executable-technology.schema.json','technology-course-pack.schema.json']) JSON.parse(fs.readFileSync('schemas/'+file))\"",
     "validate:graph-manifest": "node packages/cli/validate-graph-manifest-migration.js",
     "validate:minimal": "node packages/cli/validate-mirai-graph.js examples/minimal-graph",
     "validate:benchmark": "node packages/cli/validate-mirai-graph.js benchmarks/synthetic-context-reduction-v0",
@@ -123,5 +90,39 @@
     "validate:playground-report": "npm run --silent playground:report >/tmp/mirai-graph-playground-report.md && diff -u playground/demo-report.md /tmp/mirai-graph-playground-report.md && rg 'transition explanation|Instrumentation|Multi-source feedback|Baseline Comparison|baseline comparison' playground/demo-report.md",
     "test": "npm run validate:graph-manifest && npm run validate:minimal && npm run validate:benchmark && npm run validate:seed && npm run validate:profiles && npm run validate:ai-employee && npm run validate:skill-runtime && npm run validate:managed-project && npm run validate:implementation-control && npm run validate:implementation-control-cycles && npm run validate:launch-record && npm run validate:process-transition && npm run validate:process-transition-report && npm run validate:process-control && npm run validate:technology-quality-feedback && npm run validate:instrumentation-layer && npm run validate:instrumentation-report && npm run validate:dynamic-episodes && npm run validate:dynamic-episode-report && npm run validate:semantic-intent-resolution && npm run validate:goal-vector-quality-control && npm run validate:dna-alignment && npm run validate:work-state && npm run validate:risk-control && npm run validate:source-boundary && npm run validate:organization-governance && npm run validate:societal-governance && npm run validate:character-layer && npm run validate:character-layer-integration && npm run validate:model-portability-evidence && npm run validate:character-layer-readiness && npm run validate:templates && npm run validate:adopter-workflow && npm run validate:self-service-onboarding && npm run validate:init-fixtures && npm run validate:bootstrap-fixtures && npm run validate:release-state && npm run validate:mirai-graph-compat && npm run validate:cli-unified && npm run validate:pilots && npm run validate:context-packs && npm run validate:profile-results && npm run validate:routing-control && npm run seed:preview && npm run context:generate && npm run playground:demo && npm run playground:report && npm run readiness:benchmark && npm run benchmark:synthetic && npm run validate:baseline-comparison && npm run validate:markdown-report && npm run validate:playground-demo && npm run validate:playground-report && npm run test:negative && npm run test:character-layer-semantic-negative && npm run test:societal-governance-negative && npm run test:process-transition-negative && npm run test:technology-quality-feedback-negative && npm run test:instrumentation-layer-negative && npm run test:dynamic-episodes-negative && npm run test:semantic-intent-resolution-negative && npm run test:goal-vector-quality-control-negative",
     "release:check": "npm test && git diff --check"
-  }
-}
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zabarov/mirai-graph.git"
+  },
+  "keywords": [
+    "graph",
+    "knowledge-graph",
+    "governance",
+    "complex-systems",
+    "context-engineering",
+    "ai-assisted-work"
+  ],
+  "author": "Rim Zabarov",
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "LICENSE",
+    "LICENSE-DOCS",
+    "CITATION.cff",
+    "docs",
+    "standard",
+    "schemas",
+    "benchmarks",
+    "examples",
+    "packages",
+    "profiles",
+    "pilots",
+    "playground",
+    "publications",
+    "releases",
+    "templates",
+    ".github"
+  ]
+}

package/packages/cli/mirai-graph.js

@@ -25,7 +25,7 @@ function usage() {
   console.error("  mirai-graph report playground");
   console.error("  mirai-graph release state [--markdown] [--require-git-tag] [--require-github-release] [--require-npm-published]");
   console.error("  mirai-graph technology <explain|status|plan|verify|context> [repository] [options]");
-  console.error("  mirai-graph technology <enable|sync|connect|disconnect|provide|disable|repair|artifact> [repository] [options] [--apply]");
+  console.error("  mirai-graph technology <enable|sync|connect|disconnect|provide|disable|repair|artifact|course> [repository] [options] [--apply]");
   console.error("");
   console.error("Boundary:");
   console.error("  Reports explain validation decisions. They do not authorize canonical updates.");

package/packages/cli/project-technology.js

@@ -23,20 +23,28 @@ function usage() {
   console.error("           artifact release <repo> --input <path> --matter-id <id> --direction inbound|internal|outbound [--parent-release <id>] [--client-note <text>] [--create-export] [--apply]");
   console.error("           artifact compare <repo> --matter-id <id> --base-release <id> --target-release <id>");
   console.error("           artifact verify <repo> --matter-id <id> --release-id <id>");
+  console.error("Courses: course compile <repo> --technology <file> [--scenario <id>] [--audience <id>]");
+  console.error("         course verify <repo> --course-pack <file>");
+  console.error("         course reconcile <repo> --course-pack <file> --projection <file>");
 }
 
 function parse(argv) {
   if (!argv.length) return null;
   const operation = argv.shift();
   let artifactAction = null;
+  let courseAction = null;
   if (operation === "artifact") {
     artifactAction = argv.shift() || null;
     if (!new Set(["inspect", "release", "compare", "verify"]).has(artifactAction)) throw new Error("artifact requires inspect, release, compare or verify");
   }
+  if (operation === "course") {
+    courseAction = argv.shift() || null;
+    if (!new Set(["compile", "verify", "reconcile"]).has(courseAction)) throw new Error("course requires compile, verify or reconcile");
+  }
   let repository = ".";
   if (argv[0] && !argv[0].startsWith("--")) repository = argv.shift();
   const options = {};
-  const values = new Set(["--task", "--source", "--target-id", "--semantic-digest", "--provider-revision", "--max-objects", "--phase", "--input", "--select", "--selection", "--packet", "--evidence", "--selector", "--reason", "--confidence", "--context-budget", "--boundary", "--expected-graph-digest", "--receipt-digest", "--state-root", "--matter-id", "--direction", "--artifact-root", "--release-date", "--release-id", "--parent-release", "--base-release", "--target-release", "--client-note"]);
+  const values = new Set(["--task", "--source", "--target-id", "--semantic-digest", "--provider-revision", "--max-objects", "--phase", "--input", "--select", "--selection", "--packet", "--evidence", "--selector", "--reason", "--confidence", "--context-budget", "--boundary", "--expected-graph-digest", "--receipt-digest", "--state-root", "--matter-id", "--direction", "--artifact-root", "--release-date", "--release-id", "--parent-release", "--base-release", "--target-release", "--client-note", "--technology", "--scenario", "--audience", "--course-pack", "--projection"]);
   const flags = new Set(["--apply", "--refresh-binding", "--significant-work", "--create-export"]);
   const names = {
     "--task": "task", "--source": "source", "--target-id": "targetId",
@@ -54,6 +62,8 @@ function parse(argv) {
     "--parent-release": "parentReleaseIds", "--base-release": "baseReleaseId",
     "--target-release": "targetReleaseId", "--client-note": "clientNote",
     "--create-export": "createExport",
+    "--technology": "technologyFile", "--scenario": "scenarioIds",
+    "--audience": "audience", "--course-pack": "coursePackFile", "--projection": "projectionFile",
   };
   while (argv.length) {
     const token = argv.shift();
@@ -63,10 +73,12 @@ function parse(argv) {
       const value = argv.shift();
       if (token === "--select") options.selectedIds = [...(options.selectedIds || []), value];
       else if (token === "--parent-release") options.parentReleaseIds = [...(options.parentReleaseIds || []), value];
+      else if (token === "--scenario") options.scenarioIds = [...(options.scenarioIds || []), value];
       else options[names[token]] = value;
     } else throw new Error(`unsupported argument ${token}`);
   }
   if (artifactAction) options.artifactAction = artifactAction;
+  if (courseAction) options.courseAction = courseAction;
   return { operation, repository: path.resolve(repository), options };
 }
 

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";
@@ -790,6 +791,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 +809,7 @@ module.exports = {
   compareArtifactReleases: artifacts.compareArtifactReleases,
   connect,
   compileContext: traversal.compileContext,
+  compileTechnologyCourse: technologyCourse.compileTechnologyCourse,
   context,
   createArtifactRelease: artifacts.createArtifactRelease,
   discoverContext: traversal.discoverContext,
@@ -820,10 +823,12 @@ module.exports = {
   inventory,
   inspectArtifactBundle: artifacts.inspectArtifactBundle,
   normalizeExecutionContract,
+  normalizeTechnology: technologyCourse.normalizeTechnology,
   continuity,
   plan,
   provide,
   readExport,
+  reconcileTechnologyCourse: technologyCourse.reconcileTechnologyCourse,
   repair,
   sha256,
   status,
@@ -831,5 +836,6 @@ module.exports = {
   targetBindingStatus,
   verify,
   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,
+};

package/schemas/executable-technology.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.org/schemas/executable-technology.schema.json",
+  "title": "Mirai Graph Executable Technology",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "title", "owner", "outcome", "lifecycle", "version", "source_refs", "operations", "scenarios"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "id": { "$ref": "#/$defs/id" },
+    "title": { "$ref": "#/$defs/text" },
+    "owner": { "$ref": "#/$defs/id" },
+    "outcome": { "$ref": "#/$defs/text" },
+    "lifecycle": { "enum": ["reviewed", "accepted", "active"] },
+    "version": { "$ref": "#/$defs/text" },
+    "source_refs": { "$ref": "#/$defs/nonEmptyIds" },
+    "projection_refs": { "$ref": "#/$defs/ids" },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/operation" }
+    },
+    "scenarios": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/scenario" }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@?=+*\\-]{1,255}$" },
+    "text": { "type": "string", "minLength": 1 },
+    "ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "nonEmptyIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "summary", "owner", "capability_ref", "output_refs", "check_refs", "source_refs"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "$ref": "#/$defs/text" },
+        "summary": { "$ref": "#/$defs/text" },
+        "owner": { "$ref": "#/$defs/id" },
+        "capability_ref": { "$ref": "#/$defs/id" },
+        "prerequisites": { "$ref": "#/$defs/ids" },
+        "input_refs": { "$ref": "#/$defs/ids" },
+        "output_refs": { "$ref": "#/$defs/nonEmptyIds" },
+        "check_refs": { "$ref": "#/$defs/nonEmptyIds" },
+        "stop_condition_refs": { "$ref": "#/$defs/ids" },
+        "rollback_refs": { "$ref": "#/$defs/ids" },
+        "source_refs": { "$ref": "#/$defs/nonEmptyIds" },
+        "instructional_refs": { "$ref": "#/$defs/ids" },
+        "applicability": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } },
+        "negative_boundaries": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }
+      }
+    },
+    "scenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "outcome", "operation_ids"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "$ref": "#/$defs/text" },
+        "outcome": { "$ref": "#/$defs/text" },
+        "operation_ids": { "$ref": "#/$defs/nonEmptyIds" },
+        "required_inputs": { "$ref": "#/$defs/ids" },
+        "audience": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }
+      }
+    }
+  }
+}

package/schemas/technology-course-pack.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.org/schemas/technology-course-pack.schema.json",
+  "title": "Mirai Graph Technology Course Pack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "technology_id", "technology_title", "technology_outcome", "technology_version", "technology_digest", "audience", "scenario_ids", "source_refs", "source_revisions", "scenarios", "sections", "exercises", "checks", "omissions", "limitations", "course_pack_digest"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "technology_id": { "$ref": "#/$defs/id" },
+    "technology_title": { "type": "string", "minLength": 1 },
+    "technology_outcome": { "type": "string", "minLength": 1 },
+    "technology_version": { "type": "string", "minLength": 1 },
+    "technology_digest": { "$ref": "#/$defs/digest" },
+    "audience": { "$ref": "#/$defs/id" },
+    "scenario_ids": { "$ref": "#/$defs/nonEmptyIds" },
+    "source_refs": { "$ref": "#/$defs/nonEmptyIds" },
+    "source_revisions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } },
+    "scenarios": { "type": "array", "minItems": 1, "items": { "type": "object" } },
+    "sections": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["order", "technology_node_id", "title", "summary", "owner", "capability_ref", "prerequisite_ids", "input_refs", "output_refs", "check_refs", "stop_condition_refs", "rollback_refs", "source_refs", "instructional_refs"],
+        "properties": {
+          "order": { "type": "integer", "minimum": 1 },
+          "technology_node_id": { "$ref": "#/$defs/id" },
+          "title": { "type": "string", "minLength": 1 },
+          "summary": { "type": "string", "minLength": 1 },
+          "owner": { "$ref": "#/$defs/id" },
+          "capability_ref": { "$ref": "#/$defs/id" },
+          "prerequisite_ids": { "$ref": "#/$defs/ids" },
+          "input_refs": { "$ref": "#/$defs/ids" },
+          "output_refs": { "$ref": "#/$defs/nonEmptyIds" },
+          "check_refs": { "$ref": "#/$defs/nonEmptyIds" },
+          "stop_condition_refs": { "$ref": "#/$defs/ids" },
+          "rollback_refs": { "$ref": "#/$defs/ids" },
+          "source_refs": { "$ref": "#/$defs/nonEmptyIds" },
+          "instructional_refs": { "$ref": "#/$defs/ids" }
+        }
+      }
+    },
+    "exercises": { "type": "array" },
+    "checks": { "$ref": "#/$defs/nonEmptyIds" },
+    "omissions": { "type": "array" },
+    "limitations": { "type": "array" },
+    "course_pack_digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/@?=+*\\-]{1,255}$" },
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "nonEmptyIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } }
+  }
+}

package/standard/project-technology.md

@@ -1,6 +1,6 @@
 # Project Technology
 
-Status: 1.3 stable standard; activation contract remains 1.0.0
+Status: 1.4 stable standard; activation contract remains 1.0.0
 
 Project Technology is the shared executable mechanism of Mirai Graph. It is
 not a profile, a second graph or a source of domain methodology.
@@ -19,6 +19,35 @@ Each graph keeps its own objects and relations. Project Technology only
 standardizes safe inventory, task context, accepted-target binding, freshness
 and verification.
 
+## Executable Technologies And Course Projections
+
+An executable technology is an accepted graph of reusable operations and
+user-facing scenarios. It is suitable for a long method that has both an
+end-to-end path and independently useful parts. Each operation binds its owner,
+capability, prerequisites, inputs, outputs, checks, stop conditions, rollback
+and exact raw source references.
+
+A scenario names an outcome and selects the operations needed to reach it.
+Project Technology calculates prerequisite closure, so a course or executor
+cannot silently omit a required safety step.
+
+```bash
+mirai-graph technology course compile . --technology graph/specs/technology.json
+mirai-graph technology course compile . --technology graph/specs/technology.json --scenario scenario.recovery
+mirai-graph technology course verify . --course-pack course-pack.json
+mirai-graph technology course reconcile . --course-pack course-pack.json --projection edited-course.json
+```
+
+The JavaScript API exposes `compileTechnologyCourse`,
+`verifyTechnologyCourse` and `reconcileTechnologyCourse`.
+
+A Course Pack is hash-bound to the normalized technology, chosen scenarios,
+sources and revisions. It may be rendered into a document, learning system or
+documentation site. It remains a projection: editorial changes may be routed
+to the documentation owner, while changed prerequisites, owners, checks, stop
+conditions, rollback or scope become semantic proposals. Reconciliation never
+writes them into the accepted technology automatically.
+
 ## Immutable Artifact Releases
 
 Project Technology can preserve versioned file bundles without turning their