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

package/dist/src/evaluation/stageContextMetrics/calculateReadinessAgreement.js

@@ -0,0 +1,152 @@
+// v0.4.4 Batch 2: readiness/raw-evidence agreement. Readiness stays observed consumer
+// output (Batch 1) -- this module only compares it against an explicit fixture-declared
+// expectation. It never calls, imports, or reimplements contextReadiness.ts.
+import { checkSupplementalReadinessIdentityConsistency } from "../upstreamArtifacts/index.js";
+function unavailableStructural(field, reason) {
+    return { field, expectedValue: null, observedValue: null, agreement: null, availability: "unavailable", reason };
+}
+export function calculateReadinessStructuralAgreement(readiness, supplementalPacket, packetSourcePath) {
+    const results = [];
+    if (readiness === undefined) {
+        results.push(unavailableStructural("canonicalRepositoryIdentity", "No readiness result was supplied."));
+        results.push(unavailableStructural("packetPath", "No readiness result was supplied."));
+        return results;
+    }
+    if (supplementalPacket === undefined) {
+        results.push(unavailableStructural("canonicalRepositoryIdentity", "No supplemental document was supplied to compare against readiness."));
+    }
+    else {
+        const diagnostic = checkSupplementalReadinessIdentityConsistency(supplementalPacket, readiness);
+        results.push({
+            field: "canonicalRepositoryIdentity",
+            expectedValue: supplementalPacket.indexIdentity,
+            observedValue: readiness.indexIdentity ?? null,
+            agreement: diagnostic === null,
+            availability: readiness.indexIdentity === undefined ? "unavailable" : "available",
+            reason: readiness.indexIdentity === undefined ? "The readiness result does not declare indexIdentity." : diagnostic?.message ?? null
+        });
+    }
+    if (packetSourcePath === undefined) {
+        results.push(unavailableStructural("packetPath", "No packet source path was supplied to compare against readiness.packetPath."));
+    }
+    else {
+        results.push({
+            field: "packetPath",
+            expectedValue: packetSourcePath,
+            observedValue: readiness.packetPath,
+            agreement: packetSourcePath === readiness.packetPath,
+            availability: "available",
+            reason: null
+        });
+    }
+    return results;
+}
+export function calculateReadinessDecisionAgreement(readiness, expectation) {
+    if (expectation === undefined) {
+        return {
+            availability: "not-applicable",
+            observedDecision: readiness?.decision ?? null,
+            allowedDecisions: null,
+            decisionAgreement: null,
+            observedClassification: readiness?.classification ?? null,
+            expectedClassification: null,
+            classificationAgreement: null,
+            observedIssueCodes: readiness?.blockingIssueCodes ?? [],
+            expectedIssueCodes: null,
+            issueCodesAgreement: null,
+            observedPrimaryIssueCode: readiness?.primaryIssue?.code ?? null,
+            expectedPrimaryIssueCode: null,
+            primaryIssueAgreement: null,
+            reason: "The expectation fixture declares no readiness expectation."
+        };
+    }
+    if (readiness === undefined) {
+        return {
+            availability: "unavailable",
+            observedDecision: null,
+            allowedDecisions: expectation.allowedDecisions ?? null,
+            decisionAgreement: null,
+            observedClassification: null,
+            expectedClassification: expectation.expectedClassification ?? null,
+            classificationAgreement: null,
+            observedIssueCodes: [],
+            expectedIssueCodes: expectation.expectedIssueCodes ?? null,
+            issueCodesAgreement: null,
+            observedPrimaryIssueCode: null,
+            expectedPrimaryIssueCode: expectation.expectedPrimaryIssueCode ?? null,
+            primaryIssueAgreement: null,
+            reason: "No readiness result was supplied."
+        };
+    }
+    const decisionAgreement = expectation.allowedDecisions === undefined ? null : expectation.allowedDecisions.includes(readiness.decision);
+    const classificationAgreement = expectation.expectedClassification === undefined ? null : expectation.expectedClassification === readiness.classification;
+    const issueCodesAgreement = expectation.expectedIssueCodes === undefined
+        ? null
+        : expectation.expectedIssueCodes.length === readiness.blockingIssueCodes.length &&
+            expectation.expectedIssueCodes.every((code) => readiness.blockingIssueCodes.includes(code));
+    const primaryIssueAgreement = expectation.expectedPrimaryIssueCode === undefined
+        ? null
+        : expectation.expectedPrimaryIssueCode === (readiness.primaryIssue?.code ?? null);
+    return {
+        availability: "available",
+        observedDecision: readiness.decision,
+        allowedDecisions: expectation.allowedDecisions ?? null,
+        decisionAgreement,
+        observedClassification: readiness.classification,
+        expectedClassification: expectation.expectedClassification ?? null,
+        classificationAgreement,
+        observedIssueCodes: readiness.blockingIssueCodes,
+        expectedIssueCodes: expectation.expectedIssueCodes ?? null,
+        issueCodesAgreement,
+        observedPrimaryIssueCode: readiness.primaryIssue?.code ?? null,
+        expectedPrimaryIssueCode: expectation.expectedPrimaryIssueCode ?? null,
+        primaryIssueAgreement,
+        reason: null
+    };
+}
+export function calculateInvalidReady(readiness, expectation) {
+    if (readiness === undefined) {
+        return { availability: "unavailable", invalidReady: null, observedDecision: null, expectedBlockingDecision: false, missingExpectedIssueCodes: [], reason: "No readiness result was supplied." };
+    }
+    if (expectation === undefined) {
+        return { availability: "not-applicable", invalidReady: null, observedDecision: readiness.decision, expectedBlockingDecision: false, missingExpectedIssueCodes: [], reason: "The expectation fixture declares no readiness expectation." };
+    }
+    const expectsBlocking = (expectation.allowedDecisions !== undefined &&
+        !expectation.allowedDecisions.includes("ready") &&
+        (expectation.allowedDecisions.includes("refresh-required") || expectation.allowedDecisions.length > 0)) ||
+        (expectation.expectedIssueCodes !== undefined && expectation.expectedIssueCodes.length > 0);
+    if (!expectsBlocking) {
+        return { availability: "not-applicable", invalidReady: null, observedDecision: readiness.decision, expectedBlockingDecision: false, missingExpectedIssueCodes: [], reason: "The expectation fixture does not require blocked or refresh-required behavior." };
+    }
+    if (readiness.decision !== "ready") {
+        return { availability: "available", invalidReady: false, observedDecision: readiness.decision, expectedBlockingDecision: true, missingExpectedIssueCodes: [], reason: null };
+    }
+    const expectedCodes = expectation.expectedIssueCodes ?? [];
+    const missing = expectedCodes.filter((code) => !readiness.blockingIssueCodes.includes(code));
+    return { availability: "available", invalidReady: true, observedDecision: readiness.decision, expectedBlockingDecision: true, missingExpectedIssueCodes: missing, reason: null };
+}
+export function calculateValidBlocked(readiness, expectation) {
+    if (readiness === undefined) {
+        return { availability: "unavailable", validBlocked: null, validRefreshRequired: null, observedDecision: null, reason: "No readiness result was supplied." };
+    }
+    if (expectation === undefined) {
+        return { availability: "not-applicable", validBlocked: null, validRefreshRequired: null, observedDecision: readiness.decision, reason: "The expectation fixture declares no readiness expectation." };
+    }
+    if (readiness.decision !== "refresh-required") {
+        return { availability: "available", validBlocked: false, validRefreshRequired: false, observedDecision: readiness.decision, reason: null };
+    }
+    const allowsRefreshRequired = expectation.allowedDecisions === undefined || expectation.allowedDecisions.includes("refresh-required");
+    const issueCodesMatch = expectation.expectedIssueCodes === undefined ||
+        expectation.expectedIssueCodes.every((code) => readiness.blockingIssueCodes.includes(code));
+    const primaryMatches = expectation.expectedPrimaryIssueCode === undefined || expectation.expectedPrimaryIssueCode === (readiness.primaryIssue?.code ?? null);
+    const valid = allowsRefreshRequired && issueCodesMatch && primaryMatches;
+    return { availability: "available", validBlocked: valid, validRefreshRequired: valid, observedDecision: readiness.decision, reason: null };
+}
+export function calculateReadinessAgreementMetrics(readiness, expectation, supplementalPacket, packetSourcePath) {
+    return {
+        structuralAgreement: calculateReadinessStructuralAgreement(readiness, supplementalPacket, packetSourcePath),
+        decisionAgreement: calculateReadinessDecisionAgreement(readiness, expectation),
+        invalidReady: calculateInvalidReady(readiness, expectation),
+        validBlocked: calculateValidBlocked(readiness, expectation)
+    };
+}

package/dist/src/evaluation/stageContextMetrics/calculateSupplementalRawAgreement.js

@@ -0,0 +1,50 @@
+function extractRawIdentity(artifact) {
+    return {
+        projectRoot: artifact.index.projectRoot,
+        role: artifact.request.role,
+        freshnessState: artifact.freshness.state,
+        truncated: artifact.truncation.truncated
+    };
+}
+function truncationToYesNo(value) {
+    return value ? "yes" : "no";
+}
+function buildField(field, rawValue, supplementalValue, unavailableReason) {
+    if (unavailableReason !== null) {
+        return { field, rawValue, supplementalValue, agreement: null, availability: "unavailable", reason: unavailableReason };
+    }
+    return { field, rawValue, supplementalValue, agreement: rawValue === supplementalValue, availability: "available", reason: null };
+}
+export function calculateSupplementalRawAgreement(supplemental, raw) {
+    if (supplemental === undefined || raw === undefined) {
+        const reason = supplemental === undefined && raw === undefined
+            ? "Neither a supplemental document nor a raw artifact was supplied."
+            : supplemental === undefined
+                ? "No supplemental document was supplied."
+                : "No raw context-capsule or retrieval-audit artifact was supplied.";
+        const fields = [
+            buildField("canonicalRepositoryIdentity", null, supplemental?.indexIdentity ?? null, reason),
+            buildField("role", null, supplemental?.role ?? null, reason),
+            buildField("freshness", null, supplemental?.freshness ?? null, reason),
+            buildField("requiredEvidenceTruncated", null, supplemental?.requiredEvidenceTruncated ?? null, reason)
+        ];
+        return { fields, contradictions: [], upstreamProducerParityPreserved: null };
+    }
+    const rawIdentity = extractRawIdentity(raw);
+    const fields = [];
+    fields.push(buildField("canonicalRepositoryIdentity", rawIdentity.projectRoot ?? null, supplemental.indexIdentity, rawIdentity.projectRoot === undefined ? "The raw artifact does not declare index.projectRoot." : null));
+    const roleComparable = rawIdentity.role === "implementation" || rawIdentity.role === "test-implementation";
+    fields.push(buildField("role", rawIdentity.role, supplemental.role, roleComparable ? null : `Raw role "${rawIdentity.role}" has no supplemental-document counterpart in this vocabulary.`));
+    fields.push(buildField("freshness", rawIdentity.freshnessState, supplemental.freshness, null));
+    fields.push(buildField("requiredEvidenceTruncated", truncationToYesNo(rawIdentity.truncated), supplemental.requiredEvidenceTruncated, supplemental.requiredEvidenceTruncated === "unknown"
+        ? "The supplemental document declares truncation as \"unknown\", so agreement with the raw boolean cannot be determined."
+        : null));
+    const contradictions = fields.filter((f) => f.availability === "available" && f.agreement === false);
+    return {
+        fields,
+        contradictions,
+        // A successfully read raw pair is itself the observed outcome of the frozen
+        // assertRawEvidenceParity() write-time guard; see file header. Never recomputed here.
+        upstreamProducerParityPreserved: true
+    };
+}

package/dist/src/evaluation/stageContextMetrics/calculateTruncationClassification.js

@@ -0,0 +1,44 @@
+export function classifyTruncationRecord(record, sourceArtifact, sourceInstance) {
+    const base = {
+        groupId: record.affectedGroup,
+        sourceArtifact,
+        sourceInstance,
+        limit: record.limit,
+        used: record.used,
+        available: record.available,
+        omittedRequiredEvidenceIds: record.requiredEvidenceLost ? record.droppedEvidenceIds : []
+    };
+    if (!record.requiredEvidenceLost) {
+        return {
+            ...base,
+            cause: "none",
+            availability: "available",
+            reason: "No fixture-required evidence was reported lost for this group."
+        };
+    }
+    if (record.limit === null) {
+        return {
+            ...base,
+            cause: "unresolved",
+            availability: "available",
+            reason: "Required evidence was lost but no hard limit is declared for this group, so avoidability cannot be proven either way."
+        };
+    }
+    if (record.used < record.limit) {
+        return {
+            ...base,
+            cause: "avoidable",
+            availability: "available",
+            reason: `Required evidence was lost while used (${record.used}) remained below the declared limit (${record.limit}); compatible headroom existed under the hard limit.`
+        };
+    }
+    return {
+        ...base,
+        cause: "genuine-hard-limit",
+        availability: "available",
+        reason: `Required evidence was lost and used (${record.used}) reached or exceeded the declared limit (${record.limit}); no compatible headroom remained.`
+    };
+}
+export function classifyTruncationRecords(records, sourceArtifact, sourceInstance) {
+    return records.map((record) => classifyTruncationRecord(record, sourceArtifact, sourceInstance));
+}

package/dist/src/evaluation/stageContextMetrics/evaluateProducerReadinessBridge.js

@@ -0,0 +1,127 @@
+import { collectSelectedOwnerEvidence, calculateOwnerMetrics } from "./calculateOwnerMetrics.js";
+import { calculateAllocationFactsForGroups } from "./calculateAllocationMetrics.js";
+import { classifyTruncationRecords } from "./calculateTruncationClassification.js";
+import { calculateSupplementalRawAgreement } from "./calculateSupplementalRawAgreement.js";
+import { calculateReadinessAgreementMetrics } from "./calculateReadinessAgreement.js";
+import { calculateCriticalityMetrics } from "./calculateCriticalityMetrics.js";
+function ownerExpectationsFor(expectations, sourceArtifact) {
+    return expectations?.ownerExpectations?.filter((e) => e.sourceArtifact === sourceArtifact);
+}
+function evaluateSide(input, expectations) {
+    const producerExpectations = expectations?.producerReadinessExpectations;
+    // Owner-selection and allocation-group evidence only exist on ContextCapsule (Batch 1
+    // contract-lock evidence: RetrievalAuditRecord has no selectedOwners/evidenceGroups
+    // fields). Truncation and responsibility-mapping evidence exist on both.
+    const capsule = input.contextCapsule;
+    const truncationArtifact = input.contextCapsule ?? input.retrievalAuditRecord;
+    const rawForAgreement = input.contextCapsule ?? input.retrievalAuditRecord;
+    const selectedOwnerEvidence = capsule ? collectSelectedOwnerEvidence(capsule.selectedOwners, "context-capsule", input.role) : undefined;
+    const ownerEvaluation = calculateOwnerMetrics(selectedOwnerEvidence, ownerExpectationsFor(producerExpectations, "context-capsule"));
+    const allocationFacts = capsule
+        ? calculateAllocationFactsForGroups(capsule.evidenceGroups, "context-capsule", input.role)
+        : { requiredGroupCapacity: [], usedReservation: [], borrowedCapacity: [], unusedCapacity: [] };
+    const allocationEvaluation = {
+        ...allocationFacts,
+        requiredEvidenceOmitted: {
+            availability: "not-applicable",
+            count: null,
+            evidenceKeys: [],
+            reason: "Batch 3 bridge evaluation derives omission from truncation records, not expectation matches; see truncationEvaluation."
+        },
+        requiredEvidenceOmittedEntries: []
+    };
+    const truncationSourceArtifact = input.contextCapsule ? "context-capsule" : "retrieval-audit-record";
+    const truncationEvaluation = truncationArtifact
+        ? classifyTruncationRecords(truncationArtifact.truncation.records, truncationSourceArtifact, input.role)
+        : [];
+    const packetAgreement = input.packet !== undefined || rawForAgreement !== undefined ? calculateSupplementalRawAgreement(input.packet, rawForAgreement) : null;
+    const reportAgreement = input.report !== undefined || rawForAgreement !== undefined ? calculateSupplementalRawAgreement(input.report, rawForAgreement) : null;
+    return { ownerEvaluation, allocationEvaluation, truncationEvaluation, packetAgreement, reportAgreement };
+}
+// Builds bridge-evaluator input from an already-loaded combined-bounded-stage-context
+// execution payload (Batch 3 section 12.1: "accept already-read raw, supplemental,
+// readiness, and expectation inputs"). Never reads a file itself.
+export function buildProducerReadinessBridgeInputFromCombinedPayload(payload, expectations) {
+    const implementationPair = payload.contextArtifacts.find((p) => p.role === "implementation");
+    const testPair = payload.contextArtifacts.find((p) => p.role === "test-implementation");
+    const hasImplementationSide = implementationPair !== undefined || payload.implementationContextPacket !== undefined || payload.implementationContextRetrievalReport !== undefined;
+    const hasTestSide = testPair !== undefined || payload.testContextPacket !== undefined || payload.testContextRetrievalReport !== undefined;
+    return {
+        implementation: hasImplementationSide
+            ? {
+                role: "implementation",
+                contextCapsule: implementationPair?.contextCapsule,
+                retrievalAuditRecord: implementationPair?.retrievalAuditRecord,
+                packet: payload.implementationContextPacket,
+                packetSourcePath: payload.implementationContextPacketSourcePath,
+                report: payload.implementationContextRetrievalReport
+            }
+            : undefined,
+        testImplementation: hasTestSide
+            ? {
+                role: "test-implementation",
+                contextCapsule: testPair?.contextCapsule,
+                retrievalAuditRecord: testPair?.retrievalAuditRecord,
+                packet: payload.testContextPacket,
+                packetSourcePath: payload.testContextPacketSourcePath,
+                report: payload.testContextRetrievalReport
+            }
+            : undefined,
+        readiness: payload.readiness,
+        expectations
+    };
+}
+export function evaluateProducerReadinessBridge(input) {
+    const hasAnyInput = input.implementation !== undefined || input.testImplementation !== undefined || input.readiness !== undefined;
+    if (!hasAnyInput) {
+        return {
+            status: "not-applicable",
+            reason: "No producer-readiness bridge inputs (supplemental artifacts or readiness result) were supplied.",
+            implementation: null,
+            testImplementation: null,
+            readinessAgreement: null,
+            criticalityEvaluation: null,
+            warnings: [],
+            evidenceReferences: []
+        };
+    }
+    const evidenceReferences = [];
+    const warnings = [];
+    let implementation = null;
+    if (input.implementation !== undefined) {
+        const evaluated = evaluateSide(input.implementation, input.expectations);
+        implementation = { role: "implementation", ...evaluated };
+        if (input.implementation.packetSourcePath)
+            evidenceReferences.push(input.implementation.packetSourcePath);
+    }
+    let testImplementation = null;
+    if (input.testImplementation !== undefined) {
+        const evaluated = evaluateSide(input.testImplementation, input.expectations);
+        testImplementation = { role: "test-implementation", ...evaluated };
+        if (input.testImplementation.packetSourcePath)
+            evidenceReferences.push(input.testImplementation.packetSourcePath);
+    }
+    let readinessAgreement = null;
+    if (input.readiness !== undefined) {
+        const readinessExpectations = input.expectations.producerReadinessExpectations?.readinessExpectations;
+        const matchingExpectation = readinessExpectations?.find((e) => e.kind === input.readiness.kind);
+        const relevantPacket = input.readiness.kind === "implementation" ? input.implementation?.packet : input.testImplementation?.packet;
+        const relevantPacketPath = input.readiness.kind === "implementation" ? input.implementation?.packetSourcePath : input.testImplementation?.packetSourcePath;
+        readinessAgreement = calculateReadinessAgreementMetrics(input.readiness, matchingExpectation, relevantPacket, relevantPacketPath);
+    }
+    const criticalityMappings = input.testImplementation?.retrievalAuditRecord?.responsibilityMappings.mappings ??
+        input.testImplementation?.contextCapsule?.responsibilityMappings.mappings ??
+        input.implementation?.retrievalAuditRecord?.responsibilityMappings.mappings ??
+        input.implementation?.contextCapsule?.responsibilityMappings.mappings;
+    const criticalityEvaluation = calculateCriticalityMetrics(criticalityMappings, input.expectations.producerReadinessExpectations?.criticalityExpectations);
+    return {
+        status: "evaluated",
+        reason: null,
+        implementation,
+        testImplementation,
+        readinessAgreement,
+        criticalityEvaluation,
+        warnings,
+        evidenceReferences
+    };
+}

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

@@ -8,3 +8,10 @@ export { compareExpectedContextCapsuleState, compareExpectedRetrievalAuditState,
 export { calculateContextCapsuleResponsibilityMappingMetric, calculateRetrievalAuditResponsibilityMappingMetric } from "./calculateResponsibilityMappingMetrics.js";
 export { calculateV043ExecutionContextSize } from "./calculateContextSizeMetrics.js";
 export { evaluateV043StageContextExecution } from "./evaluateV043StageContextExecution.js";
+export { collectSelectedOwnerEvidence, calculateOwnerMetrics } from "./calculateOwnerMetrics.js";
+export { calculateAllocationFactsForGroups, calculateRequiredEvidenceOmitted, findAllocationExpectationForGroup } from "./calculateAllocationMetrics.js";
+export { classifyTruncationRecord, classifyTruncationRecords } from "./calculateTruncationClassification.js";
+export { calculateSupplementalRawAgreement } from "./calculateSupplementalRawAgreement.js";
+export { calculateReadinessStructuralAgreement, calculateReadinessDecisionAgreement, calculateInvalidReady, calculateValidBlocked, calculateReadinessAgreementMetrics } from "./calculateReadinessAgreement.js";
+export { calculateCriticalityMetrics } from "./calculateCriticalityMetrics.js";
+export { evaluateProducerReadinessBridge, buildProducerReadinessBridgeInputFromCombinedPayload } from "./evaluateProducerReadinessBridge.js";

package/dist/src/evaluation/stageContextMetrics/producerReadinessMetricTypes.js

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

package/dist/src/evaluation/stageContextSelectors/contextArtifactConsistency.js

@@ -18,6 +18,16 @@ export function checkMyDevKitContextArtifactConsistency(capsule, audit) {
             capsuleValue: capsule.index.manifestPath,
             auditValue: audit.index.manifestPath
         },
+        {
+            fieldPath: "index.manifestSchemaVersion",
+            capsuleValue: capsule.index.manifestSchemaVersion ?? null,
+            auditValue: audit.index.manifestSchemaVersion ?? null
+        },
+        {
+            fieldPath: "index.projectRoot",
+            capsuleValue: capsule.index.projectRoot ?? null,
+            auditValue: audit.index.projectRoot ?? null
+        },
         {
             fieldPath: "contextAdequacy",
             capsuleValue: capsule.contextAdequacy,

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

@@ -1,3 +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";