mirai-graph 1.1.0 → 1.2.0

package/packages/project-technology/context-traversal.js

@@ -19,7 +19,13 @@ const SUPPORTED_RELATIONS = new Set([
   "conflicts_with",
 ]);
 const TERMINAL_KINDS = new Set(["resource", "source", "check", "gate", "constraint"]);
-const ACTIVE_READINESS = new Set(["ready", "accepted", "implemented", "validated", "operating", "evolving"]);
+const ACTIVE_READINESS = new Set(["ready", "accepted", "implemented", "validated", "operating", "evolving", "pilot"]);
+const LEGACY_ACTIVE_READINESS = new Set([
+  "r3_structured", "r3_specified", "r4_integrated", "r4_validated",
+  "r4_executable", "r4_evidence_ready", "a4_validated_projection",
+  "a6_accepted_local_candidate", "t5_implementation_ready",
+  "active_controlled_paid_test",
+]);
 const BLOCKING_READINESS = new Set(["blocked", "deprecated", "stale", "retired", "superseded"]);
 const SECRET_PARTS = [".env", "credential", "secret", "token", "password", "cookie", "private-key", "id_rsa", ".pem", ".p12"];
 
@@ -53,7 +59,31 @@ function gitBlob(repo, relative) {
   return completed.status === 0 ? completed.stdout : null;
 }
 
+function trackedState(repo) {
+  const trackedRun = spawnSync("git", ["ls-files", "-z"], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  const dirtyRun = spawnSync("git", ["diff", "--name-only", "-z", "HEAD", "--"], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return {
+    hasGit: Boolean(git(repo, "rev-parse", "--is-inside-work-tree")),
+    tracked: new Set(trackedRun.status === 0 ? trackedRun.stdout.split("\0").filter(Boolean) : []),
+    dirty: new Set(dirtyRun.status === 0 ? dirtyRun.stdout.split("\0").filter(Boolean) : []),
+  };
+}
+
+function graphBlob(graph, relative) {
+  if (!graph.hasGit) {
+    const absolute = path.join(graph.repo, relative);
+    return fs.existsSync(absolute) && !fs.lstatSync(absolute).isSymbolicLink() && fs.statSync(absolute).isFile() ? fs.readFileSync(absolute) : null;
+  }
+  if (!graph.tracked?.has(relative) || graph.dirty?.has(relative)) return null;
+  if (!graph.blobCache.has(relative)) graph.blobCache.set(relative, gitBlob(graph.repo, relative));
+  return graph.blobCache.get(relative);
+}
+
 function revisionBound(repo, relative) {
+  if (!git(repo, "rev-parse", "--is-inside-work-tree")) {
+    const absolute = path.join(repo, relative);
+    return fs.existsSync(absolute) && !fs.lstatSync(absolute).isSymbolicLink() && fs.statSync(absolute).isFile();
+  }
   if (!gitBlob(repo, relative)) return false;
   return spawnSync("git", ["diff", "--quiet", "HEAD", "--", relative], { cwd: repo }).status === 0;
 }
@@ -72,6 +102,54 @@ function safeRef(value) {
   return safeRelative(value);
 }
 
+const LEGACY_RELATION_TYPES = new Map([
+  ["implements", { type: "contains" }],
+  ["has_capability", { type: "contains" }],
+  ["uses_process", { type: "contains" }],
+  ["includes", { type: "contains" }],
+  ["member_of", { type: "contains", reverse: true }],
+  ["refines", { type: "specializes" }],
+  ["depends_on", { type: "requires" }],
+  ["requires_current_source_check", { type: "requires" }],
+  ["requires_gate", { type: "validated_by" }],
+  ["requires_quality_gate", { type: "validated_by" }],
+  ["tested_by_scenario", { type: "validated_by" }],
+  ["validates", { type: "validated_by", reverse: true }],
+  ["assessed_by", { type: "validated_by" }],
+  ["blocked_without_gate", { type: "validated_by" }],
+  ["conforms_to", { type: "governed_by" }],
+  ["constrained_by", { type: "governed_by" }],
+  ["evidenced_by", { type: "documented_by" }],
+]);
+
+function normalizeObject(value) {
+  const normalized = { ...value };
+  if (!normalized.kind && normalized.type) normalized.kind = normalized.type;
+  if (!normalized.readiness) normalized.readiness = normalized.lifecycle || normalized.status || "accepted";
+  if (!value.kind) delete normalized.type;
+  return normalized;
+}
+
+function normalizeRelation(value) {
+  const legacyType = value.type || value.relation_type;
+  const mapping = LEGACY_RELATION_TYPES.get(legacyType) || { type: legacyType };
+  let source = value.source || value.from;
+  let target = value.target || value.to;
+  if (mapping.reverse) [source, target] = [target, source];
+  const normalized = {
+    ...value,
+    type: mapping.type,
+    source,
+    target,
+    readiness: value.readiness || value.status || value.lifecycle || "accepted",
+  };
+  delete normalized.from;
+  delete normalized.to;
+  delete normalized.relation_type;
+  delete normalized.status;
+  return normalized;
+}
+
 function loadEntry(repo, relative, kind, output, visited = new Set()) {
   if (!safeRelative(relative) || visited.has(relative)) return;
   visited.add(relative);
@@ -112,14 +190,15 @@ function readGraph(repoArg) {
   for (const relative of manifest.graph?.relations || []) loadEntry(repo, relative, "relations", output);
   const objects = new Map();
   for (const record of output.objects) {
-    const id = String(record.value.id || "").trim();
+    const normalized = normalizeObject(record.value);
+    const id = String(normalized.id || "").trim();
     if (!id || objects.has(id)) { output.blockers.push(id ? "duplicate_object_id" : "object_id_missing"); continue; }
-    objects.set(id, record);
+    objects.set(id, { ...record, value: normalized });
   }
   const relations = [];
   const relationIds = new Set();
   for (const record of output.relations) {
-    const relation = record.value;
+    const relation = normalizeRelation(record.value);
     const id = String(relation.id || "").trim();
     if (!id || relationIds.has(id)) { output.blockers.push(id ? "duplicate_relation_id" : "relation_id_missing"); continue; }
     relationIds.add(id);
@@ -127,18 +206,25 @@ function readGraph(repoArg) {
     if (!objects.has(relation.source) || !objects.has(relation.target)) { output.blockers.push("relation_endpoint_missing"); continue; }
     relations.push({ ...relation, _record: record });
   }
-  const revision = git(repo, "rev-parse", "HEAD") || null;
-  for (const relative of unique([
+  const state = trackedState(repo);
+  const graphSources = unique([
     "graph.json",
     ...[...objects.values()].map((record) => record.relative),
     ...relations.map((relation) => relation._record.relative),
-  ])) if (!revisionBound(repo, relative)) output.blockers.push("graph_source_not_revision_bound");
-  const graphPayload = {
+  ]);
+  const newContentBoundGraph = state.hasGit
+    && graphSources.length > 0
+    && graphSources.every((relative) => !state.tracked.has(relative))
+    && graphSources.every((relative) => !state.dirty.has(relative));
+  for (const relative of graphSources) if (state.hasGit && !newContentBoundGraph && (!state.tracked.has(relative) || state.dirty.has(relative))) output.blockers.push("graph_source_not_revision_bound");
+  const gitRevision = !newContentBoundGraph ? git(repo, "rev-parse", "HEAD") || null : null;
+  const graphPayloadBase = {
     manifest: { id: manifest.id, scope: manifest.scope, profiles: manifest.profiles, graph: manifest.graph },
     objects: [...objects.values()].map((record) => record.value).sort((a, b) => a.id.localeCompare(b.id)),
     relations: relations.map(({ _record, ...relation }) => relation).sort((a, b) => a.id.localeCompare(b.id)),
-    revision,
   };
+  const revision = gitRevision || `content:${digest(graphPayloadBase).slice(7)}`;
+  const graphPayload = { ...graphPayloadBase, revision };
   return {
     repo,
     manifest,
@@ -146,6 +232,10 @@ function readGraph(repoArg) {
     graphDigest: digest(graphPayload),
     objects,
     relations,
+    tracked: state.tracked,
+    dirty: state.dirty,
+    hasGit: state.hasGit,
+    blobCache: new Map(),
     blockers: unique(output.blockers),
   };
 }
@@ -158,6 +248,11 @@ function readinessOf(object) {
   return String(object.readiness || object.lifecycle || object.status || "unknown").toLowerCase();
 }
 
+function activeReadiness(value) {
+  const normalized = String(value || "").toLowerCase();
+  return ACTIVE_READINESS.has(normalized) || LEGACY_ACTIVE_READINESS.has(normalized);
+}
+
 function outgoing(graph, id) {
   return graph.relations.filter((relation) => relation.source === id);
 }
@@ -181,7 +276,7 @@ function sourcePassport(graph, record, value) {
     if (!fs.existsSync(absolute) || fs.lstatSync(absolute).isSymbolicLink() || !fs.statSync(absolute).isFile()) {
       return { ref, availability: "unavailable", revision: graph.revision, sha256: null };
     }
-    const blob = gitBlob(graph.repo, ref);
+    const blob = graphBlob(graph, ref);
     return { ref, availability: blob ? "available" : "unbound", revision: graph.revision, sha256: digest(blob || fs.readFileSync(absolute)) };
   }).concat([{ ref: record.relative, availability: "available", revision: graph.revision, sha256: record.sha256 }]);
 }
@@ -446,7 +541,7 @@ function compileContext(repository, traversalReceipt, selectionInput, options =
   for (const id of closure.ids) {
     const passport = nodePassport(graph, id);
     if (!passport) continue;
-    if (!ACTIVE_READINESS.has(passport.readiness)) blockers.push(`context_node_${passport.readiness}`);
+    if (!activeReadiness(passport.readiness)) blockers.push(`context_node_${passport.readiness}`);
     if (passport.omitted_source_ref_count > 0) blockers.push("unsafe_source_reference_omitted");
     if (passport.sensitive_metadata_detected) blockers.push("context_node_sensitive_metadata");
     if (passport.expansion_policy === "terminal" && passport.expandable) blockers.push("terminal_node_has_children");
@@ -468,7 +563,7 @@ function compileContext(repository, traversalReceipt, selectionInput, options =
   const includedIds = [...included].sort();
   const includedNodes = includedIds.map((id) => nodePassport(graph, id)).filter(Boolean);
   const includedRelations = graph.relations.filter((relation) => included.has(relation.source) && included.has(relation.target)).map(relationPassport).sort((a, b) => a.id.localeCompare(b.id));
-  for (const relation of includedRelations) if (!ACTIVE_READINESS.has(String(relation.readiness).toLowerCase())) blockers.push(`context_relation_${String(relation.readiness).toLowerCase()}`);
+  for (const relation of includedRelations) if (!activeReadiness(relation.readiness)) blockers.push(`context_relation_${String(relation.readiness).toLowerCase()}`);
   const terminalSourceMap = new Map();
   for (const node of includedNodes.filter((item) => !item.expandable || ["resource", "source"].includes(item.kind))) {
     for (const source of node.source_refs) {
@@ -559,7 +654,7 @@ function verifyContext(repository, contextPack, usageEvidence, options = {}) {
     const absolute = path.join(graph.repo, source.ref);
     if (!fs.existsSync(absolute) || fs.lstatSync(absolute).isSymbolicLink() || !fs.statSync(absolute).isFile()) blockers.push("context_pack_source_unavailable");
     else {
-      const blob = gitBlob(graph.repo, source.ref);
+      const blob = graphBlob(graph, source.ref);
       if (!blob || !revisionBound(graph.repo, source.ref) || digest(blob) !== source.sha256 || source.revision !== graph.revision) blockers.push("context_pack_source_revision_or_digest_mismatch");
     }
   }

package/packages/project-technology/continuity.js

@@ -0,0 +1,414 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+// Manifest refs are portable POSIX-style identifiers even when the host is Windows.
+// Convert them to host paths only when joining with the repository root.
+const CONTINUITY_FILE = "graph/specs/project-continuity.json";
+const CONTEXT_PROJECTION_FILE = "graph/docs/project-context.md";
+const BOUNDARIES = new Set(["task_start", "stage_complete", "task_complete"]);
+const SECRET_PATTERN = /(?:ghp_|github_pat_|bearer\s+)[a-z0-9_-]{12,}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|(?:^|["'\s/])\.env(?:["'\s/]|$)|(?:password|token|secret|cookie)\s*[:=]/i;
+const PRIVATE_PATH_PATTERN = /(?:^|[^A-Za-z0-9._-])source[\\/](?:private|memory|workflow|handoff)(?:[\\/]|$)/i;
+const HOST_PATH_PATTERN = /(?:^|["'\s])(?:\/[Uu]sers\/[^/\s]+|\/home\/[^/\s]+|[A-Za-z]:\\Users\\[^\\\s]+)/;
+
+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 digest(value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(typeof value === "string" ? value : canonicalBytes(value));
+  return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function safeId(value) {
+  return String(value || "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120);
+}
+
+function safeText(value, limit = 2000) {
+  const text = String(value || "").trim();
+  if (!text || text.length > limit || SECRET_PATTERN.test(text) || PRIVATE_PATH_PATTERN.test(text) || HOST_PATH_PATTERN.test(text)) return null;
+  return text;
+}
+
+function safeRef(value) {
+  const text = safeText(value, 512);
+  if (!text || path.isAbsolute(text) || text.split(/[\\/]+/).includes("..")) return null;
+  return text;
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")); } catch (_) { return fallback; }
+}
+
+function atomicWrite(file, bytes) {
+  const content = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes));
+  if (fs.existsSync(file) && fs.readFileSync(file).equals(content)) return false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`);
+  fs.writeFileSync(temp, content, { mode: 0o600 });
+  fs.renameSync(temp, file);
+  return true;
+}
+
+function graphIdentity(repo, manifest) {
+  return safeId(manifest?.id || path.basename(repo)) || digest(repo).slice(7, 23);
+}
+
+function stateRoot(repo, manifest, options = {}) {
+  const explicit = options.stateRoot || process.env.MIRAI_GRAPH_STATE_ROOT;
+  let root = explicit ? path.resolve(explicit) : null;
+  if (!root && process.platform === "win32") root = path.join(process.env.LOCALAPPDATA || os.tmpdir(), "mirai-graph", "project-technology");
+  if (!root && process.platform === "darwin") root = path.join(os.homedir(), "Library", "Application Support", "mirai-graph", "project-technology");
+  if (!root) root = path.join(process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), "mirai-graph", "project-technology");
+  return path.join(root, graphIdentity(repo, manifest));
+}
+
+function listFiles(root) {
+  if (!fs.existsSync(root)) return [];
+  const output = [];
+  const visit = (dir) => {
+    for (const name of fs.readdirSync(dir).sort()) {
+      const file = path.join(dir, name);
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) visit(file);
+      else if (stat.isFile()) output.push(file);
+    }
+  };
+  visit(root);
+  return output;
+}
+
+function graphDigest(repo) {
+  const specs = path.join(repo, "graph", "specs");
+  const entries = [];
+  const manifest = path.join(repo, "graph.json");
+  if (fs.existsSync(manifest)) entries.push({ path: "graph.json", sha256: digest(fs.readFileSync(manifest)) });
+  for (const file of listFiles(specs)) entries.push({
+    path: path.relative(repo, file).split(path.sep).join("/"),
+    sha256: digest(fs.readFileSync(file)),
+  });
+  return digest(entries);
+}
+
+function continuityPolicy(manifest) {
+  return manifest?.extensions?.["mirai.project_technology"]?.continuity_policy || null;
+}
+
+function readObjects(repo) {
+  const payload = readJson(path.join(repo, CONTINUITY_FILE), { schema_version: "1.0.0", objects: [] });
+  return payload && payload.schema_version === "1.0.0" && Array.isArray(payload.objects) ? payload.objects : [];
+}
+
+function latestReceipt(repo, manifest, options = {}) {
+  const root = stateRoot(repo, manifest, options);
+  const pointer = readJson(path.join(root, "latest-receipt.json"));
+  if (!pointer?.receipt_ref) return null;
+  const file = path.join(root, pointer.receipt_ref);
+  const receipt = readJson(file);
+  if (!receipt || receipt.receipt_digest !== digest(Object.fromEntries(Object.entries(receipt).filter(([key]) => key !== "receipt_digest")))) return null;
+  return receipt;
+}
+
+function status(repo, manifest, options = {}) {
+  const policy = continuityPolicy(manifest);
+  const currentGraphDigest = graphDigest(repo);
+  const receipt = latestReceipt(repo, manifest, options);
+  let freshness = "not_configured";
+  if (policy === "task_boundary") freshness = !receipt ? "missing" : receipt.current_graph_digest === currentGraphDigest ? "current" : "stale";
+  return {
+    policy,
+    authority: "graph/specs",
+    host_state_ref: `host-local://${graphIdentity(repo, manifest)}`,
+    graph_digest: currentGraphDigest,
+    freshness,
+    terminal_receipt: receipt ? {
+      receipt_digest: receipt.receipt_digest,
+      boundary: receipt.boundary,
+      task_digest: receipt.task_digest,
+      current_graph_digest: receipt.current_graph_digest,
+    } : null,
+  };
+}
+
+function normalizeEvidence(input) {
+  const blockers = [];
+  if (!input || typeof input !== "object" || Array.isArray(input)) return { evidence: {}, blockers: ["continuity_evidence_missing"] };
+  if (SECRET_PATTERN.test(JSON.stringify(input)) || PRIVATE_PATH_PATTERN.test(JSON.stringify(input)) || HOST_PATH_PATTERN.test(JSON.stringify(input))) blockers.push("continuity_sensitive_or_host_data_forbidden");
+  const taskDigest = String(input.task_digest || "").toLowerCase();
+  if (!/^sha256:[0-9a-f]{64}$/.test(taskDigest)) blockers.push("continuity_task_digest_invalid");
+  const outcome = safeText(input.outcome, 1200);
+  if (!outcome) blockers.push("continuity_outcome_missing_or_unsafe");
+  const requirementRefs = unique((input.requirement_refs || []).map(safeRef));
+  const evidenceRefs = unique((input.evidence_refs || []).map(safeRef));
+  const checks = (Array.isArray(input.checks) ? input.checks : []).map((item) => {
+    if (!item || typeof item !== "object") return null;
+    const id = safeRef(item.id); const verdict = String(item.verdict || "").toLowerCase(); const evidenceRef = safeRef(item.evidence_ref);
+    if (!id || !["pass", "fail", "blocked"].includes(verdict) || !evidenceRef) return null;
+    return { id, verdict, evidence_ref: evidenceRef };
+  }).filter(Boolean).sort((a, b) => a.id.localeCompare(b.id));
+  if (!requirementRefs.length) blockers.push("continuity_requirement_refs_missing");
+  if (!evidenceRefs.length || !checks.length) blockers.push("continuity_verification_missing");
+  if (checks.some((item) => item.verdict !== "pass")) blockers.push("continuity_result_not_verified");
+  const changedSurfaces = unique((input.changed_surfaces || []).map(safeRef));
+  const caseSignature = safeRef(input.case_signature || "");
+  const methodCandidate = safeText(input.method_candidate || "", 1200);
+  const decisions = (Array.isArray(input.decisions) ? input.decisions : []).map((item) => {
+    if (!item || typeof item !== "object") return null;
+    const summary = safeText(item.summary, 1200);
+    if (!summary) return null;
+    return {
+      summary,
+      changes_architecture: item.changes_architecture !== false,
+      owner_ref: safeRef(item.owner_ref || "") || null,
+      approval_ref: safeRef(item.approval_ref || "") || null,
+    };
+  }).filter(Boolean);
+  return {
+    evidence: {
+      task_digest: taskDigest,
+      outcome,
+      requirement_refs: requirementRefs,
+      evidence_refs: evidenceRefs,
+      checks,
+      changed_surfaces: changedSurfaces,
+      case_signature: caseSignature || digest({ outcome, requirementRefs }).slice(7, 31),
+      method_candidate: methodCandidate,
+      decisions,
+      source_revision: safeRef(input.source_revision || "") || null,
+    },
+    blockers: unique(blockers),
+  };
+}
+
+function buildCandidates(existing, evidence, boundary) {
+  const signature = digest({ task: evidence.task_digest, outcome: evidence.outcome, requirements: evidence.requirement_refs });
+  const suffix = signature.slice(7, 23);
+  const promoted = [
+    {
+      id: `evidence.continuity.${suffix}`,
+      kind: "evidence",
+      title: `Verified task result ${suffix}`,
+      summary: evidence.outcome,
+      readiness: "accepted",
+      profile: "project_management",
+      requirement_refs: evidence.requirement_refs,
+      evidence_refs: evidence.evidence_refs,
+      checks: evidence.checks,
+      changed_surfaces: evidence.changed_surfaces,
+      task_digest: evidence.task_digest,
+      source_revision: evidence.source_revision,
+      provenance_digest: signature,
+    },
+    {
+      id: `regression_case.continuity.${suffix}`,
+      kind: "regression_case",
+      title: `Verified reusable case ${suffix}`,
+      summary: evidence.outcome,
+      readiness: "accepted",
+      profile: "implementation_control",
+      case_signature: evidence.case_signature,
+      requirement_refs: evidence.requirement_refs,
+      evidence_refs: [`evidence.continuity.${suffix}`],
+      task_digest: evidence.task_digest,
+      boundary,
+      provenance_digest: signature,
+    },
+  ];
+  const proposals = evidence.decisions.map((decision, index) => ({
+    id: `decision.proposal.${digest({ signature, decision, index }).slice(7, 23)}`,
+    kind: "decision",
+    title: `Decision proposal ${index + 1}`,
+    summary: decision.summary,
+    readiness: decision.approval_ref && !decision.changes_architecture ? "accepted" : "proposal",
+    profile: "project_management",
+    owner_ref: decision.owner_ref,
+    approval_ref: decision.approval_ref,
+    source_evidence_ref: `evidence.continuity.${suffix}`,
+  }));
+  if (evidence.method_candidate) {
+    const relatedCaseMap = new Map([...existing, ...promoted]
+      .filter((item) => item.kind === "regression_case" && item.case_signature === evidence.case_signature)
+      .map((item) => [item.id, item]));
+    const relatedCases = [...relatedCaseMap.values()];
+    const independentTasks = unique(relatedCases.map((item) => item.task_digest));
+    proposals.push({
+      id: `lesson.continuity.${digest(evidence.case_signature).slice(7, 23)}`,
+      kind: "lesson",
+      title: `Reusable method ${evidence.case_signature}`,
+      summary: evidence.method_candidate,
+      readiness: independentTasks.length >= 2 ? "accepted" : "proposal",
+      profile: "project_management",
+      case_signature: evidence.case_signature,
+      supporting_case_ids: unique(relatedCases.map((item) => item.id)),
+      auto_promotion_rule: "two_independent_verified_cases_without_architecture_change",
+    });
+  }
+  return { promoted, proposals };
+}
+
+function mergeObjects(existing, additions) {
+  const map = new Map(existing.map((item) => [item.id, item]));
+  for (const item of additions) map.set(item.id, item);
+  return [...map.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function ensureManifestReference(manifest) {
+  const next = JSON.parse(JSON.stringify(manifest));
+  next.graph = next.graph || {};
+  next.graph.source_of_truth = unique([...(next.graph.source_of_truth || []), "graph/specs"]);
+  next.graph.objects = unique([...(next.graph.objects || []), CONTINUITY_FILE]);
+  next.graph.generated = unique([...(next.graph.generated || []), CONTEXT_PROJECTION_FILE]);
+  next.extensions = next.extensions || {};
+  next.extensions["mirai.project_technology"] = {
+    ...(next.extensions["mirai.project_technology"] || {}),
+    continuity_policy: "task_boundary",
+  };
+  return next;
+}
+
+function contextProjection(manifest, objects, currentDigest) {
+  const accepted = objects.filter((item) => item.readiness === "accepted");
+  const proposals = objects.filter((item) => item.readiness === "proposal");
+  const lines = [
+    `# ${manifest.title || manifest.id}: project context`,
+    "",
+    "> Generated from `graph/specs`. This document is a readable projection, not a source of truth.",
+    "",
+    `Graph digest: \`${currentDigest}\``,
+    "",
+    "## Accepted context",
+    "",
+    ...(accepted.length ? accepted.map((item) => `- **${item.title}** — ${item.summary}`) : ["- No accepted continuity records yet."]),
+    "",
+    "## Proposals requiring a decision",
+    "",
+    ...(proposals.length ? proposals.map((item) => `- **${item.title}** — ${item.summary}`) : ["- None."]),
+    "",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function lock(repo, root) {
+  const gitBacked = fs.existsSync(path.join(repo, ".git"));
+  const file = gitBacked ? path.join(root, "continuity.lock") : path.join(repo, "graph", ".project-technology-continuity.lock");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  try {
+    const fd = fs.openSync(file, "wx", 0o600);
+    fs.writeFileSync(fd, canonicalBytes({ pid: process.pid }));
+    fs.closeSync(fd);
+    return { file, acquired: true };
+  } catch (_) { return { file, acquired: false }; }
+}
+
+function releaseLock(entry) {
+  if (entry?.acquired) try { fs.unlinkSync(entry.file); } catch (_) { /* already removed */ }
+}
+
+function sync(repoArg, manifest, boundary, input, options = {}) {
+  const repo = path.resolve(repoArg || ".");
+  if (!BOUNDARIES.has(boundary)) return { status: "fail", changed: false, blockers: ["continuity_boundary_invalid"] };
+  if (boundary === "task_start") return {
+    status: "success", changed: false, blockers: [], continuity: { ...status(repo, manifest, options), input_digest: input ? digest(input) : null, omissions: ["task_start_is_read_only"] },
+  };
+  const normalized = normalizeEvidence(input);
+  if (normalized.blockers.length) return { status: "blocked", changed: false, blockers: normalized.blockers };
+  const beforeDigest = graphDigest(repo);
+  if (options.expectedGraphDigest && options.expectedGraphDigest !== beforeDigest) return { status: "blocked", changed: false, blockers: ["continuity_compare_and_swap_conflict"] };
+  const root = stateRoot(repo, manifest, options);
+  const lease = lock(repo, root);
+  if (!lease.acquired) return { status: "blocked", changed: false, blockers: ["continuity_lease_conflict"] };
+  const manifestPath = path.join(repo, "graph.json");
+  const continuityPath = path.join(repo, CONTINUITY_FILE);
+  const projectionPath = path.join(repo, CONTEXT_PROJECTION_FILE);
+  const manifestBefore = fs.readFileSync(manifestPath);
+  const continuityBefore = fs.existsSync(continuityPath) ? fs.readFileSync(continuityPath) : null;
+  const projectionBefore = fs.existsSync(projectionPath) ? fs.readFileSync(projectionPath) : null;
+  try {
+    if (graphDigest(repo) !== beforeDigest) return { status: "blocked", changed: false, blockers: ["continuity_compare_and_swap_conflict"] };
+    const existing = readObjects(repo);
+    const built = buildCandidates(existing, normalized.evidence, boundary);
+    const objects = mergeObjects(existing, [...built.promoted, ...built.proposals]);
+    const nextManifest = ensureManifestReference(manifest);
+    const backupId = digest({ beforeDigest, task: normalized.evidence.task_digest }).slice(7, 23);
+    const backupRoot = path.join(root, "rollback", backupId);
+    atomicWrite(path.join(backupRoot, "graph.json"), manifestBefore);
+    if (continuityBefore) atomicWrite(path.join(backupRoot, "project-continuity.json"), continuityBefore);
+    if (projectionBefore) atomicWrite(path.join(backupRoot, "project-context.md"), projectionBefore);
+    const manifestChanged = atomicWrite(manifestPath, canonicalBytes(nextManifest));
+    const continuityChanged = atomicWrite(continuityPath, canonicalBytes({ schema_version: "1.0.0", objects }));
+    const currentDigest = graphDigest(repo);
+    const projectionChanged = atomicWrite(projectionPath, contextProjection(nextManifest, objects, currentDigest));
+    const receiptBase = {
+      contract: "project-continuity-receipt",
+      contract_version: "1.0.0",
+      repository_id: nextManifest.id,
+      boundary,
+      task_digest: normalized.evidence.task_digest,
+      input_digest: digest(normalized.evidence),
+      previous_graph_digest: beforeDigest,
+      current_graph_digest: currentDigest,
+      saved_refs: built.promoted.map((item) => item.id).sort(),
+      proposals: built.proposals.filter((item) => item.readiness === "proposal").map((item) => item.id).sort(),
+      omissions: [],
+      freshness: "current",
+      rollback_ref: `host-local://${graphIdentity(repo, nextManifest)}/rollback/${backupId}`,
+    };
+    const receipt = { ...receiptBase, receipt_digest: digest(receiptBase) };
+    const receiptName = `receipts/${receipt.receipt_digest.slice(7)}.json`;
+    atomicWrite(path.join(root, receiptName), canonicalBytes(receipt));
+    atomicWrite(path.join(root, "latest-receipt.json"), canonicalBytes({ receipt_ref: receiptName, receipt_digest: receipt.receipt_digest }));
+    const readback = readJson(continuityPath);
+    if (!readback || graphDigest(repo) !== currentDigest) throw new Error("continuity_readback_failed");
+    return { status: "success", changed: manifestChanged || continuityChanged || projectionChanged, blockers: [], continuity: { ...status(repo, nextManifest, options), ...receipt } };
+  } catch (_) {
+    atomicWrite(manifestPath, manifestBefore);
+    if (continuityBefore) atomicWrite(continuityPath, continuityBefore);
+    else if (fs.existsSync(continuityPath)) fs.unlinkSync(continuityPath);
+    if (projectionBefore) atomicWrite(projectionPath, projectionBefore);
+    else if (fs.existsSync(projectionPath)) fs.unlinkSync(projectionPath);
+    return { status: "fail", changed: false, blockers: ["continuity_transaction_failed", "continuity_rollback_applied"] };
+  } finally { releaseLock(lease); }
+}
+
+function verify(repo, manifest, options = {}) {
+  const current = status(repo, manifest, options);
+  const blockers = [];
+  if (current.policy === "task_boundary" && current.freshness !== "current") blockers.push(`continuity_${current.freshness}`);
+  if (options.receiptDigest && current.terminal_receipt?.receipt_digest !== options.receiptDigest) blockers.push("continuity_receipt_digest_mismatch");
+  for (const object of readObjects(repo)) {
+    if (!object.id || !object.kind || !object.title || !object.summary || !object.readiness || !object.profile) blockers.push("continuity_object_incomplete");
+    if (SECRET_PATTERN.test(JSON.stringify(object)) || PRIVATE_PATH_PATTERN.test(JSON.stringify(object)) || HOST_PATH_PATTERN.test(JSON.stringify(object))) blockers.push("continuity_object_contains_sensitive_or_host_data");
+    if (["decision", "goal"].includes(object.kind) && object.readiness === "accepted" && !object.approval_ref && object.id.includes("proposal")) blockers.push("continuity_proposal_promoted_without_approval");
+  }
+  return { status: blockers.length ? "blocked" : "success", blockers: unique(blockers), continuity: current };
+}
+
+module.exports = {
+  BOUNDARIES,
+  CONTINUITY_FILE,
+  CONTEXT_PROJECTION_FILE,
+  canonicalBytes,
+  continuityPolicy,
+  digest,
+  graphDigest,
+  latestReceipt,
+  normalizeEvidence,
+  stateRoot,
+  status,
+  sync,
+  verify,
+};