skill-family-harness-node 0.1.0

package/src/closure.mjs

@@ -0,0 +1,153 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { resolveContained, readFileContained } from "./paths.mjs";
+
+/**
+ * Resource closure and digests.
+ *
+ * A closure bounds the read/write scope of an operation: the normalized,
+ * containment-verified set of input and output resources, each with a
+ * deterministic sha256 content digest, plus one digest over the whole set.
+ *
+ * Determinism rules: entries are de-duplicated on their normalized relative
+ * path, sorted by UTF-16 code units, and serialized with a fixed key order;
+ * equal resource sets always produce the equal closure digest.
+ */
+
+const CLOSURE_KIND = "skill-family.resource-closure";
+const CLOSURE_SCHEMA_VERSION = 1;
+const DIGEST_ALGORITHM = "sha256";
+const ROLES = Object.freeze(["input", "output"]);
+
+/** sha256 hex digest of raw bytes. */
+export function digestBytes(bytes) {
+  return createHash(DIGEST_ALGORITHM).update(bytes).digest("hex");
+}
+
+function normalizeResourcePath(relPath) {
+  if (typeof relPath !== "string" || relPath.length === 0 || relPath.includes("\0")) {
+    throw new TypeError("computeResourceClosure: every resource path must be a non-empty string");
+  }
+  const normalized = path.posix.normalize(relPath.replaceAll("\\", "/"));
+  if (normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) {
+    // Lexical escape inside a closure declaration: reject before any IO.
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.PATH_TRAVERSAL,
+      "closure resource path leaves the workspace root",
+      { input: relPath },
+    );
+  }
+  return normalized === "." ? "" : normalized;
+}
+
+/**
+ * Computes the resource closure of `resources` relative to `root`.
+ *
+ * resources: [{ path, role }] with role "input" | "output".
+ *  - input entries must exist; their bytes are read through the containment
+ *    layer and digested (missing input => SFC2004 missing-resource).
+ *  - output entries may not exist yet; existing outputs are digested,
+ *    absent outputs are recorded with exists=false and digest=null.
+ *
+ * Returns { schemaVersion, kind, digestAlgorithm, digest, resources } where
+ * resources is the sorted array of { path, role, exists, sha256 }.
+ */
+export async function computeResourceClosure({ root, resources } = {}) {
+  if (!root || typeof root !== "string") {
+    throw new TypeError("computeResourceClosure: root must be a directory path string");
+  }
+  if (!Array.isArray(resources)) {
+    throw new TypeError("computeResourceClosure: resources must be an array");
+  }
+  const byPath = new Map();
+  for (const entry of resources) {
+    if (!entry || typeof entry !== "object") {
+      throw new TypeError("computeResourceClosure: every resource entry must be an object");
+    }
+    if (!ROLES.includes(entry.role)) {
+      throw new TypeError(
+        `computeResourceClosure: role must be one of ${ROLES.join(", ")}`,
+      );
+    }
+    const normalized = normalizeResourcePath(entry.path);
+    if (normalized === "") {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.INVALID_PATH,
+        "closure resource path must address a resource strictly inside the workspace root",
+      );
+    }
+    const existing = byPath.get(normalized);
+    if (existing && existing.role !== entry.role) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.CLOSURE_CONFLICT,
+        `resource declared with conflicting roles: ${normalized}`,
+        { path: normalized },
+      );
+    }
+    if (!existing) {
+      byPath.set(normalized, { path: normalized, role: entry.role });
+    }
+  }
+
+  const records = [];
+  for (const normalized of [...byPath.keys()].sort()) {
+    const record = byPath.get(normalized);
+    // Containment proof: resolve through the same layer as every other
+    // filesystem access (traversal, symlink, and realpath checks included).
+    await resolveContained(root, normalized);
+    if (record.role === "input") {
+      const bytes = await readFileContained(root, normalized);
+      records.push({ path: normalized, role: record.role, exists: true, sha256: digestBytes(bytes) });
+    } else {
+      let bytes;
+      try {
+        bytes = await readFileContained(root, normalized);
+      } catch (cause) {
+        if (cause && cause.details && cause.details.kind === HARNESS_ERROR_KINDS.MISSING_RESOURCE) {
+          records.push({ path: normalized, role: record.role, exists: false, sha256: null });
+          continue;
+        }
+        throw cause;
+      }
+      records.push({ path: normalized, role: record.role, exists: true, sha256: digestBytes(bytes) });
+    }
+  }
+
+  const canonical = JSON.stringify({
+    kind: CLOSURE_KIND,
+    schemaVersion: CLOSURE_SCHEMA_VERSION,
+    digestAlgorithm: DIGEST_ALGORITHM,
+    resources: records.map((record) => ({
+      path: record.path,
+      role: record.role,
+      exists: record.exists,
+      sha256: record.sha256,
+    })),
+  });
+  return {
+    schemaVersion: CLOSURE_SCHEMA_VERSION,
+    kind: CLOSURE_KIND,
+    digestAlgorithm: DIGEST_ALGORITHM,
+    digest: digestBytes(Buffer.from(canonical, "utf8")),
+    resources: records,
+  };
+}
+
+/**
+ * Whether a closure already bounds `relPath` (lexical normalization only, no
+ * filesystem access).
+ */
+export function closureContains(closure, relPath) {
+  if (!closure || !Array.isArray(closure.resources)) {
+    throw new TypeError("closureContains: closure must be a computed closure object");
+  }
+  let normalized;
+  try {
+    normalized = normalizeResourcePath(relPath);
+  } catch {
+    return false;
+  }
+  if (normalized === "") return false;
+  return closure.resources.some((record) => record.path === normalized);
+}

package/src/errors.mjs

@@ -0,0 +1,75 @@
+import { ContractsError, isRegisteredErrorCode } from "skill-family-contracts";
+
+/**
+ * Harness error policy.
+ *
+ * The harness never invents error codes: every thrown or reported error
+ * carries a code from the frozen contracts registry. Mechanism failures use
+ * SFC2004 (EXECUTION_FAILED) whose registered meaning is "the mechanism
+ * runtime failed while executing a well-formed operation; details carry the
+ * mechanism evidence". The mechanism evidence is the stable `details.kind`
+ * value enumerated in HARNESS_ERROR_KINDS.
+ *
+ * Adding a brand-new SFC code would be a contracts change (the registry file
+ * lives in skill-family-contracts), which is outside this package's write
+ * set; the SFC2004 + details.kind pairing keeps the public surface stable
+ * without touching the frozen registry.
+ */
+
+/**
+ * Stable mechanism-failure kinds. Each value appears as `details.kind` on an
+ * SFC2004-coded HarnessError or operation-result error entry. The set is
+ * frozen for the v1 harness; values are strings so they serialize unchanged.
+ */
+export const HARNESS_ERROR_KINDS = Object.freeze({
+  INVALID_PATH: "invalid-path",
+  ABSOLUTE_PATH: "absolute-path",
+  WINDOWS_DRIVE_PATH: "windows-drive-path",
+  WINDOWS_PATH: "windows-path",
+  UNC_PATH: "unc-path",
+  PATH_TRAVERSAL: "path-traversal",
+  SYMLINK_ESCAPE: "symlink-escape",
+  REALPATH_ESCAPE: "realpath-escape",
+  INVALID_ROOT: "invalid-root",
+  ATOMIC_WRITE_FAILED: "atomic-write-failed",
+  READ_FAILED: "read-failed",
+  MISSING_RESOURCE: "missing-resource",
+  WORKSPACE_CREATE_FAILED: "workspace-create-failed",
+  WORKSPACE_DISPOSE_FAILED: "workspace-dispose-failed",
+  WORKSPACE_DISPOSED: "workspace-disposed",
+  CLOSURE_CONFLICT: "closure-conflict",
+  UNSUPPORTED_POLICY: "unsupported-policy",
+  EXECUTION_FAILED: "execution-failed",
+  INVALID_RESULT: "invalid-result",
+});
+
+/**
+ * Coded error for mechanism failures. The code must already exist in the
+ * frozen contracts registry; construction with anything else is a
+ * programming error and throws a TypeError immediately.
+ */
+export class HarnessError extends ContractsError {
+  constructor(code, message, details) {
+    if (!isRegisteredErrorCode(code)) {
+      throw new TypeError(
+        `HarnessError refuses unregistered error code: ${String(code)}`,
+      );
+    }
+    super(code, message, details);
+    this.name = "HarnessError";
+  }
+}
+
+/**
+ * Builds the canonical mechanism-failure error: SFC2004 with a stable
+ * details.kind. Extra structured evidence may be merged into details but can
+ * never override the kind.
+ */
+export function mechanismError(kind, message, extraDetails) {
+  const values = Object.values(HARNESS_ERROR_KINDS);
+  if (!values.includes(kind)) {
+    throw new TypeError(`mechanismError: unknown harness error kind: ${String(kind)}`);
+  }
+  const details = { ...(extraDetails ?? {}), kind };
+  return new HarnessError("SFC2004", message, details);
+}

package/src/index.mjs

@@ -0,0 +1,52 @@
+/**
+ * skill-family-harness-node: the default Node mechanism runtime for Skill
+ * Family engineering contracts.
+ *
+ * The harness is a thin runtime: it consumes skill-family-contracts (envelopes,
+ * schemas, dialect routing, kernel protocol, stable error codes, fixtures)
+ * and implements mechanism only — validator caching, contained filesystem
+ * access, atomic writes, temporary workspaces, resource closure, and the
+ * operation-request -> operation-result pipeline. It owns no business
+ * semantics, no orchestration, no git, no network, and no second language.
+ */
+
+export const HARNESS_CAPABILITIES = Object.freeze([
+  "schema-validation",
+  "atomic-write",
+  "path-containment",
+  "temporary-workspace",
+  "resource-closure",
+  "operation-envelope",
+]);
+
+export const HARNESS_EXCLUSIONS = Object.freeze([
+  "business-semantics",
+  "workflow-orchestration",
+  "git-writes",
+  "model-calls",
+  "release-state",
+  "remote-network-access",
+]);
+
+export { HarnessError, HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+
+export { classifyPathInput, resolveContained, readFileContained } from "./paths.mjs";
+
+export { writeFileAtomic } from "./atomic.mjs";
+
+export {
+  TemporaryWorkspace,
+  createTemporaryWorkspace,
+  withTemporaryWorkspace,
+} from "./workspace.mjs";
+
+export { digestBytes, computeResourceClosure, closureContains } from "./closure.mjs";
+
+export {
+  resolveSchemaContext,
+  getValidator,
+  validatorCacheSize,
+  validateContractDocument,
+} from "./validation.mjs";
+
+export { parseRequest, processRequest } from "./request.mjs";

package/src/paths.mjs

@@ -0,0 +1,285 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+
+/**
+ * Path containment.
+ *
+ * Every filesystem operation in the harness goes through resolveContained,
+ * which rejects three escape classes with stable, distinct kinds (all under
+ * the registered SFC2004 code):
+ *
+ * 1. path-traversal   — the lexically resolved target leaves the root
+ *                       (`..` segments, or any absolute input).
+ * 2. symlink-escape   — the final path component is a symbolic link whose
+ *                       real target lies outside the root.
+ * 3. realpath-escape  — the canonical (realpath) resolution of the target,
+ *                       including intermediate directories, lies outside the
+ *                       canonical root; this catches symlinked intermediate
+ *                       directories and chained links.
+ *
+ * Inputs that only make sense on another operating system (Windows drive
+ * paths, UNC paths, backslash separators on POSIX) are rejected before any
+ * resolution: ambiguous inputs never reach the filesystem.
+ *
+ * The containment guarantee is evaluated at call time (TOCTOU note: a
+ * process that can mutate the workspace between the check and the follow-up
+ * filesystem call is outside this mechanism's control; the guarantee is that
+ * the harness itself never performs an unchecked access).
+ */
+
+const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:/;
+const WINDOWS_UNC_PATTERN = /^\\\\/;
+const POSIX_UNC_PATTERN = /^\/\//;
+
+/**
+ * Classifies one candidate relative path without touching the filesystem.
+ * Returns { ok: true } or { ok: false, kind } where kind is one of the
+ * stable HARNESS_ERROR_KINDS values. Pure function of (input, platform), so
+ * the Windows-facing rules are testable on any host.
+ */
+export function classifyPathInput(input, platform = process.platform) {
+  if (typeof input !== "string") {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.INVALID_PATH };
+  }
+  if (input.length === 0) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.INVALID_PATH };
+  }
+  if (input.includes("\0")) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.INVALID_PATH };
+  }
+  if (platform === "win32") {
+    // Native separators are fine on Windows; containment is decided by the
+    // lexical + real checks. UNC paths address remote machines and are never
+    // containable; rooted paths (`\x`, `/x`, `<drive>:\x`) are absolute.
+    if (WINDOWS_UNC_PATTERN.test(input)) {
+      return { ok: false, kind: HARNESS_ERROR_KINDS.UNC_PATH };
+    }
+    if (input.startsWith("\\") || input.startsWith("/")) {
+      return { ok: false, kind: HARNESS_ERROR_KINDS.ABSOLUTE_PATH };
+    }
+    if (WINDOWS_DRIVE_PATTERN.test(input)) {
+      // `<drive>:\x` is absolute; the root-relative check would reject it too, but
+      // the explicit kind keeps the interception observable.
+      if (input.charAt(1) === ":" && /[\\/]/.test(input.charAt(2))) {
+        return { ok: false, kind: HARNESS_ERROR_KINDS.ABSOLUTE_PATH };
+      }
+      // Drive-relative forms (`C:foo`) depend on a per-drive working
+      // directory that this runtime never tracks: ambiguous, therefore
+      // rejected.
+      return { ok: false, kind: HARNESS_ERROR_KINDS.WINDOWS_DRIVE_PATH };
+    }
+    return { ok: true };
+  }
+  // POSIX (and every non-Windows host): a path is root-relative or nothing.
+  if (WINDOWS_DRIVE_PATTERN.test(input)) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.WINDOWS_DRIVE_PATH };
+  }
+  if (WINDOWS_UNC_PATTERN.test(input)) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.UNC_PATH };
+  }
+  if (POSIX_UNC_PATTERN.test(input)) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.UNC_PATH };
+  }
+  if (input.includes("\\")) {
+    // Backslash is a Windows separator; on POSIX it would silently become
+    // part of a filename. Cross-platform inputs must be unambiguous.
+    return { ok: false, kind: HARNESS_ERROR_KINDS.WINDOWS_PATH };
+  }
+  if (path.posix.isAbsolute(input)) {
+    return { ok: false, kind: HARNESS_ERROR_KINDS.ABSOLUTE_PATH };
+  }
+  return { ok: true };
+}
+
+function insideRoot(rootReal, candidate) {
+  const rel = path.relative(rootReal, candidate);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+// Anchors may coincide with the root itself (e.g. a top-level file whose
+// deepest existing ancestor is the workspace root); targets may not.
+function insideOrEqualRoot(rootReal, candidate) {
+  const rel = path.relative(rootReal, candidate);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+async function canonicalRoot(root) {
+  let rootReal;
+  try {
+    rootReal = await realpath(root);
+  } catch {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_ROOT,
+      "workspace root does not resolve to an existing path",
+      { root: "<opaque>" },
+    );
+  }
+  let rootStat;
+  try {
+    rootStat = await stat(rootReal);
+  } catch {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_ROOT,
+      "workspace root cannot be inspected",
+      { root: "<opaque>" },
+    );
+  }
+  if (!rootStat.isDirectory()) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_ROOT,
+      "workspace root is not a directory",
+      { root: "<opaque>" },
+    );
+  }
+  return rootReal;
+}
+
+async function deepestExistingAncestor(rootReal, absPath) {
+  let current = absPath;
+  const missing = [];
+  while (current.length >= rootReal.length) {
+    try {
+      await lstat(current);
+      return { anchor: current, missing };
+    } catch {
+      missing.unshift(path.basename(current));
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  // Unreachable for paths lexically inside an existing root; keep a coded
+  // failure instead of a crash.
+  throw mechanismError(
+    HARNESS_ERROR_KINDS.INVALID_ROOT,
+    "workspace root disappeared during containment resolution",
+  );
+}
+
+/**
+ * Resolves `relPath` against `root` and proves the target stays inside.
+ * Returns the absolute, lexically resolved path (strictly inside the root).
+ * Throws HarnessError (SFC2004) with a stable details.kind on any violation.
+ */
+export async function resolveContained(root, relPath) {
+  const classification = classifyPathInput(relPath);
+  if (!classification.ok) {
+    throw mechanismError(
+      classification.kind,
+      `path rejected before resolution (kind: ${classification.kind})`,
+      { input: typeof relPath === "string" ? relPath : typeof relPath },
+    );
+  }
+  const rootReal = await canonicalRoot(root);
+  const resolved = path.resolve(rootReal, relPath);
+  if (resolved === rootReal) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_PATH,
+      "path must address a resource strictly inside the workspace root",
+    );
+  }
+  if (!insideRoot(rootReal, resolved)) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.PATH_TRAVERSAL,
+      "resolved path leaves the workspace root",
+      { input: relPath },
+    );
+  }
+
+  // Escape class 2: the final component itself is a symlink pointing out.
+  let finalStat;
+  try {
+    finalStat = await lstat(resolved);
+  } catch (cause) {
+    if (cause && cause.code !== "ENOENT" && cause.code !== "ENOTDIR") {
+      throw mechanismError(HARNESS_ERROR_KINDS.READ_FAILED, `path cannot be inspected: ${cause.code}`);
+    }
+    finalStat = null;
+  }
+  if (finalStat && finalStat.isSymbolicLink()) {
+    let realTarget;
+    try {
+      realTarget = await realpath(resolved);
+    } catch {
+      // A broken symlink has no determinable target: never usable.
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.SYMLINK_ESCAPE,
+        "symbolic link target does not resolve; treated as an escape",
+        { input: relPath },
+      );
+    }
+    if (!insideRoot(rootReal, realTarget)) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.SYMLINK_ESCAPE,
+        "final path component is a symbolic link escaping the workspace root",
+        { input: relPath },
+      );
+    }
+  }
+
+  // Escape class 3: canonical resolution (any intermediate symlink chain)
+  // must stay inside the canonical root.
+  const { anchor, missing } = await deepestExistingAncestor(rootReal, resolved);
+  let anchorReal;
+  try {
+    anchorReal = await realpath(anchor);
+  } catch {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+      "anchor directory vanished during canonical resolution",
+      { input: relPath },
+    );
+  }
+  if (!insideOrEqualRoot(rootReal, anchorReal)) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+      "canonical anchor of the target lies outside the workspace root",
+      { input: relPath },
+    );
+  }
+  const canonical = path.join(anchorReal, ...missing);
+  if (!insideRoot(rootReal, canonical)) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+      "canonical target path leaves the workspace root",
+      { input: relPath },
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Contained read. Returns the file content as a Buffer (utf8 string when
+ * encoding is "utf8"). Missing resources surface as SFC2004 with the stable
+ * missing-resource kind instead of a raw fs error.
+ */
+export async function readFileContained(root, relPath, { encoding } = {}) {
+  const target = await resolveContained(root, relPath);
+  try {
+    return encoding === undefined
+      ? await readFile(target)
+      : await readFile(target, encoding);
+  } catch (cause) {
+    if (cause && cause.code === "ENOENT") {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.MISSING_RESOURCE,
+        "contained resource does not exist",
+        { input: relPath },
+      );
+    }
+    if (cause && cause.code === "EISDIR") {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.READ_FAILED,
+        "contained resource is a directory",
+        { input: relPath },
+      );
+    }
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.READ_FAILED,
+      `contained read failed: ${cause && cause.code ? cause.code : "unknown"}`,
+      { input: relPath },
+    );
+  }
+}