mdkg 0.1.1 → 0.1.3

package/dist/graph/agent_file_types.js

@@ -10,6 +10,7 @@ exports.validateAgentFrontmatter = validateAgentFrontmatter;
 exports.extractAgentAttributes = extractAgentAttributes;
 const path_1 = __importDefault(require("path"));
 const id_1 = require("../util/id");
+const refs_1 = require("../util/refs");
 exports.AGENT_FILE_TYPES = [
     "spec",
     "work",
@@ -67,6 +68,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "requester",
         "order_status",
         "request_ref",
+        "input_refs",
+        "requested_outputs",
+        "constraint_refs",
+        "artifact_policy",
     ],
     receipt: [
         "version",
@@ -74,6 +79,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "receipt_status",
         "outcome",
         "cost_ref",
+        "proof_refs",
+        "attestation_refs",
+        "input_hashes",
+        "output_hashes",
     ],
     feedback: [
         "version",
@@ -135,8 +144,13 @@ const ORDER_STATUS_VALUES = new Set([
     "cancelled",
     "failed",
 ]);
-const RECEIPT_STATUS_VALUES = new Set(["recorded", "verified", "rejected"]);
+const RECEIPT_STATUS_VALUES = new Set(["recorded", "verified", "rejected", "superseded"]);
 const OUTCOME_VALUES = new Set(["success", "partial", "failure"]);
+const ARTIFACT_POLICY_VALUES = new Set([
+    "commit_sidecar_and_zip",
+    "external_only",
+    "local_only",
+]);
 const SENTIMENT_VALUES = new Set(["positive", "neutral", "negative", "mixed"]);
 const FEEDBACK_STATUS_VALUES = new Set(["new", "triaged", "accepted", "rejected"]);
 const DISPUTE_STATUS_VALUES = new Set(["open", "investigating", "resolved", "rejected"]);
@@ -190,6 +204,23 @@ function optionalString(frontmatter, key, filePath) {
     }
     return value;
 }
+function expectRefString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw formatError(filePath, `${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function optionalRefString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw formatError(filePath, `${key} must be a non-empty string`);
+    }
+    return value;
+}
 function expectBoolean(frontmatter, key, filePath) {
     const value = frontmatter[key];
     if (typeof value !== "boolean") {
@@ -254,6 +285,31 @@ function validatePortableRefs(values, key, filePath) {
         }
     }
 }
+function validatePortableOrUriRefs(values, key, filePath) {
+    for (const [index, value] of values.entries()) {
+        if (!(0, refs_1.validatePortableOrUriRef)(value)) {
+            throw formatError(filePath, `${key}[${index}] must be a portable id or URI ref`);
+        }
+    }
+}
+function validatePortableOrUriScalar(value, key, filePath) {
+    if (!(0, refs_1.validatePortableOrUriRef)(value)) {
+        throw formatError(filePath, `${key} must be a portable id or URI ref`);
+    }
+}
+function validateOptionalFieldDescriptors(values, key, filePath) {
+    if (values.length === 0) {
+        return;
+    }
+    validateFieldDescriptors(values, key, filePath);
+}
+function validateHashRefs(values, key, filePath) {
+    for (const [index, value] of values.entries()) {
+        if (!(0, refs_1.isSha256Ref)(value)) {
+            throw formatError(filePath, `${key}[${index}] must be sha256:<64 lowercase hex chars>`);
+        }
+    }
+}
 function validateRelativeMarkdownPaths(values, key, basename, filePath) {
     for (const [index, value] of values.entries()) {
         if (path_1.default.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
@@ -327,11 +383,21 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             requirePortableId(workId, "work_id", filePath);
             const workVersion = expectString(frontmatter, "work_version", filePath);
             requireSemver(workVersion, "work_version", filePath);
-            const requester = expectString(frontmatter, "requester", filePath);
-            requirePortableId(requester, "requester", filePath);
+            const requester = expectRefString(frontmatter, "requester", filePath);
+            validatePortableOrUriScalar(requester, "requester", filePath);
             const orderStatus = expectString(frontmatter, "order_status", filePath);
             requireEnum(orderStatus, "order_status", ORDER_STATUS_VALUES, filePath);
-            optionalString(frontmatter, "request_ref", filePath);
+            const requestRef = optionalRefString(frontmatter, "request_ref", filePath);
+            if (requestRef) {
+                validatePortableOrUriScalar(requestRef, "request_ref", filePath);
+            }
+            validatePortableOrUriRefs(optionalList(frontmatter, "input_refs", filePath), "input_refs", filePath);
+            validateOptionalFieldDescriptors(optionalList(frontmatter, "requested_outputs", filePath), "requested_outputs", filePath);
+            validatePortableOrUriRefs(optionalList(frontmatter, "constraint_refs", filePath), "constraint_refs", filePath);
+            const artifactPolicy = optionalString(frontmatter, "artifact_policy", filePath);
+            if (artifactPolicy) {
+                requireEnum(artifactPolicy, "artifact_policy", ARTIFACT_POLICY_VALUES, filePath);
+            }
             break;
         }
         case "receipt": {
@@ -341,7 +407,14 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             requireEnum(receiptStatus, "receipt_status", RECEIPT_STATUS_VALUES, filePath);
             const outcome = expectString(frontmatter, "outcome", filePath);
             requireEnum(outcome, "outcome", OUTCOME_VALUES, filePath);
-            optionalString(frontmatter, "cost_ref", filePath);
+            const costRef = optionalRefString(frontmatter, "cost_ref", filePath);
+            if (costRef) {
+                validatePortableOrUriScalar(costRef, "cost_ref", filePath);
+            }
+            validatePortableOrUriRefs(optionalList(frontmatter, "proof_refs", filePath), "proof_refs", filePath);
+            validatePortableOrUriRefs(optionalList(frontmatter, "attestation_refs", filePath), "attestation_refs", filePath);
+            validateHashRefs(optionalList(frontmatter, "input_hashes", filePath), "input_hashes", filePath);
+            validateHashRefs(optionalList(frontmatter, "output_hashes", filePath), "output_hashes", filePath);
             break;
         }
         case "feedback": {

package/dist/graph/archive_file.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARCHIVE_ATTRIBUTE_KEY_ORDER = void 0;
+exports.isArchiveType = isArchiveType;
+exports.validateArchiveFrontmatter = validateArchiveFrontmatter;
+exports.extractArchiveAttributes = extractArchiveAttributes;
+const path_1 = __importDefault(require("path"));
+const archive_integrity_1 = require("./archive_integrity");
+const id_1 = require("../util/id");
+exports.ARCHIVE_ATTRIBUTE_KEY_ORDER = [
+    "archive_kind",
+    "source_path",
+    "stored_path",
+    "compressed_path",
+    "mime_type",
+    "byte_size",
+    "sha256",
+    "compressed_sha256",
+    "visibility",
+    "provenance",
+    "ingest_status",
+];
+const ARCHIVE_KIND_VALUES = new Set(["source", "artifact"]);
+const VISIBILITY_VALUES = new Set(["private", "internal", "public"]);
+const INGEST_STATUS_VALUES = new Set(["pending", "ingested", "compressed", "verified", "failed"]);
+const SHA256_RE = /^sha256:[a-f0-9]{64}$/;
+const MIME_RE = /^[a-z0-9.+-]+\/[a-z0-9.+-]+$/;
+function formatError(filePath, message) {
+    return new Error(`${filePath}: ${message}`);
+}
+function expectString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw formatError(filePath, `${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function requireEnum(value, key, allowed, filePath) {
+    if (!allowed.has(value)) {
+        throw formatError(filePath, `${key} must be one of ${Array.from(allowed).join(", ")}`);
+    }
+}
+function requireRelativePath(value, key, filePath) {
+    if (path_1.default.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
+        throw formatError(filePath, `${key} must be a relative path`);
+    }
+}
+function requireSha256(value, key, filePath) {
+    if (!SHA256_RE.test(value)) {
+        throw formatError(filePath, `${key} must be sha256:<64 lowercase hex chars>`);
+    }
+}
+function isArchiveType(type) {
+    return type === "archive";
+}
+function validateArchiveFrontmatter(type, frontmatter, filePath) {
+    if (!isArchiveType(type)) {
+        return;
+    }
+    const id = expectString(frontmatter, "id", filePath);
+    if (id !== id.toLowerCase() || !(0, id_1.isPortableId)(id) || !id.startsWith("archive.")) {
+        throw formatError(filePath, "id must be a lowercase portable archive id like archive.example");
+    }
+    const archiveKind = expectString(frontmatter, "archive_kind", filePath);
+    requireEnum(archiveKind, "archive_kind", ARCHIVE_KIND_VALUES, filePath);
+    const sourcePath = expectString(frontmatter, "source_path", filePath);
+    if (sourcePath.includes("\0")) {
+        throw formatError(filePath, "source_path must not contain NUL bytes");
+    }
+    if (path_1.default.isAbsolute(sourcePath) || sourcePath.split(/[\\/]/).includes("..")) {
+        throw formatError(filePath, "source_path must be repo-relative or external:<label>");
+    }
+    const storedPath = expectString(frontmatter, "stored_path", filePath);
+    requireRelativePath(storedPath, "stored_path", filePath);
+    const compressedPath = expectString(frontmatter, "compressed_path", filePath);
+    requireRelativePath(compressedPath, "compressed_path", filePath);
+    const mimeType = expectString(frontmatter, "mime_type", filePath);
+    if (!MIME_RE.test(mimeType)) {
+        throw formatError(filePath, "mime_type must look like type/subtype");
+    }
+    const byteSize = expectString(frontmatter, "byte_size", filePath);
+    if (!/^[0-9]+$/.test(byteSize)) {
+        throw formatError(filePath, "byte_size must be a non-negative integer string");
+    }
+    const sourceHash = expectString(frontmatter, "sha256", filePath);
+    requireSha256(sourceHash, "sha256", filePath);
+    const compressedHash = expectString(frontmatter, "compressed_sha256", filePath);
+    requireSha256(compressedHash, "compressed_sha256", filePath);
+    const visibility = expectString(frontmatter, "visibility", filePath);
+    requireEnum(visibility, "visibility", VISIBILITY_VALUES, filePath);
+    const provenance = expectString(frontmatter, "provenance", filePath);
+    if (provenance.trim().length === 0) {
+        throw formatError(filePath, "provenance must not be empty");
+    }
+    const ingestStatus = expectString(frontmatter, "ingest_status", filePath);
+    requireEnum(ingestStatus, "ingest_status", INGEST_STATUS_VALUES, filePath);
+    const sidecarDir = path_1.default.dirname(filePath);
+    const checked = (0, archive_integrity_1.checkArchiveIntegrity)({
+        root: sidecarDir,
+        rawPath: path_1.default.resolve(sidecarDir, storedPath),
+        zipPath: path_1.default.resolve(sidecarDir, compressedPath),
+        expectedRawHash: sourceHash,
+        expectedCompressedHash: compressedHash,
+        expectedByteSize: byteSize,
+    });
+    if (!checked.ok) {
+        throw formatError(filePath, checked.errors.join("; "));
+    }
+}
+function extractArchiveAttributes(type, frontmatter) {
+    if (!isArchiveType(type)) {
+        return {};
+    }
+    const attributes = {};
+    for (const key of exports.ARCHIVE_ATTRIBUTE_KEY_ORDER) {
+        const value = frontmatter[key];
+        if (value !== undefined) {
+            attributes[key] = value;
+        }
+    }
+    return attributes;
+}

package/dist/graph/archive_integrity.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashArchiveBuffer = hashArchiveBuffer;
+exports.hashArchiveFile = hashArchiveFile;
+exports.checkArchiveIntegrity = checkArchiveIntegrity;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const zip_1 = require("../util/zip");
+function hashArchiveBuffer(buffer) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(buffer).digest("hex")}`;
+}
+function hashArchiveFile(filePath) {
+    return hashArchiveBuffer(fs_1.default.readFileSync(filePath));
+}
+function relativeLabel(root, filePath) {
+    return path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+}
+function checkArchiveIntegrity(options) {
+    const result = {
+        ok: true,
+        raw_present: false,
+        compressed_present: false,
+        errors: [],
+    };
+    if (!fs_1.default.existsSync(options.zipPath)) {
+        result.errors.push(`compressed cache missing: ${relativeLabel(options.root, options.zipPath)}`);
+    }
+    else {
+        result.compressed_present = true;
+        const actualCompressedHash = hashArchiveFile(options.zipPath);
+        if (actualCompressedHash !== options.expectedCompressedHash) {
+            result.errors.push(`compressed_sha256 mismatch: ${actualCompressedHash}`);
+        }
+        try {
+            const unzipped = (0, zip_1.readSingleFileZip)(fs_1.default.readFileSync(options.zipPath));
+            const unzippedHash = hashArchiveBuffer(unzipped.data);
+            if (unzippedHash !== options.expectedRawHash) {
+                result.errors.push(`zip payload sha256 mismatch: ${unzippedHash}`);
+            }
+            if (String(unzipped.data.length) !== options.expectedByteSize) {
+                result.errors.push(`zip payload byte_size mismatch: ${unzipped.data.length}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.errors.push(`zip read failed: ${message}`);
+        }
+    }
+    if (fs_1.default.existsSync(options.rawPath)) {
+        result.raw_present = true;
+        const actualRawHash = hashArchiveFile(options.rawPath);
+        if (actualRawHash !== options.expectedRawHash) {
+            result.errors.push(`raw sha256 mismatch: ${actualRawHash}`);
+        }
+        const actualByteSize = String(fs_1.default.statSync(options.rawPath).size);
+        if (actualByteSize !== options.expectedByteSize) {
+            result.errors.push(`raw byte_size mismatch: ${actualByteSize}`);
+        }
+    }
+    result.ok = result.errors.length === 0;
+    return result;
+}