@moretea-labs/forge 1.8.0 → 1.8.1

package/packages/kernel/scheduler/infrastructure/schedule-store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from 'crypto';
 import { existsSync, readdirSync, rmSync, statSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
 import { withControllerLock } from '../../../../src/cli/repositories/locks';
 import {
   createHandoffItem,
@@ -11,7 +11,7 @@ import {
 } from '../../../../src/runtime/control-plane/facade/handoff-inbox-store';
 import { readJsonFile, writeJsonAtomic } from '../../../../src/runtime/shared/json-files';
 import { appendRuntimeEvent } from '../../../../src/runtime/evidence/event-ledger';
-import type { RepositorySchedule, ScheduleDecision, ScheduleOccurrence } from '../domain/schedule';
+import { type RepositorySchedule, type ScheduleDecision, type ScheduleOccurrence, type ScheduleDefinition, type ScheduleRuntimeState, extractScheduleDefinition, extractScheduleRuntimeState } from '../domain/schedule';
 
 interface OccurrenceIndex {
   schemaVersion: 1;
@@ -27,6 +27,19 @@ interface ScheduleRequestRecord {
   repoId: string;
   createdAt: string;
 }
+
+class ScheduleStoreError extends Error {
+  readonly code: 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH';
+  readonly scheduleId: string;
+
+  constructor(scheduleId: string) {
+    super(`SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH: ${scheduleId}`);
+    this.name = 'ScheduleStoreError';
+    this.code = 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH';
+    this.scheduleId = scheduleId;
+  }
+}
+
 type CreateScheduleInput = Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'createdAt' | 'updatedAt' | 'consecutiveFailures'>;
 type ScheduleMutableUpdate = Partial<Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'repoId' | 'requestId' | 'createdAt' | 'updatedAt'>>;
 
@@ -34,7 +47,7 @@ export interface ScheduleOccurrenceHandoffInput {
   title: string;
   summary: string;
   reason: string;
-  creationReason: 'ambiguous_outcome' | 'missing_authorization' | 'repeated_infrastructure_failure';
+  creationReason: 'ambiguous_outcome' | 'missing_authorization';
   blockingDecision: string;
   recommendedDecision: string;
   recommendedPrompt: string;
@@ -44,27 +57,49 @@ export interface ScheduleOccurrenceHandoffInput {
   evidenceRefs?: Array<{ title: string; summary?: string; detailLevel?: 'summary' | 'detail' | 'raw' }>;
 }
 
-function schedulesRoot(controllerHome: string, repoId: string): string {
+function schedulesRoot(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'schedules');
+}
+function legacySchedulesRoot(controllerHome: string, repoId: string): string {
   return join(repositoryControllerRoot(controllerHome, repoId), 'schedules');
 }
-function schedulePath(controllerHome: string, repoId: string, scheduleId: string): string {
-  return join(schedulesRoot(controllerHome, repoId), 'records', `${scheduleId}.json`);
+function schedulePath(controllerHome: string, _repoId: string, scheduleId: string): string {
+  return join(schedulesRoot(controllerHome), 'records', `${scheduleId}.json`);
 }
-function occurrencePath(controllerHome: string, repoId: string, occurrenceId: string): string {
-  return join(schedulesRoot(controllerHome, repoId), 'occurrences', `${occurrenceId}.json`);
+function legacySchedulePath(controllerHome: string, repoId: string, scheduleId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'records', `${scheduleId}.json`);
 }
-
-function decisionPath(controllerHome: string, repoId: string, decisionId: string): string {
-  return join(schedulesRoot(controllerHome, repoId), 'decisions', `${decisionId}.json`);
+function occurrencePath(controllerHome: string, _repoId: string, occurrenceId: string): string {
+  return join(schedulesRoot(controllerHome), 'occurrences', `${occurrenceId}.json`);
+}
+function legacyOccurrencePath(controllerHome: string, repoId: string, occurrenceId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'occurrences', `${occurrenceId}.json`);
+}
+function decisionPath(controllerHome: string, _repoId: string, decisionId: string): string {
+  return join(schedulesRoot(controllerHome), 'decisions', `${decisionId}.json`);
+}
+function legacyDecisionPath(controllerHome: string, repoId: string, decisionId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'decisions', `${decisionId}.json`);
 }
 function occurrenceIndexPath(controllerHome: string, repoId: string): string {
-  return join(schedulesRoot(controllerHome, repoId), 'indexes', 'occurrences.json');
+  const key = createHash('sha256').update(repoId).digest('hex').slice(0, 24);
+  return join(schedulesRoot(controllerHome), 'indexes', 'occurrences', `${key}.json`);
 }
-function requestPath(controllerHome: string, repoId: string, requestId: string): string {
-  return join(schedulesRoot(controllerHome, repoId), 'indexes', 'requests', `${createHash('sha256').update(requestId).digest('hex')}.json`);
+function requestTargetKey(input: Pick<RepositorySchedule, 'repoId' | 'scopeRef' | 'executionPlacement' | 'action'>): string {
+  return createHash('sha256').update(JSON.stringify(canonical({
+    scopeRef: input.scopeRef,
+    executionPlacement: input.executionPlacement,
+    repoId: input.repoId,
+    actionTarget: input.action.target,
+    operation: input.action.operation,
+  }))).digest('hex');
+}
+function requestPath(controllerHome: string, targetKey: string, requestId: string): string {
+  return join(schedulesRoot(controllerHome), 'indexes', 'requests', targetKey, `${createHash('sha256').update(requestId).digest('hex')}.json`);
 }
 
 export const SCHEDULE_OCCURRENCE_RECENT_LIMIT = 5_000;
+export const SCHEDULE_CREATED_OCCURRENCE_STALE_MS = 5 * 60 * 1_000;
 
 const EXTERNAL_CONTROLLER_WAKE_MAX_FAILURES = 3;
 const EXTERNAL_CONTROLLER_WAKE_DAILY_BUDGET_MINUTES = 60;
@@ -131,8 +166,9 @@ export function createSchedule(controllerHome: string, input: CreateScheduleInpu
   const requestId = input.requestId.trim();
   if (!requestId) throw new Error('SCHEDULE_REQUEST_ID_REQUIRED');
   const semanticKey = scheduleSemanticKey(input);
-  return withControllerLock(controllerHome, { scope: 'task', repoId: input.repoId, taskId: `schedule-request-${createHash('sha256').update(requestId).digest('hex').slice(0, 16)}` }, `create-schedule:${requestId}`, () => {
-    const requestRecordPath = requestPath(controllerHome, input.repoId, requestId);
+  const targetKey = requestTargetKey(input);
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule-request:${targetKey}:${createHash('sha256').update(requestId).digest('hex').slice(0, 16)}` }, `create-schedule:${requestId}`, () => {
+    const requestRecordPath = requestPath(controllerHome, targetKey, requestId);
     if (existsSync(requestRecordPath)) {
       const record = readJsonFile<ScheduleRequestRecord>(requestRecordPath);
       if (record.semanticKey !== semanticKey) throw new Error(`SCHEDULE_REQUEST_ID_CONFLICT: ${requestId}`);
@@ -157,8 +193,18 @@ export function createSchedule(controllerHome: string, input: CreateScheduleInpu
 }
 
 export function getSchedule(controllerHome: string, repoId: string, scheduleId: string): RepositorySchedule {
-  const schedule = readJsonFile<RepositorySchedule>(schedulePath(controllerHome, repoId, scheduleId));
-  // Hydrate schedules written before requestId/revision became mandatory.
+  const canonicalPath = schedulePath(controllerHome, repoId, scheduleId);
+  const legacyPath = legacySchedulePath(controllerHome, repoId, scheduleId);
+  const canonicalSchedule = existsSync(canonicalPath) ? readJsonFile<RepositorySchedule>(canonicalPath) : undefined;
+  const legacySchedule = existsSync(legacyPath) ? readJsonFile<RepositorySchedule>(legacyPath) : undefined;
+  if (canonicalSchedule && legacySchedule && JSON.stringify(canonicalSchedule) !== JSON.stringify(legacySchedule)) {
+    const canonicalRevision = Number.isFinite(canonicalSchedule.revision) ? canonicalSchedule.revision : 1;
+    const legacyRevision = Number.isFinite(legacySchedule.revision) ? legacySchedule.revision : 1;
+    if (canonicalRevision <= legacyRevision) throw new Error(`SCHEDULE_ID_COLLISION: ${scheduleId}`);
+  }
+  const schedule = canonicalSchedule ?? legacySchedule;
+  if (!schedule) throw new Error(`SCHEDULE_NOT_FOUND: ${scheduleId}`);
+  if (schedule.repoId !== repoId) throw new ScheduleStoreError(scheduleId);
   return {
     ...schedule,
     revision: Number.isFinite(schedule.revision) ? schedule.revision : 1,
@@ -194,7 +240,7 @@ function persistScheduleRevision(
  * writers fail closed instead of overwriting a newer decision.
  */
 export function saveSchedule(controllerHome: string, schedule: RepositorySchedule): RepositorySchedule {
-  return withControllerLock(controllerHome, { scope: 'task', repoId: schedule.repoId, taskId: `schedule-${schedule.scheduleId}` }, `save-schedule:${schedule.scheduleId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${schedule.scheduleId}` }, `save-schedule:${schedule.scheduleId}`, () => {
     const current = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
     if (schedule.revision !== current.revision) {
       throw new Error(`SCHEDULE_REVISION_CONFLICT: ${schedule.scheduleId}:expected=${schedule.revision}:actual=${current.revision}`);
@@ -215,7 +261,7 @@ export function updateSchedule(
   scheduleId: string,
   update: (current: RepositorySchedule) => ScheduleMutableUpdate,
 ): RepositorySchedule {
-  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${scheduleId}` }, `update-schedule:${scheduleId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${scheduleId}` }, `update-schedule:${scheduleId}`, () => {
     const current = getSchedule(controllerHome, repoId, scheduleId);
     const changes = update(current);
     return persistScheduleRevision(controllerHome, current, { ...current, ...changes });
@@ -223,23 +269,34 @@ export function updateSchedule(
 }
 
 export function listSchedules(controllerHome: string, repoId: string): RepositorySchedule[] {
-  const root = join(schedulesRoot(controllerHome, repoId), 'records');
-  try {
-    return readdirSync(root).filter((name) => name.endsWith('.json'))
-      .map((name) => getSchedule(controllerHome, repoId, name.slice(0, -'.json'.length)))
-      .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-  } catch { return []; }
+  const ids = new Set<string>();
+  for (const root of [join(schedulesRoot(controllerHome), 'records'), join(legacySchedulesRoot(controllerHome, repoId), 'records')]) {
+    try {
+      for (const name of readdirSync(root)) if (name.endsWith('.json')) ids.add(name.slice(0, -'.json'.length));
+    } catch { /* missing storage root is empty */ }
+  }
+  return [...ids]
+    .flatMap((scheduleId) => {
+      try {
+        const schedule = getSchedule(controllerHome, repoId, scheduleId);
+        return schedule.repoId === repoId ? [schedule] : [];
+      } catch (error) {
+        if (error instanceof ScheduleStoreError && error.code === 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH') return [];
+        throw error;
+      }
+    })
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
 
 export function deleteSchedule(controllerHome: string, repoId: string, scheduleId: string): RepositorySchedule {
-  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${scheduleId}` }, `delete-schedule:${scheduleId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${scheduleId}` }, `delete-schedule:${scheduleId}`, () => {
     const current = getSchedule(controllerHome, repoId, scheduleId);
     if (current.enabled) throw new Error(`SCHEDULE_DELETE_REQUIRES_PAUSED: ${scheduleId}`);
     if (listActiveOccurrences(controllerHome, repoId, scheduleId).length > 0) {
       throw new Error(`SCHEDULE_DELETE_ACTIVE_OCCURRENCE: ${scheduleId}`);
     }
     rmSync(schedulePath(controllerHome, repoId, scheduleId), { force: true });
-    const requestRecordPath = requestPath(controllerHome, repoId, current.requestId);
+    const requestRecordPath = requestPath(controllerHome, requestTargetKey(current), current.requestId);
     if (existsSync(requestRecordPath)) {
       const record = readJsonFile<ScheduleRequestRecord>(requestRecordPath);
       if (record.scheduleId === scheduleId) rmSync(requestRecordPath, { force: true });
@@ -257,83 +314,8 @@ export function deleteSchedule(controllerHome: string, repoId: string, scheduleI
   }, 10_000);
 }
 
-function scheduleFailureClass(reason: string): string {
-  const trimmed = reason.trim();
-  const explicitCode = trimmed.match(/^([A-Z][A-Z0-9_]{2,})(?::|\b)/)?.[1];
-  if (explicitCode) return explicitCode;
-  const prefix = (trimmed.split(':', 1)[0] ?? trimmed)
-    .replace(/\s+/g, ' ')
-    .trim()
-    .toLowerCase()
-    .slice(0, 120);
-  return prefix || 'unknown_failure';
-}
-
-function activeScheduleFailureHandoff(
-  controllerHome: string,
-  repoId: string,
-  scheduleId: string,
-  creationReason: ScheduleOccurrenceHandoffInput['creationReason'],
-  reason: string,
-) {
-  const failureClass = scheduleFailureClass(reason);
-  return listHandoffItems({ controllerHome, repoId, status: 'active', limit: 100 }).find((item) => (
-    item.currentState?.taskId === scheduleId
-    && item.creationReason === creationReason
-    && scheduleFailureClass(item.reason) === failureClass
-  ));
-}
-
-function stableScheduleFailureHandoffId(
-  controllerHome: string,
-  repoId: string,
-  scheduleId: string,
-  creationReason: ScheduleOccurrenceHandoffInput['creationReason'],
-  reason: string,
-  occurrenceId: string,
-): string {
-  const digest = createHash('sha256')
-    .update(`${scheduleId}:${creationReason}:${scheduleFailureClass(reason)}`)
-    .digest('hex')
-    .slice(0, 20);
-  const baseId = `schedule-failure-${digest}`;
-  if (!getHandoffItem({ controllerHome, repoId }, baseId)) return baseId;
-  // A previous failure streak may already have resolved the stable item. Handoff
-  // records are immutable apart from lifecycle status, so use one new epoch id;
-  // subsequent failures in this streak will discover and reuse the active item.
-  const epoch = createHash('sha256').update(occurrenceId).digest('hex').slice(0, 8);
-  return `${baseId}-${epoch}`;
-}
-
-function resolveRecoveredScheduleFailureHandoffs(controllerHome: string, occurrence: ScheduleOccurrence): void {
-  try {
-    const active = listHandoffItems({ controllerHome, repoId: occurrence.repoId, status: 'active', limit: 100 })
-      .filter((item) => (
-        item.currentState?.taskId === occurrence.scheduleId
-        && item.creationReason === 'repeated_infrastructure_failure'
-      ));
-    for (const item of active) {
-      try {
-        resolveHandoffItem(
-          { controllerHome, repoId: occurrence.repoId },
-          item.id,
-          {
-            decision: `Schedule ${occurrence.scheduleId} recovered on occurrence ${occurrence.occurrenceId}.`,
-            resolver: 'schedule-runtime',
-          },
-        );
-      } catch {
-        // The succeeded occurrence remains authoritative. Inbox cleanup is
-        // best-effort and must never turn schedule recovery into a failure.
-      }
-    }
-  } catch {
-    // Preserve successful Schedule settlement even if Inbox storage is unavailable.
-  }
-}
-
 export function saveOccurrence(controllerHome: string, occurrence: ScheduleOccurrence): ScheduleOccurrence {
-  const next = withControllerLock(controllerHome, { scope: 'task', repoId: occurrence.repoId, taskId: `schedule-${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
+  const next = withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
     const existingPath = occurrencePath(controllerHome, occurrence.repoId, occurrence.occurrenceId);
     const previous = existsSync(existingPath) ? readJsonFile<ScheduleOccurrence>(existingPath) : undefined;
     const expectedRevision = previous?.revision ?? 0;
@@ -347,13 +329,17 @@ export function saveOccurrence(controllerHome: string, occurrence: ScheduleOccur
     appendRuntimeEvent(controllerHome, { repoId: saved.repoId, entityType: 'occurrence', entityId: saved.occurrenceId, eventType: `occurrence_${saved.status}`, requestId: `${schedule.requestId}:${saved.windowKey}`, revision: saved.revision, correlationId: saved.scheduleId, data: { decision: saved.decision, jobId: saved.jobId, reason: saved.reason } });
     return saved;
   }, 10_000);
-  if (next.status === 'succeeded' || next.status === 'dispatched') resolveRecoveredScheduleFailureHandoffs(controllerHome, next);
   return next;
 }
 
 export function getOccurrence(controllerHome: string, repoId: string, occurrenceId: string): ScheduleOccurrence | undefined {
-  const path = occurrencePath(controllerHome, repoId, occurrenceId);
-  return existsSync(path) ? readJsonFile<ScheduleOccurrence>(path) : undefined;
+  const canonicalPath = occurrencePath(controllerHome, repoId, occurrenceId);
+  if (existsSync(canonicalPath)) {
+    const occurrence = readJsonFile<ScheduleOccurrence>(canonicalPath);
+    return occurrence.repoId === repoId ? occurrence : undefined;
+  }
+  const legacyPath = legacyOccurrencePath(controllerHome, repoId, occurrenceId);
+  return existsSync(legacyPath) ? readJsonFile<ScheduleOccurrence>(legacyPath) : undefined;
 }
 
 export function recordScheduleOccurrenceHandoff(
@@ -363,20 +349,7 @@ export function recordScheduleOccurrenceHandoff(
   input: ScheduleOccurrenceHandoffInput,
 ): ScheduleOccurrence {
   if (occurrence.handoffId) return occurrence;
-  const reusable = input.creationReason === 'repeated_infrastructure_failure'
-    ? activeScheduleFailureHandoff(controllerHome, occurrence.repoId, schedule.scheduleId, input.creationReason, input.reason)
-    : undefined;
-  if (reusable) return saveOccurrence(controllerHome, { ...occurrence, handoffId: reusable.id });
-  const handoffId = input.creationReason === 'repeated_infrastructure_failure'
-    ? stableScheduleFailureHandoffId(
-      controllerHome,
-      occurrence.repoId,
-      schedule.scheduleId,
-      input.creationReason,
-      input.reason,
-      occurrence.occurrenceId,
-    )
-    : `schedule-${occurrence.occurrenceId}`;
+  const handoffId = `schedule-${occurrence.occurrenceId}`;
   const evidenceRefs: NonNullable<ScheduleOccurrenceHandoffInput['evidenceRefs']> = [
     { title: `Occurrence ${occurrence.occurrenceId}`, summary: occurrence.reason ?? input.reason, detailLevel: 'summary' as const },
   ];
@@ -434,6 +407,36 @@ export function listActiveOccurrences(controllerHome: string, repoId: string, sc
     });
 }
 
+/**
+ * A created occurrence must be settled by the same evaluateSchedule call that
+ * creates it. If the process dies or an early Controller/Supervisor exception
+ * escapes before that settlement, leaving it active permanently blocks the
+ * schedule's maxActiveOccurrences admission. Reclaim only old `created`
+ * records; queued/running work remains owned by the normal worker recovery
+ * path.
+ */
+export function reclaimStaleCreatedOccurrences(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  nowMs = Date.now(),
+  staleAfterMs = SCHEDULE_CREATED_OCCURRENCE_STALE_MS,
+): ScheduleOccurrence[] {
+  const threshold = Math.max(1_000, staleAfterMs);
+  return listActiveOccurrences(controllerHome, repoId, scheduleId)
+    .filter((occurrence) => occurrence.status === 'created')
+    .filter((occurrence) => {
+      const createdAt = Date.parse(occurrence.createdAt);
+      return Number.isFinite(createdAt) && nowMs - createdAt >= threshold;
+    })
+    .map((occurrence) => saveOccurrence(controllerHome, {
+      ...occurrence,
+      status: 'skipped',
+      decision: 'operation_blocked',
+      reason: `Orphaned created occurrence reclaimed after ${threshold}ms without Scheduler settlement.`,
+    }));
+}
+
 export function listOccurrences(controllerHome: string, repoId: string, scheduleId?: string, limit = 100): ScheduleOccurrence[] {
   const bounded = Math.max(1, Math.min(limit, 1000));
   const index = readOccurrenceIndex(controllerHome, repoId);
@@ -446,15 +449,17 @@ export function listOccurrences(controllerHome: string, repoId: string, schedule
     });
   if (indexed.length > 0) return indexed;
 
-  const root = join(schedulesRoot(controllerHome, repoId), 'occurrences');
+  const roots = [join(schedulesRoot(controllerHome), 'occurrences'), join(legacySchedulesRoot(controllerHome, repoId), 'occurrences')];
   try {
-    const legacy = readdirSync(root).filter((name) => name.endsWith('.json'))
-      .map((name) => readJsonFile<ScheduleOccurrence>(join(root, name)))
+    const legacy = roots.flatMap((root) => {
+      try { return readdirSync(root).filter((name) => name.endsWith('.json')).map((name) => readJsonFile<ScheduleOccurrence>(join(root, name))); }
+      catch { return []; }
+    })
       .filter((entry) => !scheduleId || entry.scheduleId === scheduleId)
       .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
       .slice(0, bounded);
     if (legacy.length > 0) {
-      withControllerLock(controllerHome, { scope: 'repository', repoId }, `schedule-index-backfill:${repoId}`, () => {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule-index:${repoId}` }, `schedule-index-backfill:${repoId}`, () => {
         for (const occurrence of legacy) upsertOccurrenceIndexUnlocked(controllerHome, occurrence);
       }, 10_000);
     }
@@ -543,7 +548,7 @@ export function cleanupScheduleOccurrenceHistory(
     return true;
   };
 
-  const occurrenceRoot = join(schedulesRoot(controllerHome, repoId), 'occurrences');
+  const occurrenceRoot = join(schedulesRoot(controllerHome), 'occurrences');
   let occurrenceNames: string[] = [];
   try { occurrenceNames = readdirSync(occurrenceRoot).filter((name) => name.endsWith('.json')).sort(); }
   catch { occurrenceNames = []; }
@@ -568,7 +573,7 @@ export function cleanupScheduleOccurrenceHistory(
     }
     if (!canRemove()) break;
     try {
-      withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${occurrence.scheduleId}` }, `cleanup-schedule-occurrence:${occurrence.occurrenceId}`, () => {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${occurrence.scheduleId}` }, `cleanup-schedule-occurrence:${occurrence.occurrenceId}`, () => {
         if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(occurrence.occurrenceId)) {
           skip('indexed_occurrence_recheck');
           return;
@@ -588,7 +593,7 @@ export function cleanupScheduleOccurrenceHistory(
     }
   }
 
-  const decisionRoot = join(schedulesRoot(controllerHome, repoId), 'decisions');
+  const decisionRoot = join(schedulesRoot(controllerHome), 'decisions');
   let decisionNames: string[] = [];
   try { decisionNames = readdirSync(decisionRoot).filter((name) => name.endsWith('.json')).sort(); }
   catch { decisionNames = []; }
@@ -615,7 +620,7 @@ export function cleanupScheduleOccurrenceHistory(
     }
     if (!canRemove()) break;
     try {
-      withControllerLock(controllerHome, { scope: 'task', repoId, taskId: `schedule-${decision.scheduleId}` }, `cleanup-schedule-decision:${decision.decisionId}`, () => {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${decision.scheduleId}` }, `cleanup-schedule-decision:${decision.decisionId}`, () => {
         if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(decision.occurrenceId)) {
           skip('indexed_decision_recheck');
           return;
@@ -640,7 +645,7 @@ export function cleanupScheduleOccurrenceHistory(
 
 
 export function saveScheduleDecision(controllerHome: string, decision: ScheduleDecision): ScheduleDecision {
-  return withControllerLock(controllerHome, { scope: 'task', repoId: decision.repoId, taskId: `schedule-${decision.scheduleId}` }, `save-schedule-decision:${decision.decisionId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${decision.scheduleId}` }, `save-schedule-decision:${decision.decisionId}`, () => {
     const path = decisionPath(controllerHome, decision.repoId, decision.decisionId);
     if (existsSync(path)) return readJsonFile<ScheduleDecision>(path);
     writeJsonAtomic(path, decision);
@@ -659,8 +664,13 @@ export function saveScheduleDecision(controllerHome: string, decision: ScheduleD
 }
 
 export function getScheduleDecision(controllerHome: string, repoId: string, decisionId: string): ScheduleDecision | undefined {
-  const path = decisionPath(controllerHome, repoId, decisionId);
-  return existsSync(path) ? readJsonFile<ScheduleDecision>(path) : undefined;
+  const canonicalPath = decisionPath(controllerHome, repoId, decisionId);
+  if (existsSync(canonicalPath)) {
+    const decision = readJsonFile<ScheduleDecision>(canonicalPath);
+    return decision.repoId === repoId ? decision : undefined;
+  }
+  const legacyPath = legacyDecisionPath(controllerHome, repoId, decisionId);
+  return existsSync(legacyPath) ? readJsonFile<ScheduleDecision>(legacyPath) : undefined;
 }
 
 
@@ -765,7 +775,7 @@ export function buildScheduleDedupeReport(controllerHome: string, repoId: string
 export function applyScheduleDedupe(controllerHome: string, repoId: string, input: { dryRun?: unknown; confirmAuthorization?: unknown } = {}): ScheduleDedupeApplyResult {
   const dryRun = input.dryRun === true;
   if (!dryRun && input.confirmAuthorization !== true) throw new Error('SCHEDULE_DEDUPE_AUTHORIZATION_REQUIRED: confirm_authorization must be true to pause duplicate schedules');
-  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: 'schedule-dedupe' }, `schedule-dedupe:${repoId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule-dedupe:${repoId}` }, `schedule-dedupe:${repoId}`, () => {
     const report = buildScheduleDedupeReport(controllerHome, repoId);
     const disabled: ScheduleDedupeApplyResult['disabled'] = [];
     if (!dryRun) {
@@ -783,3 +793,13 @@ export function applyScheduleDedupe(controllerHome: string, repoId: string, inpu
     return { repoId, appliedAt: new Date().toISOString(), dryRun, report, disabled };
   }, 10_000);
 }
+
+export function getScheduleDefinition(controllerHome: string, repoId: string, scheduleId: string): ScheduleDefinition {
+  const schedule = getSchedule(controllerHome, repoId, scheduleId);
+  return extractScheduleDefinition(schedule);
+}
+
+export function getScheduleRuntimeState(controllerHome: string, repoId: string, scheduleId: string): ScheduleRuntimeState {
+  const schedule = getSchedule(controllerHome, repoId, scheduleId);
+  return extractScheduleRuntimeState(schedule);
+}

package/packages/kernel/work/api/index.ts

@@ -1,15 +1,16 @@
 /** Stable in-process API for the Kernel Work module. */
 export * from '../application/work-service';
 export * from '../domain/implementation-review';
-export * from '../domain/admission-policy';
 export * from '../domain/check-receipt';
 export * from '../domain/context-closure-receipt';
+export * from '../domain/current-task-lineage';
+export * from '../domain/objective-graph';
 export * from '../domain/execution-snapshot';
 export * from '../domain/execution-concurrency';
 export * from '../domain/engineering-contracts';
 export * from '../domain/engineering-design';
 export * from '../domain/engineering-profile';
+export * from '../domain/evaluation-promotion-receipt';
 export * from '../domain/project-engineering-contract';
 export * from '../domain/repository-completion-receipt';
-export * from '../domain/state-machine';
 export * from '../domain/types';

package/packages/kernel/work/application/work-service.ts

@@ -1,11 +1,8 @@
 import {
   appendWorkEvidence as persistWorkEvidence,
   getWorkContract as readWorkContract,
-  recordWorkCompletionReceipt as persistWorkCompletionReceipt,
+  recordWorkCompletionReceipt as persistWorkDeliveryReceipt,
   canonicalizeWorkContractForAuthority,
-  rebindPlanBoundWorkContract as buildPlanBoundWorkRebind,
-  refreshPlanBoundWorkRevision as buildPlanBoundWorkRevisionRefresh,
-  retirePlanBoundWorkContract as buildPlanBoundWorkRetirement,
 } from '../infrastructure/work-contract-store';
 import type { WorkContract } from '../domain/types';
 import type { WorkContractStoreOptions } from '../ports/work-contract-store';
@@ -20,11 +17,10 @@ export interface CompleteRemoteEffectProcessInput {
 }
 
 /**
- * Application command for terminalizing a Work from one trusted repository
- * remote-effect Process receipt. Gateway supplies evidence identity only; Work
- * kind checks, evidence append, and terminal lifecycle mutation stay here.
+ * Record one trusted repository remote-effect Process receipt as Work evidence.
+ * This never changes semantic Work state; the model/user decides completion via complete.
  */
-export function completeRemoteEffectWorkFromProcessReceipt(
+export function recordRemoteEffectWorkProcessReceipt(
   options: WorkContractStoreOptions,
   workId: string,
   input: CompleteRemoteEffectProcessInput,
@@ -34,7 +30,7 @@ export function completeRemoteEffectWorkFromProcessReceipt(
   if (work.workKind !== 'remote_effect') {
     throw new Error(`WORK_REMOTE_EFFECT_PROCESS_KIND_MISMATCH: ${workId} is ${work.workKind}, expected remote_effect`);
   }
-  if (work.status === 'completed' && work.completionReceipt?.source === 'remote_effect') return work;
+  if (work.completionReceipt?.source === 'remote_effect') return work;
   if (!work.evidenceRefs.some((candidate) => candidate.evidenceId === input.processId)) {
     persistWorkEvidence(options, workId, {
       evidenceId: input.processId,
@@ -43,7 +39,7 @@ export function completeRemoteEffectWorkFromProcessReceipt(
       detailLevel: 'summary',
     });
   }
-  return persistWorkCompletionReceipt(
+  return persistWorkDeliveryReceipt(
     options,
     workId,
     {
@@ -77,15 +73,21 @@ export {
   emptyWorkContractStore,
   readWorkContractStore,
   writeWorkContractStore,
+  createWorkSemanticContext,
   createWorkContract,
   getWorkContractByRequestId,
   acceptSubmittedWorkContract,
   listWorkContracts,
   readActiveWorkCandidates,
+  readWorkContractLineageSnapshot,
   initializeWorkCandidateIndex,
   isCurrentWorkContract,
   supersedeWorkContract,
   getWorkContract,
+  semanticWorkState,
+  workSemanticView,
+  listWorkSemanticRevisionRecords,
+  reviseWorkSemanticContext,
   summarizeWorkContract,
   updateWorkContract,
   promoteWorkToRepositoryChange,
@@ -93,13 +95,10 @@ export {
   activateWorkContract,
   failWorkContract,
   cancelWorkContract,
-  resumeRetainedCancelledWorkContract,
+  recordCancelledWorkCleanupCompleted,
   recordWorkScopeEvidence,
   transitionWorkContractPhase,
-  requestWorkImplementationReview,
   recordWorkImplementationReview,
-  recordContentEquivalentCommitAuthorityTransfer,
-  reconcileApprovedWorkImplementationReviewProjection,
   appendWorkEvidence,
   appendWorkHandoffRef,
   appendVerificationRecord,
@@ -107,42 +106,18 @@ export {
   canonicalizeWorkContractForAuthority,
 } from '../infrastructure/work-contract-store';
 export type {
+  CreateWorkSemanticInput,
   CreateWorkContractInput,
   ListWorkContractOptions,
   InvalidActiveWorkCandidate,
   ActiveWorkCandidateSnapshot,
+  WorkContractLineageSnapshot,
   SupersedeWorkContractInput,
   WorkContractSummary,
+  WorkSemanticRevisionRecord,
+  ReviseWorkSemanticInput,
   AcceptSubmittedWorkInput,
   WorkContractStoreLocation,
   WorkContractStoreOptions,
   WorkContractMetadataPatch,
 } from '../infrastructure/work-contract-store';
-
-/**
- * Public Work application command for constructing a validated scope-only
- * successor-Plan binding. Persistence remains with the caller so a higher-level
- * control-plane transaction can atomically update Plan + Work authority.
- */
-export function rebindPlanBoundWorkContract(
-  current: WorkContract,
-  input: Parameters<typeof buildPlanBoundWorkRebind>[1],
-): WorkContract {
-  return buildPlanBoundWorkRebind(current, input);
-}
-
-/** Build a validated terminal authority-retirement transition for a Work whose Plan is no longer current. */
-/** Refresh a Work against a newer revision of the same stable Plan identity. */
-export function refreshPlanBoundWorkRevision(
-  current: WorkContract,
-  input: Parameters<typeof buildPlanBoundWorkRevisionRefresh>[1],
-): WorkContract {
-  return buildPlanBoundWorkRevisionRefresh(current, input);
-}
-
-export function retirePlanBoundWorkContract(
-  current: WorkContract,
-  input: Parameters<typeof buildPlanBoundWorkRetirement>[1],
-): WorkContract {
-  return buildPlanBoundWorkRetirement(current, input);
-}