@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/control/providerLinearWorkerTruth.js

@@ -0,0 +1,383 @@
+const AUXILIARY_PROOF_HARNESS_SUMMARY = 'manual live proof harness';
+const AUXILIARY_PROOF_HARNESS_RUN_ID_SUFFIX = '-manual-live-proof';
+const FOLLOW_UP_PARITY_MATRIX_SUPPRESSION_CODES = new Set([
+    'linear_follow_up_parity_matrix_missing',
+    'linear_follow_up_parity_matrix_retry_suppressed'
+]);
+const CHILD_LANE_PARENT_DIRTY_SUPPRESSION_CODES = new Set([
+    'provider_worker_child_lane_parent_dirty',
+    'provider_worker_child_lane_parent_dirty_retry_suppressed'
+]);
+export function isAuxiliaryProviderProofHarnessManifest(manifest) {
+    const runId = readStringValue(manifest, 'run_id', 'runId');
+    const summary = readStringValue(manifest, 'summary');
+    return (summary === AUXILIARY_PROOF_HARNESS_SUMMARY ||
+        (typeof runId === 'string' && runId.endsWith(AUXILIARY_PROOF_HARNESS_RUN_ID_SUFFIX)));
+}
+export function resolveProviderLinearWorkerTerminalStatus(proof) {
+    if (!proof) {
+        return null;
+    }
+    if (readStringValue(proof, 'owner_phase') !== 'ended') {
+        return null;
+    }
+    const ownerStatus = readStringValue(proof, 'owner_status');
+    return ownerStatus === 'failed' || ownerStatus === 'succeeded' ? ownerStatus : null;
+}
+export function resolveProviderLinearWorkerTerminalReason(proof) {
+    if (!resolveProviderLinearWorkerTerminalStatus(proof)) {
+        return null;
+    }
+    return readStringValue(proof ?? {}, 'end_reason');
+}
+export function resolveProviderLinearWorkerAttemptStartedAt(proof) {
+    return readStringValue(proof ?? {}, 'attempt_started_at');
+}
+export function isProviderLinearWorkerProofFreshForStage(proof, stageStartedAt) {
+    if (!proof) {
+        return false;
+    }
+    const stageStartedAtMs = readTimestampMs({
+        started_at: stageStartedAt ?? null
+    }, 'started_at');
+    if (!Number.isFinite(stageStartedAtMs)) {
+        return true;
+    }
+    const proofAttemptStartedAtMs = readTimestampMs(proof ?? {}, 'attempt_started_at');
+    if (Number.isFinite(proofAttemptStartedAtMs)) {
+        return proofAttemptStartedAtMs >= stageStartedAtMs;
+    }
+    const proofUpdatedAtMs = readTimestampMs(proof ?? {}, 'updated_at');
+    return Number.isFinite(proofUpdatedAtMs) && proofUpdatedAtMs >= stageStartedAtMs;
+}
+export function shouldUseProviderLinearWorkerTerminalProofForSelectedRun(manifest, proof) {
+    const proofStatus = resolveProviderLinearWorkerTerminalStatus(proof);
+    if (!proofStatus) {
+        return false;
+    }
+    const proofUpdatedAtMs = readTimestampMs(proof ?? {}, 'updated_at');
+    if (!Number.isFinite(proofUpdatedAtMs)) {
+        return false;
+    }
+    const manifestStatus = readStringValue(manifest, 'status');
+    const manifestUpdatedAtMs = readTimestampMs(manifest, 'updated_at', 'updatedAt', 'started_at', 'startedAt');
+    if (!manifestStatus || manifestStatus === 'in_progress') {
+        return !Number.isFinite(manifestUpdatedAtMs) || proofUpdatedAtMs >= manifestUpdatedAtMs;
+    }
+    if (manifestStatus === proofStatus) {
+        return !Number.isFinite(manifestUpdatedAtMs) || proofUpdatedAtMs >= manifestUpdatedAtMs;
+    }
+    return proofStatus === 'failed' && (!Number.isFinite(manifestUpdatedAtMs) || proofUpdatedAtMs > manifestUpdatedAtMs);
+}
+export function buildProviderLinearWorkerTerminalSummary(input) {
+    const baseSummary = formatProviderLinearWorkerTerminalBaseSummary(input.status, input.endReason);
+    const annotations = [input.reviewOutcomeSummary ?? null, input.degradationSummary ?? null].filter((value) => Boolean(value));
+    if (annotations.length === 0) {
+        return baseSummary;
+    }
+    return `${baseSummary} (${annotations.join('; ')})`;
+}
+export function deriveDeterministicProviderMutationSuppressions(audit, options = {}) {
+    if (!audit) {
+        return [];
+    }
+    const latestByOperation = audit.latest_by_operation;
+    if (!latestByOperation || typeof latestByOperation !== 'object') {
+        return [];
+    }
+    const recordedAtNotBeforeMs = readTimestampMs({
+        recorded_at: options.recordedAtNotBefore ?? null
+    }, 'recorded_at');
+    if (!Number.isFinite(recordedAtNotBeforeMs)) {
+        return [];
+    }
+    const issueId = normalizeOptionalString(options.issueId);
+    const entries = selectProviderLinearMutationEntries(audit, latestByOperation)
+        .filter((entry) => Boolean(entry))
+        .filter((entry) => !issueId || entry.issue_id === issueId)
+        .filter((entry) => readTimestampMs(entry, 'recorded_at') >= recordedAtNotBeforeMs)
+        .filter((entry) => entry.ok === false && isDeterministicProviderMutationFailure(entry))
+        .reduce((latestByOperationAndAction, entry) => {
+        latestByOperationAndAction.set(buildProviderLinearMutationEntryKey(entry), entry);
+        return latestByOperationAndAction;
+    }, new Map());
+    return Array.from(entries.values())
+        .sort((left, right) => {
+        const operationOrder = left.operation.localeCompare(right.operation);
+        if (operationOrder !== 0) {
+            return operationOrder;
+        }
+        const leftAction = normalizeAuditAction(left.action) ?? '';
+        const rightAction = normalizeAuditAction(right.action) ?? '';
+        return leftAction.localeCompare(rightAction);
+    })
+        .map((entry) => buildDeterministicProviderMutationSuppression(entry));
+}
+export function findDeterministicProviderMutationSuppression(audit, operation, options = {}) {
+    const requestedAction = normalizeAuditAction(options.action);
+    return (deriveDeterministicProviderMutationSuppressions(audit, options).find((suppression) => suppression.operation === operation &&
+        (!requestedAction || suppression.action === requestedAction)) ?? null);
+}
+export function isFollowUpParityMatrixSuppressionCode(errorCode) {
+    const normalized = normalizeOptionalString(errorCode);
+    return normalized ? FOLLOW_UP_PARITY_MATRIX_SUPPRESSION_CODES.has(normalized) : false;
+}
+export function isChildLaneParentDirtySuppressionCode(errorCode) {
+    const normalized = normalizeOptionalString(errorCode);
+    return normalized ? CHILD_LANE_PARENT_DIRTY_SUPPRESSION_CODES.has(normalized) : false;
+}
+export function formatDeterministicProviderMutationDegradationSummary(suppressions) {
+    if (suppressions.length === 0) {
+        return null;
+    }
+    if (suppressions.length === 1) {
+        return suppressions[0]?.summary ?? null;
+    }
+    const labels = suppressions.map((suppression) => suppression.error_code ? `${suppression.operation}:${suppression.error_code}` : suppression.operation);
+    return `${suppressions.length} deterministic provider mutations were suppressed for this attempt: ${labels.join(', ')}`;
+}
+function buildDeterministicProviderMutationSuppression(entry) {
+    const action = normalizeAuditAction(entry.action);
+    const errorCode = normalizeOptionalString(entry.error_code);
+    const errorMessage = normalizeOptionalString(entry.error_message);
+    switch (entry.operation) {
+        case 'create-follow-up':
+            return {
+                operation: entry.operation,
+                action,
+                error_code: errorCode,
+                error_message: errorMessage,
+                instruction: isFollowUpParityMatrixSuppressionCode(errorCode)
+                    ? 'Do not retry `create-follow-up` in this attempt unless you first add the required parity matrix or explicitly reclassify the follow-up as non-parity/alignment and omit `--parity-lane`.'
+                    : buildGenericSuppressionInstruction(entry.operation, errorCode, errorMessage),
+                summary: isFollowUpParityMatrixSuppressionCode(errorCode)
+                    ? 'deterministic provider mutation suppressed: create-follow-up retry is blocked until a parity matrix is added or the follow-up is reclassified as non-parity/alignment with --parity-lane omitted'
+                    : buildGenericSuppressionSummary(entry.operation, errorCode, errorMessage)
+            };
+        case 'child-lane':
+            if (errorCode === 'provider_worker_child_lane_provenance_invalid') {
+                const launchTimeControlHostProvenanceFailure = action === 'launch' || errorMessage?.includes('control-host provenance') === true;
+                return {
+                    operation: entry.operation,
+                    action,
+                    error_code: errorCode,
+                    error_message: errorMessage,
+                    instruction: launchTimeControlHostProvenanceFailure
+                        ? `Do not retry \`${entry.operation}\` until you first confirm the parent provider-worker run now has matching control-host provenance recorded in the manifest and active environment; if that provenance has already been repaired since the failed audit entry, you may retry once without restarting the attempt. Preserve the fail-closed provenance contract instead of forcing the launch.`
+                        : 'Do not retry `child-lane` until you first confirm the pending child-lane record now matches the expected parent-owned pipeline, task, and issue binding; if that binding has already been repaired since the failed audit entry, you may retry once without restarting the attempt. Preserve the fail-closed provenance contract instead of forcing the decision.',
+                    summary: launchTimeControlHostProvenanceFailure
+                        ? `deterministic provider mutation suppressed: ${entry.operation} fail-closed provenance mismatch must be repaired before retry`
+                        : 'deterministic provider mutation suppressed: child-lane fail-closed provenance mismatch must be reconciled before retry'
+                };
+            }
+            return {
+                operation: entry.operation,
+                action,
+                error_code: errorCode,
+                error_message: errorMessage,
+                instruction: isChildLaneParentDirtySuppressionCode(errorCode)
+                    ? buildChildLaneParentDirtySuppressionInstruction(action)
+                    : buildGenericSuppressionInstruction(entry.operation, errorCode, errorMessage),
+                summary: isChildLaneParentDirtySuppressionCode(errorCode)
+                    ? buildChildLaneParentDirtySuppressionSummary(action)
+                    : buildGenericSuppressionSummary(entry.operation, errorCode, errorMessage)
+            };
+        case 'transition':
+        case 'upsert-workpad':
+            if (errorCode === 'linear_issue_not_mutable') {
+                return {
+                    operation: entry.operation,
+                    action,
+                    error_code: errorCode,
+                    error_message: errorMessage,
+                    instruction: `Do not retry \`${entry.operation}\` in this attempt until the Linear issue is restored to a mutable active state.`,
+                    summary: `deterministic provider mutation suppressed: ${entry.operation} cannot run while the Linear issue is archived or trashed`
+                };
+            }
+            return {
+                operation: entry.operation,
+                action,
+                error_code: errorCode,
+                error_message: errorMessage,
+                instruction: buildGenericSuppressionInstruction(entry.operation, errorCode, errorMessage),
+                summary: buildGenericSuppressionSummary(entry.operation, errorCode, errorMessage)
+            };
+        case 'child-stream':
+            if (errorCode === 'provider_worker_child_stream_provenance_invalid') {
+                return {
+                    operation: entry.operation,
+                    action,
+                    error_code: errorCode,
+                    error_message: errorMessage,
+                    instruction: `Do not retry \`${entry.operation}\` until you first confirm the parent provider-worker run now has matching control-host provenance recorded in the manifest and active environment; if that provenance has already been repaired since the failed audit entry, you may retry once without restarting the attempt. Preserve the fail-closed provenance contract instead of forcing the launch.`,
+                    summary: `deterministic provider mutation suppressed: ${entry.operation} fail-closed provenance mismatch must be repaired before retry`
+                };
+            }
+            return {
+                operation: entry.operation,
+                action,
+                error_code: errorCode,
+                error_message: errorMessage,
+                instruction: buildGenericSuppressionInstruction(entry.operation, errorCode, errorMessage),
+                summary: buildGenericSuppressionSummary(entry.operation, errorCode, errorMessage)
+            };
+        default:
+            return {
+                operation: entry.operation,
+                action,
+                error_code: errorCode,
+                error_message: errorMessage,
+                instruction: buildGenericSuppressionInstruction(entry.operation, errorCode, errorMessage),
+                summary: buildGenericSuppressionSummary(entry.operation, errorCode, errorMessage)
+            };
+    }
+}
+function buildGenericSuppressionInstruction(operation, errorCode, errorMessage) {
+    const detail = [errorCode, errorMessage].filter((value) => Boolean(value)).join(': ');
+    return detail.length > 0
+        ? `Do not retry \`${operation}\` in this attempt until you first fix the deterministic validation error (${detail}).`
+        : `Do not retry \`${operation}\` in this attempt until you first fix the deterministic validation error.`;
+}
+function buildGenericSuppressionSummary(operation, errorCode, errorMessage) {
+    const detail = [errorCode, errorMessage].filter((value) => Boolean(value)).join(': ');
+    return detail.length > 0
+        ? `deterministic provider mutation suppressed: ${operation} failed with ${detail}`
+        : `deterministic provider mutation suppressed: ${operation} failed validation`;
+}
+function buildChildLaneParentDirtySuppressionInstruction(action) {
+    if (action === 'accept') {
+        return 'Do not retry `child-lane --action accept` in this attempt while the parent workspace still has in-scope dirty files. Reconcile those parent changes or move scratch artifacts outside the repo, then accept only after the requested patch scope is clean.';
+    }
+    return 'Do not retry `child-lane --action launch` in this attempt while the parent workspace still has in-scope dirty files. Reconcile those parent changes or move scratch artifacts outside the repo, then relaunch only after the requested scope is clean.';
+}
+function buildChildLaneParentDirtySuppressionSummary(action) {
+    if (action === 'accept') {
+        return 'deterministic provider mutation suppressed: child-lane accept retry is blocked until the parent workspace is clean for the requested patch scope';
+    }
+    return 'deterministic provider mutation suppressed: child-lane launch retry is blocked until the parent workspace is clean for the requested scope';
+}
+function isDeterministicProviderMutationFailure(entry) {
+    const errorCode = normalizeOptionalString(entry.error_code);
+    if (!errorCode) {
+        return false;
+    }
+    if (isFollowUpParityMatrixSuppressionCode(errorCode)) {
+        return true;
+    }
+    if (isChildLaneParentDirtySuppressionCode(errorCode)) {
+        return true;
+    }
+    if (errorCode === 'linear_workpad_comment_id_invalid') {
+        return true;
+    }
+    if (errorCode === 'workpad_body_missing') {
+        return true;
+    }
+    if (errorCode === 'workpad_marker_missing') {
+        return true;
+    }
+    if (errorCode === 'workpad_structure_invalid') {
+        return true;
+    }
+    if (errorCode === 'workpad_section_empty') {
+        return true;
+    }
+    if (errorCode === 'workpad_checklist_required') {
+        return true;
+    }
+    if (errorCode === 'workpad_validation_requirements_missing') {
+        return true;
+    }
+    if (errorCode === 'linear_issue_id_missing') {
+        return true;
+    }
+    if (errorCode === 'linear_issue_not_mutable') {
+        return true;
+    }
+    if (errorCode === 'provider_worker_child_lane_provenance_invalid') {
+        return true;
+    }
+    if (errorCode === 'provider_worker_child_stream_provenance_invalid') {
+        return true;
+    }
+    return /^linear_follow_up_.*_missing$/u.test(errorCode);
+}
+function formatProviderLinearWorkerTerminalBaseSummary(status, endReason) {
+    if (status === 'failed') {
+        if (endReason) {
+            const codexExitMatch = endReason.match(/^codex_exit_(.+)$/u);
+            if (codexExitMatch) {
+                return `Provider linear worker failed with Codex exit code ${codexExitMatch[1] ?? 'unknown'}.`;
+            }
+            switch (endReason) {
+                case 'tracked_issue_rate_limited':
+                    return 'Provider linear worker failed because tracked issue rereads remained rate limited.';
+                case 'tracked_issue_read_failed':
+                    return 'Provider linear worker failed because tracked issue rereads did not succeed.';
+                case 'exec_runner_failed':
+                    return 'Provider linear worker failed because the Codex exec runner could not start or complete.';
+                case 'runtime_parity_command_unavailable':
+                    return 'Provider linear worker failed because the requested runtime executable was unavailable under the current environment.';
+                case 'thread_id_missing':
+                    return 'Provider linear worker failed because Codex did not emit a thread identifier.';
+                case 'provider_linear_worker_proof_missing_or_unreadable':
+                    return 'Provider linear worker failed because authoritative proof was missing or unreadable.';
+                default:
+                    return `Provider linear worker failed (${endReason}).`;
+            }
+        }
+        return 'Provider linear worker failed.';
+    }
+    switch (endReason) {
+        case 'issue_review_handoff':
+            return 'Provider linear worker reached review handoff.';
+        case 'issue_inactive':
+            return 'Provider linear worker stopped because the issue was no longer active.';
+        case 'max_turns_reached_issue_still_active':
+            return 'Provider linear worker exhausted the max turn budget while the issue remained active.';
+        case 'worker_completed':
+            return 'Provider linear worker completed.';
+        default:
+            return endReason ? `Provider linear worker completed (${endReason}).` : 'Provider linear worker completed.';
+    }
+}
+function readTimestampMs(record, ...keys) {
+    const value = readStringValue(record, ...keys);
+    if (!value) {
+        return Number.NaN;
+    }
+    return Date.parse(value);
+}
+function readStringValue(record, ...keys) {
+    for (const key of keys) {
+        const value = normalizeOptionalString(record[key]);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function selectProviderLinearMutationEntries(audit, latestByOperation) {
+    if (Array.isArray(audit.entries) && audit.entries.length > 0) {
+        return audit.entries.filter((entry) => Boolean(entry));
+    }
+    return Object.values(latestByOperation).filter((entry) => Boolean(entry));
+}
+function buildProviderLinearMutationEntryKey(entry) {
+    return `${entry.operation}:${normalizeAuditAction(entry.action) ?? ''}`;
+}
+function normalizeAuditAction(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return null;
+    }
+    const separatorIndex = normalized.indexOf(':');
+    return separatorIndex >= 0 ? normalized.slice(0, separatorIndex) : normalized;
+}

package/dist/orchestrator/src/cli/control/providerLinearWorkflowAudit.js

@@ -0,0 +1,254 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const PROVIDER_LINEAR_AUDIT_ENV_VAR = 'CODEX_PROVIDER_LINEAR_AUDIT_PATH';
+export const PROVIDER_LINEAR_PARALLELIZATION_REASONS = {
+    parallelize_now: ['independent_scope_available'],
+    stay_serial: [
+        'single_bounded_change',
+        'overlapping_scope',
+        'existing_child_lane_active',
+        'review_or_validation_only'
+    ],
+    forbid_parallel: ['parent_only_mutation', 'merge_or_handoff_state', 'blocked_by_dependency']
+};
+export function isProviderLinearParallelizationDecision(value) {
+    return value === 'parallelize_now' || value === 'stay_serial' || value === 'forbid_parallel';
+}
+export function isProviderLinearParallelizationReason(value) {
+    return (value === 'independent_scope_available' ||
+        value === 'single_bounded_change' ||
+        value === 'overlapping_scope' ||
+        value === 'existing_child_lane_active' ||
+        value === 'review_or_validation_only' ||
+        value === 'parent_only_mutation' ||
+        value === 'merge_or_handoff_state' ||
+        value === 'blocked_by_dependency');
+}
+export function isProviderLinearParallelizationReasonAllowed(decision, reason) {
+    return PROVIDER_LINEAR_PARALLELIZATION_REASONS[decision].includes(reason);
+}
+export function readProviderLinearParallelizationSnapshots(audit, options = {}) {
+    const issueId = normalizeOptionalString(options.issueId);
+    const recordedAtNotBefore = normalizeOptionalString(options.recordedAtNotBefore);
+    return selectProviderLinearParallelizationEntries(audit)
+        .filter((entry) => entry.ok)
+        .filter((entry) => !issueId || entry.issue_id === issueId)
+        .filter((entry) => !recordedAtNotBefore || compareIsoTimestamp(entry.recorded_at, recordedAtNotBefore) >= 0)
+        .flatMap((entry) => {
+        const decision = normalizeOptionalString(entry.action);
+        const reason = normalizeOptionalString(entry.state);
+        if (!isProviderLinearParallelizationDecision(decision) ||
+            !isProviderLinearParallelizationReason(reason) ||
+            !isProviderLinearParallelizationReasonAllowed(decision, reason)) {
+            return [];
+        }
+        return [{
+                decision,
+                reason,
+                summary: normalizeOptionalString(entry.via),
+                recorded_at: entry.recorded_at
+            }];
+    })
+        .sort((left, right) => compareIsoTimestamp(left.recorded_at, right.recorded_at));
+}
+export function readProviderLinearParallelizationSnapshot(audit, options = {}) {
+    return readProviderLinearParallelizationSnapshots(audit, options).at(-1) ?? null;
+}
+export function resolveProviderLinearAuditPath(env) {
+    const value = env[PROVIDER_LINEAR_AUDIT_ENV_VAR];
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export async function appendProviderLinearAuditEntry(auditPath, entry) {
+    await mkdir(dirname(auditPath), { recursive: true });
+    await appendFile(auditPath, `${JSON.stringify(entry)}\n`, 'utf8');
+}
+export async function summarizeProviderLinearAuditPath(auditPath) {
+    const summary = buildEmptyProviderLinearAuditSummary(auditPath);
+    let raw;
+    try {
+        raw = await readFile(auditPath, 'utf8');
+    }
+    catch {
+        return summary;
+    }
+    for (const line of raw.split(/\r?\n/u)) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const entry = normalizeProviderLinearAuditEntry(parsed);
+        if (!entry) {
+            continue;
+        }
+        summary.attempted_count += 1;
+        if (entry.ok) {
+            summary.success_count += 1;
+        }
+        else {
+            summary.failure_count += 1;
+        }
+        summary.entries?.push(entry);
+        summary.latest_by_operation[entry.operation] = entry;
+        if (entry.operation === 'parallelization') {
+            summary.parallelization_entries.push(entry);
+        }
+        summary.latest_recorded_at = entry.recorded_at;
+    }
+    return summary;
+}
+function buildEmptyProviderLinearAuditSummary(auditPath) {
+    return {
+        path: auditPath,
+        attempted_count: 0,
+        success_count: 0,
+        failure_count: 0,
+        latest_recorded_at: null,
+        latest_by_operation: {},
+        parallelization_entries: [],
+        entries: []
+    };
+}
+function selectProviderLinearParallelizationEntries(audit) {
+    if (Array.isArray(audit?.parallelization_entries) && audit.parallelization_entries.length > 0) {
+        return audit.parallelization_entries.filter((entry) => Boolean(entry));
+    }
+    const latestEntry = audit?.latest_by_operation?.parallelization ?? null;
+    return latestEntry ? [latestEntry] : [];
+}
+function normalizeProviderLinearAuditEntry(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const entry = value;
+    const operation = entry.operation;
+    if (operation !== 'issue-context'
+        && operation !== 'upsert-workpad'
+        && operation !== 'delete-workpad'
+        && operation !== 'transition'
+        && operation !== 'attach-pr'
+        && operation !== 'parallelization'
+        && operation !== 'screenshot-proof'
+        && operation !== 'runtime-proof'
+        && operation !== 'create-follow-up'
+        && operation !== 'child-stream'
+        && operation !== 'child-lane') {
+        return null;
+    }
+    const recordedAt = normalizeOptionalString(entry.recorded_at);
+    if (!recordedAt) {
+        return null;
+    }
+    return {
+        recorded_at: recordedAt,
+        operation,
+        ok: entry.ok === true,
+        issue_id: normalizeOptionalString(entry.issue_id),
+        issue_identifier: normalizeOptionalString(entry.issue_identifier),
+        source_setup: normalizeSourceSetup(entry.source_setup),
+        action: normalizeOptionalString(entry.action),
+        via: normalizeOptionalString(entry.via),
+        state: normalizeOptionalString(entry.state),
+        follow_up_issue_id: normalizeOptionalString(entry.follow_up_issue_id),
+        follow_up_issue_identifier: normalizeOptionalString(entry.follow_up_issue_identifier),
+        failed_relation_type: normalizeOptionalString(entry.failed_relation_type),
+        comment_id: normalizeOptionalString(entry.comment_id),
+        attachment_id: normalizeOptionalString(entry.attachment_id),
+        ...(Array.isArray(entry.asset_urls)
+            ? {
+                asset_urls: entry.asset_urls
+                    .map((value) => normalizeOptionalString(value))
+                    .filter((value) => value !== null)
+            }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'previous_state')
+            ? { previous_state: normalizeOptionalString(entry.previous_state) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'previous_state_type')
+            ? { previous_state_type: normalizeOptionalString(entry.previous_state_type) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'target_state')
+            ? { target_state: normalizeOptionalString(entry.target_state) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'target_state_type')
+            ? { target_state_type: normalizeOptionalString(entry.target_state_type) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'issue_updated_at')
+            ? { issue_updated_at: normalizeOptionalString(entry.issue_updated_at) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'expected_state')
+            ? { expected_state: normalizeOptionalString(entry.expected_state) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'expected_state_type')
+            ? { expected_state_type: normalizeOptionalString(entry.expected_state_type) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'expected_updated_at')
+            ? { expected_updated_at: normalizeOptionalString(entry.expected_updated_at) }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'force')
+            && typeof entry.force === 'boolean'
+            ? { force: entry.force }
+            : {}),
+        ...(Object.prototype.hasOwnProperty.call(entry, 'force_reason')
+            ? { force_reason: normalizeOptionalString(entry.force_reason) }
+            : {}),
+        error_code: normalizeOptionalString(entry.error_code),
+        error_message: normalizeOptionalString(entry.error_message)
+    };
+}
+function normalizeSourceSetup(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    if (record.provider !== 'linear') {
+        return null;
+    }
+    return {
+        provider: 'linear',
+        workspace_id: normalizeOptionalString(record.workspace_id),
+        team_id: normalizeOptionalString(record.team_id),
+        project_id: normalizeOptionalString(record.project_id)
+    };
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function compareIsoTimestamp(left, right) {
+    const leftValue = normalizeOptionalString(left);
+    const rightValue = normalizeOptionalString(right);
+    if (leftValue === rightValue) {
+        return 0;
+    }
+    if (!leftValue) {
+        return -1;
+    }
+    if (!rightValue) {
+        return 1;
+    }
+    const leftMs = Date.parse(leftValue);
+    const rightMs = Date.parse(rightValue);
+    if (Number.isFinite(leftMs) && Number.isFinite(rightMs)) {
+        return leftMs - rightMs;
+    }
+    if (Number.isFinite(leftMs)) {
+        return 1;
+    }
+    if (Number.isFinite(rightMs)) {
+        return -1;
+    }
+    return leftValue.localeCompare(rightValue);
+}