@neuraloom/contracts 0.0.0-stage → 0.1.22

package/dist/schemas/implement-patch-lifecycle.schema.js

@@ -0,0 +1,317 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalPatchLifecycleStateSchema = exports.ImplementPatchLifecycleStateSchema = void 0;
+exports.toCanonicalPatchLifecycleState = toCanonicalPatchLifecycleState;
+exports.deriveImplementPatchLifecycle = deriveImplementPatchLifecycle;
+exports.implementPatchLifecycleStateLabel = implementPatchLifecycleStateLabel;
+exports.extractImplementPatchFailureDetail = extractImplementPatchFailureDetail;
+const zod_1 = require("zod");
+/**
+ * Canonical Implement patch lifecycle for UI + CI gate copy (SSOT).
+ * Derived from workflow row, active patch row, and full patch list (incl. terminal failures).
+ */
+exports.ImplementPatchLifecycleStateSchema = zod_1.z.enum([
+    "no_patch",
+    "patch_generating",
+    "patch_draft",
+    "patch_validating",
+    "patch_failed",
+    "patch_validated",
+    "patch_pushed",
+    "pr_open",
+    "pr_merged",
+    "implementation_complete",
+]);
+/**
+ * Canonical 7-state patch lifecycle for evidence spine (ms09 Wave 3).
+ * Maps from the richer ImplementPatchLifecycleState for UI/CI consumers.
+ */
+exports.CanonicalPatchLifecycleStateSchema = zod_1.z.enum([
+    "planned",
+    "drafted",
+    "realized",
+    "validated",
+    "writeback_ready",
+    "pr_created",
+    "merged",
+]);
+/** Maps the rich ImplementPatchLifecycleState to canonical 7-state. */
+function toCanonicalPatchLifecycleState(state) {
+    switch (state) {
+        case "no_patch":
+        case "patch_generating":
+            return "planned";
+        case "patch_draft":
+            return "drafted";
+        case "patch_validating":
+        case "patch_failed":
+            return "drafted";
+        case "patch_validated":
+            return "validated";
+        case "patch_pushed":
+            return "writeback_ready";
+        case "pr_open":
+            return "pr_created";
+        case "pr_merged":
+        case "implementation_complete":
+            return "merged";
+    }
+}
+function isTerminalPatchStatus(s) {
+    return s === "failed" || s === "rejected" || s === "quarantined";
+}
+/** Draft / validated / pushed — operator still owes Validate → Push → PR on this patch. */
+function isInPipelinePatchStatus(s) {
+    return s === "draft" || s === "validated" || s === "pushed";
+}
+function deriveStateFromActivePatch(activePatchSet) {
+    const { status, artifactId } = activePatchSet;
+    if (status === "draft") {
+        return { state: "patch_draft", focusedPatchArtifactId: artifactId };
+    }
+    if (status === "validated") {
+        return { state: "patch_validated", focusedPatchArtifactId: artifactId };
+    }
+    if (status === "pushed") {
+        return { state: "patch_pushed", focusedPatchArtifactId: artifactId };
+    }
+    if (status === "pr_created") {
+        return { state: "pr_open", focusedPatchArtifactId: artifactId };
+    }
+    if (status === "failed" || status === "rejected") {
+        return { state: "patch_failed", focusedPatchArtifactId: artifactId };
+    }
+    return { state: "no_patch", focusedPatchArtifactId: null };
+}
+/** Newest patch by updatedAt (ISO string compare). */
+function newestPatch(patches) {
+    if (patches.length === 0)
+        return null;
+    let best = patches[0];
+    for (let i = 1; i < patches.length; i++) {
+        const p = patches[i];
+        if (p.updatedAt > best.updatedAt)
+            best = p;
+    }
+    return best;
+}
+/**
+ * Single derivation for Implement + CI consumers.
+ * Precedence: step complete → stuck running w/ terminal patch (no active) → transient generating → validating → active patch row → terminal failure patch → empty.
+ */
+function deriveImplementPatchLifecycle(input) {
+    const { implementStepComplete, implementNormalizedStatus, clientFlow = "idle", activePatchSet, patches, latestCompletedPatchSet, } = input;
+    // In-pipeline patch rows win over workflow "complete" (prior PR must not hide active work).
+    if (activePatchSet !== null &&
+        isInPipelinePatchStatus(activePatchSet.status)) {
+        return deriveStateFromActivePatch(activePatchSet);
+    }
+    if (implementStepComplete) {
+        const hadPrHandoff = latestCompletedPatchSet !== null;
+        return {
+            // Patch list only proves pr_created — not GitHub merge. Do not label "PR merged".
+            state: hadPrHandoff ? "pr_open" : "implementation_complete",
+            focusedPatchArtifactId: latestCompletedPatchSet?.artifactId ?? null,
+        };
+    }
+    // #630: Validate→failed clears actionable patch (getActivePatch excludes terminal rows)
+    // while workflow can remain "running". Prefer surfacing the failed patch over empty/generating.
+    if (clientFlow === "idle" &&
+        implementNormalizedStatus === "running" &&
+        activePatchSet === null) {
+        const terminalPatches = patches.filter((p) => isTerminalPatchStatus(p.status));
+        const latestTerminal = newestPatch(terminalPatches);
+        if (latestTerminal !== null) {
+            return {
+                state: "patch_failed",
+                focusedPatchArtifactId: latestTerminal.artifactId,
+            };
+        }
+    }
+    // Remaining active patch rows (incl. pr_created on active row).
+    if (activePatchSet !== null) {
+        return deriveStateFromActivePatch(activePatchSet);
+    }
+    if (clientFlow === "generating" ||
+        implementNormalizedStatus === "running") {
+        return {
+            state: "patch_generating",
+            focusedPatchArtifactId: null,
+        };
+    }
+    if (clientFlow === "validating") {
+        return {
+            state: "patch_validating",
+            focusedPatchArtifactId: null,
+        };
+    }
+    const latest = newestPatch(patches);
+    if (latest !== null && isTerminalPatchStatus(latest.status)) {
+        return {
+            state: "patch_failed",
+            focusedPatchArtifactId: latest.artifactId,
+        };
+    }
+    return { state: "no_patch", focusedPatchArtifactId: null };
+}
+const LIFECYCLE_LABEL = {
+    no_patch: "No patch yet",
+    patch_generating: "Generating patch",
+    patch_draft: "Patch draft",
+    patch_validating: "Validating patch",
+    patch_failed: "Patch failed",
+    patch_validated: "Patch validated",
+    patch_pushed: "Branch pushed",
+    pr_open: "PR open",
+    pr_merged: "PR merged on GitHub",
+    implementation_complete: "Implementation complete",
+};
+function implementPatchLifecycleStateLabel(state) {
+    return LIFECYCLE_LABEL[state];
+}
+function collectFailedChecks(validation) {
+    if (validation === null || typeof validation !== "object")
+        return [];
+    const raw = validation.checks;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const c of raw) {
+        if (c === null || typeof c !== "object")
+            continue;
+        const o = c;
+        const status = typeof o.status === "string" ? o.status : "";
+        if (status !== "fail")
+            continue;
+        const code = typeof o.code === "string" ? o.code : "UNKNOWN_CHECK";
+        const message = typeof o.message === "string" ? o.message : "";
+        if (message.length === 0)
+            continue;
+        const filePath = typeof o.filePath === "string" && o.filePath.length > 0 ? o.filePath : undefined;
+        out.push(filePath !== undefined ? { code, message, filePath } : { code, message });
+    }
+    return out;
+}
+function metaFromValidation(validation) {
+    if (validation === null || typeof validation !== "object")
+        return {};
+    const o = validation;
+    const stderr = typeof o.stderr === "string" && o.stderr.length > 0 ? o.stderr : undefined;
+    const command = typeof o.command === "string" && o.command.length > 0 ? o.command : undefined;
+    const stage = typeof o.stage === "string" && o.stage.length > 0 ? o.stage : undefined;
+    const meta = typeof o.meta === "object" && o.meta !== null ? o.meta : {};
+    const stderrFromMeta = stderr ?? (typeof meta.stderr === "string" && meta.stderr.length > 0 ? meta.stderr : undefined);
+    const commandFromMeta = command ??
+        (typeof meta.command === "string" && meta.command.length > 0 ? meta.command : undefined);
+    const stageFromMeta = stage ?? (typeof meta.stage === "string" && meta.stage.length > 0 ? meta.stage : undefined);
+    return {
+        ...(stderrFromMeta !== undefined ? { stderr: stderrFromMeta } : {}),
+        ...(commandFromMeta !== undefined ? { command: commandFromMeta } : {}),
+        ...(stageFromMeta !== undefined ? { stage: stageFromMeta } : {}),
+    };
+}
+/** Best-effort failure surface for Implement patch detail (task binding errors first). */
+function extractImplementPatchFailureDetail(detail) {
+    if (detail === null || detail === undefined)
+        return null;
+    if (detail.status !== "failed" && detail.status !== "rejected")
+        return null;
+    const correlationId = detail.artifactId;
+    for (const b of detail.taskBindings) {
+        if (typeof b.errorMessage === "string" && b.errorMessage.length > 0) {
+            return { correlationId, message: b.errorMessage };
+        }
+        if (typeof b.errorCode === "string" && b.errorCode.length > 0) {
+            return {
+                correlationId,
+                message: b.errorCode,
+            };
+        }
+    }
+    const failingChecks = collectFailedChecks(detail.validation);
+    const meta = metaFromValidation(detail.validation);
+    const diagnostics = detail.validation !== null &&
+        typeof detail.validation === "object" &&
+        "diagnostics" in detail.validation &&
+        detail.validation.diagnostics !== null &&
+        typeof detail.validation.diagnostics === "object"
+        ? detail.validation.diagnostics
+        : null;
+    const firstFail = failingChecks[0];
+    let message = firstFail !== undefined
+        ? firstFail.code === firstFail.message
+            ? firstFail.message
+            : `[${firstFail.code}] ${firstFail.message}`
+        : "";
+    if (message.length === 0 && detail.validation !== null && typeof detail.validation === "object") {
+        const v = detail.validation;
+        const topMsg = typeof v.message === "string" ? v.message : "";
+        if (topMsg.length > 0)
+            message = topMsg;
+    }
+    if (message.length === 0) {
+        return {
+            correlationId,
+            message: "",
+            ...(failingChecks.length > 0 ? { failingChecks } : {}),
+            ...(meta.stderr !== undefined ? { stderr: meta.stderr } : {}),
+            ...(meta.command !== undefined ? { command: meta.command } : {}),
+            ...(meta.stage !== undefined ? { stage: meta.stage } : {}),
+        };
+    }
+    const offendingFilePath = firstFail?.filePath !== undefined
+        ? firstFail.filePath
+        : failingChecks.find((x) => x.filePath)?.filePath;
+    const diagRealisationMode = diagnostics !== null && typeof diagnostics.realisationMode === "string"
+        ? diagnostics.realisationMode
+        : undefined;
+    const diagSelectedTaskIds = diagnostics !== null && Array.isArray(diagnostics.selectedTaskIds)
+        ? diagnostics.selectedTaskIds.filter((x) => typeof x === "string")
+        : undefined;
+    const diagGeneratedFilePaths = diagnostics !== null && Array.isArray(diagnostics.generatedFilePaths)
+        ? diagnostics.generatedFilePaths.filter((x) => typeof x === "string")
+        : undefined;
+    const diagExpectedFilesMissing = diagnostics !== null && Array.isArray(diagnostics.expectedFilesMissing)
+        ? diagnostics.expectedFilesMissing.filter((x) => typeof x === "string")
+        : undefined;
+    const diagTypecheckCommand = diagnostics !== null && typeof diagnostics.typecheckCommand === "string"
+        ? diagnostics.typecheckCommand
+        : undefined;
+    const diagOutsideScope = diagnostics !== null && Array.isArray(diagnostics.outsideScopeFiles)
+        ? diagnostics.outsideScopeFiles.filter((x) => typeof x === "string")
+        : undefined;
+    const diagAllowedFiles = diagnostics !== null && Array.isArray(diagnostics.allowedPacketFiles)
+        ? diagnostics.allowedPacketFiles.filter((x) => typeof x === "string")
+        : undefined;
+    const diagScopeCode = diagnostics !== null && typeof diagnostics.scopePreflightCode === "string"
+        ? diagnostics.scopePreflightCode
+        : undefined;
+    const out = {
+        correlationId,
+        message,
+        ...(offendingFilePath !== undefined ? { offendingFilePath } : {}),
+        ...(failingChecks.length > 0 ? { failingChecks } : {}),
+        ...(meta.stderr !== undefined ? { stderr: meta.stderr } : {}),
+        ...(meta.command !== undefined ? { command: meta.command } : {}),
+        ...(meta.stage !== undefined ? { stage: meta.stage } : {}),
+        ...(diagRealisationMode !== undefined ? { realisationMode: diagRealisationMode } : {}),
+        ...(diagSelectedTaskIds !== undefined && diagSelectedTaskIds.length > 0
+            ? { selectedTaskIds: diagSelectedTaskIds }
+            : {}),
+        ...(diagGeneratedFilePaths !== undefined && diagGeneratedFilePaths.length > 0
+            ? { generatedFilePaths: diagGeneratedFilePaths }
+            : {}),
+        ...(diagExpectedFilesMissing !== undefined && diagExpectedFilesMissing.length > 0
+            ? { expectedFilesMissing: diagExpectedFilesMissing }
+            : {}),
+        ...(diagOutsideScope !== undefined && diagOutsideScope.length > 0
+            ? { outsideScopeFiles: diagOutsideScope }
+            : {}),
+        ...(diagAllowedFiles !== undefined && diagAllowedFiles.length > 0
+            ? { allowedPacketFiles: diagAllowedFiles }
+            : {}),
+        ...(diagScopeCode !== undefined ? { scopePreflightCode: diagScopeCode } : {}),
+        ...(diagTypecheckCommand !== undefined ? { typecheckCommand: diagTypecheckCommand } : {}),
+    };
+    return out;
+}

package/dist/schemas/implement-patch-task.schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const ImplementPatchTaskStatusSchema: z.ZodEnum<["queued", "generating", "draft", "validated", "push_pending", "in_branch", "pr_pending", "in_review", "merged", "failed", "abandoned"]>;
+export type ImplementPatchTaskStatus = z.infer<typeof ImplementPatchTaskStatusSchema>;
+export declare const ImplementPatchTaskBindingSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    status: z.ZodEnum<["queued", "generating", "draft", "validated", "push_pending", "in_branch", "pr_pending", "in_review", "merged", "failed", "abandoned"]>;
+    branchName: z.ZodNullable<z.ZodString>;
+    pullRequestUrl: z.ZodNullable<z.ZodString>;
+    pullRequestNumber: z.ZodNullable<z.ZodNumber>;
+    errorCode: z.ZodNullable<z.ZodString>;
+    errorMessage: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "generating" | "queued" | "draft" | "merged" | "validated" | "in_review" | "push_pending" | "in_branch" | "pr_pending" | "abandoned";
+    branchName: string | null;
+    errorCode: string | null;
+    taskId: string;
+    pullRequestNumber: number | null;
+    pullRequestUrl: string | null;
+    errorMessage: string | null;
+}, {
+    status: "failed" | "generating" | "queued" | "draft" | "merged" | "validated" | "in_review" | "push_pending" | "in_branch" | "pr_pending" | "abandoned";
+    branchName: string | null;
+    errorCode: string | null;
+    taskId: string;
+    pullRequestNumber: number | null;
+    pullRequestUrl: string | null;
+    errorMessage: string | null;
+}>;
+export type ImplementPatchTaskBinding = z.infer<typeof ImplementPatchTaskBindingSchema>;

package/dist/schemas/implement-patch-task.schema.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImplementPatchTaskBindingSchema = exports.ImplementPatchTaskStatusSchema = void 0;
+const zod_1 = require("zod");
+exports.ImplementPatchTaskStatusSchema = zod_1.z.enum([
+    "queued",
+    "generating",
+    "draft",
+    "validated",
+    "push_pending",
+    "in_branch",
+    "pr_pending",
+    "in_review",
+    "merged",
+    "failed",
+    "abandoned",
+]);
+exports.ImplementPatchTaskBindingSchema = zod_1.z.object({
+    taskId: zod_1.z.string().uuid(),
+    status: exports.ImplementPatchTaskStatusSchema,
+    branchName: zod_1.z.string().nullable(),
+    pullRequestUrl: zod_1.z.string().nullable(),
+    pullRequestNumber: zod_1.z.number().int().nullable(),
+    errorCode: zod_1.z.string().nullable(),
+    errorMessage: zod_1.z.string().nullable(),
+});