@moretea-labs/forge 1.7.1 → 1.8.0

package/packages/kernel/scheduler/application/continuation-service.ts

@@ -0,0 +1,212 @@
+import {
+  beginInitialControllerRoundDispatch,
+  bindLegacyControllerRoundOccurrence,
+  controllerSessionPrincipalId,
+  finishControllerRoundRelayDispatch,
+  getControllerRoundRelay,
+  readControllerRoundSemanticStateFingerprint,
+  getControllerWorkBinding,
+  getRetainedControllerSession,
+  type ControllerHost,
+} from '../../controller/api/index';
+import { getWorkContract, isTerminalWorkContractStatus } from '../../work/api/index';
+import type { ScheduledControllerContinuationInput, ScheduledContinuationDispatch } from '../domain/continuation';
+import {
+  getScheduledContinuationDispatch,
+  updateScheduledContinuationDispatch,
+  type SchedulerContinuationStoreOptions,
+} from '../infrastructure/continuation-dispatch-store';
+
+export interface ScheduledControllerContinuationResult {
+  dispatch: ScheduledContinuationDispatch;
+  reused: boolean;
+}
+
+/**
+ * Canonical Scheduler continuation path:
+ * Schedule occurrence -> exact Work -> Work-scoped durable ControllerBinding -> current Controller delivery session -> ControllerHost.resume.
+ * The occurrence record fences external replay independently of transport/provider behavior; ControllerSession ids are observation, not semantic continuation identity.
+ */
+export async function resumeScheduledControllerContinuation(
+  options: SchedulerContinuationStoreOptions,
+  input: ScheduledControllerContinuationInput,
+  host: ControllerHost,
+): Promise<ScheduledControllerContinuationResult> {
+  const previous = getScheduledContinuationDispatch(options, input.occurrenceId);
+  if (previous) {
+    if (
+      previous.scheduleId !== input.scheduleId
+      || previous.workId !== input.workId
+      || previous.controllerBindingId !== input.controllerBindingId
+    ) throw new Error(`SCHEDULE_CONTINUATION_OCCURRENCE_IDENTITY_CONFLICT: ${input.occurrenceId}`);
+    if (previous.status === 'dispatched' || previous.status === 'wait_for_user' || previous.status === 'semantic_wait' || previous.status === 'rejected') return { dispatch: previous, reused: true };
+    if (previous.status === 'outcome_unknown') throw new Error(`SCHEDULE_CONTINUATION_OUTCOME_UNKNOWN: ${input.occurrenceId}`);
+    if (previous.status === 'dispatching') throw new Error(`SCHEDULE_CONTINUATION_ALREADY_DISPATCHING: ${input.occurrenceId}`);
+  }
+
+  const work = getWorkContract(options, input.workId);
+  if (!work) throw new Error(`WORK_NOT_FOUND: ${input.workId}`);
+  if (isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ALREADY_TERMINAL: ${work.workId}:${work.status}`);
+
+  const session = getRetainedControllerSession(options, work.workId);
+  if (!session) throw new Error(`CONTROLLER_SESSION_NOT_RETAINED: ${work.workId}`);
+  const bindingRecord = getControllerWorkBinding(options, work.workId);
+  if (!bindingRecord) throw new Error(`CONTROLLER_WORK_BINDING_NOT_FOUND: ${work.workId}`);
+  if (bindingRecord.binding.bindingId !== input.controllerBindingId) {
+    throw new Error(`SCHEDULE_CONTINUATION_BINDING_DRIFT: ${work.workId}:expected=${input.controllerBindingId}:actual=${bindingRecord.binding.bindingId}`);
+  }
+  if (bindingRecord.binding.hostKind !== session.controllerType) {
+    throw new Error(`SCHEDULE_CONTINUATION_HOST_KIND_MISMATCH: ${work.workId}`);
+  }
+
+  const requestedRelayScopeId = input.relayScopeId?.trim() || undefined;
+  const canonicalRelayScopeId = requestedRelayScopeId
+    ?? (work.requirementId ? `requirement:${work.requirementId}` : `goal:${work.workId}`);
+
+  // A semantic `wait` is quiescent, not a request to periodically reread the same
+  // state. Suppress unchanged schedule/manual wakes before a provider host is even
+  // selected. A new occurrence may proceed only after Kernel semantic state changes.
+  const waitingRelay = getControllerRoundRelay(options, work.workId);
+  if (waitingRelay?.status === 'waiting' && waitingRelay.relayScopeId === canonicalRelayScopeId) {
+    const currentFingerprint = readControllerRoundSemanticStateFingerprint(options, work.workId);
+    if (currentFingerprint && currentFingerprint === waitingRelay.stateFingerprint) {
+      const quiesced = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_semantic_wait', (current, at) => current ?? ({
+        schemaVersion: 1, repoId: options.repoId, scheduleId: input.scheduleId, occurrenceId: input.occurrenceId,
+        workId: work.workId, controllerSessionId: session.sessionId, controllerBindingId: bindingRecord.binding.bindingId,
+        relayScopeId: canonicalRelayScopeId, status: 'semantic_wait',
+        reason: `Controller semantic wait remains unchanged for ${canonicalRelayScopeId}; provider dispatch suppressed.`,
+        createdAt: at, updatedAt: at,
+      }));
+      return { dispatch: quiesced, reused: Boolean(previous) };
+    }
+  }
+
+  // Reserve the exact occurrence before creating a ControllerRound. If Forge dies
+  // after the round write but before the authority is copied back here, the next
+  // attempt can safely adopt only the exact still-dispatching round for this
+  // retained session/binding instead of minting or replaying another wake.
+  let prepared = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_prepare', (current, at) => current ?? ({
+    schemaVersion: 1, repoId: options.repoId, scheduleId: input.scheduleId, occurrenceId: input.occurrenceId,
+    workId: work.workId, controllerSessionId: session.sessionId, controllerBindingId: bindingRecord.binding.bindingId,
+    relayScopeId: canonicalRelayScopeId, status: 'prepared', createdAt: at, updatedAt: at,
+  }));
+  if (prepared.status === 'dispatched' || prepared.status === 'wait_for_user' || prepared.status === 'semantic_wait' || prepared.status === 'rejected') return { dispatch: prepared, reused: true };
+  if (prepared.status === 'outcome_unknown') throw new Error(`SCHEDULE_CONTINUATION_OUTCOME_UNKNOWN: ${input.occurrenceId}`);
+  if (prepared.status === 'dispatching') throw new Error(`SCHEDULE_CONTINUATION_ALREADY_DISPATCHING: ${input.occurrenceId}`);
+
+  const currentControllerPrincipalId = controllerSessionPrincipalId(session);
+  const roundMatchesReservedOccurrence = (candidate: ReturnType<typeof getControllerRoundRelay>): boolean => Boolean(
+    candidate
+    && candidate.status === 'dispatching'
+    && candidate.relayScopeId === prepared.relayScopeId
+    && candidate.occurrenceId === prepared.occurrenceId
+    && candidate.controllerId === session.controllerId
+    && candidate.controllerType === session.controllerType
+    && candidate.authorityId,
+  );
+  const bindRecoveredLegacyOccurrence = (candidate: ReturnType<typeof getControllerRoundRelay>) => {
+    if (!candidate
+      || candidate.status !== 'dispatching'
+      || candidate.occurrenceId
+      || candidate.relayScopeId !== prepared.relayScopeId
+      || candidate.controllerId !== session.controllerId
+      || candidate.controllerType !== session.controllerType
+      || (candidate.principalId?.trim() || candidate.controllerId) !== currentControllerPrincipalId
+      || !candidate.authorityId
+      || (candidate.providerRecoveryEpoch ?? 0) < 1
+      || !candidate.providerRecoveryEvidenceId) return candidate;
+    return bindLegacyControllerRoundOccurrence(options, {
+      workId: work.workId,
+      relayScopeId: prepared.relayScopeId,
+      occurrenceId: prepared.occurrenceId,
+      authorityId: candidate.authorityId,
+      expectedUpdatedAt: candidate.updatedAt,
+      identity: { controllerId: session.controllerId, controllerType: session.controllerType, principalId: currentControllerPrincipalId },
+    });
+  };
+
+  let relay = previous ? getControllerRoundRelay(options, work.workId) : undefined;
+  if (relay && !roundMatchesReservedOccurrence(relay)) {
+    relay = bindRecoveredLegacyOccurrence(relay);
+    if (!roundMatchesReservedOccurrence(relay)) {
+      throw new Error(`SCHEDULE_CONTINUATION_ROUND_ALREADY_OPEN: ${input.occurrenceId}:${relay?.relayScopeId ?? canonicalRelayScopeId}`);
+    }
+  }
+  if (!relay) {
+    try {
+      relay = beginInitialControllerRoundDispatch(options, {
+        workId: work.workId,
+        relayScopeId: requestedRelayScopeId,
+        requirementId: work.requirementId,
+        bindingId: bindingRecord.binding.bindingId,
+        occurrenceId: input.occurrenceId,
+        identity: {
+          controllerId: session.controllerId,
+          controllerType: session.controllerType,
+          principalId: controllerSessionPrincipalId(session),
+          controllerInstanceId: session.controllerInstanceId?.trim() || session.controllerId,
+          sessionId: session.sessionId,
+        },
+      });
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('CONTROLLER_RELAY_ROUND_ALREADY_OPEN:')) {
+        let existing = getControllerRoundRelay(options, work.workId);
+        if (!roundMatchesReservedOccurrence(existing)) existing = bindRecoveredLegacyOccurrence(existing);
+        if (roundMatchesReservedOccurrence(existing)) relay = existing;
+        else throw new Error(`SCHEDULE_CONTINUATION_ROUND_ALREADY_OPEN: ${input.occurrenceId}:${canonicalRelayScopeId}`);
+      } else {
+        throw error;
+      }
+    }
+  }
+  if (!relay) throw new Error(`SCHEDULE_CONTINUATION_ROUND_MISSING: ${input.occurrenceId}`);
+  if (relay.status === 'blocked') throw new Error(`CONTROLLER_RELAY_LAUNCH_BLOCKED: ${relay.blockedReason ?? relay.relayScopeId}`);
+  if (!relay.authorityId) throw new Error(`CONTROLLER_ROUND_AUTHORITY_REQUIRED: ${relay.relayScopeId}`);
+
+  prepared = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_bind_round', (current, at) => ({
+    ...(current ?? prepared), relayScopeId: relay.relayScopeId, controllerAuthorityId: relay.authorityId, status: 'prepared', updatedAt: at,
+  }));
+
+  updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_dispatch_begin', (current, at) => ({
+    ...(current ?? prepared), status: 'dispatching', updatedAt: at,
+  }));
+  try {
+    const result = await host.resume(bindingRecord.binding, {
+      workId: work.workId,
+      relayScopeId: relay.relayScopeId,
+      roundNumber: relay.roundCount,
+      authorityId: relay.authorityId,
+      occurrenceId: input.occurrenceId,
+      exactOriginWork: true,
+      continuationHint: input.continuationHint?.trim() || undefined,
+    });
+    if (!result.accepted) {
+      const reason = result.reason ?? 'CONTROLLER_HOST_RESUME_REJECTED';
+      if (result.waitForUser) {
+        finishControllerRoundRelayDispatch(options, { workId: work.workId, ok: false, waitForUser: true, handoffId: result.handoffId, error: reason });
+        const waiting = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_wait_for_user', (current, at) => ({
+          ...(current ?? prepared), status: 'wait_for_user', reason, ...(result.handoffId ? { handoffId: result.handoffId } : {}), updatedAt: at,
+        }));
+        return { dispatch: waiting, reused: false };
+      }
+      finishControllerRoundRelayDispatch(options, { workId: work.workId, ok: false, error: reason });
+      const rejected = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_rejected', (current, at) => ({
+        ...(current ?? prepared), status: 'rejected', reason, updatedAt: at,
+      }));
+      return { dispatch: rejected, reused: false };
+    }
+    finishControllerRoundRelayDispatch(options, { workId: work.workId, ok: true, bindingId: bindingRecord.binding.bindingId, providerDispatchReceiptId: result.dispatchId });
+    const dispatched = updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_dispatched', (current, at) => ({
+      ...(current ?? prepared), status: 'dispatched', ...(result.dispatchId ? { hostDispatchId: result.dispatchId } : {}), updatedAt: at,
+    }));
+    return { dispatch: dispatched, reused: false };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const providerDispatchOutcomeUnknown = /CONTROLLER_HOST_PROVIDER_DISPATCH_OUTCOME_UNKNOWN|CHATGPT_AUTOMATION_SUBMISSION_OUTCOME_UNKNOWN/i.test(reason);
+    try { finishControllerRoundRelayDispatch(options, { workId: work.workId, ok: false, error: reason, outcomeUnknown: providerDispatchOutcomeUnknown }); } catch {}
+    updateScheduledContinuationDispatch(options, input.occurrenceId, 'scheduler_continuation_outcome_unknown', (current, at) => ({
+      ...(current ?? prepared), status: 'outcome_unknown', reason, updatedAt: at,
+    }));
+    throw error;
+  }
+}

package/packages/kernel/scheduler/application/eligibility.ts

@@ -0,0 +1,252 @@
+import { createHash, randomUUID } from 'crypto';
+import type { RepositorySchedule, ScheduleTriggerContext } from '../domain/schedule';
+
+export interface ScheduleTriggerEligibilityFacts {
+  nowMs: number;
+  force: boolean;
+  context?: ScheduleTriggerContext;
+  repositoryClean?: boolean;
+  jobStatuses?: Readonly<Record<string, string | undefined>>;
+}
+
+export interface ScheduleTriggerEligibilityDecision {
+  due: boolean;
+  windowKey?: string;
+  reason?: string;
+  evidence?: Record<string, unknown>;
+}
+
+export type ScheduleOccurrenceAdmissionKind =
+  | 'eligible'
+  | 'stop_condition'
+  | 'active_occurrence'
+  | 'failure_limit'
+  | 'cooldown'
+  | 'budget_exhausted';
+
+export interface ScheduleOccurrenceAdmissionFacts {
+  nowMs: number;
+  force: boolean;
+  stopReason?: string;
+  activeOccurrenceCount: number;
+  dailyRuntimeMinutes: number;
+}
+
+export interface ScheduleOccurrenceAdmissionDecision {
+  kind: ScheduleOccurrenceAdmissionKind;
+  reason?: string;
+}
+
+function normalizedWindow(minutes: number, at: number): string {
+  return String(Math.floor(at / (Math.max(1, minutes) * 60_000)));
+}
+
+interface ZonedDateParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  weekday: number;
+}
+
+function zonedDateParts(at: number, timezone = 'UTC'): ZonedDateParts {
+  let formatter: Intl.DateTimeFormat;
+  try {
+    formatter = new Intl.DateTimeFormat('en-US-u-ca-iso8601', {
+      timeZone: timezone,
+      year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', weekday: 'short',
+      hourCycle: 'h23',
+    });
+  } catch {
+    throw new Error(`SCHEDULE_TIMEZONE_INVALID: ${timezone}`);
+  }
+  const values = Object.fromEntries(formatter.formatToParts(new Date(at)).map((entry) => [entry.type, entry.value]));
+  const weekdays: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return {
+    year: Number(values.year),
+    month: Number(values.month),
+    day: Number(values.day),
+    hour: Number(values.hour),
+    minute: Number(values.minute),
+    weekday: weekdays[String(values.weekday)] ?? 0,
+  };
+}
+
+function fixedCronTime(expression: string | undefined): { minute: number; hour: number; day: string; month: string; weekday: string } | undefined {
+  if (!expression) return undefined;
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5 || !/^\d+$/.test(fields[0]) || !/^\d+$/.test(fields[1])) return undefined;
+  const minute = Number(fields[0]);
+  const hour = Number(fields[1]);
+  if (minute < 0 || minute > 59 || hour < 0 || hour > 23) return undefined;
+  return { minute, hour, day: fields[2], month: fields[3], weekday: fields[4] };
+}
+
+function cronWindowKey(schedule: RepositorySchedule, at: number): string {
+  const timezone = schedule.trigger.timezone ?? 'UTC';
+  const parts = zonedDateParts(at, timezone);
+  const fixed = fixedCronTime(schedule.trigger.cronExpression);
+  if (fixed) {
+    return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}@${String(fixed.hour).padStart(2, '0')}:${String(fixed.minute).padStart(2, '0')}[${timezone}]`;
+  }
+  return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}T${String(parts.hour).padStart(2, '0')}:${String(parts.minute).padStart(2, '0')}[${timezone}]`;
+}
+
+export function scheduleTriggerWindowKey(schedule: RepositorySchedule, context: ScheduleTriggerContext | undefined, at: number): string {
+  if (context?.source === 'manual' && schedule.trigger.type !== 'manual') {
+    const stableManualKey = context.eventId?.trim();
+    return `manual:${stableManualKey || randomUUID()}`;
+  }
+  switch (schedule.trigger.type) {
+    case 'cron':
+      return cronWindowKey(schedule, at);
+    case 'calendar':
+      return schedule.trigger.calendarAt ?? new Date(at).toISOString().slice(0, 16);
+    case 'repository-event':
+      return context?.eventId?.trim() || `${context?.eventName ?? schedule.trigger.eventName ?? 'event'}:${normalizedWindow(1, at)}`;
+    case 'dependency-checkpoint':
+      return createHash('sha256').update(JSON.stringify(schedule.trigger.dependencyJobIds ?? [])).digest('hex').slice(0, 20);
+    case 'manual':
+      return context?.eventId?.trim() || normalizedWindow(1, at);
+    case 'condition':
+    case 'interval':
+    default:
+      return normalizedWindow(schedule.trigger.everyMinutes ?? 60, at);
+  }
+}
+
+function cronFieldMatches(value: number, field: string, min: number, max: number): boolean {
+  return field.split(',').some((part) => {
+    const trimmed = part.trim();
+    if (trimmed === '*') return true;
+    const stepMatch = trimmed.match(/^\*\/(\d+)$/);
+    if (stepMatch) return value % Math.max(1, Number(stepMatch[1])) === 0;
+    const rangeMatch = trimmed.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+    if (rangeMatch) {
+      const start = Math.max(min, Number(rangeMatch[1]));
+      const end = Math.min(max, Number(rangeMatch[2]));
+      const step = Math.max(1, Number(rangeMatch[3] ?? 1));
+      return value >= start && value <= end && (value - start) % step === 0;
+    }
+    const exact = Number(trimmed);
+    return Number.isInteger(exact) && exact >= min && exact <= max && value === exact;
+  });
+}
+
+export function cronDue(expression: string | undefined, at: number, timezone = 'UTC', catchUpMinutes = 0): boolean {
+  if (!expression) return false;
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error(`SCHEDULE_CRON_INVALID: expected five fields, received ${fields.length}`);
+  const parts = zonedDateParts(at, timezone);
+  const calendarMatches = cronFieldMatches(parts.day, fields[2], 1, 31)
+    && cronFieldMatches(parts.month, fields[3], 1, 12)
+    && cronFieldMatches(parts.weekday, fields[4], 0, 6);
+  if (!calendarMatches) return false;
+  if (cronFieldMatches(parts.minute, fields[0], 0, 59) && cronFieldMatches(parts.hour, fields[1], 0, 23)) return true;
+  const fixed = fixedCronTime(expression);
+  if (!fixed || catchUpMinutes <= 0) return false;
+  const scheduledMinute = fixed.hour * 60 + fixed.minute;
+  const currentMinute = parts.hour * 60 + parts.minute;
+  return currentMinute >= scheduledMinute && currentMinute - scheduledMinute <= Math.min(24 * 60, catchUpMinutes);
+}
+
+export function evaluateScheduleTriggerEligibility(
+  schedule: RepositorySchedule,
+  facts: ScheduleTriggerEligibilityFacts,
+): ScheduleTriggerEligibilityDecision {
+  if (!schedule.enabled && !facts.force) return { due: false, reason: 'Schedule is disabled.' };
+  let due = false;
+  let reason: string | undefined;
+  let evidence: Record<string, unknown> | undefined;
+  if (facts.force && schedule.trigger.type !== 'repository-event') {
+    due = true;
+  } else {
+    switch (schedule.trigger.type) {
+      case 'manual':
+        due = facts.force;
+        reason = due ? undefined : 'Manual Schedule requires an explicit trigger.';
+        break;
+      case 'interval':
+        due = true;
+        break;
+      case 'cron':
+        due = cronDue(schedule.trigger.cronExpression, facts.nowMs, schedule.trigger.timezone ?? 'UTC', schedule.trigger.catchUpMinutes ?? 0);
+        reason = due ? undefined : `Cron expression is not due in the current ${schedule.trigger.timezone ?? 'UTC'} minute or catch-up window.`;
+        break;
+      case 'calendar': {
+        const at = Date.parse(schedule.trigger.calendarAt ?? '');
+        if (!Number.isFinite(at)) throw new Error('SCHEDULE_CALENDAR_INVALID: calendarAt must be an ISO-8601 timestamp');
+        due = facts.nowMs >= at;
+        reason = due ? undefined : 'Calendar trigger is not due yet.';
+        evidence = { calendarAt: schedule.trigger.calendarAt };
+        break;
+      }
+      case 'repository-event': {
+        const expected = schedule.trigger.eventName?.trim();
+        const actual = facts.context?.eventName?.trim();
+        due = facts.context?.source === 'repository-event' && Boolean(actual) && (!expected || expected === actual);
+        reason = due ? undefined : 'Repository event did not match this Schedule.';
+        evidence = { expected, actual, eventId: facts.context?.eventId };
+        break;
+      }
+      case 'dependency-checkpoint': {
+        const ids = schedule.trigger.dependencyJobIds ?? [];
+        if (ids.length === 0) throw new Error('SCHEDULE_DEPENDENCY_REQUIRED: dependency checkpoint has no Job ids');
+        due = ids.every((jobId) => facts.jobStatuses?.[jobId] === 'succeeded');
+        reason = due ? undefined : 'Dependency checkpoint is not ready.';
+        evidence = { dependencies: ids.map((jobId) => ({ jobId, status: facts.jobStatuses?.[jobId] ?? 'missing' })) };
+        break;
+      }
+      case 'condition': {
+        const condition = schedule.trigger.condition;
+        if (!condition) throw new Error('SCHEDULE_CONDITION_REQUIRED');
+        if (condition.kind === 'repository_clean') {
+          due = facts.repositoryClean === true;
+          reason = due ? undefined : 'Repository is not clean.';
+          evidence = { clean: facts.repositoryClean === true };
+          break;
+        }
+        const status = condition.jobId ? facts.jobStatuses?.[condition.jobId] : undefined;
+        const terminal = Boolean(status && ['succeeded', 'failed', 'timed_out', 'cancelled', 'orphaned', 'stale', 'human_attention_required'].includes(status));
+        due = condition.kind === 'job_succeeded' ? status === 'succeeded' : terminal;
+        reason = due ? undefined : `Condition ${condition.kind} is not met.`;
+        evidence = { jobId: condition.jobId, status: status ?? 'missing' };
+        break;
+      }
+      default:
+        due = false;
+        reason = 'Unsupported Schedule trigger.';
+    }
+  }
+  return {
+    due,
+    ...(due ? { windowKey: scheduleTriggerWindowKey(schedule, facts.context, facts.nowMs) } : {}),
+    ...(reason ? { reason } : {}),
+    ...(evidence ? { evidence } : {}),
+  };
+}
+
+export function evaluateScheduleOccurrenceAdmission(
+  schedule: RepositorySchedule,
+  facts: ScheduleOccurrenceAdmissionFacts,
+): ScheduleOccurrenceAdmissionDecision {
+  if (facts.stopReason) return { kind: 'stop_condition', reason: facts.stopReason };
+  if (facts.activeOccurrenceCount >= schedule.policy.maxActiveOccurrences) {
+    return { kind: 'active_occurrence', reason: 'Maximum active occurrences reached.' };
+  }
+  if (schedule.consecutiveFailures >= schedule.policy.maxFailures) {
+    return { kind: 'failure_limit', reason: 'Schedule paused after repeated failures.' };
+  }
+  if (!facts.force && schedule.nextEligibleAt && Date.parse(schedule.nextEligibleAt) > facts.nowMs) {
+    return { kind: 'cooldown', reason: `Schedule backoff remains active until ${schedule.nextEligibleAt}.` };
+  }
+  if (!facts.force && schedule.lastTriggeredAt && facts.nowMs - Date.parse(schedule.lastTriggeredAt) < schedule.policy.cooldownMinutes * 60_000) {
+    return { kind: 'cooldown', reason: 'Schedule is cooling down.' };
+  }
+  if (facts.dailyRuntimeMinutes >= schedule.policy.dailyBudgetMinutes) {
+    return { kind: 'budget_exhausted', reason: 'Daily schedule budget exhausted.' };
+  }
+  return { kind: 'eligible' };
+}

package/packages/kernel/scheduler/application/schedule-service.ts

@@ -0,0 +1,24 @@
+/** Stable Scheduler lifecycle façade. Persistence remains internal to the Scheduler module. */
+export {
+  applyScheduleDedupe,
+  buildScheduleDedupeReport,
+  cleanupScheduleOccurrenceHistory,
+  createSchedule,
+  deleteSchedule,
+  getOccurrence,
+  getSchedule,
+  getScheduleDecision,
+  listActiveOccurrences,
+  listOccurrences,
+  listSchedules,
+  recordScheduleOccurrenceHandoff,
+  saveOccurrence,
+  saveSchedule,
+  saveScheduleDecision,
+  updateSchedule,
+  type ScheduleHistoryCleanupResult,
+  type ScheduleDedupeApplyResult,
+  type ScheduleDedupeReport,
+  type ScheduleDuplicateGroup,
+  type ScheduleDuplicateMember,
+} from '../infrastructure/schedule-store';