nexakit 0.0.0-stage → 0.2.0

package/src/memory-connection-package.js

@@ -0,0 +1,176 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { copyBytes, copyInertJson, decode, parseEventJson } from "./client-output-json.js";
+import {
+  createMemoryConnectionDescriptor, copyMemoryConnectionData, freezeMemoryConnectionData,
+  memoryConnectionHash, MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+import { containsSensitiveData } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_PACKAGE_LIMITS = Object.freeze({
+  packageJsonBytes: 512 * 1024, packageLockBytes: 2 * 1024 * 1024,
+  totalBytes: 2560 * 1024, reportBytes: 128 * 1024,
+  depth: 64, nodes: 30000, arrayItems: 256, metadataBytes: 2000000,
+  dependencies: 256, nameChars: 256, specifierChars: 1024
+});
+const KEYS = ["descriptor", "packageJsonBytes", "packageLockBytes", "expectedPackageJsonSha256", "expectedPackageLockSha256"];
+const HASH = /^[a-f0-9]{64}$/;
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const within = (root, full) => full === root || full.startsWith(root + "/");
+const sha256 = bytes => createHash("sha256").update(bytes).digest("hex");
+class Rejected extends Error {
+  constructor(code, state = "blocked") { super(code); this.code = code; this.state = state; }
+}
+const reject = (code, state) => { throw new Rejected(code, state); };
+
+function inputs(input) {
+  try {
+    if (!object(input) || types.isProxy(input) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length) {
+      reject("MC_PACKAGE_INPUT", "invalid");
+    }
+    const fields = Object.getOwnPropertyDescriptors(input);
+    if (Object.keys(fields).length !== KEYS.length || !KEYS.every(key =>
+      Object.hasOwn(fields, key) && fields[key].enumerable && Object.hasOwn(fields[key], "value"))) reject("MC_PACKAGE_INPUT", "invalid");
+    // Copy only small metadata here: file bytes have their own larger budgets.
+    const data = copyMemoryConnectionData({
+      descriptor: fields.descriptor.value,
+      packagePin: fields.expectedPackageJsonSha256.value,
+      lockPin: fields.expectedPackageLockSha256.value
+    });
+    if (typeof data.packagePin !== "string" || !HASH.test(data.packagePin) ||
+        typeof data.lockPin !== "string" || !HASH.test(data.lockPin)) reject("MC_PACKAGE_INPUT", "invalid");
+    const descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    if (memoryConnectionHash(descriptor) !== memoryConnectionHash(data.descriptor)) reject("MC_PACKAGE_INPUT", "invalid");
+    const { toolkitRoot, vaultPath, manifestPath } = descriptor.identity;
+    if (within(toolkitRoot, vaultPath) || within(vaultPath, toolkitRoot) || !manifestPath.startsWith(vaultPath + "/")) {
+      reject("MC_PACKAGE_INPUT", "invalid");
+    }
+    return { descriptor, packagePin: data.packagePin, lockPin: data.lockPin,
+      packageValue: fields.packageJsonBytes.value, lockValue: fields.packageLockBytes.value };
+  } catch { reject("MC_PACKAGE_INPUT", "invalid"); }
+}
+
+function capture(value, limit) {
+  try {
+    if (value && typeof value === "object" && !types.isProxy(value) && types.isUint8Array(value)) {
+      const typed = Object.getPrototypeOf(Uint8Array.prototype);
+      const backing = Object.getOwnPropertyDescriptor(typed, "buffer").get.call(value);
+      if (types.isSharedArrayBuffer(backing)) reject("MC_PACKAGE_INPUT", "invalid");
+    }
+    return copyBytes(value, limit);
+  } catch (error) {
+    if (error instanceof Rejected) throw error;
+    if (error?.code === "byte-limit") reject("MC_PACKAGE_LIMIT");
+    if (["invalid-unicode", "invalid-utf8"].includes(error?.code)) reject("MC_PACKAGE_FORMAT");
+    reject("MC_PACKAGE_INPUT", "invalid");
+  }
+}
+
+function parse(bytes) {
+  try { return copyInertJson(parseEventJson(decode(bytes))); }
+  catch (error) { reject(["event-json-limit", "metadata-limit"].includes(error?.code) ? "MC_PACKAGE_LIMIT" : "MC_PACKAGE_FORMAT"); }
+}
+
+function profile(pkg, lock) {
+  if (lock.lockfileVersion !== 3 || !object(lock.packages) || !Object.hasOwn(lock.packages, "") || !object(lock.packages[""])) {
+    reject("MC_PACKAGE_PROFILE");
+  }
+  const root = lock.packages[""];
+  for (const item of [pkg, root]) {
+    for (const field of ["devDependencies", "optionalDependencies", "peerDependencies"]) {
+      if (Object.hasOwn(item, field) && (!object(item[field]) || Object.keys(item[field]).length)) reject("MC_PACKAGE_PROFILE");
+    }
+    for (const field of ["workspaces", "overrides", "bundleDependencies", "bundledDependencies"]) {
+      if (Object.hasOwn(item, field)) reject("MC_PACKAGE_PROFILE");
+    }
+  }
+  return root;
+}
+
+function literal(value, limit, reason) {
+  if (typeof value === "string" && value.length > limit) reject("MC_PACKAGE_LIMIT");
+  if (typeof value !== "string" || !value || value !== value.trim() || CONTROL.test(value)) reject(reason);
+  return value;
+}
+
+function identity(pkg, lock, root) {
+  for (const field of ["name", "version"]) {
+    const values = [pkg, lock, root].map(item => literal(item[field], MEMORY_CONNECTION_PACKAGE_LIMITS.nameChars, "MC_PACKAGE_IDENTITY"));
+    if (values.some(value => value !== values[0])) reject("MC_PACKAGE_IDENTITY");
+  }
+}
+
+function dependencies(item) {
+  if (!Object.hasOwn(item, "dependencies")) return {};
+  const value = item.dependencies;
+  if (!object(value)) reject("MC_PACKAGE_DEPENDENCIES");
+  const keys = Object.keys(value);
+  if (keys.length > MEMORY_CONNECTION_PACKAGE_LIMITS.dependencies) reject("MC_PACKAGE_LIMIT");
+  for (const key of keys) {
+    literal(key, MEMORY_CONNECTION_PACKAGE_LIMITS.nameChars, "MC_PACKAGE_DEPENDENCIES");
+    literal(value[key], MEMORY_CONNECTION_PACKAGE_LIMITS.specifierChars, "MC_PACKAGE_DEPENDENCIES");
+  }
+  return value;
+}
+
+function engines(pkg, root) {
+  for (const item of [pkg, root]) {
+    if (Object.hasOwn(item, "engines") && !object(item.engines)) reject("MC_PACKAGE_ENGINES");
+  }
+  const has = item => Object.hasOwn(item, "engines") && Object.hasOwn(item.engines, "node");
+  const a = has(pkg), b = has(root);
+  if (!a && !b) return false;
+  if (!a || !b) reject("MC_PACKAGE_ENGINES");
+  const left = literal(pkg.engines.node, MEMORY_CONNECTION_PACKAGE_LIMITS.specifierChars, "MC_PACKAGE_ENGINES");
+  const right = literal(root.engines.node, MEMORY_CONNECTION_PACKAGE_LIMITS.specifierChars, "MC_PACKAGE_ENGINES");
+  if (left !== right) reject("MC_PACKAGE_ENGINES");
+  return true;
+}
+
+function report(state, reason, hashes = {}, engineMatched = false) {
+  const matched = state === "consistent";
+  const result = {
+    schemaVersion: MEMORY_CONNECTION_VERSION, state, reasons: [reason],
+    descriptorSha256: null, packageJsonSha256: null, packageLockSha256: null, ...hashes,
+    facts: {
+      ...MEMORY_CONNECTION_FACTS, evidence: "provided-bytes", verificationScope: "package-root-declarations-only",
+      packageIdentityMatched: matched, directDependencyDeclarationsMatched: matched,
+      engineDeclarationMatched: matched && engineMatched,
+      rangeSatisfactionVerified: false, dependencyGraphVerified: false, installedDependenciesVerified: false,
+      runtimeVersionVerified: false, runtimeCompatibilityVerified: false
+    }
+  };
+  if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_PACKAGE_LIMITS.reportBytes) reject("MC_PACKAGE_LIMIT");
+  return freezeMemoryConnectionData(result);
+}
+
+/**
+ * Compare two reviewed byte captures and root declarations only. No candidate IO,
+ * npm/Node execution, range solving, installed-tree inspection or plan integration.
+ */
+export function validateMemoryConnectionPackage(input) {
+  try {
+    const data = inputs(input);
+    const packageBytes = capture(data.packageValue, MEMORY_CONNECTION_PACKAGE_LIMITS.packageJsonBytes);
+    const lockBytes = capture(data.lockValue, MEMORY_CONNECTION_PACKAGE_LIMITS.packageLockBytes);
+    if (packageBytes.length + lockBytes.length > MEMORY_CONNECTION_PACKAGE_LIMITS.totalBytes) reject("MC_PACKAGE_LIMIT");
+    const packageHash = sha256(packageBytes), lockHash = sha256(lockBytes);
+    if (packageHash !== data.packagePin || lockHash !== data.lockPin) reject("MC_PACKAGE_PIN_MISMATCH");
+    const pkg = parse(packageBytes), lock = parse(lockBytes);
+    if (containsSensitiveData(JSON.stringify(pkg)) || containsSensitiveData(JSON.stringify(lock))) reject("MC_PACKAGE_SENSITIVE");
+    const root = profile(pkg, lock);
+    identity(pkg, lock, root);
+    const left = dependencies(pkg), right = dependencies(root), keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length || keys.some(key => !Object.hasOwn(right, key) || left[key] !== right[key])) {
+      reject("MC_PACKAGE_DEPENDENCIES");
+    }
+    const engineMatched = engines(pkg, root);
+    return report("consistent", "MC_PACKAGE_CONSISTENT", {
+      descriptorSha256: memoryConnectionHash(data.descriptor), packageJsonSha256: data.packagePin, packageLockSha256: data.lockPin
+    }, engineMatched);
+  } catch (error) {
+    return report(error instanceof Rejected ? error.state : "blocked", error instanceof Rejected ? error.code : "MC_PACKAGE_VALIDATION");
+  }
+}

package/src/memory-connection-plan.js

@@ -0,0 +1,211 @@
+import {
+  createMemoryConnectionDescriptor,
+  copyMemoryConnectionData,
+  freezeMemoryConnectionData,
+  hasMemoryConnectionKeys,
+  memoryConnectionHash,
+  MEMORY_CONNECTION_FACTS,
+  MEMORY_CONNECTION_LIMITS,
+  MEMORY_CONNECTION_VERSION,
+  MemoryConnectionInputError
+} from "./memory-connection-descriptor.js";
+import { containsSensitiveData } from "./sensitive-data.js";
+
+const PIN_KEYS = [
+  "manifestSha256", "binSha256", "nodeSha256", "dependenciesSha256",
+  "pathMetadataSha256", "skillMetadataSha256"
+];
+const SERVER_KEYS = ["command", "args", "enabled"];
+const SERVER_OPTIONAL = ["cwd", "enabled_tools"];
+const HASH = /^[a-f0-9]{64}$/;
+const states = (value, allowed) => typeof value === "string" && allowed.includes(value);
+const component = (id, action, code) => ({ id, action, code });
+const reject = (code) => { throw new MemoryConnectionInputError(code); };
+const equal = (a, b) => memoryConnectionHash(a) === memoryConnectionHash(b);
+
+function blank() {
+  return {
+    command: "project-memory connect plan",
+    schemaVersion: MEMORY_CONNECTION_VERSION,
+    state: "invalid",
+    connectionClass: "unknown",
+    identity: null,
+    candidateServer: null,
+    components: [],
+    summary: { create: 0, update: 0, migrate: 0, unchanged: 0, conflicts: 0, blocked: 0 },
+    reasons: [],
+    planHash: null,
+    facts: { ...MEMORY_CONNECTION_FACTS }
+  };
+}
+
+function finish(report, state, reasons) {
+  report.state = state;
+  report.reasons = [...new Set(reasons)].sort();
+  report.summary = {
+    create: report.components.filter((item) => item.action === "create").length,
+    update: report.components.filter((item) => item.action === "update").length,
+    migrate: report.components.filter((item) => item.action === "migrate").length,
+    unchanged: report.components.filter((item) => item.action === "unchanged").length,
+    conflicts: report.components.filter((item) => item.action === "conflict").length,
+    blocked: report.components.filter((item) => item.action === "blocked").length
+  };
+  if (!["preview", "unchanged"].includes(state)) {
+    report.candidateServer = null;
+    report.planHash = null;
+  }
+  if (Buffer.byteLength(JSON.stringify(report)) > MEMORY_CONNECTION_LIMITS.reportBytes) {
+    const limited = blank();
+    limited.reasons = ["MC_REPORT_LIMIT"];
+    return freezeMemoryConnectionData(limited);
+  }
+  return freezeMemoryConnectionData(report);
+}
+
+function checkObservations(observations) {
+  if (!hasMemoryConnectionKeys(observations, ["configuration", "skill"])) {
+    reject("MC_OBSERVATIONS_INVALID");
+  }
+  const config = observations.configuration;
+  if (!hasMemoryConnectionKeys(config, ["state", "sha256", "server"]) ||
+      !states(config.state, ["absent", "present", "unsafe"])) {
+    reject("MC_OBSERVATIONS_INVALID");
+  }
+  if (config.state === "present") {
+    if (typeof config.sha256 !== "string" || !HASH.test(config.sha256) ||
+        config.server !== null && (typeof config.server !== "object" || Array.isArray(config.server))) {
+      reject("MC_OBSERVATIONS_INVALID");
+    }
+  } else if (config.sha256 !== null || config.server !== null) {
+    reject("MC_OBSERVATIONS_INVALID");
+  }
+  const skill = observations.skill;
+  if (!hasMemoryConnectionKeys(skill, ["state", "resolvedSource"]) ||
+      !states(skill.state, ["absent", "matched", "conflict", "unsafe"]) ||
+      ["absent", "unsafe"].includes(skill.state) && skill.resolvedSource !== null ||
+      skill.state === "matched" && typeof skill.resolvedSource !== "string" ||
+      skill.state === "conflict" && skill.resolvedSource !== null && typeof skill.resolvedSource !== "string") {
+    reject("MC_OBSERVATIONS_INVALID");
+  }
+}
+
+function sensitive(value) {
+  if (typeof value === "string") return containsSensitiveData(value);
+  return value !== null && typeof value === "object" &&
+    Object.values(value).some(sensitive);
+}
+
+function serverShape(server) {
+  return hasMemoryConnectionKeys(server, SERVER_KEYS, SERVER_OPTIONAL) &&
+    typeof server.command === "string" && Array.isArray(server.args) &&
+    server.args.length <= 16 && server.args.every((arg) => typeof arg === "string") &&
+    typeof server.enabled === "boolean" &&
+    (server.cwd === undefined || typeof server.cwd === "string") &&
+    (server.enabled_tools === undefined || Array.isArray(server.enabled_tools) &&
+      server.enabled_tools.every((tool) => typeof tool === "string"));
+}
+
+function policyMatches(tools, expected) {
+  return Array.isArray(tools) && tools.length === expected.length &&
+    new Set(tools).size === tools.length && expected.every((tool) => tools.includes(tool));
+}
+
+/**
+ * Classifies explicit declarations and creates an intent pin, never a permission.
+ * Only these two modules and their tests are part of RG3-A1a: no TOML collector,
+ * writer, public CLI dispatch, native MCP test or actual client configuration.
+ */
+export function createMemoryConnectionPlan(input) {
+  const report = blank();
+  let data, descriptor;
+  try {
+    data = copyMemoryConnectionData(input);
+    if (!hasMemoryConnectionKeys(data, ["schemaVersion", "descriptor", "observations", "pins", "migrateLegacy"]) ||
+        data.schemaVersion !== MEMORY_CONNECTION_VERSION || typeof data.migrateLegacy !== "boolean") {
+      reject("MC_PLAN_INVALID");
+    }
+    if (sensitive(data)) reject("MC_SENSITIVE_INPUT");
+    descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    if (!equal(descriptor, data.descriptor)) reject("MC_DESCRIPTOR_MISMATCH");
+    if (!hasMemoryConnectionKeys(data.pins, PIN_KEYS) ||
+        Object.values(data.pins).some((hash) => typeof hash !== "string" || !HASH.test(hash))) {
+      reject("MC_PINS_INVALID");
+    }
+    checkObservations(data.observations);
+    if (data.observations.skill.state === "matched" &&
+        data.observations.skill.resolvedSource !== descriptor.skill.source) {
+      reject("MC_SKILL_DECLARATION_MISMATCH");
+    }
+  } catch (error) {
+    return finish(report, "invalid", [error instanceof MemoryConnectionInputError ? error.code : "MC_PLAN_INVALID"]);
+  }
+
+  report.identity = { ...descriptor.identity };
+  const { configuration, skill } = data.observations;
+  report.components.push(component("skill", {
+    absent: "create", matched: "unchanged", conflict: "conflict", unsafe: "blocked"
+  }[skill.state], {
+    absent: "MC_SKILL_MISSING", matched: "MC_SKILL_MATCH_DECLARED",
+    conflict: "MC_SKILL_CONFLICT", unsafe: "MC_SKILL_UNSAFE"
+  }[skill.state]));
+
+  if (configuration.state === "unsafe") {
+    report.connectionClass = "unsafe";
+    report.components.push(component("mcp", "blocked", "MC_CONFIG_UNSAFE"));
+  } else if (configuration.server === null) {
+    report.connectionClass = "absent";
+    report.components.push(component("mcp", "create", "MC_SERVER_MISSING"),
+      component("policy", "create", "MC_POLICY_PROPOSED"));
+    report.candidateServer = structuredClone(descriptor.server);
+  } else {
+    const current = configuration.server;
+    if (!serverShape(current)) {
+      report.components.push(component("mcp", "conflict", "MC_SERVER_UNKNOWN"));
+    } else if (current.command === descriptor.server.command &&
+        equal(current.args, descriptor.server.args) && current.cwd === descriptor.server.cwd) {
+      report.connectionClass = "protected";
+      report.components.push(component("mcp", "unchanged", "MC_SERVER_MATCH_DECLARED"));
+      if (policyMatches(current.enabled_tools, descriptor.server.enabled_tools)) {
+        report.components.push(component("policy", "unchanged", "MC_POLICY_MATCH_DECLARED"));
+        report.candidateServer = { ...structuredClone(descriptor.server), enabled: current.enabled };
+      } else {
+        report.components.push(component("policy", "conflict", "MC_POLICY_MISMATCH"));
+      }
+    } else if (current.command === "npx" && equal(current.args, [
+      "-y", "@modelcontextprotocol/server-filesystem@2026.8.31", descriptor.identity.vaultPath
+    ]) && (current.cwd === undefined || current.cwd === descriptor.server.cwd)) {
+      report.connectionClass = "legacy-direct";
+      if (data.migrateLegacy) {
+        report.components.push(component("mcp", "migrate", "MC_LEGACY_MIGRATION_PROPOSED"),
+          component("policy", "migrate", "MC_POLICY_PROPOSED"));
+        report.candidateServer = structuredClone(descriptor.server);
+      } else {
+        report.components.push(component("mcp", "conflict", "MC_LEGACY_OPT_IN_REQUIRED"));
+      }
+    } else {
+      report.components.push(component("mcp", "conflict", "MC_SERVER_IDENTITY_MISMATCH"));
+    }
+  }
+
+  const reasons = report.components.filter((item) => ["conflict", "blocked"].includes(item.action))
+    .map((item) => item.code);
+  if (report.components.some((item) => item.action === "blocked")) return finish(report, "blocked", reasons);
+  if (report.components.some((item) => item.action === "conflict")) return finish(report, "conflict", reasons);
+  try {
+    report.planHash = memoryConnectionHash({
+      schemaVersion: MEMORY_CONNECTION_VERSION,
+      descriptor,
+      observations: data.observations,
+      pins: data.pins,
+      migrateLegacy: data.migrateLegacy,
+      components: report.components,
+      candidateServer: report.candidateServer
+    });
+  } catch {
+    return finish(report, "invalid", ["MC_PLAN_LIMIT"]);
+  }
+  const unchanged = report.components.every((item) => item.action === "unchanged");
+  const notes = [unchanged ? "MC_MATCH_DECLARED" : "MC_PREVIEW_ONLY"];
+  if (report.candidateServer.enabled === false) notes.push("MC_SERVER_DISABLED");
+  return finish(report, unchanged ? "unchanged" : "preview", notes);
+}

package/src/memory-connection-skill.js

@@ -0,0 +1,211 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { copyBytes, decode } from "./client-output-json.js";
+
+import {
+  createMemoryConnectionDescriptor, copyMemoryConnectionData,
+  freezeMemoryConnectionData, memoryConnectionHash,
+  MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+
+export const MEMORY_CONNECTION_SKILL_LIMITS = Object.freeze({
+  fileBytes: 131072, chunkBytes: 65536, pathChars: 4096,
+  components: 64, reportBytes: 131072
+});
+export const MEMORY_CONNECTION_SKILL_OPEN_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+class Rejected extends Error {
+  constructor(code, state = "blocked") { super(code); this.code = code; this.state = state; }
+}
+const reject = (code, state) => { throw new Rejected(code, state); };
+const errno = (e) => e instanceof Error && typeof e.code === "string" ? e.code : "";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const dirSignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode]);
+const fileSignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode, s.nlink, s.size, s.mtimeMs, s.ctimeMs]);
+
+function inputs(input) {
+  try {
+    const data = copyMemoryConnectionData(input);
+    if (!data || Array.isArray(data) || Object.keys(data).length !== 2 ||
+        !Object.hasOwn(data, "descriptor") || !Object.hasOwn(data, "expectedSkillSha256") ||
+        typeof data.expectedSkillSha256 !== "string" || !/^[a-f0-9]{64}$/.test(data.expectedSkillSha256)) {
+      reject("MC_SKILL_INPUT", "invalid");
+    }
+    const descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    if (memoryConnectionHash(descriptor) !== memoryConnectionHash(data.descriptor)) reject("MC_SKILL_INPUT", "invalid");
+    const sourceFile = descriptor.skill.source + "/SKILL.md";
+    for (const full of [descriptor.skill.target, sourceFile]) {
+      if (full.length > MEMORY_CONNECTION_SKILL_LIMITS.pathChars ||
+          full.split("/").length - 1 > MEMORY_CONNECTION_SKILL_LIMITS.components) reject("MC_SKILL_INPUT", "invalid");
+    }
+    return { descriptor, expected: data.expectedSkillSha256, sourceFile };
+  } catch { reject("MC_SKILL_INPUT", "invalid"); }
+}
+
+function safeDir(s, uid, owned) {
+  if (!s.isDirectory() || s.isSymbolicLink() || !(s.mode & 0o100)) reject("MC_SKILL_PARENT_UNSAFE");
+  if (owned) {
+    if (s.uid !== uid || s.mode & 0o7022) reject("MC_SKILL_PARENT_UNSAFE");
+  } else {
+    const sharedSticky = s.uid === 0 && (s.mode & 0o7777) === 0o1777;
+    if (![0, uid].includes(s.uid) || !sharedSticky && s.mode & 0o7022) reject("MC_SKILL_PARENT_UNSAFE");
+  }
+}
+function safeSourceFile(s, uid) {
+  if (!s.isFile() || s.isSymbolicLink() || s.uid !== uid || s.nlink !== 1 || (s.mode & 0o7777) !== 0o600) {
+    reject("MC_SKILL_FILE_UNSAFE");
+  }
+  if (!Number.isSafeInteger(s.size) || s.size < 0 || s.size > MEMORY_CONNECTION_SKILL_LIMITS.fileBytes) reject("MC_SKILL_FILE_LIMIT");
+}
+async function parents(io, full, ownedRoot, uid, missingAllowed = []) {
+  const chain = []; let current = "/";
+  const root = await io.lstat(current); safeDir(root, uid, false);
+  chain.push({ path: current, signature: dirSignature(root) });
+  const parts = full.slice(1).split("/");
+  for (const part of parts.slice(0, -1)) {
+    current = path.posix.join(current, part); let s;
+    try { s = await io.lstat(current); }
+    catch (e) {
+      if (errno(e) === "ENOENT" && missingAllowed.includes(current)) return { chain, missing: current };
+      reject(errno(e) === "ENOENT" ? "MC_SKILL_PATH_MISSING" : "MC_SKILL_UNREADABLE");
+    }
+    safeDir(s, uid, current === ownedRoot || current.startsWith(ownedRoot + "/"));
+    chain.push({ path: current, signature: dirSignature(s) });
+  }
+  return { chain, missing: null };
+}
+async function recheckParents(io, snapshot, ownedRoot, uid) {
+  for (const parent of snapshot.chain) {
+    let s; try { s = await io.lstat(parent.path); } catch { reject("MC_SKILL_CHANGED"); }
+    safeDir(s, uid, parent.path === ownedRoot || parent.path.startsWith(ownedRoot + "/"));
+    if (dirSignature(s) !== parent.signature) reject("MC_SKILL_CHANGED");
+  }
+}
+async function targetSnapshot(io, descriptor, uid) {
+  const home = descriptor.identity.homeDirectory, target = descriptor.skill.target;
+  const snapshot = await parents(io, target, home, uid, [home + "/.agents", home + "/.agents/skills"]);
+  snapshot.stat = null; snapshot.link = null;
+  if (snapshot.missing) return snapshot;
+  let s;
+  try { s = await io.lstat(target); }
+  catch (e) { if (errno(e) === "ENOENT") { snapshot.missing = target; return snapshot; } reject("MC_SKILL_UNREADABLE"); }
+  if (s.uid !== uid) reject("MC_SKILL_TARGET_UNSAFE");
+  snapshot.stat = s;
+  if (s.isSymbolicLink()) {
+    if (s.nlink !== 1 || s.mode & 0o7000) reject("MC_SKILL_TARGET_UNSAFE");
+    snapshot.link = await linkText(io, target);
+  } else if (!s.isFile() && !s.isDirectory()) reject("MC_SKILL_TARGET_UNSAFE");
+  return snapshot;
+}
+async function linkText(io, target) {
+  // Native readlink must not silently replace invalid path bytes with U+FFFD.
+  const raw = await io.readlink(target, { encoding: "buffer" });
+  try {
+    const text = decode(copyBytes(raw, MEMORY_CONNECTION_SKILL_LIMITS.pathChars * 4));
+    if (text.length > MEMORY_CONNECTION_SKILL_LIMITS.pathChars) reject("MC_SKILL_TARGET_UNSAFE");
+    return text;
+  } catch { reject("MC_SKILL_TARGET_UNSAFE"); }
+}
+async function recheckTarget(io, descriptor, snapshot, uid) {
+  await recheckParents(io, snapshot, descriptor.identity.homeDirectory, uid);
+  if (snapshot.missing) {
+    try { await io.lstat(snapshot.missing); }
+    catch (e) { if (errno(e) === "ENOENT") return; reject("MC_SKILL_CHANGED"); }
+    reject("MC_SKILL_CHANGED");
+  }
+  let s;
+  try { s = await io.lstat(descriptor.skill.target); } catch { reject("MC_SKILL_CHANGED"); }
+  if (fileSignature(s) !== fileSignature(snapshot.stat)) reject("MC_SKILL_CHANGED");
+  if (snapshot.link !== null && await linkText(io, descriptor.skill.target) !== snapshot.link) reject("MC_SKILL_CHANGED");
+}
+async function sourceSnapshot(io, data, uid) {
+  const snapshot = await parents(io, data.sourceFile, data.descriptor.identity.vaultPath, uid);
+  let s;
+  try { s = await io.lstat(data.sourceFile); }
+  catch (e) { reject(errno(e) === "ENOENT" ? "MC_SKILL_SOURCE_MISSING" : "MC_SKILL_UNREADABLE"); }
+  safeSourceFile(s, uid); snapshot.stat = s; return snapshot;
+}
+async function recheckSource(io, data, snapshot, uid) {
+  await recheckParents(io, snapshot, data.descriptor.identity.vaultPath, uid);
+  let s;
+  try { s = await io.lstat(data.sourceFile); } catch { reject("MC_SKILL_CHANGED"); }
+  safeSourceFile(s, uid);
+  if (fileSignature(s) !== fileSignature(snapshot.stat)) reject("MC_SKILL_CHANGED");
+}
+
+/**
+ * Check only the exact own link and reviewed SKILL.md bytes. Never enumerate,
+ * interpret Skill text, follow foreign destinations, install, repair or execute.
+ * IO overrides are trusted simulations, not a sandbox or native-read evidence.
+ * Rechecks detect observable races; they are not atomic openat/ABA protection.
+ */
+export async function inspectMemoryConnectionSkill(input, dependencies = {}) {
+  let data = null, nativeIO = false;
+  const report = (state, details = {}) => {
+    const read = ["matched", "absent"].includes(state), observed = read || state === "conflict";
+    const result = {
+      schemaVersion: MEMORY_CONNECTION_VERSION, state, skillName: data?.descriptor.identity.skillName ?? null,
+      sourceSha256: null, metadataSha256: null, resolvedSource: null, reasons: [], ...details,
+      facts: {
+        ...MEMORY_CONNECTION_FACTS, verificationScope: "skill-installation-only",
+        evidence: observed ? nativeIO ? read ? "local-skill-file" : "local-skill-metadata" : "simulated-local-skill" : "none",
+        targetObservationVerified: observed && nativeIO, skillSourceVerified: read && nativeIO,
+        localReadVerified: read && nativeIO, bytePinMatched: read,
+        skillFormatVerified: false, skillLoadedVerified: false
+      }
+    };
+    if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_SKILL_LIMITS.reportBytes) reject("MC_SKILL_REPORT_LIMIT");
+    return freezeMemoryConnectionData(result);
+  };
+  try {
+    data = inputs(input);
+    nativeIO = dependencies.io === undefined;
+    const io = dependencies.io ?? fs, uid = process.getuid?.();
+    if (!["darwin", "linux"].includes(process.platform) || !Number.isSafeInteger(uid) || constants.O_NOFOLLOW === undefined) reject("MC_SKILL_PLATFORM");
+    const descriptor = data.descriptor, target = await targetSnapshot(io, descriptor, uid);
+    await recheckTarget(io, descriptor, target, uid);
+    if (target.stat && target.link !== descriptor.skill.source) {
+      return report("conflict", { reasons: ["MC_SKILL_TARGET_CONFLICT"] });
+    }
+    const source = await sourceSnapshot(io, data, uid);
+    await recheckSource(io, data, source, uid); await recheckTarget(io, descriptor, target, uid);
+    let handle;
+    try { handle = await io.open(data.sourceFile, MEMORY_CONNECTION_SKILL_OPEN_FLAGS); }
+    catch (e) { reject(errno(e) === "ELOOP" ? "MC_SKILL_FILE_UNSAFE" : "MC_SKILL_UNREADABLE"); }
+    let bytes;
+    try {
+      const start = await handle.stat(); safeSourceFile(start, uid);
+      if (fileSignature(start) !== fileSignature(source.stat)) reject("MC_SKILL_CHANGED");
+      await recheckSource(io, data, source, uid); await recheckTarget(io, descriptor, target, uid);
+      bytes = Buffer.alloc(source.stat.size); let offset = 0;
+      while (offset < bytes.length) {
+        const request = Math.min(MEMORY_CONNECTION_SKILL_LIMITS.chunkBytes, bytes.length - offset);
+        const { bytesRead } = await handle.read(bytes, offset, request, offset);
+        if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > request) reject("MC_SKILL_READ");
+        if (!bytesRead) reject("MC_SKILL_CHANGED");
+        offset += bytesRead;
+      }
+      const after = await handle.stat(); safeSourceFile(after, uid);
+      if (fileSignature(after) !== fileSignature(source.stat)) reject("MC_SKILL_CHANGED");
+      await recheckSource(io, data, source, uid); await recheckTarget(io, descriptor, target, uid);
+    } finally {
+      try { await handle.close(); } catch { reject("MC_SKILL_CLOSE"); }
+    }
+    await recheckSource(io, data, source, uid); await recheckTarget(io, descriptor, target, uid);
+    const sha256 = digest(bytes);
+    if (sha256 !== data.expected) reject("MC_SKILL_PIN_MISMATCH");
+    const metadataSha256 = digest(JSON.stringify({
+      source: { path: data.sourceFile, parents: source.chain, signature: fileSignature(source.stat) },
+      target: { path: descriptor.skill.target, parents: target.chain, missing: target.missing,
+        signature: target.stat ? fileSignature(target.stat) : null, link: target.link }
+    }));
+    return report(target.missing ? "absent" : "matched", {
+      sourceSha256: sha256, metadataSha256,
+      resolvedSource: target.missing ? null : descriptor.skill.source,
+      reasons: [target.missing ? "MC_SKILL_TARGET_MISSING" : "MC_SKILL_MATCH"]
+    });
+  } catch (e) {
+    return report(e instanceof Rejected ? e.state : "blocked", { reasons: [e instanceof Rejected ? e.code : "MC_SKILL_IO"] });
+  }
+}