@moretea-labs/forge 1.8.0 → 1.8.1

package/packages/kernel/identity/infrastructure/user-request-store.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type {
+  CreateUserRequestInput,
+  ResolveUserRequestInput,
+  UserRequest,
+} from '../domain/user-request';
+
+interface UserRequestStoreData {
+  schemaVersion: 1;
+  requests: UserRequest[];
+}
+
+export function userRequestStorePath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'system', 'user-requests', 'requests.json');
+}
+
+function loadStore(controllerHome: string): UserRequestStoreData {
+  const path = userRequestStorePath(controllerHome);
+  if (!existsSync(path)) return { schemaVersion: 1, requests: [] };
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('store must be an object');
+    const record = raw as Record<string, unknown>;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.requests)) throw new Error('schemaVersion/requests are invalid');
+    return { schemaVersion: 1, requests: record.requests as UserRequest[] };
+  } catch (error) {
+    throw new Error(`USER_REQUEST_STORE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function saveStore(controllerHome: string, store: UserRequestStoreData): void {
+  const path = userRequestStorePath(controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+  renameSync(temporary, path);
+}
+
+function canonicalRequestIndex(requests: readonly UserRequest[], requestId: string): number {
+  let selected = -1;
+  let selectedAt = Number.NEGATIVE_INFINITY;
+  for (let index = 0; index < requests.length; index += 1) {
+    const request = requests[index]!;
+    if (request.requestId !== requestId) continue;
+    const updatedAt = Date.parse(request.updatedAt);
+    const comparableAt = Number.isFinite(updatedAt) ? updatedAt : Number.NEGATIVE_INFINITY;
+    if (selected < 0 || comparableAt >= selectedAt) {
+      selected = index;
+      selectedAt = comparableAt;
+    }
+  }
+  return selected;
+}
+
+function canonicalUserRequests(requests: readonly UserRequest[]): UserRequest[] {
+  const requestIds = [...new Set(requests.map((request) => request.requestId))];
+  return requestIds.map((requestId) => requests[canonicalRequestIndex(requests, requestId)]!);
+}
+
+/**
+ * Creates or coalesces a UserActionRequest / UserDecisionRequest.
+ * If an active (pending) request exists with the exact same rootCauseKey,
+ * return the existing record to guarantee deduplication across retries.
+ */
+export function recordUserRequest(controllerHome: string, input: CreateUserRequestInput): UserRequest {
+  const rootCauseKey = input.rootCauseKey.trim();
+  if (!rootCauseKey) throw new Error('USER_REQUEST_ROOT_CAUSE_KEY_REQUIRED');
+
+  const store = loadStore(controllerHome);
+  const explicitRequestId = input.requestId?.trim();
+  if (explicitRequestId) {
+    const identityMatches = store.requests.filter((request) => request.requestId === explicitRequestId);
+    if (identityMatches.some((request) => request.rootCauseKey !== rootCauseKey)) {
+      throw new Error(`USER_REQUEST_ID_CONFLICT: ${explicitRequestId}`);
+    }
+    if (identityMatches.length) {
+      const existingIndex = canonicalRequestIndex(store.requests, explicitRequestId);
+      const existing = store.requests[existingIndex]!;
+      if (existing.status !== 'pending' || !input.presentation) return structuredClone(existing);
+      const merged = {
+        ...existing,
+        presentation: { ...(existing.presentation ?? {}), ...input.presentation },
+      };
+      if (JSON.stringify(merged.presentation) !== JSON.stringify(existing.presentation ?? {})) {
+        merged.updatedAt = (input.now ?? new Date()).toISOString();
+        store.requests[existingIndex] = merged;
+        saveStore(controllerHome, store);
+        return structuredClone(merged);
+      }
+      return structuredClone(existing);
+    }
+  }
+
+  // Coalescing: return matching pending request for the same semantic root cause.
+  const existingIndex = store.requests.findIndex(
+    (r) => r.status === 'pending' && r.rootCauseKey === rootCauseKey,
+  );
+  if (existingIndex >= 0) {
+    const existing = store.requests[existingIndex]!;
+    if (input.presentation) {
+      const merged = {
+        ...existing,
+        presentation: { ...(existing.presentation ?? {}), ...input.presentation },
+      };
+      if (JSON.stringify(merged.presentation) !== JSON.stringify(existing.presentation ?? {})) {
+        merged.updatedAt = (input.now ?? new Date()).toISOString();
+        store.requests[existingIndex] = merged;
+        saveStore(controllerHome, store);
+        return structuredClone(merged);
+      }
+    }
+    return structuredClone(existing);
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const requestId = explicitRequestId || `usrreq_${randomUUID().replaceAll('-', '')}`;
+  const record: UserRequest = {
+    schemaVersion: 1,
+    requestId,
+    kind: input.kind,
+    rootCauseKey,
+    title: input.title.trim(),
+    summary: input.summary.trim(),
+    actionRequired: input.actionRequired,
+    ...(input.targetScope ? { targetScope: input.targetScope } : {}),
+    ...(input.options ? { options: input.options } : {}),
+    ...(input.presentation ? { presentation: input.presentation } : {}),
+    status: 'pending',
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  store.requests.push(record);
+  saveStore(controllerHome, store);
+  return record;
+}
+
+export function resolveUserRequest(controllerHome: string, input: ResolveUserRequestInput): UserRequest {
+  const requestId = input.requestId.trim();
+  const decision = input.decision.trim();
+  const resolvedBy = input.resolvedBy.trim();
+  if (!requestId || !decision || !resolvedBy) throw new Error('RESOLVE_USER_REQUEST_ARGS_REQUIRED');
+
+  const store = loadStore(controllerHome);
+  const matchingIndexes = store.requests.flatMap((request, index) => request.requestId === requestId ? [index] : []);
+  if (!matchingIndexes.length) throw new Error(`USER_REQUEST_NOT_FOUND: ${requestId}`);
+  const canonicalIndex = canonicalRequestIndex(store.requests, requestId);
+  const now = (input.now ?? new Date()).toISOString();
+  let changed = false;
+  for (const index of matchingIndexes) {
+    const current = store.requests[index]!;
+    if (current.status !== 'pending') continue;
+    store.requests[index] = {
+      ...current,
+      status: 'resolved',
+      resolution: { decision, resolvedBy, resolvedAt: now },
+      updatedAt: now,
+    };
+    changed = true;
+  }
+  if (changed) saveStore(controllerHome, store);
+  const resolvedCanonicalIndex = canonicalRequestIndex(store.requests, requestId);
+  return structuredClone(store.requests[resolvedCanonicalIndex >= 0 ? resolvedCanonicalIndex : canonicalIndex]!);
+}
+
+export function getUserRequest(controllerHome: string, requestId: string): UserRequest | undefined {
+  const normalized = requestId.trim();
+  if (!normalized) return undefined;
+  const store = loadStore(controllerHome);
+  const index = canonicalRequestIndex(store.requests, normalized);
+  return index >= 0 ? structuredClone(store.requests[index]!) : undefined;
+}
+
+export function listUserRequests(controllerHome: string, status?: 'pending' | 'resolved' | 'cancelled' | 'all'): UserRequest[] {
+  const store = loadStore(controllerHome);
+  return canonicalUserRequests(store.requests)
+    .filter((r) => !status || status === 'all' || r.status === status)
+    .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt))
+    .map((r) => structuredClone(r));
+}

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

@@ -1,6 +1,4 @@
 export * from '../domain/schedule';
-export * from '../domain/continuation';
 export * from '../application/schedule-service';
-export * from '../application/continuation-service';
 export * from '../application/eligibility';
 export * from '../application/settlement';

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

@@ -10,12 +10,15 @@ export {
   getScheduleDecision,
   listActiveOccurrences,
   listOccurrences,
+  reclaimStaleCreatedOccurrences,
   listSchedules,
   recordScheduleOccurrenceHandoff,
   saveOccurrence,
   saveSchedule,
   saveScheduleDecision,
   updateSchedule,
+  getScheduleDefinition,
+  getScheduleRuntimeState,
   type ScheduleHistoryCleanupResult,
   type ScheduleDedupeApplyResult,
   type ScheduleDedupeReport,

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

@@ -167,21 +167,6 @@ export function settleScheduledExecution(
         outcome,
         decision: 'execute',
         reason,
-        handoff: {
-          title: `Scheduled maintenance occurrence ${occurrenceId} failed`,
-          summary: 'A bounded live maintenance occurrence failed and requires review before the schedule continues unattended.',
-          reason,
-          creationReason: 'repeated_infrastructure_failure',
-          blockingDecision: 'Review the failed maintenance occurrence and decide whether the schedule should continue automatically.',
-          recommendedDecision: 'Inspect the failed occurrence, fix the runtime blocker, then re-enable or retrigger the schedule intentionally.',
-          recommendedPrompt: `Review schedule occurrence ${occurrenceId} for ${scheduleId}, inspect the failed runtime maintenance action, and decide whether to resume automatic maintenance.`,
-          statusSummary: 'Scheduled maintenance execution failed.',
-          blockedBy: ['scheduled_execution_failed'],
-          attemptedActions: [
-            `job:${job.jobId}`,
-            `operation:${String(job.payload.operation ?? 'unknown')}`,
-          ],
-        },
       });
       return;
     }

package/packages/kernel/scheduler/domain/schedule.ts

@@ -100,6 +100,13 @@ export interface RepositorySchedule {
   lastObservationStatus?: 'baseline' | 'unchanged' | 'changed' | 'keepalive' | 'auth_required';
 }
 
+/** Mechanical schedule-to-Work targeting only; never semantic Work lifecycle authority. */
+export function scheduleOwnsWork(schedule: Pick<RepositorySchedule, 'action'>, workId: string): boolean {
+  if (schedule.action.resourceClaims?.some((claim) => claim.workId === workId)) return true;
+  const args = schedule.action.arguments ?? {};
+  return args.workId === workId || args.work_id === workId;
+}
+
 export type ScheduleDecisionType =
   | 'nothing_to_do'
   | 'would_execute'
@@ -147,3 +154,83 @@ export interface ScheduleOccurrence {
   handoffId?: string;
   reason?: string;
 }
+
+/**
+ * Authored schedule intent, revisioned independently from runtime/execution state.
+ */
+export interface ScheduleDefinition {
+  schemaVersion: 1;
+  revision: number;
+  scheduleId: string;
+  requestId: string;
+  scopeRef?: ScopeRef;
+  executionPlacement?: ExecutionPlacement;
+  repoId?: string;
+  name: string;
+  enabled: boolean;
+  trigger: ScheduleTrigger;
+  policy: SchedulePolicy;
+  action: ScheduleAction;
+  stopConditions: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Mechanical runtime facts and observation state for a schedule.
+ */
+export interface ScheduleRuntimeState {
+  schemaVersion: 1;
+  scheduleId: string;
+  repoId?: string;
+  lastTriggeredAt?: string;
+  lastOccurrenceId?: string;
+  consecutiveFailures: number;
+  consecutiveNoops?: number;
+  nextEligibleAt?: string;
+  pausedReason?: string;
+  lastObservationAt?: string;
+  lastObservationFingerprint?: string;
+  lastObservationChangedAt?: string;
+  lastObservationStatus?: 'baseline' | 'unchanged' | 'changed' | 'keepalive' | 'auth_required';
+  updatedAt: string;
+}
+
+export function extractScheduleDefinition(schedule: RepositorySchedule): ScheduleDefinition {
+  return {
+    schemaVersion: schedule.schemaVersion,
+    revision: schedule.revision,
+    scheduleId: schedule.scheduleId,
+    requestId: schedule.requestId,
+    scopeRef: schedule.scopeRef,
+    executionPlacement: schedule.executionPlacement,
+    repoId: schedule.repoId,
+    name: schedule.name,
+    enabled: schedule.enabled,
+    trigger: schedule.trigger,
+    policy: schedule.policy,
+    action: schedule.action,
+    stopConditions: schedule.stopConditions,
+    createdAt: schedule.createdAt,
+    updatedAt: schedule.updatedAt,
+  };
+}
+
+export function extractScheduleRuntimeState(schedule: RepositorySchedule): ScheduleRuntimeState {
+  return {
+    schemaVersion: 1,
+    scheduleId: schedule.scheduleId,
+    repoId: schedule.repoId,
+    lastTriggeredAt: schedule.lastTriggeredAt,
+    lastOccurrenceId: schedule.lastOccurrenceId,
+    consecutiveFailures: schedule.consecutiveFailures,
+    consecutiveNoops: schedule.consecutiveNoops,
+    nextEligibleAt: schedule.nextEligibleAt,
+    pausedReason: schedule.pausedReason,
+    lastObservationAt: schedule.lastObservationAt,
+    lastObservationFingerprint: schedule.lastObservationFingerprint,
+    lastObservationChangedAt: schedule.lastObservationChangedAt,
+    lastObservationStatus: schedule.lastObservationStatus,
+    updatedAt: schedule.updatedAt,
+  };
+}