@zq-silk/yui 0.6.0 → 0.6.2

package/dist/integration/integrationAttempt.js

@@ -4,7 +4,7 @@ import { normalizeCheckResult } from "./checkResult.js";
 export function createIntegrationAttempt(input, now) {
     const timestamp = now.toISOString();
     return validateIntegrationAttempt({
-        schemaVersion: 2,
+        schemaVersion: 4,
         id: input.id,
         taskId: input.taskId,
         projectId: input.projectId,
@@ -17,6 +17,26 @@ export function createIntegrationAttempt(input, now) {
         updatedAt: timestamp
     });
 }
+/**
+ * Bind the check DurableJob to a running attempt. Set-once: the job is the
+ * durable source of truth for the checks, so a retry of the start path must
+ * find the recorded job instead of spawning a second one.
+ */
+export function recordIntegrationCheckJob(attempt, jobId, now) {
+    validateIntegrationAttempt(attempt);
+    if (attempt.status !== "running") {
+        throw new Error(`Integration check job can only bind a running attempt: ${attempt.status}.`);
+    }
+    if (attempt.jobId !== undefined) {
+        throw new Error(`Integration check job is already recorded: ${attempt.jobId}.`);
+    }
+    validateTaskRecordReference({ taskId: attempt.taskId, localId: jobId }, "durableJob");
+    return validateIntegrationAttempt({
+        ...attempt,
+        jobId,
+        updatedAt: now.toISOString()
+    });
+}
 export function requireLeaderDecision(attempt, report, now) {
     validateIntegrationAttempt(attempt);
     const continuingAfterResolution = attempt.status === "blocked"
@@ -54,10 +74,11 @@ export function recordResolutionDecision(attempt, decision, now) {
         ...(decision.action === "reject" ? { endedAt: timestamp } : {})
     });
 }
+const TERMINAL_STATUSES = ["committed", "superseded", "failed"];
 export function updateIntegrationAttempt(attempt, patch, now) {
     validateIntegrationAttempt(attempt);
     const status = patch.status ?? attempt.status;
-    const terminal = ["committed", "failed"].includes(status);
+    const terminal = TERMINAL_STATUSES.includes(status);
     const updated = {
         ...attempt,
         ...patch,
@@ -71,9 +92,33 @@ export function updateIntegrationAttempt(attempt, patch, now) {
     }
     return validateIntegrationAttempt(updated);
 }
+/**
+ * Mark a committed Integration as superseded (obsolete).  A superseded
+ * Integration retains its evidence but is excluded from latest-committed
+ * selection, allowing the next valid committed Integration to become the
+ * Task's delivery baseline.  Only a committed Integration may be superseded;
+ * a reason is required for the audit trail.
+ */
+export function supersedeIntegration(attempt, reason, now) {
+    validateIntegrationAttempt(attempt);
+    if (attempt.status !== "committed") {
+        throw new Error(`Integration cannot be superseded from ${attempt.status}: ${attempt.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateIntegrationAttempt({
+        ...attempt,
+        status: "superseded",
+        checks: [
+            ...(attempt.checks ?? []),
+            { name: "superseded", outcome: "failed", details: requireText(reason, "Supersede reason") }
+        ],
+        updatedAt: timestamp,
+        endedAt: timestamp
+    });
+}
 export function validateIntegrationAttempt(attempt) {
-    if (attempt.schemaVersion !== 2) {
-        throw new Error("IntegrationAttempt must use schemaVersion 2.");
+    if (attempt.schemaVersion !== 4) {
+        throw new Error("IntegrationAttempt must use schemaVersion 4.");
     }
     validateTaskRecordReference({
         taskId: attempt.taskId,
@@ -93,11 +138,15 @@ export function validateIntegrationAttempt(attempt) {
     if (attempt.candidateCommit !== undefined) {
         requireCommit(attempt.candidateCommit, "Integration candidate commit");
     }
+    if (attempt.jobId !== undefined) {
+        validateTaskRecordReference({ taskId: attempt.taskId, localId: attempt.jobId }, "durableJob");
+    }
     if (![
         "running",
         "blocked",
         "validating",
         "committed",
+        "superseded",
         "failed"
     ].includes(attempt.status)) {
         throw new Error(`Integration status is invalid: ${String(attempt.status)}.`);
@@ -121,7 +170,7 @@ export function validateIntegrationAttempt(attempt) {
     attempt.checks?.forEach(normalizeCheckResult);
     requireTimestamp(attempt.createdAt, "Integration Attempt createdAt");
     requireTimestamp(attempt.updatedAt, "Integration Attempt updatedAt");
-    if (["committed", "failed"].includes(attempt.status)) {
+    if (TERMINAL_STATUSES.includes(attempt.status)) {
         requireTimestamp(attempt.endedAt ?? "", "Integration Attempt endedAt");
     }
     return attempt;

package/dist/integration/integrationQueueEntry.js

@@ -0,0 +1,221 @@
+import { normalizedUniqueIdentities, normalizedUniqueText, requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+export function createIntegrationQueueEntry(input, now) {
+    const timestamp = now.toISOString();
+    return validateIntegrationQueueEntry({
+        schemaVersion: 1,
+        id: input.id,
+        taskId: input.taskId,
+        projectId: input.projectId,
+        changeSetId: input.changeSetId,
+        targetRef: input.targetRef,
+        status: "queued",
+        checkCommands: normalizedUniqueText(input.checkCommands ?? [], "Integration queue check command"),
+        evidenceRefs: normalizedUniqueText(input.evidenceRefs ?? [], "Integration queue evidence"),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+/**
+ * An entry whose ChangeSet is already represented on the target (an ancestor
+ * or a same-tree commit) converges directly to committed with its proof.  The
+ * entry still names the committed IntegrationAttempt that recorded the
+ * convergence, so every acceptance and provenance consumer reads one
+ * integration authority.
+ */
+export function createConvergedIntegrationQueueEntry(input, now) {
+    const timestamp = now.toISOString();
+    return validateIntegrationQueueEntry({
+        schemaVersion: 1,
+        id: input.id,
+        taskId: input.taskId,
+        projectId: input.projectId,
+        changeSetId: input.changeSetId,
+        targetRef: input.targetRef,
+        status: "committed",
+        checkCommands: [],
+        targetBefore: input.targetHead,
+        targetAfter: input.targetHead,
+        evidenceRefs: [input.proof],
+        ...(input.integrationAttemptId === undefined
+            ? {}
+            : { integrationAttemptId: input.integrationAttemptId }),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        endedAt: timestamp
+    });
+}
+export function markIntegrationQueueRunning(entry, targetBefore, now) {
+    validateIntegrationQueueEntry(entry);
+    if (!["queued", "conflicted", "validated"].includes(entry.status)) {
+        throw new Error(`Integration queue entry cannot run from ${entry.status}: ${entry.id}.`);
+    }
+    const { conflictSummary: _previousConflict, ...rest } = entry;
+    return validateIntegrationQueueEntry({
+        ...rest,
+        status: "running",
+        targetBefore,
+        updatedAt: now.toISOString()
+    });
+}
+export function recordIntegrationQueueAttempt(entry, integrationAttemptId, now) {
+    validateIntegrationQueueEntry(entry);
+    if (entry.status !== "running") {
+        throw new Error(`Integration queue entry is not running: ${entry.id}/${entry.status}.`);
+    }
+    return validateIntegrationQueueEntry({
+        ...entry,
+        integrationAttemptId,
+        updatedAt: now.toISOString()
+    });
+}
+export function markIntegrationQueueBlocked(entry, conflictSummary, now) {
+    validateIntegrationQueueEntry(entry);
+    if (entry.status !== "running") {
+        throw new Error(`Integration queue entry is not running: ${entry.id}/${entry.status}.`);
+    }
+    return validateIntegrationQueueEntry({
+        ...entry,
+        status: "conflicted",
+        conflictSummary: requireText(conflictSummary, "Integration queue conflict summary"),
+        updatedAt: now.toISOString()
+    });
+}
+export function markIntegrationQueueCommitted(entry, targetAfter, now) {
+    validateIntegrationQueueEntry(entry);
+    if (entry.status !== "running" && entry.status !== "conflicted") {
+        throw new Error(`Integration queue entry cannot commit from ${entry.status}: ${entry.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateIntegrationQueueEntry({
+        ...entry,
+        status: "committed",
+        targetAfter,
+        updatedAt: timestamp,
+        endedAt: timestamp
+    });
+}
+/**
+ * Records that this entry's reusable evidence was checked against an exact
+ * target head.  The evidence only covers `evidenceTargetHead`; a target
+ * advance invalidates it unless the delta is provably empty.  Path
+ * disjointness alone never justifies this transition: a gate may read any
+ * file, so a non-empty target increment cannot be proven irrelevant.
+ */
+export function markIntegrationQueueValidated(entry, now, evidenceTargetHead) {
+    validateIntegrationQueueEntry(entry);
+    if (entry.status !== "queued") {
+        throw new Error(`Integration queue entry cannot validate from ${entry.status}: ${entry.id}.`);
+    }
+    if (entry.evidenceRefs.length === 0) {
+        throw new Error(`Integration queue entry has no reusable evidence: ${entry.id}.`);
+    }
+    return validateIntegrationQueueEntry({
+        ...entry,
+        status: "validated",
+        ...(evidenceTargetHead === undefined ? {} : { evidenceTargetHead }),
+        updatedAt: now.toISOString()
+    });
+}
+/**
+ * A validated entry whose ChangeSet became affected by a later target advance
+ * loses its evidence coverage and runs its checks again; a conflicted entry is
+ * manually retried after its underlying issue was fixed.
+ */
+export function markIntegrationQueueRequeued(entry, now) {
+    validateIntegrationQueueEntry(entry);
+    if (entry.status !== "validated" && entry.status !== "conflicted") {
+        throw new Error(`Integration queue entry cannot requeue from ${entry.status}: ${entry.id}.`);
+    }
+    return validateIntegrationQueueEntry({
+        ...entry,
+        status: "queued",
+        updatedAt: now.toISOString()
+    });
+}
+export function recordIntegrationQueueAffectedPaths(entry, affectedPaths, now) {
+    validateIntegrationQueueEntry(entry);
+    if (!["queued", "validated"].includes(entry.status)) {
+        throw new Error(`Integration queue entry cannot recompute overlap from ${entry.status}: ${entry.id}.`);
+    }
+    const previous = new Set(entry.affectedPaths ?? []);
+    const merged = [...new Set([...previous, ...affectedPaths])].sort();
+    return validateIntegrationQueueEntry({
+        ...entry,
+        affectedPaths: merged,
+        updatedAt: now.toISOString()
+    });
+}
+export function markIntegrationQueueSuperseded(entry, reason, now) {
+    validateIntegrationQueueEntry(entry);
+    if (!["queued", "conflicted", "validated"].includes(entry.status)) {
+        throw new Error(`Integration queue entry cannot be superseded from ${entry.status}: ${entry.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateIntegrationQueueEntry({
+        ...entry,
+        status: "superseded",
+        supersedeReason: requireText(reason, "Integration queue supersede reason"),
+        updatedAt: timestamp,
+        endedAt: timestamp
+    });
+}
+export function validateIntegrationQueueEntry(entry) {
+    if (entry.schemaVersion !== 1) {
+        throw new Error("IntegrationQueueEntry must use schemaVersion 1.");
+    }
+    validateTaskRecordReference({ taskId: entry.taskId, localId: entry.id }, "integrationQueue");
+    validateTaskRecordReference({ taskId: entry.taskId, localId: entry.changeSetId }, "changeSet");
+    requireIdentity(entry.projectId, "Project id");
+    requireText(entry.targetRef, "Integration queue target ref");
+    normalizedUniqueText(entry.checkCommands, "Integration queue check command");
+    normalizedUniqueText(entry.evidenceRefs, "Integration queue evidence");
+    if (![
+        "queued",
+        "running",
+        "conflicted",
+        "validated",
+        "committed",
+        "superseded"
+    ].includes(entry.status)) {
+        throw new Error(`Integration queue status is invalid: ${String(entry.status)}.`);
+    }
+    if (entry.targetBefore !== undefined)
+        requireCommit(entry.targetBefore, "Integration queue targetBefore");
+    if (entry.targetAfter !== undefined)
+        requireCommit(entry.targetAfter, "Integration queue targetAfter");
+    if (entry.evidenceTargetHead !== undefined) {
+        requireCommit(entry.evidenceTargetHead, "Integration queue evidenceTargetHead");
+    }
+    if (entry.integrationAttemptId !== undefined) {
+        normalizedUniqueIdentities([entry.integrationAttemptId], "Integration attempt id");
+    }
+    if (entry.conflictSummary !== undefined) {
+        requireText(entry.conflictSummary, "Integration queue conflict summary");
+    }
+    if (entry.affectedPaths !== undefined) {
+        normalizedUniqueText(entry.affectedPaths, "Integration queue affected path");
+    }
+    if (entry.supersedeReason !== undefined) {
+        requireText(entry.supersedeReason, "Integration queue supersede reason");
+    }
+    requireTimestamp(entry.createdAt, "Integration queue entry createdAt");
+    requireTimestamp(entry.updatedAt, "Integration queue entry updatedAt");
+    if (["committed", "superseded"].includes(entry.status)) {
+        requireTimestamp(entry.endedAt ?? "", "Integration queue entry endedAt");
+    }
+    if (entry.status === "committed") {
+        requireCommit(entry.targetAfter ?? "", "Integration queue targetAfter");
+    }
+    if (entry.status === "running") {
+        requireCommit(entry.targetBefore ?? "", "Integration queue targetBefore");
+    }
+    return entry;
+}
+function requireCommit(value, label) {
+    const normalized = requireText(value, label).toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}