@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/memory/domain/experience.ts

@@ -0,0 +1,103 @@
+import type { ScopeRef } from '../../identity/api/index';
+
+export interface ExperienceApplicability { channel?: string; account?: string; locale?: string }
+export interface ExperienceRecord {
+  schemaVersion: 1;
+  id: string;
+  revision: number;
+  scope: ScopeRef;
+  applicability: ExperienceApplicability;
+  kind: 'observation' | 'hypothesis' | 'lesson';
+  statement: string;
+  evidenceRefs: string[];
+  sourceWorkId: string;
+  sourceRoundId: string;
+  recordedAt: string;
+  expiresAt?: string;
+  durableRationale?: string;
+  supersedesId?: string;
+  counterEvidenceRefs: string[];
+  retractedAt?: string;
+  retractionReason?: string;
+  retractionSourceWorkId?: string;
+  retractionSourceRoundId?: string;
+}
+
+export type ExperienceDraft = Omit<ExperienceRecord, 'schemaVersion' | 'revision' | 'retractedAt' | 'retractionReason' | 'retractionSourceWorkId' | 'retractionSourceRoundId'>;
+
+/** A metric is an observation at a time, never an automatically additive total. */
+export interface OutcomeObservation {
+  schemaVersion: 1;
+  id: string;
+  scope: ScopeRef;
+  sourceWorkId: string;
+  sourceRoundId: string;
+  evidenceRef: string;
+  remoteObject: { id: string; url: string; account: string; channel: string };
+  observedAt: string;
+  window: { start: string; end: string };
+  metrics: Array<{ name: string; unit: string; value: number | null; missingReason?: string; cumulative: boolean }>;
+}
+
+export function requireExperienceText(value: string, label: string, max = 256): void {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(`EXPERIENCE_${label}_INVALID`);
+}
+
+export function validateExperienceScope(scope: ScopeRef): void {
+  if (scope.schemaVersion !== 1 || !['workspace', 'project', 'requirement', 'plan', 'plan_step', 'work'].includes(scope.kind)) throw new Error('EXPERIENCE_SCOPE_INVALID');
+  requireExperienceText(scope.id, 'SCOPE', 512);
+}
+
+export function matchesExperienceApplicability(stored: ExperienceApplicability, requested: ExperienceApplicability): boolean {
+  return (['channel', 'account', 'locale'] as const).every((key) => stored[key] === undefined || stored[key] === requested[key]);
+}
+
+export function validateExperience(record: ExperienceRecord): ExperienceRecord {
+  if (record.schemaVersion !== 1 || !Number.isSafeInteger(record.revision) || record.revision < 1) throw new Error('EXPERIENCE_VERSION_INVALID');
+  validateExperienceScope(record.scope);
+  for (const [key, value] of Object.entries({ id: record.id, work: record.sourceWorkId, round: record.sourceRoundId })) requireExperienceText(value, key);
+  requireExperienceText(record.statement, 'STATEMENT', 4000);
+  if (!['observation', 'hypothesis', 'lesson'].includes(record.kind)) throw new Error('EXPERIENCE_KIND_INVALID');
+  if (!record.applicability || Object.keys(record.applicability).some(key => !['channel', 'account', 'locale'].includes(key))) throw new Error('EXPERIENCE_APPLICABILITY_INVALID');
+  Object.values(record.applicability).forEach(value => requireExperienceText(value, 'APPLICABILITY'));
+  if (record.applicability.account && !record.applicability.channel) throw new Error('EXPERIENCE_ACCOUNT_CHANNEL_REQUIRED');
+  for (const refs of [record.evidenceRefs, record.counterEvidenceRefs]) {
+    if (!Array.isArray(refs) || refs.length > 32 || new Set(refs).size !== refs.length) throw new Error('EXPERIENCE_EVIDENCE_INVALID');
+    refs.forEach(ref => requireExperienceText(ref, 'EVIDENCE', 512));
+  }
+  if (!record.evidenceRefs.length) throw new Error('EXPERIENCE_EVIDENCE_REQUIRED');
+  const at = Date.parse(record.recordedAt);
+  if (!Number.isFinite(at)) throw new Error('EXPERIENCE_TIME_INVALID');
+  if (record.expiresAt && (!Number.isFinite(Date.parse(record.expiresAt)) || Date.parse(record.expiresAt) <= at)) throw new Error('EXPERIENCE_EXPIRY_INVALID');
+  if (!record.expiresAt && (record.kind !== 'lesson' || !record.durableRationale?.trim())) throw new Error('EXPERIENCE_EXPIRY_REQUIRED');
+  if (record.durableRationale) requireExperienceText(record.durableRationale, 'DURABLE_RATIONALE', 2000);
+  if (record.supersedesId) requireExperienceText(record.supersedesId, 'SUPERSEDES');
+  if (record.retractedAt) {
+    if (!Number.isFinite(Date.parse(record.retractedAt)) || Date.parse(record.retractedAt) < at) throw new Error('EXPERIENCE_RETRACTION_INVALID');
+    requireExperienceText(record.retractionReason!, 'RETRACTION_REASON', 1000);
+    requireExperienceText(record.retractionSourceWorkId!, 'RETRACTION_WORK');
+    requireExperienceText(record.retractionSourceRoundId!, 'RETRACTION_ROUND');
+  }
+  return record;
+}
+
+export function validateOutcomeObservation(value: OutcomeObservation): OutcomeObservation {
+  if (value.schemaVersion !== 1) throw new Error('OUTCOME_SCHEMA_INVALID');
+  validateExperienceScope(value.scope);
+  for (const text of [value.id, value.sourceWorkId, value.sourceRoundId, value.evidenceRef, value.remoteObject.id, value.remoteObject.account, value.remoteObject.channel]) requireExperienceText(text, 'OUTCOME_ID', 512);
+  const url = new URL(value.remoteObject.url);
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error('OUTCOME_URL_INVALID');
+  const times = [value.window.start, value.window.end, value.observedAt].map(Date.parse);
+  if (times.some(time => !Number.isFinite(time)) || times[0]! > times[1]! || times[1]! > times[2]!) throw new Error('OUTCOME_WINDOW_INVALID');
+  if (!Array.isArray(value.metrics) || value.metrics.length < 1 || value.metrics.length > 32) throw new Error('OUTCOME_METRICS_INVALID');
+  const names = new Set<string>();
+  for (const metric of value.metrics) {
+    requireExperienceText(metric.name, 'METRIC'); requireExperienceText(metric.unit, 'UNIT');
+    if (names.has(metric.name)) throw new Error('OUTCOME_METRIC_DUPLICATE');
+    names.add(metric.name);
+    if (typeof metric.cumulative !== 'boolean') throw new Error('OUTCOME_METRIC_CUMULATIVE_REQUIRED');
+    if (metric.value === null) requireExperienceText(metric.missingReason!, 'MISSING_REASON', 1000);
+    else if (!Number.isFinite(metric.value) || metric.missingReason !== undefined) throw new Error('OUTCOME_METRIC_VALUE_INVALID');
+  }
+  return value;
+}

package/packages/kernel/memory/domain/operational-prior.ts

@@ -0,0 +1,92 @@
+import type { ScopeKind, ScopeRef } from '../../identity/api/index';
+
+export const OPERATIONAL_SIGNAL_IDS = ['execution_job.terminal_mechanical','process_check.terminal_mechanical'] as const;
+export type OperationalSignalId = (typeof OPERATIONAL_SIGNAL_IDS)[number];
+export const OPERATIONAL_TARGET_IDS = ['mechanical_candidate_ordering','check_completion_grace'] as const;
+export type OperationalTargetId = (typeof OPERATIONAL_TARGET_IDS)[number];
+export const OPERATIONAL_ACTION_IDS = ['baseline','candidate','observed_check'] as const;
+export type OperationalActionId = (typeof OPERATIONAL_ACTION_IDS)[number];
+export const OPERATIONAL_METRIC_IDS = ['latency_ms','success_rate'] as const;
+export type OperationalMetricId = (typeof OPERATIONAL_METRIC_IDS)[number];
+export const OPERATIONAL_CONSUMER_IDS = ['shadow_evaluation','run_check_completion_grace'] as const;
+export type OperationalConsumerId = (typeof OPERATIONAL_CONSUMER_IDS)[number];
+export const OPERATIONAL_SOURCE_SCHEMAS = ['execution_job/v1','process_check_receipt/v1'] as const;
+export type OperationalSourceSchema = (typeof OPERATIONAL_SOURCE_SCHEMAS)[number];
+export const OPERATIONAL_COMPATIBILITY_DIMENSIONS = ['operation','environment'] as const;
+export type OperationalCompatibilityDimension = (typeof OPERATIONAL_COMPATIBILITY_DIMENSIONS)[number];
+
+export type OperationalOutcomeClass = 'executed_success'|'executed_failure'|'admission_wait'|'contention_wait'|'policy_denied'|'cancelled'|'timeout'|'infrastructure_failure'|'unknown';
+
+export interface OperationalSignalDefinition {
+  schemaVersion:1; signalId:OperationalSignalId; owner:'kernel.memory.shadow'; sourceSchema:OperationalSourceSchema;
+  eventKinds:readonly string[]; extractorVersion:1; valueType:'number'; dataClass:'mechanical_telemetry';
+  maxScopeCardinality:number; maxCompatibilityCardinality:number; retentionHorizonMs:number; invalidationDimensions:readonly OperationalCompatibilityDimension[];
+}
+export interface OperationalMetricDefinition {
+  schemaVersion:1; metricId:OperationalMetricId; direction:'lower_is_better'|'higher_is_better';
+  admissibleOutcomes:readonly OperationalOutcomeClass[]; decayHalfLifeMs:number;
+}
+export interface OperationalTargetDefinition {
+  schemaVersion:1; targetId:OperationalTargetId; owner:'kernel.memory.shadow'; consumerId:OperationalConsumerId;
+  actions:readonly OperationalActionId[]; metricIds:readonly OperationalMetricId[]; applicableScopeKinds:readonly ScopeKind[];
+  compatibilityDimensions:readonly OperationalCompatibilityDimension[];
+  forbiddenDecisions:readonly ['semantic_acceptance','lifecycle_transition','approval','authorization','external_effect','product_or_coding_strategy'];
+  activationThreshold:{minSamples:number;minDistinctEvidence:number;maxSamples:number};
+}
+const DAY_MS=24*60*60*1000;
+export const OPERATIONAL_SIGNAL_DEFINITIONS:Readonly<Record<OperationalSignalId,OperationalSignalDefinition>>=Object.freeze({
+  'execution_job.terminal_mechanical':Object.freeze({schemaVersion:1,signalId:'execution_job.terminal_mechanical',owner:'kernel.memory.shadow',sourceSchema:'execution_job/v1',eventKinds:Object.freeze(['succeeded','failed','timed_out','cancelled','waiting_for_dependency','waiting_for_workspace','waiting_for_heavy_check','waiting_for_integration','waiting_for_release_barrier','waiting_for_approval']),extractorVersion:1,valueType:'number',dataClass:'mechanical_telemetry',maxScopeCardinality:128,maxCompatibilityCardinality:256,retentionHorizonMs:30*DAY_MS,invalidationDimensions:OPERATIONAL_COMPATIBILITY_DIMENSIONS}),
+  'process_check.terminal_mechanical':Object.freeze({schemaVersion:1,signalId:'process_check.terminal_mechanical',owner:'kernel.memory.shadow',sourceSchema:'process_check_receipt/v1',eventKinds:Object.freeze(['passed','failed','timed_out','cancelled']),extractorVersion:1,valueType:'number',dataClass:'mechanical_telemetry',maxScopeCardinality:128,maxCompatibilityCardinality:256,retentionHorizonMs:7*DAY_MS,invalidationDimensions:OPERATIONAL_COMPATIBILITY_DIMENSIONS}),
+});
+export const OPERATIONAL_METRIC_DEFINITIONS:Readonly<Record<OperationalMetricId,OperationalMetricDefinition>>=Object.freeze({
+  latency_ms:Object.freeze({schemaVersion:1,metricId:'latency_ms',direction:'lower_is_better',admissibleOutcomes:['executed_success','executed_failure','timeout'] as const,decayHalfLifeMs:7*DAY_MS}),
+  success_rate:Object.freeze({schemaVersion:1,metricId:'success_rate',direction:'higher_is_better',admissibleOutcomes:['executed_success','executed_failure'] as const,decayHalfLifeMs:14*DAY_MS}),
+});
+export const OPERATIONAL_TARGET_DEFINITIONS:Readonly<Record<OperationalTargetId,OperationalTargetDefinition>>=Object.freeze({
+  mechanical_candidate_ordering:Object.freeze({schemaVersion:1,targetId:'mechanical_candidate_ordering',owner:'kernel.memory.shadow',consumerId:'shadow_evaluation',actions:['baseline','candidate'] as const,metricIds:OPERATIONAL_METRIC_IDS,applicableScopeKinds:['workspace','project','requirement','plan','plan_step','work'] as const,compatibilityDimensions:OPERATIONAL_COMPATIBILITY_DIMENSIONS,forbiddenDecisions:['semantic_acceptance','lifecycle_transition','approval','authorization','external_effect','product_or_coding_strategy'] as const,activationThreshold:Object.freeze({minSamples:3,minDistinctEvidence:3,maxSamples:64})}),
+  check_completion_grace:Object.freeze({schemaVersion:1,targetId:'check_completion_grace',owner:'kernel.memory.shadow',consumerId:'run_check_completion_grace',actions:['observed_check'] as const,metricIds:['latency_ms'] as const,applicableScopeKinds:['project'] as const,compatibilityDimensions:OPERATIONAL_COMPATIBILITY_DIMENSIONS,forbiddenDecisions:['semantic_acceptance','lifecycle_transition','approval','authorization','external_effect','product_or_coding_strategy'] as const,activationThreshold:Object.freeze({minSamples:3,minDistinctEvidence:3,maxSamples:32})}),
+});
+
+export interface OperationalObservation {
+  schemaVersion:1; observationId:string; signalId:OperationalSignalId; targetId:OperationalTargetId; actionId:OperationalActionId;
+  metricId:OperationalMetricId; scope:ScopeRef;
+  source:{schema:OperationalSourceSchema;sourceId:string;eventKind:string;evidenceRef:string;requestId:string;observedAt:string;retainedUntil:string};
+  attribution:{kind:'exact'|'ambiguous';consumerId:OperationalConsumerId;requestId:string;sourceId:string};
+  outcomeClass:OperationalOutcomeClass; value:number; compatibility:Readonly<Record<OperationalCompatibilityDimension,string>>;
+}
+export type OperationalObservationRejectionReason='unregistered_signal'|'source_schema_mismatch'|'unregistered_event_kind'|'unregistered_target'|'unregistered_action'|'unregistered_metric'|'scope_not_applicable'|'ambiguous_attribution'|'attribution_identity_mismatch'|'invalid_value'|'invalid_compatibility'|'inadmissible_outcome'|'replay_expired'|'retention_horizon_exceeded'|'scope_cardinality_exceeded'|'compatibility_cardinality_exceeded'|'duplicate_evidence'|'sample_cap_exceeded';
+export interface OperationalShadowPrior {schemaVersion:1;mode:'shadow';targetId:OperationalTargetId;actionId:OperationalActionId;metricId:OperationalMetricId;scope:ScopeRef;compatibility:Readonly<Record<OperationalCompatibilityDimension,string>>;estimate:number;sampleCount:number;distinctEvidenceCount:number;latestObservedAt:string;replayHorizonEndsAt:string;supportEvidenceRefs:readonly string[];sourceObservationIds:readonly string[];readiness:'insufficient_samples'|'shadow_candidate'}
+export interface OperationalPriorReduction {priors:OperationalShadowPrior[];rejected:Array<{observationId:string;reason:OperationalObservationRejectionReason}>}
+function validInstant(v:string){const n=Date.parse(v);return Number.isFinite(n)?n:undefined}
+function boundedIdentity(v:string){return v.trim().length>0&&v.length<=256}
+function scopeKey(s:ScopeRef){return `${s.kind}:${s.id}`}
+function compatibilityKey(v:Readonly<Record<OperationalCompatibilityDimension,string>>){return OPERATIONAL_COMPATIBILITY_DIMENSIONS.map(d=>`${d}=${v[d]}`).join('|')}
+function validateObservation(o:OperationalObservation,asOfMs:number):OperationalObservationRejectionReason|undefined{
+  const signal=OPERATIONAL_SIGNAL_DEFINITIONS[o.signalId]; if(!signal)return'unregistered_signal';
+  if(o.source.schema!==signal.sourceSchema)return'source_schema_mismatch'; if(!signal.eventKinds.includes(o.source.eventKind))return'unregistered_event_kind';
+  const target=OPERATIONAL_TARGET_DEFINITIONS[o.targetId]; if(!target)return'unregistered_target';
+  if(!target.actions.includes(o.actionId))return'unregistered_action'; if(!target.metricIds.includes(o.metricId))return'unregistered_metric';
+  if(!target.applicableScopeKinds.includes(o.scope.kind))return'scope_not_applicable'; if(o.attribution.kind!=='exact')return'ambiguous_attribution';
+  if(o.attribution.consumerId!==target.consumerId||o.attribution.requestId!==o.source.requestId||o.attribution.sourceId!==o.source.sourceId)return'attribution_identity_mismatch';
+  if(!Number.isFinite(o.value)||o.value<0)return'invalid_value'; if(o.metricId==='success_rate'&&o.value!==0&&o.value!==1)return'invalid_value';
+  for(const d of target.compatibilityDimensions)if(!boundedIdentity(o.compatibility[d]))return'invalid_compatibility';
+  const metric=OPERATIONAL_METRIC_DEFINITIONS[o.metricId]; if(!metric.admissibleOutcomes.includes(o.outcomeClass))return'inadmissible_outcome';
+  const observed=validInstant(o.source.observedAt), retained=validInstant(o.source.retainedUntil); if(observed===undefined||retained===undefined||retained<=observed||retained<=asOfMs)return'replay_expired';if(retained-observed>signal.retentionHorizonMs)return'retention_horizon_exceeded';
+  if(![o.observationId,o.source.sourceId,o.source.evidenceRef,o.source.requestId].every(boundedIdentity))return'attribution_identity_mismatch';
+}
+export function reduceOperationalObservations(input:{observations:readonly OperationalObservation[];asOf:string}):OperationalPriorReduction{
+  const asOfMs=validInstant(input.asOf); if(asOfMs===undefined)throw new Error('OPERATIONAL_PRIOR_INVALID_AS_OF');
+  const rejected:OperationalPriorReduction['rejected']=[]; const scopesBySignal=new Map<OperationalSignalId,Set<string>>(); const compatibilityBySignal=new Map<OperationalSignalId,Set<string>>(); const buckets=new Map<string,{observation:OperationalObservation;sum:number;count:number;evidenceRefs:Set<string>;observationIds:Set<string>;latestObservedAt:string;replayHorizonEndsAt:string}>();
+  const ordered=[...input.observations].sort((a,b)=>a.source.observedAt.localeCompare(b.source.observedAt)||a.source.evidenceRef.localeCompare(b.source.evidenceRef)||a.observationId.localeCompare(b.observationId));
+  for(const o of ordered){const reason=validateObservation(o,asOfMs);if(reason){rejected.push({observationId:o.observationId,reason});continue}const signalScopes=scopesBySignal.get(o.signalId)??new Set<string>();const observedScope=scopeKey(o.scope);if(!signalScopes.has(observedScope)&&signalScopes.size>=OPERATIONAL_SIGNAL_DEFINITIONS[o.signalId].maxScopeCardinality){rejected.push({observationId:o.observationId,reason:'scope_cardinality_exceeded'});continue}signalScopes.add(observedScope);scopesBySignal.set(o.signalId,signalScopes);const compat=compatibilityKey(o.compatibility);const signalCompatibility=compatibilityBySignal.get(o.signalId)??new Set<string>();if(!signalCompatibility.has(compat)&&signalCompatibility.size>=OPERATIONAL_SIGNAL_DEFINITIONS[o.signalId].maxCompatibilityCardinality){rejected.push({observationId:o.observationId,reason:'compatibility_cardinality_exceeded'});continue}signalCompatibility.add(compat);compatibilityBySignal.set(o.signalId,signalCompatibility);const key=[o.targetId,o.actionId,o.metricId,scopeKey(o.scope),compat].join('|');const x=buckets.get(key);if(!x){buckets.set(key,{observation:o,sum:o.value,count:1,evidenceRefs:new Set([o.source.evidenceRef]),observationIds:new Set([o.observationId]),latestObservedAt:o.source.observedAt,replayHorizonEndsAt:o.source.retainedUntil});continue}if(x.observationIds.has(o.observationId)||x.evidenceRefs.has(o.source.evidenceRef)){rejected.push({observationId:o.observationId,reason:'duplicate_evidence'});continue}if(x.count>=OPERATIONAL_TARGET_DEFINITIONS[o.targetId].activationThreshold.maxSamples){rejected.push({observationId:o.observationId,reason:'sample_cap_exceeded'});continue}x.sum+=o.value;x.count++;x.evidenceRefs.add(o.source.evidenceRef);x.observationIds.add(o.observationId);if(o.source.observedAt>x.latestObservedAt)x.latestObservedAt=o.source.observedAt;if(o.source.retainedUntil<x.replayHorizonEndsAt)x.replayHorizonEndsAt=o.source.retainedUntil}
+  const priors=[...buckets.values()].map((b):OperationalShadowPrior=>{const target=OPERATIONAL_TARGET_DEFINITIONS[b.observation.targetId];const refs=[...b.evidenceRefs].sort();return{schemaVersion:1,mode:'shadow',targetId:b.observation.targetId,actionId:b.observation.actionId,metricId:b.observation.metricId,scope:b.observation.scope,compatibility:b.observation.compatibility,estimate:b.sum/b.count,sampleCount:b.count,distinctEvidenceCount:refs.length,latestObservedAt:b.latestObservedAt,replayHorizonEndsAt:b.replayHorizonEndsAt,supportEvidenceRefs:refs,sourceObservationIds:[...b.observationIds].sort(),readiness:b.count>=target.activationThreshold.minSamples&&refs.length>=target.activationThreshold.minDistinctEvidence?'shadow_candidate':'insufficient_samples'}}).sort((a,b)=>a.targetId.localeCompare(b.targetId)||a.metricId.localeCompare(b.metricId)||a.actionId.localeCompare(b.actionId)||scopeKey(a.scope).localeCompare(scopeKey(b.scope))||compatibilityKey(a.compatibility).localeCompare(compatibilityKey(b.compatibility)));
+  return{priors,rejected};
+}
+export interface ResolvedOperationalShadowPrior{prior:OperationalShadowPrior;status:'insufficient_samples'|'shadow_candidate'|'invalidated'|'replay_gap';ageWeight:number;effectiveSampleCount:number}
+export function resolveOperationalShadowPrior(input:{prior:OperationalShadowPrior;compatibility:Readonly<Record<OperationalCompatibilityDimension,string>>;retainedEvidenceRefs:ReadonlySet<string>;asOf:string}):ResolvedOperationalShadowPrior{
+  const target=OPERATIONAL_TARGET_DEFINITIONS[input.prior.targetId];for(const d of target.compatibilityDimensions)if(input.prior.compatibility[d]!==input.compatibility[d])return{prior:input.prior,status:'invalidated',ageWeight:0,effectiveSampleCount:0};
+  if(input.prior.supportEvidenceRefs.some(r=>!input.retainedEvidenceRefs.has(r)))return{prior:input.prior,status:'replay_gap',ageWeight:0,effectiveSampleCount:0};
+  const now=validInstant(input.asOf),observed=validInstant(input.prior.latestObservedAt);if(now===undefined||observed===undefined)throw new Error('OPERATIONAL_PRIOR_INVALID_RESOLUTION_TIME');const metric=OPERATIONAL_METRIC_DEFINITIONS[input.prior.metricId];const age=Math.max(0,now-observed);const ageWeight=Math.pow(.5,age/metric.decayHalfLifeMs);return{prior:input.prior,status:input.prior.readiness,ageWeight,effectiveSampleCount:input.prior.sampleCount*ageWeight};
+}
+export function rankOperationalShadowPriors(input:{priors:readonly OperationalShadowPrior[];compatibility:Readonly<Record<OperationalCompatibilityDimension,string>>;retainedEvidenceRefs:ReadonlySet<string>;asOf:string}){return input.priors.map(prior=>resolveOperationalShadowPrior({prior,compatibility:input.compatibility,retainedEvidenceRefs:input.retainedEvidenceRefs,asOf:input.asOf})).filter(x=>x.status==='shadow_candidate').sort((a,b)=>{const m=OPERATIONAL_METRIC_DEFINITIONS[a.prior.metricId];const d=m.direction==='lower_is_better'?a.prior.estimate-b.prior.estimate:b.prior.estimate-a.prior.estimate;return d||a.prior.actionId.localeCompare(b.prior.actionId)})}
+export function replayOperationalPriors(input:{observations:readonly OperationalObservation[];asOf:string}){return reduceOperationalObservations(input)}

package/packages/kernel/memory/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

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

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

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,27 @@
+/** Stable Scheduler lifecycle façade. Persistence remains internal to the Scheduler module. */
+export {
+  applyScheduleDedupe,
+  buildScheduleDedupeReport,
+  cleanupScheduleOccurrenceHistory,
+  createSchedule,
+  deleteSchedule,
+  getOccurrence,
+  getSchedule,
+  getScheduleDecision,
+  listActiveOccurrences,
+  listOccurrences,
+  reclaimStaleCreatedOccurrences,
+  listSchedules,
+  recordScheduleOccurrenceHandoff,
+  saveOccurrence,
+  saveSchedule,
+  saveScheduleDecision,
+  updateSchedule,
+  getScheduleDefinition,
+  getScheduleRuntimeState,
+  type ScheduleHistoryCleanupResult,
+  type ScheduleDedupeApplyResult,
+  type ScheduleDedupeReport,
+  type ScheduleDuplicateGroup,
+  type ScheduleDuplicateMember,
+} from '../infrastructure/schedule-store';