@moretea-labs/forge 1.7.2 → 1.8.0

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/progression/api/index.ts

@@ -0,0 +1,2 @@
+export * from '../domain/types';
+export * from '../application/projector';

package/packages/kernel/progression/application/projector.ts

@@ -0,0 +1,211 @@
+import { createHash } from 'crypto';
+import type {
+  AutonomousGoalProgressionAction,
+  AutonomousGoalProgressionDecision,
+  AutonomousGoalProgressionReason,
+  AutonomousGoalProgressionSnapshot,
+  ProgressionControllerRoundSnapshot,
+  ProgressionPlanStepSnapshot,
+  ProgressionWorkSnapshot,
+} from '../domain/types';
+
+const EXECUTABLE_PLAN_STATUSES = new Set(['approved', 'executing', 'verifying', 'ready_to_finalize']);
+const ACTIVE_WORK_STATUSES = new Set(['open', 'running', 'ready']);
+const IN_FLIGHT_ROUND_STATUSES = new Set(['pending_release', 'dispatching', 'dispatched', 'claimed', 'waiting']);
+
+function stableSnapshot(snapshot: AutonomousGoalProgressionSnapshot): unknown {
+  return {
+    requirement: snapshot.requirement,
+    plan: {
+      planId: snapshot.plan.planId,
+      requirementId: snapshot.plan.requirementId,
+      sourceRevision: snapshot.plan.sourceRevision,
+      status: snapshot.plan.status,
+      steps: snapshot.plan.steps.map((step) => ({
+        id: step.id,
+        dependencies: [...step.dependencies],
+        status: step.status,
+        workId: step.workId,
+      })),
+    },
+    currentSourceRevision: snapshot.currentSourceRevision,
+    works: [...snapshot.works]
+      .map((work) => ({ ...work }))
+      .sort((left, right) => left.workId.localeCompare(right.workId)),
+    controllerRounds: [...(snapshot.controllerRounds ?? [])]
+      .map((round) => ({ ...round }))
+      .sort((left, right) => left.originWorkId.localeCompare(right.originWorkId) || left.roundCount - right.roundCount),
+    schedules: [...(snapshot.schedules ?? [])]
+      .map((schedule) => ({ ...schedule }))
+      .sort((left, right) => left.scheduleId.localeCompare(right.scheduleId)),
+  };
+}
+
+function decision(
+  snapshot: AutonomousGoalProgressionSnapshot,
+  kind: AutonomousGoalProgressionAction,
+  reasonCode: AutonomousGoalProgressionReason,
+  detail: Pick<AutonomousGoalProgressionDecision, 'planStepId' | 'workId' | 'dependencyStepIds'> = {},
+): AutonomousGoalProgressionDecision {
+  const identityInput = JSON.stringify({
+    snapshot: stableSnapshot(snapshot),
+    decision: { kind, reasonCode, ...detail },
+  });
+  return {
+    schemaVersion: 1,
+    kind,
+    reasonCode,
+    requirementId: snapshot.requirement.requirementId,
+    planId: snapshot.plan.planId,
+    ...detail,
+    idempotencyKey: `goal-progression:v1:${createHash('sha256').update(identityInput).digest('hex').slice(0, 32)}`,
+  };
+}
+
+function latestRoundForWork(
+  rounds: readonly ProgressionControllerRoundSnapshot[] | undefined,
+  workId: string,
+): ProgressionControllerRoundSnapshot | undefined {
+  return (rounds ?? [])
+    .filter((round) => round.originWorkId === workId)
+    .reduce<ProgressionControllerRoundSnapshot | undefined>(
+      (latest, round) => !latest || round.roundCount > latest.roundCount ? round : latest,
+      undefined,
+    );
+}
+
+function boundWork(
+  snapshot: AutonomousGoalProgressionSnapshot,
+  step: ProgressionPlanStepSnapshot,
+): ProgressionWorkSnapshot | undefined {
+  if (!step.workId) return undefined;
+  return snapshot.works.find((work) => work.workId === step.workId);
+}
+
+function invalidDependency(
+  steps: readonly ProgressionPlanStepSnapshot[],
+): { stepId: string; dependencyIds: string[] } | undefined {
+  const ids = new Set(steps.map((step) => step.id));
+  for (const step of steps) {
+    const missing = step.dependencies.filter((dependencyId) => dependencyId === step.id || !ids.has(dependencyId));
+    if (missing.length > 0) return { stepId: step.id, dependencyIds: [...missing] };
+  }
+  return undefined;
+}
+
+/**
+ * Pure Goal-level progression projection. It never writes lifecycle state and
+ * never equates machine delivery with Controller semantic acceptance.
+ */
+export function projectAutonomousGoalProgression(
+  snapshot: AutonomousGoalProgressionSnapshot,
+): AutonomousGoalProgressionDecision {
+  const { requirement, plan } = snapshot;
+
+  if (requirement.state === 'done') return decision(snapshot, 'goal_complete', 'REQUIREMENT_ALREADY_DONE');
+  if (requirement.state === 'waiting_for_user') return decision(snapshot, 'wait_for_user', 'REQUIREMENT_WAITING_FOR_USER');
+  if (requirement.state === 'cancelled') return decision(snapshot, 'blocked_invalid_state', 'REQUIREMENT_CANCELLED');
+  if (plan.requirementId && plan.requirementId !== requirement.requirementId) {
+    return decision(snapshot, 'blocked_invalid_state', 'PLAN_REQUIREMENT_MISMATCH');
+  }
+
+  // A terminal Work may legitimately advance repository source A -> B before
+  // Controller semantic acceptance advances Plan.sourceRevision to B. Only that
+  // exact Work completion target may cross the drift boundary. Any later C is
+  // unrelated drift and still requires explicit re-evaluation.
+  const validatingDelivery = plan.steps
+    .filter((step) => step.status === 'executing' || step.status === 'validating')
+    .map((step) => ({ step, work: boundWork(snapshot, step) }))
+    .find(({ work }) => work?.status === 'completed'
+      && work.baseRevision === plan.sourceRevision
+      && work.completionTargetRevision === snapshot.currentSourceRevision);
+  const expectedDeliveryAdvance = Boolean(validatingDelivery && plan.sourceRevision !== snapshot.currentSourceRevision);
+  if (plan.sourceRevision !== snapshot.currentSourceRevision && !expectedDeliveryAdvance) {
+    return decision(snapshot, 'request_replan', 'PLAN_SOURCE_DRIFT');
+  }
+  if (plan.status === 'replanning' || plan.status === 'invalidated_by_drift') return decision(snapshot, 'request_replan', 'PLAN_REPLAN_REQUIRED');
+  if (plan.status === 'finalized') {
+    if (!plan.steps.every((step) => step.status === 'completed')) {
+      return decision(snapshot, 'blocked_invalid_state', 'PLAN_COMPLETION_STATE_CONTRADICTION');
+    }
+    return decision(snapshot, 'request_requirement_acceptance', 'PLAN_FINALIZED_REQUIRES_REQUIREMENT_ACCEPTANCE');
+  }
+  if (plan.status === 'superseded' || plan.status === 'cancelled') return decision(snapshot, 'blocked_invalid_state', 'PLAN_TERMINAL_INVALID');
+  if (!EXECUTABLE_PLAN_STATUSES.has(plan.status)) return decision(snapshot, 'blocked_invalid_state', 'PLAN_NOT_EXECUTABLE');
+  if (plan.steps.length === 0) return decision(snapshot, 'blocked_invalid_state', 'PLAN_EMPTY');
+
+  const ids = new Set(plan.steps.map((step) => step.id));
+  if (ids.size !== plan.steps.length) return decision(snapshot, 'blocked_invalid_state', 'PLAN_STEP_ID_DUPLICATE');
+  const badDependency = invalidDependency(plan.steps);
+  if (badDependency) {
+    return decision(snapshot, 'blocked_invalid_state', 'PLAN_DEPENDENCY_INVALID', {
+      planStepId: badDependency.stepId,
+      dependencyStepIds: badDependency.dependencyIds,
+    });
+  }
+
+  for (const step of plan.steps) {
+    if (step.status !== 'executing' && step.status !== 'validating') continue;
+    const work = boundWork(snapshot, step);
+    if (!work) return decision(snapshot, 'blocked_invalid_state', 'PLAN_STEP_WORK_MISSING', { planStepId: step.id, workId: step.workId });
+    if (work.planId !== plan.planId || work.planStepId !== step.id || (work.requirementId && work.requirementId !== requirement.requirementId)) {
+      return decision(snapshot, 'blocked_invalid_state', 'WORK_IDENTITY_MISMATCH', { planStepId: step.id, workId: work.workId });
+    }
+    if ((work.status === 'completed' || work.status === 'failed' || work.status === 'cancelled') && step.status === 'executing') {
+      return decision(snapshot, 'blocked_invalid_state', 'PLAN_STEP_TERMINAL_WORK_RECONCILIATION_REQUIRED', { planStepId: step.id, workId: work.workId });
+    }
+    if (work.status === 'failed' || work.status === 'cancelled') {
+      return decision(snapshot, 'request_replan', 'WORK_FAILED_REPLAN', { planStepId: step.id, workId: work.workId });
+    }
+    if (work.status === 'blocked') return decision(snapshot, 'wait_current_work', 'WORK_BLOCKED', { planStepId: step.id, workId: work.workId });
+    if (work.status === 'completed') {
+      return decision(snapshot, 'request_controller_acceptance', 'MACHINE_COMPLETE_REQUIRES_CONTROLLER_ACCEPTANCE', {
+        planStepId: step.id,
+        workId: work.workId,
+      });
+    }
+    if (ACTIVE_WORK_STATUSES.has(work.status)) {
+      const round = latestRoundForWork(snapshot.controllerRounds, work.workId);
+      if (round?.status === 'waiting_for_user') {
+        return decision(snapshot, 'wait_for_user', 'CONTROLLER_ROUND_WAITING_FOR_USER', { planStepId: step.id, workId: work.workId });
+      }
+      if (round?.status === 'goal_complete') {
+        return decision(snapshot, 'blocked_invalid_state', 'CONTROLLER_ROUND_TERMINAL_CONTRADICTION', { planStepId: step.id, workId: work.workId });
+      }
+      if (round && (IN_FLIGHT_ROUND_STATUSES.has(round.status) || round.status === 'blocked' || round.status === 'failed')) {
+        return decision(snapshot, 'wait_current_work', 'CONTROLLER_ROUND_IN_FLIGHT', { planStepId: step.id, workId: work.workId });
+      }
+      return decision(snapshot, 'continue_current_work', 'WORK_READY_TO_CONTINUE', { planStepId: step.id, workId: work.workId });
+    }
+  }
+
+  if (plan.steps.every((step) => step.status === 'completed')) {
+    return decision(snapshot, 'blocked_invalid_state', 'PLAN_COMPLETION_STATE_CONTRADICTION');
+  }
+
+  const completedIds = new Set(plan.steps.filter((step) => step.status === 'completed').map((step) => step.id));
+  const dependencyReady = plan.steps.filter((step) =>
+    step.status !== 'completed'
+    && step.dependencies.every((dependencyId) => completedIds.has(dependencyId)),
+  );
+  const explicitReady = dependencyReady.filter((step) => step.status === 'ready');
+
+  if (explicitReady.length === 1) {
+    return decision(snapshot, 'start_next_plan_step', 'NEXT_PLAN_STEP_READY', { planStepId: explicitReady[0].id });
+  }
+  if (explicitReady.length > 1) {
+    return decision(snapshot, 'blocked_invalid_state', 'MULTIPLE_READY_PLAN_STEPS', {
+      dependencyStepIds: explicitReady.map((step) => step.id),
+    });
+  }
+  const readinessNotProjected = dependencyReady.find((step) => step.status === 'pending');
+  if (readinessNotProjected) {
+    return decision(snapshot, 'blocked_invalid_state', 'PLAN_STEP_READINESS_NOT_PROJECTED', { planStepId: readinessNotProjected.id });
+  }
+
+  const blocked = plan.steps.find((step) => step.status !== 'completed');
+  return decision(snapshot, 'wait_dependency', 'PLAN_DEPENDENCY_WAIT', {
+    planStepId: blocked?.id,
+    dependencyStepIds: blocked?.dependencies.filter((dependencyId) => !completedIds.has(dependencyId)) ?? [],
+  });
+}

package/packages/kernel/progression/domain/types.ts

@@ -0,0 +1,116 @@
+import type { ControllerRoundRelayStatus } from '../../controller/api/index';
+import type { RequirementState, PlanContractStatus, PlanStepStatus } from '../../goal/api/index';
+import type { RepositorySchedule } from '../../scheduler/api/index';
+import type { WorkContractStatus } from '../../work/api/index';
+
+/**
+ * Read-only lifecycle facts consumed by the Goal Progression projector.
+ * These are projections of existing authorities, never a persistence schema.
+ */
+export interface ProgressionRequirementSnapshot {
+  requirementId: string;
+  state: RequirementState;
+  revision: number;
+}
+
+export interface ProgressionPlanStepSnapshot {
+  id: string;
+  dependencies: readonly string[];
+  status: PlanStepStatus;
+  workId?: string;
+}
+
+export interface ProgressionPlanSnapshot {
+  planId: string;
+  requirementId?: string;
+  sourceRevision: string;
+  status: PlanContractStatus;
+  steps: readonly ProgressionPlanStepSnapshot[];
+}
+
+export interface ProgressionWorkSnapshot {
+  workId: string;
+  requirementId?: string;
+  planId?: string;
+  planStepId?: string;
+  status: WorkContractStatus;
+  /** Exact source revision from which this Work execution started. */
+  baseRevision?: string;
+  /** Exact integrated target revision from the canonical Work completion receipt, when delivery changed source. */
+  completionTargetRevision?: string;
+}
+
+export type ProgressionScheduleSnapshot = Pick<RepositorySchedule, 'scheduleId' | 'revision' | 'enabled' | 'nextEligibleAt' | 'pausedReason'>;
+
+export interface ProgressionControllerRoundSnapshot {
+  originWorkId: string;
+  status: ControllerRoundRelayStatus;
+  roundCount: number;
+}
+
+export interface AutonomousGoalProgressionSnapshot {
+  requirement: ProgressionRequirementSnapshot;
+  plan: ProgressionPlanSnapshot;
+  currentSourceRevision: string;
+  works: readonly ProgressionWorkSnapshot[];
+  controllerRounds?: readonly ProgressionControllerRoundSnapshot[];
+  schedules?: readonly ProgressionScheduleSnapshot[];
+}
+
+export const AUTONOMOUS_GOAL_PROGRESSION_ACTIONS = [
+  'continue_current_work',
+  'wait_current_work',
+  'request_controller_acceptance',
+  'request_requirement_acceptance',
+  'start_next_plan_step',
+  'wait_dependency',
+  'request_replan',
+  'wait_for_user',
+  'goal_complete',
+  'blocked_invalid_state',
+] as const;
+export type AutonomousGoalProgressionAction = (typeof AUTONOMOUS_GOAL_PROGRESSION_ACTIONS)[number];
+
+export const AUTONOMOUS_GOAL_PROGRESSION_REASONS = [
+  'REQUIREMENT_ALREADY_DONE',
+  'REQUIREMENT_WAITING_FOR_USER',
+  'REQUIREMENT_CANCELLED',
+  'PLAN_REQUIREMENT_MISMATCH',
+  'PLAN_SOURCE_DRIFT',
+  'PLAN_REPLAN_REQUIRED',
+  'PLAN_TERMINAL_INVALID',
+  'PLAN_NOT_EXECUTABLE',
+  'PLAN_EMPTY',
+  'PLAN_STEP_ID_DUPLICATE',
+  'PLAN_DEPENDENCY_INVALID',
+  'PLAN_STEP_WORK_MISSING',
+  'WORK_IDENTITY_MISMATCH',
+  'PLAN_STEP_TERMINAL_WORK_RECONCILIATION_REQUIRED',
+  'WORK_FAILED_REPLAN',
+  'WORK_BLOCKED',
+  'CONTROLLER_ROUND_IN_FLIGHT',
+  'CONTROLLER_ROUND_WAITING_FOR_USER',
+  'CONTROLLER_ROUND_TERMINAL_CONTRADICTION',
+  'WORK_READY_TO_CONTINUE',
+  'MACHINE_COMPLETE_REQUIRES_CONTROLLER_ACCEPTANCE',
+  'PLAN_FINALIZED_REQUIRES_REQUIREMENT_ACCEPTANCE',
+  'PLAN_COMPLETION_STATE_CONTRADICTION',
+  'NEXT_PLAN_STEP_READY',
+  'PLAN_DEPENDENCY_WAIT',
+  'MULTIPLE_READY_PLAN_STEPS',
+  'PLAN_STEP_READINESS_NOT_PROJECTED',
+] as const;
+export type AutonomousGoalProgressionReason = (typeof AUTONOMOUS_GOAL_PROGRESSION_REASONS)[number];
+
+export interface AutonomousGoalProgressionDecision {
+  schemaVersion: 1;
+  kind: AutonomousGoalProgressionAction;
+  reasonCode: AutonomousGoalProgressionReason;
+  requirementId: string;
+  planId: string;
+  planStepId?: string;
+  workId?: string;
+  dependencyStepIds?: string[];
+  /** Stable replay identity derived only from the immutable input snapshot + decision. */
+  idempotencyKey: string;
+}

package/packages/kernel/progression/index.ts

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

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

@@ -0,0 +1,6 @@
+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';