owlrunkit 0.13.0

package/packages/attest/src/reference-contract.mjs

@@ -0,0 +1,64 @@
+import {
+  decodeUtf8Strict,
+  hasExactKeys,
+  isPlainJsonObject,
+  isSha256Ref,
+  parseJsonStrict,
+  readFileBytesBounded,
+  sha256Bytes,
+} from "./formal.mjs";
+import { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
+
+export function referenceError(message) {
+  const error = new Error(message);
+  error.code = "receipt_schema_invalid";
+  return error;
+}
+
+export function readQuickReceiptFile(receiptPath) {
+  const { absolutePath, bytes } = readFileBytesBounded(receiptPath);
+  const receipt = parseJsonStrict(decodeUtf8Strict(bytes));
+  if (!isPlainJsonObject(receipt) || !validQuickReceiptShape(receipt)) {
+    throw referenceError("receipt does not satisfy Quick Receipt V1");
+  }
+  return { absolutePath, bytes, receipt };
+}
+
+export function createAttestationRef(receiptPath) {
+  const { bytes, receipt } = readQuickReceiptFile(receiptPath);
+  return {
+    schemaVersion: "OwlCodaAttestationRefV1",
+    receiptId: receipt.receiptId,
+    receiptSha256: sha256Bytes(bytes),
+    coreIdentity: {
+      contractVersion: receipt.coreIdentity.contractVersion,
+      coreManifestSha256: receipt.coreIdentity.coreManifestSha256,
+    },
+  };
+}
+
+export function parseAttestationRef(input) {
+  let value;
+  try {
+    value = typeof input === "string" ? parseJsonStrict(input) : input;
+  } catch (error) {
+    if (error?.code === "DUPLICATE_OBJECT_KEY") {
+      error.code = "receipt_duplicate_key";
+    }
+    throw error;
+  }
+  if (
+    !hasExactKeys(value, ["schemaVersion", "receiptId", "receiptSha256", "coreIdentity"])
+    || value.schemaVersion !== "OwlCodaAttestationRefV1"
+    || typeof value.receiptId !== "string"
+    || value.receiptId.length === 0
+    || !isSha256Ref(value.receiptSha256)
+    || !hasExactKeys(value.coreIdentity, ["contractVersion", "coreManifestSha256"])
+    || typeof value.coreIdentity.contractVersion !== "string"
+    || value.coreIdentity.contractVersion.length === 0
+    || !isSha256Ref(value.coreIdentity.coreManifestSha256)
+  ) {
+    throw referenceError("reference does not satisfy OwlCodaAttestationRefV1");
+  }
+  return value;
+}

package/packages/attest/src/reference.mjs

@@ -0,0 +1,131 @@
+import {
+  existsSync,
+  lstatSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import { sha256Bytes } from "./formal.mjs";
+import { attestQuickReceiptDetailsFromBytes } from "./quick.mjs";
+import {
+  createAttestationRef,
+  parseAttestationRef,
+  readQuickReceiptFile,
+  referenceError,
+} from "./reference-contract.mjs";
+
+export {
+  createAttestationRef,
+  parseAttestationRef,
+} from "./reference-contract.mjs";
+
+function withinRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== ""
+    && relative !== ".."
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+function safeQuickCandidate(store, receiptId) {
+  if (!/^[A-Za-z0-9._-]+$/.test(receiptId)) return null;
+  const rootStat = lstatSync(store);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return null;
+  const root = realpathSync(store);
+  const segments = ["quick", "receipts", receiptId, "receipt.json"];
+  let current = root;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    if (!existsSync(current)) return null;
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink()) return null;
+    if (segment === "receipt.json" ? !stat.isFile() : !stat.isDirectory()) return null;
+  }
+  const resolved = realpathSync(current);
+  return withinRoot(root, resolved) ? resolved : null;
+}
+
+function issue(code) {
+  return { code };
+}
+
+export function resolveAttestationRef({ reference, stores, workspaceRoot }) {
+  const parsed = parseAttestationRef(reference);
+  if (!Array.isArray(stores) || stores.length === 0) {
+    throw referenceError("at least one explicit local store is required");
+  }
+  const candidates = [];
+  for (const selectedStore of stores) {
+    if (typeof selectedStore !== "string" || selectedStore.length === 0) {
+      throw referenceError("store paths must be non-empty strings");
+    }
+    try {
+      const candidate = safeQuickCandidate(selectedStore, parsed.receiptId);
+      if (candidate !== null) candidates.push(candidate);
+    } catch {
+      continue;
+    }
+  }
+  const base = {
+    schemaVersion: "OwlCodaAttestationResolutionV1",
+    reference: parsed,
+    authorizationGranted: false,
+    networkRequests: 0,
+  };
+  if (candidates.length === 0) {
+    return {
+      ...base,
+      status: "not_found",
+      exitCode: 3,
+      issueCodes: ["attestation_target_not_found"],
+      candidates: [],
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      ...base,
+      status: "ambiguous",
+      exitCode: 1,
+      issueCodes: ["attestation_target_ambiguous"],
+      candidates,
+    };
+  }
+
+  const candidate = candidates[0];
+  const { bytes, receipt } = readQuickReceiptFile(candidate);
+  const actualHash = sha256Bytes(bytes);
+  const identityValid = receipt.receiptId === parsed.receiptId
+    && receipt.coreIdentity.contractVersion === parsed.coreIdentity.contractVersion
+    && receipt.coreIdentity.coreManifestSha256 === parsed.coreIdentity.coreManifestSha256;
+  if (actualHash !== parsed.receiptSha256 || !identityValid) {
+    return {
+      ...base,
+      status: "resolved_invalid",
+      exitCode: 1,
+      issueCodes: [
+        ...(actualHash === parsed.receiptSha256 ? [] : ["receipt_material_hash_mismatch"]),
+        ...(identityValid ? [] : ["core_identity_mismatch"]),
+      ],
+      candidates,
+    };
+  }
+  const details = attestQuickReceiptDetailsFromBytes({
+    receiptPath: candidate,
+    receiptBytes: bytes,
+    workspaceRoot,
+  });
+  return {
+    ...base,
+    status: details.attestation.decision === "GO"
+      ? "resolved_valid"
+      : details.attestation.decision === "INDETERMINATE"
+        ? "resolved_indeterminate"
+        : "resolved_invalid",
+    exitCode: details.attestation.decision === "GO" ? 0 : details.attestation.decision === "INDETERMINATE" ? 3 : 1,
+    issueCodes: details.attestation.issueCodes,
+    candidates,
+    receiptPath: candidate,
+    receiptSha256: actualHash,
+    attestation: details.attestation,
+  };
+}

package/packages/attest/src/workspace-snapshot.mjs

@@ -0,0 +1,171 @@
+import { execFileSync } from "node:child_process";
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+import { sha256Bytes, sha256Canonical } from "./formal.mjs";
+
+const CONTROL_ROOT = ".owlcoda/runkit";
+const LOCKFILE_NAMES = new Set([
+  "bun.lock",
+  "bun.lockb",
+  "Cargo.lock",
+  "composer.lock",
+  "Gemfile.lock",
+  "go.sum",
+  "npm-shrinkwrap.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "poetry.lock",
+  "uv.lock",
+  "yarn.lock",
+]);
+
+function git(root, args, options = {}) {
+  return execFileSync("git", args, {
+    cwd: root,
+    encoding: options.encoding ?? "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      GIT_OPTIONAL_LOCKS: "0",
+    },
+  });
+}
+
+function optionalGit(root, args) {
+  try {
+    return git(root, args).trim();
+  } catch {
+    return "";
+  }
+}
+
+function normalizePath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function isControlPath(value) {
+  return value === CONTROL_ROOT || value.startsWith(`${CONTROL_ROOT}/`);
+}
+
+function fileHash(root, relativePath) {
+  const absolutePath = path.resolve(root, relativePath);
+  const stat = lstatSync(absolutePath);
+  if (stat.isSymbolicLink()) {
+    return sha256Bytes(Buffer.from(`symlink:${readlinkSync(absolutePath)}`, "utf8"));
+  }
+  if (stat.isDirectory()) {
+    const commit = optionalGit(absolutePath, ["rev-parse", "HEAD"]);
+    return sha256Canonical({
+      algorithm: "gitlink-worktree-v1",
+      commit,
+      dirtyOverlay: parseStatus(absolutePath),
+      submodules: submodules(absolutePath),
+    });
+  }
+  return sha256Bytes(readFileSync(absolutePath));
+}
+
+function parseStatus(root) {
+  const raw = git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  const fields = raw.split("\0");
+  const entries = new Map();
+  for (let index = 0; index < fields.length; index += 1) {
+    const field = fields[index];
+    if (!field) continue;
+    const status = field.slice(0, 2);
+    const currentPath = normalizePath(field.slice(3));
+    if (status.includes("R") || status.includes("C")) index += 1;
+    if (!currentPath || isControlPath(currentPath)) continue;
+    let state = "modified";
+    if (status === "??") state = "untracked";
+    if (status.includes("D")) state = "deleted";
+    let sha256 = null;
+    if (state !== "deleted") {
+      try {
+        sha256 = fileHash(root, currentPath);
+      } catch {
+        state = "deleted";
+      }
+    }
+    entries.set(currentPath, { path: currentPath, state, sha256 });
+  }
+  return [...entries.values()].sort((left, right) => left.path.localeCompare(right.path, "en"));
+}
+
+function submodules(root) {
+  const output = optionalGit(root, ["submodule", "status", "--recursive"]);
+  if (!output) return [];
+  return output
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const match = /^[ +-U]?([0-9a-f]{40,64})\s+([^\s]+)/.exec(line);
+      if (!match) throw new Error(`Cannot parse git submodule status: ${line}`);
+      return { path: normalizePath(match[2]), commit: match[1] };
+    })
+    .sort((left, right) => left.path.localeCompare(right.path, "en"));
+}
+
+function dependencyLockfiles(root) {
+  const raw = git(root, ["ls-files", "-co", "--exclude-standard", "-z"]);
+  return raw
+    .split("\0")
+    .filter(Boolean)
+    .map(normalizePath)
+    .filter((entry) => !isControlPath(entry) && LOCKFILE_NAMES.has(path.posix.basename(entry)))
+    .sort((left, right) => left.localeCompare(right, "en"))
+    .map((entry) => ({ path: entry, sha256: fileHash(root, entry) }));
+}
+
+function sanitizedRemoteIdentity(remote) {
+  try {
+    const parsed = new URL(remote);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return remote.replace(/^[^/@\s]+@(?=[^/\s]+:)/, "");
+  }
+}
+
+function repositoryIdentity(root) {
+  const remote = optionalGit(root, ["remote", "get-url", "origin"]);
+  if (remote) return sanitizedRemoteIdentity(remote);
+  return `local:${realpathSync(root)}`;
+}
+
+function trackedTreeIdentity(root, headCommit) {
+  const tree = headCommit ? git(root, ["rev-parse", "HEAD^{tree}"]).trim() : "";
+  const objectFormat = optionalGit(root, ["rev-parse", "--show-object-format"]) || "sha1";
+  return sha256Canonical({
+    algorithm: "git-tree-object-v1",
+    objectFormat,
+    tree,
+  });
+}
+
+export function captureWorkspaceSnapshot(workspaceRoot) {
+  const root = realpathSync(workspaceRoot);
+  git(root, ["rev-parse", "--is-inside-work-tree"]);
+  const headCommit = optionalGit(root, ["rev-parse", "HEAD"]) || null;
+  const payload = {
+    schemaVersion: "OwlCodaWorkspaceSnapshotV1",
+    repositoryIdentity: repositoryIdentity(root),
+    headCommit,
+    trackedTreeIdentity: trackedTreeIdentity(root, headCommit),
+    submodules: submodules(root),
+    dirtyOverlay: parseStatus(root),
+    dependencyLockfiles: dependencyLockfiles(root),
+    excludedRoots: [CONTROL_ROOT],
+    ignoredPathsBound: false,
+    policyVersion: "workspace-snapshot-v1",
+  };
+  return {
+    ...payload,
+    sourceFingerprint: sha256Canonical(payload),
+  };
+}

package/registry-release-policy-v1.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV1",
+  "status": "release_candidate_unpublished",
+  "packageName": "owlrunkit",
+  "candidateVersion": "0.13.0",
+  "registry": "https://registry.npmjs.org",
+  "registryRequiredBeforeAdoption": true,
+  "exactVersionRequired": true,
+  "requiredRegistryBindings": [
+    "packageName",
+    "version",
+    "shasum",
+    "integrity",
+    "tarballUrl"
+  ],
+  "forbiddenAdoptionSources": [
+    "directory",
+    "file",
+    "git",
+    "local_tarball",
+    "symlink",
+    "workspace"
+  ],
+  "currentPublishedRelease": null,
+  "registryRelease": null,
+  "registryEvidenceMustBeExternal": true,
+  "registryEvidenceSchemaVersion": "OwlCodaRunKitRegistryReleaseEvidenceV1",
+  "embeddedAttestComponentVersion": "0.2.0",
+  "standaloneAttestPublicationRequired": false,
+  "signatureRequired": false,
+  "githubActionRequired": false,
+  "foreignProjectWriteAuthorized": false,
+  "authorizationGranted": false
+}

package/sbom.spdx.json

@@ -0,0 +1,39 @@
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "owlrunkit-0.13.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.13.0",
+  "creationInfo": {
+    "created": "2026-07-29T00:00:00Z",
+    "creators": [
+      "Organization: OwlCoda"
+    ]
+  },
+  "packages": [
+    {
+      "name": "owlrunkit",
+      "SPDXID": "SPDXRef-Package-OwlRunKit",
+      "versionInfo": "0.13.0",
+      "downloadLocation": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.13.0.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "GPL-3.0-or-later",
+      "licenseDeclared": "GPL-3.0-or-later",
+      "copyrightText": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/owlrunkit@0.13.0"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "spdxElementId": "SPDXRef-DOCUMENT",
+      "relationshipType": "DESCRIBES",
+      "relatedSpdxElement": "SPDXRef-Package-OwlRunKit"
+    }
+  ]
+}

package/scripts/runkit-contract/acceptance-evidence.mjs

@@ -0,0 +1,103 @@
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateAllowedKeys(value, label, allowedKeys) {
+  if (!isRecord(value)) return [];
+  const allowed = new Set(allowedKeys);
+  return Object.keys(value)
+    .filter((key) => !allowed.has(key))
+    .map((key) => `${label} contains unsupported field: ${key}`);
+}
+
+function validateVersionEntries(values, label) {
+  if (!Array.isArray(values)) return [`${label} must be an array.`];
+  const issues = [];
+  for (const [index, value] of values.entries()) {
+    if (!isRecord(value)
+      || typeof value.name !== "string"
+      || value.name.length === 0
+      || typeof value.version !== "string"
+      || value.version.length === 0) {
+      issues.push(`${label}[${index}] requires name and version.`);
+    } else {
+      issues.push(...validateAllowedKeys(value, `${label}[${index}]`, ["name", "version"]));
+    }
+  }
+  return issues;
+}
+
+function validateHashEntries(values, label, identityField) {
+  if (!Array.isArray(values)) return [`${label} must be an array.`];
+  const issues = [];
+  for (const [index, value] of values.entries()) {
+    if (!isRecord(value)
+      || typeof value[identityField] !== "string"
+      || value[identityField].length === 0
+      || typeof value.sha256 !== "string"
+      || !SHA256_PATTERN.test(value.sha256)) {
+      issues.push(`${label}[${index}] requires ${identityField} and lowercase sha256.`);
+    } else {
+      issues.push(...validateAllowedKeys(value, `${label}[${index}]`, [identityField, "sha256"]));
+    }
+  }
+  return issues;
+}
+
+export function validateReplayableEvidence(evidence) {
+  if (!isRecord(evidence)) {
+    return { valid: false, issues: ["Replayable evidence must be an object."] };
+  }
+  const issues = validateAllowedKeys(evidence, "Replayable evidence", [
+    "schemaVersion",
+    "kind",
+    "cwd",
+    "launcher",
+    "argv",
+    "automationManifestSha256",
+    "toolVersions",
+    "materialInputs",
+    "outputArtifacts",
+  ]);
+  if (evidence.schemaVersion !== "OwlCodaRunKitReplayableEvidenceV1") {
+    issues.push("Unsupported replayable evidence schemaVersion.");
+  }
+  if (!new Set(["shell", "automation"]).has(evidence.kind)) {
+    issues.push("Replayable evidence kind must be shell or automation.");
+  }
+  if (typeof evidence.cwd !== "string" || evidence.cwd.length === 0) {
+    issues.push("Replayable evidence requires cwd.");
+  }
+  if (!isRecord(evidence.launcher)
+    || typeof evidence.launcher.executable !== "string"
+    || evidence.launcher.executable.length === 0
+    || typeof evidence.launcher.version !== "string"
+    || evidence.launcher.version.length === 0) {
+    issues.push("Replayable evidence requires launcher executable and version.");
+  } else {
+    issues.push(...validateAllowedKeys(evidence.launcher, "launcher", ["executable", "version"]));
+  }
+  issues.push(...validateVersionEntries(evidence.toolVersions, "toolVersions"));
+  issues.push(...validateHashEntries(evidence.materialInputs, "materialInputs", "id"));
+  issues.push(...validateHashEntries(evidence.outputArtifacts, "outputArtifacts", "path"));
+  if (evidence.kind === "shell") {
+    if (!Array.isArray(evidence.argv)
+      || evidence.argv.length === 0
+      || typeof evidence.argv[0] !== "string"
+      || evidence.argv[0].length === 0
+      || evidence.argv.some((value) => typeof value !== "string")) {
+      issues.push("Shell evidence requires exact argv with a non-empty executable.");
+    }
+  } else if (evidence.kind === "automation") {
+    if (typeof evidence.automationManifestSha256 !== "string"
+      || !SHA256_PATTERN.test(evidence.automationManifestSha256)) {
+      issues.push("Automation evidence requires automationManifestSha256.");
+    }
+    if (!Array.isArray(evidence.outputArtifacts) || evidence.outputArtifacts.length === 0) {
+      issues.push("Automation evidence requires at least one output artifact.");
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}