@dailephd/my-dev-kit-lab 0.4.2 → 0.4.4

package/dist/src/evaluation/targetImmutability/validateTargetImmutabilityConfig.js

@@ -0,0 +1,130 @@
+const ALLOWED_KEYS = ["targetRootPath", "relativeFilePaths"];
+const MAX_RELATIVE_FILES = 100;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAbsolutePathLike(value) {
+    if (value.startsWith("/") || value.startsWith("\\"))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(value))
+        return true;
+    return false;
+}
+function hasTraversalSegment(value) {
+    return value.split(/[\\/]/).includes("..");
+}
+export function validateTargetImmutabilityConfig(value) {
+    if (!isPlainObject(value)) {
+        return {
+            ok: false,
+            issues: [{ code: "NON_OBJECT_CONFIG", fieldPath: "", message: "Target immutability config must be an object." }]
+        };
+    }
+    const root = value;
+    const issues = [];
+    for (const key of Object.keys(root)) {
+        if (!ALLOWED_KEYS.includes(key)) {
+            issues.push({ code: "UNKNOWN_CONFIG_FIELD", fieldPath: key, message: `"${key}" is not a recognized field.` });
+        }
+    }
+    if (root.targetRootPath === undefined) {
+        issues.push({ code: "MISSING_REQUIRED_FIELD", fieldPath: "targetRootPath", message: "targetRootPath is required." });
+    }
+    if (root.relativeFilePaths === undefined) {
+        issues.push({ code: "MISSING_REQUIRED_FIELD", fieldPath: "relativeFilePaths", message: "relativeFilePaths is required." });
+    }
+    const targetRootPathIsString = root.targetRootPath !== undefined && typeof root.targetRootPath === "string";
+    if (root.targetRootPath !== undefined && !targetRootPathIsString) {
+        issues.push({ code: "INVALID_FIELD_TYPE", fieldPath: "targetRootPath", message: "targetRootPath must be a string." });
+    }
+    const relativeFilePathsIsArray = root.relativeFilePaths !== undefined && Array.isArray(root.relativeFilePaths);
+    if (root.relativeFilePaths !== undefined && !relativeFilePathsIsArray) {
+        issues.push({ code: "INVALID_FIELD_TYPE", fieldPath: "relativeFilePaths", message: "relativeFilePaths must be an array." });
+    }
+    if (targetRootPathIsString && root.targetRootPath.trim().length === 0) {
+        issues.push({ code: "EMPTY_TARGET_ROOT_PATH", fieldPath: "targetRootPath", message: "targetRootPath must be a nonempty string." });
+    }
+    let pathsArray = [];
+    if (relativeFilePathsIsArray) {
+        pathsArray = root.relativeFilePaths;
+        if (pathsArray.length === 0) {
+            issues.push({
+                code: "EMPTY_RELATIVE_FILE_SET",
+                fieldPath: "relativeFilePaths",
+                message: "relativeFilePaths must contain at least one entry."
+            });
+        }
+        else if (pathsArray.length > MAX_RELATIVE_FILES) {
+            issues.push({
+                code: "TOO_MANY_RELATIVE_FILES",
+                fieldPath: "relativeFilePaths",
+                message: `relativeFilePaths must contain at most ${MAX_RELATIVE_FILES} entries.`
+            });
+        }
+    }
+    const validStringPaths = [];
+    if (relativeFilePathsIsArray) {
+        pathsArray.forEach((entry, index) => {
+            if (typeof entry !== "string") {
+                issues.push({
+                    code: "INVALID_FIELD_TYPE",
+                    fieldPath: `relativeFilePaths[${index}]`,
+                    message: `relativeFilePaths[${index}] must be a string.`
+                });
+                validStringPaths.push(null);
+            }
+            else if (entry.trim().length === 0) {
+                issues.push({
+                    code: "EMPTY_RELATIVE_FILE_PATH",
+                    fieldPath: `relativeFilePaths[${index}]`,
+                    message: `relativeFilePaths[${index}] must be a nonempty string.`
+                });
+                validStringPaths.push(null);
+            }
+            else {
+                validStringPaths.push(entry);
+            }
+        });
+    }
+    if (relativeFilePathsIsArray) {
+        validStringPaths.forEach((entry, index) => {
+            if (entry !== null && isAbsolutePathLike(entry)) {
+                issues.push({
+                    code: "ABSOLUTE_RELATIVE_FILE_PATH",
+                    fieldPath: `relativeFilePaths[${index}]`,
+                    message: `relativeFilePaths[${index}] must be a relative path.`
+                });
+            }
+        });
+    }
+    if (relativeFilePathsIsArray) {
+        validStringPaths.forEach((entry, index) => {
+            if (entry !== null && hasTraversalSegment(entry)) {
+                issues.push({
+                    code: "RELATIVE_FILE_PATH_TRAVERSAL",
+                    fieldPath: `relativeFilePaths[${index}]`,
+                    message: `relativeFilePaths[${index}] must not contain a ".." path segment.`
+                });
+            }
+        });
+    }
+    if (relativeFilePathsIsArray) {
+        const seen = new Set();
+        validStringPaths.forEach((entry, index) => {
+            if (entry === null)
+                return;
+            if (seen.has(entry)) {
+                issues.push({
+                    code: "DUPLICATE_RELATIVE_FILE_PATH",
+                    fieldPath: `relativeFilePaths[${index}]`,
+                    message: `relativeFilePaths[${index}] duplicates an earlier entry.`
+                });
+            }
+            seen.add(entry);
+        });
+    }
+    if (issues.length > 0) {
+        return { ok: false, issues };
+    }
+    return { ok: true, config: value };
+}

package/dist/src/evaluation/upstreamArtifacts/artifactReadTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/index.js

@@ -0,0 +1,9 @@
+export { readMyDevKitContextCapsuleV1 } from "./readMyDevKitContextCapsuleV1.js";
+export { readMyDevKitRetrievalAuditRecordV1 } from "./readMyDevKitRetrievalAuditRecordV1.js";
+export { readOrchestratorWorkflowInstructionPacketV1 } from "./readOrchestratorWorkflowInstructionPacketV1.js";
+export { ROLE_BY_DOCUMENT_KIND, REQUIRED_METADATA_BY_DOCUMENT_KIND, REQUIRED_SECTIONS_BY_DOCUMENT_KIND, VALID_REPOSITORY_SCOPES, VALID_DECLARED_STATUSES, VALID_FRESHNESS_VALUES, VALID_ADEQUACY_VALUES, VALID_TRUNCATION_VALUES } from "./supplementalContextTypes.js";
+export { readImplementationContextPacketV1 } from "./readImplementationContextPacketV1.js";
+export { readImplementationContextRetrievalReportV1 } from "./readImplementationContextRetrievalReportV1.js";
+export { readTestContextPacketV1 } from "./readTestContextPacketV1.js";
+export { readTestContextRetrievalReportV1 } from "./readTestContextRetrievalReportV1.js";
+export { READINESS_DECISIONS, READINESS_CLASSIFICATIONS, validateOrchestratorContextReadinessResultV1, checkSupplementalReadinessIdentityConsistency } from "./orchestratorContextReadinessResultV1.js";

package/dist/src/evaluation/upstreamArtifacts/jsonTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/myDevKitClassificationTypesV1.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/myDevKitContextArtifactsV1.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/myDevKitSemanticTypesV1.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/orchestratorContextReadinessResultV1.js

@@ -0,0 +1,247 @@
+// Lab-owned bounded plain-object adapter for the frozen my-dev-kit-orchestrator
+// ContextReadinessResult (commit bc08a05d3b52a629e7e4504372af199c324c4ae4,
+// src/instructions/contextReadiness.ts). At the frozen commit, readiness is never
+// serialized to a stable file artifact -- `check`/`export` only render it as formatted
+// text (src/commands/check.ts, src/commands/export.ts). This adapter therefore
+// validates and normalizes a plain object (as constructed by a caller that already has
+// an in-memory readiness result -- e.g. a future integration or a test fixture), rather
+// than parsing a file. It never imports orchestrator runtime code and never
+// recomputes/reevaluates readiness, producer parity, or issue prioritization -- it only
+// preserves what is already declared on the object.
+import { makeFailure } from "./runtimeValidation.js";
+import { VALID_ADEQUACY_VALUES, VALID_FRESHNESS_VALUES, VALID_TRUNCATION_VALUES } from "./supplementalContextTypes.js";
+const ARTIFACT_KIND = "orchestrator-context-readiness-result-v1";
+export const READINESS_DECISIONS = ["not-required", "ready", "refresh-required"];
+export const READINESS_CLASSIFICATIONS = [
+    "not-required",
+    "ready",
+    "missing",
+    "template",
+    "partial",
+    "malformed",
+    "unsupported-schema",
+    "incompatible",
+    "source-reference-missing",
+    "source-reference-unreadable",
+    "source-evidence-malformed",
+    "source-evidence-unsupported-schema",
+    "role-mismatch",
+    "repository-scope-mismatch",
+    "repository-identity-incomplete",
+    "index-identity-incomplete",
+    "index-identity-mismatch",
+    "freshness-unknown",
+    "stale",
+    "adequacy-unknown",
+    "inadequate",
+    "conflict",
+    "required-evidence-truncated",
+    "required-evidence-incomplete",
+    "provenance-missing",
+    "test-strategy-missing",
+    "test-responsibility-invalid",
+    "test-responsibility-criticality-unknown",
+    "responsibility-mappings-truncated",
+    "critical-responsibilities-unmapped"
+];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(sourceLabel, code, message, fieldPath) {
+    return makeFailure(ARTIFACT_KIND, sourceLabel, code, message, fieldPath);
+}
+function requireEnum(value, allowed, fieldPath, sourceLabel, errorCode) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        return fail(sourceLabel, errorCode, `Field "${fieldPath}" must be one of: ${allowed.join(", ")}. Received: ${JSON.stringify(value)}.`, fieldPath);
+    }
+    return value;
+}
+function isReadinessIssue(value) {
+    if (!isPlainObject(value))
+        return false;
+    return (typeof value.code === "string" &&
+        (value.severity === "error" || value.severity === "warning") &&
+        typeof value.message === "string" &&
+        typeof value.priority === "number" &&
+        typeof value.correctiveAction === "string" &&
+        typeof value.evidenceTarget === "string" &&
+        typeof value.stageId === "string" &&
+        (value.contextKind === "implementation" || value.contextKind === "test"));
+}
+function isBlockerSummary(value) {
+    if (!isPlainObject(value))
+        return false;
+    return ((value.contextKind === "implementation" || value.contextKind === "test") &&
+        typeof value.primaryCode === "string" &&
+        typeof value.primaryReason === "string" &&
+        typeof value.correctiveAction === "string" &&
+        typeof value.evidenceTarget === "string" &&
+        Array.isArray(value.blockingIssueCodes) &&
+        value.blockingIssueCodes.every((c) => typeof c === "string") &&
+        Array.isArray(value.supportingIssueCodes) &&
+        value.supportingIssueCodes.every((c) => typeof c === "string"));
+}
+export function validateOrchestratorContextReadinessResultV1(input, sourceLabel) {
+    if (!isPlainObject(input)) {
+        return fail(sourceLabel, "MALFORMED_TEXT_ARTIFACT", `Readiness input at "${sourceLabel}" must be a plain object.`);
+    }
+    const schemaVersion = input["schemaVersion"];
+    if (typeof schemaVersion !== "string" || schemaVersion.length === 0) {
+        return fail(sourceLabel, "MISSING_REQUIRED_FIELD", `Readiness input at "${sourceLabel}" is missing "schemaVersion".`, "schemaVersion");
+    }
+    const kind = requireEnum(input["kind"], ["implementation", "test"], "kind", sourceLabel, "MISSING_REQUIRED_FIELD");
+    if (typeof kind !== "string")
+        return kind;
+    const roleAllowed = ["implementation", "test-implementation"];
+    const role = requireEnum(input["role"], roleAllowed, "role", sourceLabel, "MISSING_REQUIRED_FIELD");
+    if (typeof role !== "string")
+        return role;
+    const expectedRole = kind === "implementation" ? "implementation" : "test-implementation";
+    if (role !== expectedRole) {
+        return fail(sourceLabel, "DOCUMENT_ROLE_MISMATCH", `Readiness input at "${sourceLabel}" declares kind "${kind}" with role "${role}", but role must be "${expectedRole}" for that kind.`, "role");
+    }
+    const decision = requireEnum(input["decision"], READINESS_DECISIONS, "decision", sourceLabel, "UNKNOWN_READINESS_DECISION");
+    if (typeof decision !== "string")
+        return decision;
+    const classification = requireEnum(input["classification"], READINESS_CLASSIFICATIONS, "classification", sourceLabel, "INVALID_LITERAL_VALUE");
+    if (typeof classification !== "string")
+        return classification;
+    const stageId = input["stageId"];
+    if (typeof stageId !== "string" || stageId.length === 0) {
+        return fail(sourceLabel, "MISSING_REQUIRED_FIELD", `Readiness input at "${sourceLabel}" is missing "stageId".`, "stageId");
+    }
+    const packetPath = input["packetPath"];
+    const reportPath = input["reportPath"];
+    if (typeof packetPath !== "string" || typeof reportPath !== "string") {
+        return fail(sourceLabel, "MISSING_REQUIRED_FIELD", `Readiness input at "${sourceLabel}" must declare string "packetPath" and "reportPath".`);
+    }
+    const issuesRaw = input["issues"];
+    if (!Array.isArray(issuesRaw) || !issuesRaw.every(isReadinessIssue)) {
+        return fail(sourceLabel, "MALFORMED_ISSUE_STRUCTURE", `Readiness input at "${sourceLabel}" has a malformed "issues" array.`, "issues");
+    }
+    const issues = issuesRaw;
+    const warningsRaw = input["warnings"];
+    if (!Array.isArray(warningsRaw) || !warningsRaw.every((w) => typeof w === "string")) {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" must declare a string array "warnings".`, "warnings");
+    }
+    const blockingIssueCodesRaw = input["blockingIssueCodes"];
+    if (!Array.isArray(blockingIssueCodesRaw) || !blockingIssueCodesRaw.every((c) => typeof c === "string")) {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" must declare a string array "blockingIssueCodes".`, "blockingIssueCodes");
+    }
+    let primaryIssue;
+    if (input["primaryIssue"] !== undefined) {
+        if (!isReadinessIssue(input["primaryIssue"])) {
+            return fail(sourceLabel, "MALFORMED_ISSUE_STRUCTURE", `Readiness input at "${sourceLabel}" has a malformed "primaryIssue".`, "primaryIssue");
+        }
+        primaryIssue = input["primaryIssue"];
+    }
+    let blockerSummary;
+    if (input["blockerSummary"] !== undefined) {
+        if (!isBlockerSummary(input["blockerSummary"])) {
+            return fail(sourceLabel, "MALFORMED_ISSUE_STRUCTURE", `Readiness input at "${sourceLabel}" has a malformed "blockerSummary".`, "blockerSummary");
+        }
+        blockerSummary = input["blockerSummary"];
+    }
+    const affectedResponsibilityIdsRaw = input["affectedResponsibilityIds"];
+    if (!Array.isArray(affectedResponsibilityIdsRaw) || !affectedResponsibilityIdsRaw.every((id) => typeof id === "string")) {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" must declare a string array "affectedResponsibilityIds".`, "affectedResponsibilityIds");
+    }
+    const evaluatedFreshness = requireEnum(input["evaluatedFreshness"], VALID_FRESHNESS_VALUES, "evaluatedFreshness", sourceLabel, "MISSING_REQUIRED_FIELD");
+    if (typeof evaluatedFreshness !== "string")
+        return evaluatedFreshness;
+    const evaluatedAdequacy = requireEnum(input["evaluatedAdequacy"], VALID_ADEQUACY_VALUES, "evaluatedAdequacy", sourceLabel, "MISSING_REQUIRED_FIELD");
+    if (typeof evaluatedAdequacy !== "string")
+        return evaluatedAdequacy;
+    const requiredEvidenceTruncated = requireEnum(input["requiredEvidenceTruncated"], VALID_TRUNCATION_VALUES, "requiredEvidenceTruncated", sourceLabel, "MISSING_REQUIRED_FIELD");
+    if (typeof requiredEvidenceTruncated !== "string")
+        return requiredEvidenceTruncated;
+    let declaredFreshness;
+    if (input["declaredFreshness"] !== undefined) {
+        const v = requireEnum(input["declaredFreshness"], VALID_FRESHNESS_VALUES, "declaredFreshness", sourceLabel, "INVALID_LITERAL_VALUE");
+        if (typeof v !== "string")
+            return v;
+        declaredFreshness = v;
+    }
+    let declaredAdequacy;
+    if (input["declaredAdequacy"] !== undefined) {
+        const v = requireEnum(input["declaredAdequacy"], VALID_ADEQUACY_VALUES, "declaredAdequacy", sourceLabel, "INVALID_LITERAL_VALUE");
+        if (typeof v !== "string")
+            return v;
+        declaredAdequacy = v;
+    }
+    let responsibilityMappingsTruncated;
+    if (input["responsibilityMappingsTruncated"] !== undefined) {
+        const v = requireEnum(input["responsibilityMappingsTruncated"], VALID_TRUNCATION_VALUES, "responsibilityMappingsTruncated", sourceLabel, "INVALID_LITERAL_VALUE");
+        if (typeof v !== "string")
+            return v;
+        responsibilityMappingsTruncated = v;
+    }
+    const readyWithAssumptions = input["readyWithAssumptions"];
+    if (typeof readyWithAssumptions !== "boolean") {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" must declare boolean "readyWithAssumptions".`, "readyWithAssumptions");
+    }
+    const provenanceSummary = input["provenanceSummary"];
+    if (typeof provenanceSummary !== "string") {
+        return fail(sourceLabel, "MISSING_REQUIRED_FIELD", `Readiness input at "${sourceLabel}" is missing string "provenanceSummary".`, "provenanceSummary");
+    }
+    const indexIdentity = input["indexIdentity"];
+    if (indexIdentity !== undefined && (typeof indexIdentity !== "string" || indexIdentity.length === 0)) {
+        return fail(sourceLabel, "MISSING_CANONICAL_IDENTITY", `Readiness input at "${sourceLabel}" declares a non-string or empty "indexIdentity".`, "indexIdentity");
+    }
+    const sourceCapsulePath = input["sourceCapsulePath"];
+    const sourceAuditPath = input["sourceAuditPath"];
+    if (sourceCapsulePath !== undefined && typeof sourceCapsulePath !== "string") {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" has non-string "sourceCapsulePath".`, "sourceCapsulePath");
+    }
+    if (sourceAuditPath !== undefined && typeof sourceAuditPath !== "string") {
+        return fail(sourceLabel, "INVALID_FIELD_TYPE", `Readiness input at "${sourceLabel}" has non-string "sourceAuditPath".`, "sourceAuditPath");
+    }
+    const artifact = {
+        schemaVersion,
+        kind,
+        role,
+        decision,
+        classification,
+        stageId,
+        packetPath,
+        reportPath,
+        sourceCapsulePath: sourceCapsulePath,
+        sourceAuditPath: sourceAuditPath,
+        issues,
+        warnings: warningsRaw,
+        blockingIssueCodes: blockingIssueCodesRaw,
+        primaryIssue,
+        blockerSummary,
+        affectedResponsibilityIds: affectedResponsibilityIdsRaw,
+        declaredFreshness,
+        evaluatedFreshness,
+        declaredAdequacy,
+        evaluatedAdequacy,
+        requiredEvidenceTruncated,
+        responsibilityMappingsTruncated,
+        indexIdentity: indexIdentity,
+        readyWithAssumptions,
+        provenanceSummary
+    };
+    return {
+        ok: true,
+        artifactKind: ARTIFACT_KIND,
+        sourcePath: sourceLabel,
+        schemaVersion,
+        schemaMajor: 1,
+        artifact,
+        rawArtifact: input
+    };
+}
+export function checkSupplementalReadinessIdentityConsistency(document, readiness) {
+    if (readiness.indexIdentity === undefined)
+        return null;
+    if (document.indexIdentity === readiness.indexIdentity)
+        return null;
+    return {
+        code: "INCOMPATIBLE_ARTIFACT_IDENTITY",
+        message: `Supplemental document index identity "${document.indexIdentity}" does not match readiness result index identity "${readiness.indexIdentity}".`,
+        documentIndexIdentity: document.indexIdentity,
+        readinessIndexIdentity: readiness.indexIdentity
+    };
+}

package/dist/src/evaluation/upstreamArtifacts/orchestratorWorkflowInstructionPacketV1.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/upstreamArtifacts/readImplementationContextPacketV1.js

@@ -0,0 +1,9 @@
+import { readTextArtifactFile } from "./readSupplementalContextTextFile.js";
+import { validateSupplementalContextDocumentV1 } from "./validateSupplementalContextDocumentV1.js";
+const ARTIFACT_KIND = "orchestrator-implementation-context-packet-v1";
+export async function readImplementationContextPacketV1(sourcePath) {
+    const loaded = await readTextArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateSupplementalContextDocumentV1(ARTIFACT_KIND, "implementation-context-packet", loaded.text, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readImplementationContextRetrievalReportV1.js

@@ -0,0 +1,9 @@
+import { readTextArtifactFile } from "./readSupplementalContextTextFile.js";
+import { validateSupplementalContextDocumentV1 } from "./validateSupplementalContextDocumentV1.js";
+const ARTIFACT_KIND = "orchestrator-implementation-context-retrieval-report-v1";
+export async function readImplementationContextRetrievalReportV1(sourcePath) {
+    const loaded = await readTextArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateSupplementalContextDocumentV1(ARTIFACT_KIND, "implementation-context-retrieval-report", loaded.text, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readJsonArtifact.js

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function readJsonArtifactFile(artifactKind, sourcePathInput) {
+    const sourcePath = path.resolve(sourcePathInput);
+    let raw;
+    try {
+        raw = await readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                artifactKind,
+                sourcePath,
+                code: "FILE_NOT_FOUND",
+                message: `Artifact "${artifactKind}" file was not found at "${sourcePath}".`
+            };
+        }
+        return {
+            ok: false,
+            artifactKind,
+            sourcePath,
+            code: "UNREADABLE_FILE",
+            message: `Artifact "${artifactKind}" file at "${sourcePath}" could not be read: ${error.message}`
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            artifactKind,
+            sourcePath,
+            code: "MALFORMED_JSON",
+            message: `Artifact "${artifactKind}" file at "${sourcePath}" is not valid JSON: ${error.message}`
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            artifactKind,
+            sourcePath,
+            code: "NON_OBJECT_ROOT",
+            message: `Artifact "${artifactKind}" file at "${sourcePath}" must parse to a JSON object at the root.`,
+            expected: "object",
+            actual: parsed
+        };
+    }
+    return { ok: true, sourcePath, value: parsed };
+}

package/dist/src/evaluation/upstreamArtifacts/readMyDevKitContextCapsuleV1.js

@@ -0,0 +1,9 @@
+import { readJsonArtifactFile } from "./readJsonArtifact.js";
+import { validateMyDevKitContextCapsuleV1 } from "./validateMyDevKitContextCapsuleV1.js";
+const ARTIFACT_KIND = "my-dev-kit-context-capsule-v1";
+export async function readMyDevKitContextCapsuleV1(sourcePath) {
+    const loaded = await readJsonArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateMyDevKitContextCapsuleV1(loaded.value, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readMyDevKitRetrievalAuditRecordV1.js

@@ -0,0 +1,9 @@
+import { readJsonArtifactFile } from "./readJsonArtifact.js";
+import { validateMyDevKitRetrievalAuditRecordV1 } from "./validateMyDevKitRetrievalAuditRecordV1.js";
+const ARTIFACT_KIND = "my-dev-kit-retrieval-audit-record-v1";
+export async function readMyDevKitRetrievalAuditRecordV1(sourcePath) {
+    const loaded = await readJsonArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateMyDevKitRetrievalAuditRecordV1(loaded.value, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readOrchestratorWorkflowInstructionPacketV1.js

@@ -0,0 +1,9 @@
+import { readJsonArtifactFile } from "./readJsonArtifact.js";
+import { validateOrchestratorWorkflowInstructionPacketV1 } from "./validateOrchestratorWorkflowInstructionPacketV1.js";
+const ARTIFACT_KIND = "orchestrator-workflow-instruction-packet-v1";
+export async function readOrchestratorWorkflowInstructionPacketV1(sourcePath) {
+    const loaded = await readJsonArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateOrchestratorWorkflowInstructionPacketV1(loaded.value, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readSupplementalContextTextFile.js

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function readTextArtifactFile(artifactKind, sourcePathInput) {
+    const sourcePath = path.resolve(sourcePathInput);
+    let text;
+    try {
+        text = await readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                artifactKind,
+                sourcePath,
+                code: "FILE_NOT_FOUND",
+                message: `Artifact "${artifactKind}" file was not found at "${sourcePath}".`
+            };
+        }
+        return {
+            ok: false,
+            artifactKind,
+            sourcePath,
+            code: "UNREADABLE_FILE",
+            message: `Artifact "${artifactKind}" file at "${sourcePath}" could not be read: ${error.message}`
+        };
+    }
+    return { ok: true, sourcePath, text };
+}

package/dist/src/evaluation/upstreamArtifacts/readTestContextPacketV1.js

@@ -0,0 +1,9 @@
+import { readTextArtifactFile } from "./readSupplementalContextTextFile.js";
+import { validateSupplementalContextDocumentV1 } from "./validateSupplementalContextDocumentV1.js";
+const ARTIFACT_KIND = "orchestrator-test-context-packet-v1";
+export async function readTestContextPacketV1(sourcePath) {
+    const loaded = await readTextArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateSupplementalContextDocumentV1(ARTIFACT_KIND, "test-context-packet", loaded.text, loaded.sourcePath);
+}

package/dist/src/evaluation/upstreamArtifacts/readTestContextRetrievalReportV1.js

@@ -0,0 +1,9 @@
+import { readTextArtifactFile } from "./readSupplementalContextTextFile.js";
+import { validateSupplementalContextDocumentV1 } from "./validateSupplementalContextDocumentV1.js";
+const ARTIFACT_KIND = "orchestrator-test-context-retrieval-report-v1";
+export async function readTestContextRetrievalReportV1(sourcePath) {
+    const loaded = await readTextArtifactFile(ARTIFACT_KIND, sourcePath);
+    if (!loaded.ok)
+        return loaded;
+    return validateSupplementalContextDocumentV1(ARTIFACT_KIND, "test-context-retrieval-report", loaded.text, loaded.sourcePath);
+}