@dailephd/my-dev-kit-lab 0.4.3 → 0.4.5

package/dist/src/evaluation/ecosystemFixtures/loadContextIntegrityFixture.js

@@ -0,0 +1,102 @@
+// v0.4.5 Batch 4: bounded end-to-end fixture loader (section 22). Loads a frozen
+// context-integrity ecosystem fixture (failed-run or corrected-replay) through the existing
+// Batch 1 producer readers and Batch 3 run-integrity reader, verifies hashes, and rejects
+// path traversal. It never recalculates metrics itself -- evaluation happens through the
+// existing evaluateProducerReadinessBridge, called by the test/consumer, not by this loader.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { readMyDevKitContextCapsuleV1 } from "../upstreamArtifacts/readMyDevKitContextCapsuleV1.js";
+import { readMyDevKitRetrievalAuditRecordV1 } from "../upstreamArtifacts/readMyDevKitRetrievalAuditRecordV1.js";
+import { readOrchestratorRunIntegrityEvidenceV1 } from "../upstreamArtifacts/readOrchestratorRunIntegrityV1.js";
+import { isSafeFixtureRelativePath, validateEcosystemFixtureManifest } from "./validateManifest.js";
+import { verifyFixtureHashes } from "./verifyFixtureHashes.js";
+function findEntry(manifest, role) {
+    return manifest.artifacts.find((a) => a.role === role && a.evaluationUse);
+}
+export async function loadContextIntegrityFixture(fixtureRoot, manifestPath) {
+    const issues = [];
+    let manifestRaw;
+    try {
+        manifestRaw = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            manifest: null,
+            hashVerification: null,
+            implementationCapsule: null,
+            implementationAudit: null,
+            runIntegrityEvidence: null,
+            issues: [`Manifest at "${manifestPath}" could not be read or parsed: ${error.message}`]
+        };
+    }
+    const manifestResult = validateEcosystemFixtureManifest(manifestRaw);
+    if (!manifestResult.ok) {
+        return {
+            ok: false,
+            manifest: null,
+            hashVerification: null,
+            implementationCapsule: null,
+            implementationAudit: null,
+            runIntegrityEvidence: null,
+            issues: manifestResult.issues.map((i) => `[${i.code}] ${i.fieldPath}: ${i.message}`)
+        };
+    }
+    const manifest = manifestResult.manifest;
+    const hashVerification = await verifyFixtureHashes(manifest, fixtureRoot);
+    if (!hashVerification.ok) {
+        issues.push(...hashVerification.issues.map((i) => `[${i.code}] ${i.fixtureRelativePath}: ${i.message}`));
+    }
+    function resolveSafe(relativePath) {
+        if (!isSafeFixtureRelativePath(relativePath)) {
+            issues.push(`Refused to resolve unsafe fixture-relative path "${relativePath}".`);
+            return null;
+        }
+        return path.resolve(fixtureRoot, relativePath);
+    }
+    let implementationCapsule = null;
+    const capsuleEntry = findEntry(manifest, "context-capsule");
+    if (capsuleEntry) {
+        const resolved = resolveSafe(capsuleEntry.fixtureRelativePath);
+        if (resolved) {
+            const result = await readMyDevKitContextCapsuleV1(resolved);
+            if (result.ok)
+                implementationCapsule = result.artifact;
+            else
+                issues.push(`context-capsule reader failed for "${capsuleEntry.fixtureRelativePath}": [${result.code}] ${result.message}`);
+        }
+    }
+    let implementationAudit = null;
+    const auditEntry = findEntry(manifest, "retrieval-audit-record");
+    if (auditEntry) {
+        const resolved = resolveSafe(auditEntry.fixtureRelativePath);
+        if (resolved) {
+            const result = await readMyDevKitRetrievalAuditRecordV1(resolved);
+            if (result.ok)
+                implementationAudit = result.artifact;
+            else
+                issues.push(`retrieval-audit-record reader failed for "${auditEntry.fixtureRelativePath}": [${result.code}] ${result.message}`);
+        }
+    }
+    let runIntegrityEvidence = null;
+    const runIntegrityEntry = findEntry(manifest, "run-integrity-evidence");
+    if (runIntegrityEntry) {
+        const resolved = resolveSafe(runIntegrityEntry.fixtureRelativePath);
+        if (resolved) {
+            const result = await readOrchestratorRunIntegrityEvidenceV1(resolved);
+            if (result.ok)
+                runIntegrityEvidence = result.artifact;
+            else
+                issues.push(`run-integrity-evidence reader failed for "${runIntegrityEntry.fixtureRelativePath}": [${result.code}] ${result.message}`);
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        manifest,
+        hashVerification,
+        implementationCapsule,
+        implementationAudit,
+        runIntegrityEvidence,
+        issues
+    };
+}

package/dist/src/evaluation/ecosystemFixtures/manifestTypes.js

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

package/dist/src/evaluation/ecosystemFixtures/validateManifest.js

@@ -0,0 +1,82 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Rejects any fixture-relative path that is absolute, empty, or escapes the fixture root
+// via ".." segments (section 22 "rejects path traversal"). Windows and POSIX separators are
+// both checked since fixture manifests are authored on Windows but tests may run on either.
+export function isSafeFixtureRelativePath(candidate) {
+    if (candidate.length === 0)
+        return false;
+    if (candidate.startsWith("/") || candidate.startsWith("\\"))
+        return false;
+    if (/^[a-zA-Z]:[\\/]/.test(candidate))
+        return false;
+    const segments = candidate.split(/[\\/]/);
+    return segments.every((segment) => segment !== "..") && segments.length > 0;
+}
+export function validateEcosystemFixtureManifest(value) {
+    const issues = [];
+    if (!isPlainObject(value)) {
+        return { ok: false, issues: [{ code: "NON_OBJECT_MANIFEST", fieldPath: "", message: "Manifest must be a plain JSON object." }] };
+    }
+    const schemaVersion = value["manifestSchemaVersion"];
+    if (typeof schemaVersion !== "string" || !/^1\./.test(schemaVersion)) {
+        return {
+            ok: false,
+            issues: [
+                {
+                    code: "UNSUPPORTED_MANIFEST_SCHEMA_MAJOR",
+                    fieldPath: "manifestSchemaVersion",
+                    message: `Manifest schema version "${String(schemaVersion)}" is unsupported; expected major version 1.`
+                }
+            ]
+        };
+    }
+    const requiredStringFields = ["fixtureId", "description", "sourceEvidenceRoot", "generatedAt"];
+    for (const field of requiredStringFields) {
+        if (typeof value[field] !== "string" || value[field].length === 0) {
+            issues.push({ code: "MISSING_REQUIRED_FIELD", fieldPath: field, message: `Manifest is missing required non-empty string field "${field}".` });
+        }
+    }
+    const artifacts = value["artifacts"];
+    if (!Array.isArray(artifacts)) {
+        issues.push({ code: "INVALID_FIELD_TYPE", fieldPath: "artifacts", message: 'Manifest field "artifacts" must be an array.' });
+    }
+    else {
+        const seenPaths = new Set();
+        artifacts.forEach((entry, index) => {
+            const fieldPath = `artifacts[${index}]`;
+            if (!isPlainObject(entry)) {
+                issues.push({ code: "INVALID_FIELD_TYPE", fieldPath, message: "Each artifact entry must be an object." });
+                return;
+            }
+            const relPath = entry["fixtureRelativePath"];
+            if (typeof relPath !== "string" || relPath.length === 0) {
+                issues.push({ code: "MISSING_REQUIRED_FIELD", fieldPath: `${fieldPath}.fixtureRelativePath`, message: "Missing fixtureRelativePath." });
+                return;
+            }
+            if (!isSafeFixtureRelativePath(relPath)) {
+                issues.push({
+                    code: "PATH_ESCAPES_FIXTURE_ROOT",
+                    fieldPath: `${fieldPath}.fixtureRelativePath`,
+                    message: `fixtureRelativePath "${relPath}" is absolute or escapes the fixture root.`
+                });
+                return;
+            }
+            if (seenPaths.has(relPath)) {
+                issues.push({ code: "DUPLICATE_ARTIFACT_PATH", fieldPath: `${fieldPath}.fixtureRelativePath`, message: `Duplicate fixtureRelativePath "${relPath}".` });
+                return;
+            }
+            seenPaths.add(relPath);
+            for (const hashField of ["originalSha256", "copiedSha256"]) {
+                const v = entry[hashField];
+                if (typeof v !== "string" || !/^[0-9a-f]{64}$/i.test(v)) {
+                    issues.push({ code: "INVALID_FIELD_TYPE", fieldPath: `${fieldPath}.${hashField}`, message: `${hashField} must be a 64-hex-character SHA-256 digest.` });
+                }
+            }
+        });
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    return { ok: true, manifest: value };
+}

package/dist/src/evaluation/ecosystemFixtures/verifyFixtureHashes.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isSafeFixtureRelativePath } from "./validateManifest.js";
+async function sha256OfFile(absolutePath) {
+    const contents = await readFile(absolutePath);
+    return createHash("sha256").update(contents).digest("hex");
+}
+// Section 21: reads the manifest, hashes each tracked fixture file, and reports missing
+// files, hash mismatches, and path-traversal attempts with deterministic (manifest) order.
+// Never rewrites the manifest or the fixture; a mismatch is reported, not repaired.
+export async function verifyFixtureHashes(manifest, fixtureRoot) {
+    const issues = [];
+    let checkedCount = 0;
+    for (const artifact of manifest.artifacts) {
+        const relPath = artifact.fixtureRelativePath;
+        if (!isSafeFixtureRelativePath(relPath)) {
+            issues.push({ code: "PATH_ESCAPES_FIXTURE_ROOT", fixtureRelativePath: relPath, message: `Manifest entry references an unsafe path: "${relPath}".` });
+            continue;
+        }
+        const absolutePath = path.resolve(fixtureRoot, relPath);
+        let actualSha256;
+        try {
+            actualSha256 = await sha256OfFile(absolutePath);
+        }
+        catch (error) {
+            const code = error.code;
+            issues.push({
+                code: code === "ENOENT" ? "MISSING_FILE" : "UNREADABLE_FILE",
+                fixtureRelativePath: relPath,
+                message: code === "ENOENT" ? `Fixture file is missing: "${relPath}".` : `Fixture file could not be read: "${relPath}" (${error.message}).`
+            });
+            continue;
+        }
+        checkedCount += 1;
+        if (actualSha256 !== artifact.copiedSha256) {
+            issues.push({
+                code: "HASH_MISMATCH",
+                fixtureRelativePath: relPath,
+                message: `Fixture file "${relPath}" hash does not match the manifest's recorded copiedSha256 (expected ${artifact.copiedSha256}, got ${actualSha256}).`
+            });
+        }
+    }
+    return { ok: issues.length === 0, checkedCount, issues };
+}

package/dist/src/evaluation/stageContextExpectations/producerReadinessExpectationTypes.js

@@ -0,0 +1,8 @@
+// v0.4.4 Batch 2: additive, optional expectation facets covering the producer/readiness
+// evidence Batch 1 preserves (selected owners, allocation/truncation evidence on the raw
+// my-dev-kit artifacts, orchestrator readiness, and responsibility criticality). These are
+// a separate axis from StageContextExpectationItemV1/expectedEvidence -- they are the
+// deterministic lab oracle for Batch 2 metrics, not evidence-match expectations. Fully
+// optional so every existing v0.4.3 StageContextExpectationFixtureV1 remains valid and
+// unchanged (schema major stays 1).
+export {};

package/dist/src/evaluation/stageContextExpectations/validation.js

@@ -199,6 +199,11 @@ export function validateStageContextExpectationFixtureV1(value, sourcePath) {
     const statesFailure = validateExpectedStates(root.expectedStates, sourcePath);
     if (statesFailure)
         return statesFailure;
+    if (root.producerReadinessExpectations !== undefined) {
+        const producerReadinessFailure = validateProducerReadinessExpectations(root.producerReadinessExpectations, sourcePath);
+        if (producerReadinessFailure)
+            return producerReadinessFailure;
+    }
     return {
         ok: true,
         sourcePath,
@@ -566,3 +571,198 @@ function validateExpectedStates(statesValue, sourcePath) {
         return immutabilityFailure;
     return null;
 }
+// v0.4.4 Batch 2: additive, optional producer/readiness expectation validation. Structural
+// classification only, mirroring the existing expectation-item validation conventions.
+const OWNER_INCLUSION_VALUES = ["required", "allowed", "forbidden"];
+const READINESS_KIND_VALUES = ["implementation", "test"];
+const READINESS_DECISION_VALUES = ["not-required", "ready", "refresh-required"];
+const CRITICALITY_VALUES = ["critical", "noncritical"];
+const PRODUCER_READINESS_SOURCE_ARTIFACT_VALUES = ["context-capsule", "retrieval-audit-record"];
+function requireNonEmptyExpectationId(item, itemPath, sourcePath) {
+    return requireNonEmptyString(item, "expectationId", `${itemPath}.expectationId`, sourcePath);
+}
+function validateOwnerExpectation(itemValue, itemPath, sourcePath) {
+    if (!isPlainObject(itemValue)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath} must be an object.`, { fieldPath: itemPath });
+    }
+    const idFailure = requireNonEmptyExpectationId(itemValue, itemPath, sourcePath);
+    if (idFailure)
+        return idFailure;
+    if (!OWNER_INCLUSION_VALUES.includes(itemValue.inclusion)) {
+        return failure(sourcePath, "INVALID_LITERAL_VALUE", `${itemPath}.inclusion is not valid.`, {
+            fieldPath: `${itemPath}.inclusion`,
+            actual: itemValue.inclusion
+        });
+    }
+    if (!PRODUCER_READINESS_SOURCE_ARTIFACT_VALUES.includes(itemValue.sourceArtifact)) {
+        return failure(sourcePath, "INVALID_LITERAL_VALUE", `${itemPath}.sourceArtifact is not valid.`, {
+            fieldPath: `${itemPath}.sourceArtifact`,
+            actual: itemValue.sourceArtifact
+        });
+    }
+    const ownerIdFailure = requireNonEmptyString(itemValue, "ownerId", `${itemPath}.ownerId`, sourcePath);
+    if (ownerIdFailure)
+        return ownerIdFailure;
+    if (itemValue.notes === undefined || !isStringArray(itemValue.notes)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.notes must be an array of strings.`, {
+            fieldPath: `${itemPath}.notes`
+        });
+    }
+    return null;
+}
+function validateAllocationExpectation(itemValue, itemPath, sourcePath) {
+    if (!isPlainObject(itemValue)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath} must be an object.`, { fieldPath: itemPath });
+    }
+    const idFailure = requireNonEmptyExpectationId(itemValue, itemPath, sourcePath);
+    if (idFailure)
+        return idFailure;
+    const groupIdFailure = requireNonEmptyString(itemValue, "groupId", `${itemPath}.groupId`, sourcePath);
+    if (groupIdFailure)
+        return groupIdFailure;
+    if (itemValue.expectedCapacity !== undefined && itemValue.expectedCapacity !== null && !isNonNegativeInteger(itemValue.expectedCapacity)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedCapacity must be a nonnegative integer or null.`, {
+            fieldPath: `${itemPath}.expectedCapacity`
+        });
+    }
+    if (itemValue.expectedUsedReservation !== undefined &&
+        itemValue.expectedUsedReservation !== null &&
+        !isNonNegativeInteger(itemValue.expectedUsedReservation)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedUsedReservation must be a nonnegative integer or null.`, {
+            fieldPath: `${itemPath}.expectedUsedReservation`
+        });
+    }
+    if (itemValue.expectedRequiredEvidenceIds !== undefined && !isStringArray(itemValue.expectedRequiredEvidenceIds)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedRequiredEvidenceIds must be an array of strings.`, {
+            fieldPath: `${itemPath}.expectedRequiredEvidenceIds`
+        });
+    }
+    if (itemValue.expectedOmitted !== undefined && typeof itemValue.expectedOmitted !== "boolean") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedOmitted must be a boolean.`, {
+            fieldPath: `${itemPath}.expectedOmitted`
+        });
+    }
+    if (itemValue.notes === undefined || !isStringArray(itemValue.notes)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.notes must be an array of strings.`, {
+            fieldPath: `${itemPath}.notes`
+        });
+    }
+    return null;
+}
+function validateReadinessExpectation(itemValue, itemPath, sourcePath) {
+    if (!isPlainObject(itemValue)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath} must be an object.`, { fieldPath: itemPath });
+    }
+    const idFailure = requireNonEmptyExpectationId(itemValue, itemPath, sourcePath);
+    if (idFailure)
+        return idFailure;
+    if (!READINESS_KIND_VALUES.includes(itemValue.kind)) {
+        return failure(sourcePath, "INVALID_LITERAL_VALUE", `${itemPath}.kind is not valid.`, {
+            fieldPath: `${itemPath}.kind`,
+            actual: itemValue.kind
+        });
+    }
+    if (itemValue.allowedDecisions !== undefined) {
+        if (!isStringArray(itemValue.allowedDecisions) || itemValue.allowedDecisions.some((d) => !READINESS_DECISION_VALUES.includes(d))) {
+            return failure(sourcePath, "INVALID_LITERAL_VALUE", `${itemPath}.allowedDecisions contains an invalid decision value.`, {
+                fieldPath: `${itemPath}.allowedDecisions`
+            });
+        }
+    }
+    if (itemValue.expectedClassification !== undefined && typeof itemValue.expectedClassification !== "string") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedClassification must be a string.`, {
+            fieldPath: `${itemPath}.expectedClassification`
+        });
+    }
+    if (itemValue.expectedIssueCodes !== undefined && !isStringArray(itemValue.expectedIssueCodes)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedIssueCodes must be an array of strings.`, {
+            fieldPath: `${itemPath}.expectedIssueCodes`
+        });
+    }
+    if (itemValue.expectedPrimaryIssueCode !== undefined && typeof itemValue.expectedPrimaryIssueCode !== "string") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.expectedPrimaryIssueCode must be a string.`, {
+            fieldPath: `${itemPath}.expectedPrimaryIssueCode`
+        });
+    }
+    if (itemValue.notApplicable !== undefined && typeof itemValue.notApplicable !== "boolean") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.notApplicable must be a boolean.`, {
+            fieldPath: `${itemPath}.notApplicable`
+        });
+    }
+    if (itemValue.notes === undefined || !isStringArray(itemValue.notes)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.notes must be an array of strings.`, {
+            fieldPath: `${itemPath}.notes`
+        });
+    }
+    return null;
+}
+function validateCriticalityExpectation(itemValue, itemPath, sourcePath) {
+    if (!isPlainObject(itemValue)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath} must be an object.`, { fieldPath: itemPath });
+    }
+    const idFailure = requireNonEmptyExpectationId(itemValue, itemPath, sourcePath);
+    if (idFailure)
+        return idFailure;
+    const responsibilityIdFailure = requireNonEmptyString(itemValue, "responsibilityId", `${itemPath}.responsibilityId`, sourcePath);
+    if (responsibilityIdFailure)
+        return responsibilityIdFailure;
+    if (!CRITICALITY_VALUES.includes(itemValue.expectedCriticality)) {
+        return failure(sourcePath, "INVALID_LITERAL_VALUE", `${itemPath}.expectedCriticality is not valid.`, {
+            fieldPath: `${itemPath}.expectedCriticality`,
+            actual: itemValue.expectedCriticality
+        });
+    }
+    if (typeof itemValue.applicable !== "boolean") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.applicable must be a boolean.`, {
+            fieldPath: `${itemPath}.applicable`
+        });
+    }
+    if (typeof itemValue.requiresFullMapping !== "boolean") {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.requiresFullMapping must be a boolean.`, {
+            fieldPath: `${itemPath}.requiresFullMapping`
+        });
+    }
+    if (itemValue.notes === undefined || !isStringArray(itemValue.notes)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${itemPath}.notes must be an array of strings.`, {
+            fieldPath: `${itemPath}.notes`
+        });
+    }
+    return null;
+}
+function validateProducerReadinessExpectations(value, sourcePath) {
+    const fieldPath = "producerReadinessExpectations";
+    if (!isPlainObject(value)) {
+        return failure(sourcePath, "INVALID_FIELD_TYPE", `${fieldPath} must be an object.`, { fieldPath });
+    }
+    const lists = [
+        ["ownerExpectations", value.ownerExpectations, validateOwnerExpectation],
+        ["allocationExpectations", value.allocationExpectations, validateAllocationExpectation],
+        ["readinessExpectations", value.readinessExpectations, validateReadinessExpectation],
+        ["criticalityExpectations", value.criticalityExpectations, validateCriticalityExpectation]
+    ];
+    const seenIds = new Set();
+    for (const [key, listValue, validateItem] of lists) {
+        if (listValue === undefined)
+            continue;
+        if (!Array.isArray(listValue)) {
+            return failure(sourcePath, "INVALID_FIELD_TYPE", `${fieldPath}.${key} must be an array.`, {
+                fieldPath: `${fieldPath}.${key}`
+            });
+        }
+        for (let index = 0; index < listValue.length; index += 1) {
+            const itemPath = `${fieldPath}.${key}[${index}]`;
+            const itemFailure = validateItem(listValue[index], itemPath, sourcePath);
+            if (itemFailure)
+                return itemFailure;
+            const id = listValue[index].expectationId;
+            if (seenIds.has(id)) {
+                return failure(sourcePath, "DUPLICATE_PRODUCER_READINESS_EXPECTATION_ID", `${itemPath}.expectationId "${id}" is duplicated.`, {
+                    fieldPath: `${itemPath}.expectationId`,
+                    actual: id
+                });
+            }
+            seenIds.add(id);
+        }
+    }
+    return null;
+}