@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -0,0 +1,15 @@
+/** 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/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/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

@@ -0,0 +1,148 @@
+import {
+  appendWorkEvidence as persistWorkEvidence,
+  getWorkContract as readWorkContract,
+  recordWorkCompletionReceipt as persistWorkCompletionReceipt,
+  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';
+
+export interface CompleteRemoteEffectProcessInput {
+  processId: string;
+  actionId: string;
+  requestId: string;
+  semanticKey: string;
+  resultDigest: string;
+  recordedAt: string;
+}
+
+/**
+ * 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.
+ */
+export function completeRemoteEffectWorkFromProcessReceipt(
+  options: WorkContractStoreOptions,
+  workId: string,
+  input: CompleteRemoteEffectProcessInput,
+): WorkContract {
+  const work = readWorkContract(options, workId);
+  if (!work) throw new Error(`WORK_REMOTE_EFFECT_PROCESS_BINDING_NOT_FOUND: ${workId}`);
+  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.evidenceRefs.some((candidate) => candidate.evidenceId === input.processId)) {
+    persistWorkEvidence(options, workId, {
+      evidenceId: input.processId,
+      title: 'trusted repository remote effect completed',
+      summary: `Trusted Work-attributed git push completed with durable Process ${input.processId}.`,
+      detailLevel: 'summary',
+    });
+  }
+  return persistWorkCompletionReceipt(
+    options,
+    workId,
+    {
+      schemaVersion: 1,
+      receiptId: input.processId,
+      source: 'remote_effect',
+      workId,
+      authority: 'repository_process',
+      actionId: input.actionId,
+      requestId: input.requestId,
+      semanticKey: input.semanticKey,
+      resultDigest: input.resultDigest,
+      processId: input.processId,
+      recordedAt: input.recordedAt,
+    },
+    'completed_remote',
+    'remote_effect',
+  );
+}
+
+/**
+ * Canonical Work application boundary.
+ *
+ * Domain transition/review rules live in ../domain. Durable storage lives in
+ * ../infrastructure. Runtime/Gateway/Controller callers consume this module (or
+ * ../api) instead of importing persistence implementation directly.
+ */
+export {
+  workContractRoot,
+  workContractStorePath,
+  emptyWorkContractStore,
+  readWorkContractStore,
+  writeWorkContractStore,
+  createWorkContract,
+  getWorkContractByRequestId,
+  acceptSubmittedWorkContract,
+  listWorkContracts,
+  readActiveWorkCandidates,
+  initializeWorkCandidateIndex,
+  isCurrentWorkContract,
+  supersedeWorkContract,
+  getWorkContract,
+  summarizeWorkContract,
+  updateWorkContract,
+  promoteWorkToRepositoryChange,
+  recordWorkEvidenceState,
+  activateWorkContract,
+  failWorkContract,
+  cancelWorkContract,
+  resumeRetainedCancelledWorkContract,
+  recordWorkScopeEvidence,
+  transitionWorkContractPhase,
+  requestWorkImplementationReview,
+  recordWorkImplementationReview,
+  recordContentEquivalentCommitAuthorityTransfer,
+  reconcileApprovedWorkImplementationReviewProjection,
+  appendWorkEvidence,
+  appendWorkHandoffRef,
+  appendVerificationRecord,
+  recordWorkCompletionReceipt,
+  canonicalizeWorkContractForAuthority,
+} from '../infrastructure/work-contract-store';
+export type {
+  CreateWorkContractInput,
+  ListWorkContractOptions,
+  InvalidActiveWorkCandidate,
+  ActiveWorkCandidateSnapshot,
+  SupersedeWorkContractInput,
+  WorkContractSummary,
+  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);
+}

package/packages/kernel/work/domain/admission-policy.ts

@@ -0,0 +1,34 @@
+export interface WorkAdmissionPolicy {
+  schemaVersion: 1;
+  mode: 'normal' | 'exclusive_work' | 'convergence';
+  allowedWorkId?: string;
+  allowReadOnlyDiagnostics: true;
+  reason?: string;
+  activatedAt?: string;
+  updatedAt: string;
+}
+
+export const WORK_ADMISSION_POLICY_NAMESPACE = 'runtime_policy';
+export const WORK_ADMISSION_POLICY_SCOPE = 'global';
+export const WORK_ADMISSION_POLICY_KEY = 'work_admission';
+
+export function normalWorkAdmissionPolicy(now = new Date().toISOString()): WorkAdmissionPolicy {
+  return { schemaVersion: 1, mode: 'normal', allowReadOnlyDiagnostics: true, updatedAt: now };
+}
+
+export function assertWorkAdmissionPolicyAllows(
+  policy: WorkAdmissionPolicy,
+  input: { operation: 'create' | 'continue' | 'maintenance'; workId?: string },
+): WorkAdmissionPolicy {
+  if (policy.mode === 'normal' || input.operation === 'maintenance') return policy;
+  if (policy.mode === 'convergence') {
+    if (input.operation !== 'create') return policy;
+    throw new Error('WORK_ADMISSION_BLOCKED:CONVERGENCE:operation=create');
+  }
+  if (input.workId?.trim() === policy.allowedWorkId) return policy;
+  throw new Error(`WORK_ADMISSION_BLOCKED:P0_EXCLUSIVE_WORK:operation=${input.operation}:allowed=${policy.allowedWorkId ?? 'none'}`);
+}
+
+export function schedulerDispatchPolicyAllowed(policy: WorkAdmissionPolicy): boolean {
+  return policy.mode !== 'exclusive_work';
+}

package/packages/kernel/work/domain/check-receipt.ts

@@ -0,0 +1,43 @@
+export type ProcessCheckReceiptStatus = 'passed' | 'failed' | 'timed_out' | 'cancelled';
+export type ProcessCheckReceiptRuntimeStatus = 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+
+/**
+ * Stable, persistence-safe evidence contract shared by Edit Sessions, Work and Tasks.
+ * It deliberately contains no execution-runtime implementation types.
+ */
+export interface ProcessCheckReceiptEvidence {
+  schemaVersion: 1;
+  receiptId: string;
+  resultDigest: string;
+  repoId: string;
+  checkoutId?: string;
+  workId?: string;
+  executionSessionId?: string;
+  editSessionId?: string;
+  editRevision?: number;
+  issueId?: string;
+  taskId?: string;
+  checkId: string;
+  requestId?: string;
+  processId: string;
+  commandId?: string;
+  /** Physical checkout that executed the Check; differs from checkoutId on safe cross-checkout reuse. */
+  sourceCheckoutId?: string;
+  /** Existing controller-check cache identity proving content/definition/environment equivalence. */
+  checkCacheKey?: string;
+  checkRevision?: string;
+  checkDefinitionDigest?: string;
+  checkEnvironmentFingerprint?: string;
+  /** True when this consumer is bound to a physical Process originally launched by another consumer/checkout. */
+  reusedExecution?: boolean;
+  status: ProcessCheckReceiptStatus;
+  runtimeStatus: ProcessCheckReceiptRuntimeStatus;
+  ok: boolean;
+  exitCode?: number;
+  timedOut: boolean;
+  cancelled: boolean;
+  artifactPath: string;
+  summary: string;
+  startedAt: string;
+  finishedAt: string;
+}

package/packages/kernel/work/domain/context-closure-receipt.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'crypto';
+import type { ContextClosureReceipt } from './engineering-contracts';
+
+export function contextClosureReceiptIdentity(value: ContextClosureReceipt): string {
+  const unique = (values: string[], limit: number): string[] => {
+    const out = [...new Set(values.map((entry) => entry.trim()).filter(Boolean))];
+    if (out.length > limit) throw new Error('CONTEXT_CLOSURE_RECEIPT_BOUNDS_INVALID');
+    return out;
+  };
+  const core = {
+    sourceRevision: value.sourceRevision.trim(),
+    projectContractDigest: value.projectContract?.contentDigest ?? null,
+    currentPaths: unique(value.sourceEvidence.currentPaths, 48),
+    testPaths: unique(value.sourceEvidence.testPaths, 24),
+    languages: unique(value.detected.languages, 16).sort(),
+    platforms: unique(value.detected.platforms, 16).sort(),
+    skillIds: value.skills.resolved.map((skill) => `${skill.id.trim()}@${skill.version?.trim() ?? ''}`),
+    semanticProviders: value.semanticTools.providers.map((provider) => `${provider.providerId.trim()}:${provider.status}`),
+    reasonCodes: unique(value.readiness.reasonCodes, 80),
+  };
+  return `context_closure_${createHash('sha256').update(JSON.stringify(core)).digest('hex').slice(0, 32)}`;
+}
+
+export function validateContextClosureReceipt(value: ContextClosureReceipt): ContextClosureReceipt {
+  if (value.schemaVersion !== 1) throw new Error('CONTEXT_CLOSURE_RECEIPT_SCHEMA_INVALID');
+  if (!value.sourceRevision?.trim()) throw new Error('CONTEXT_CLOSURE_SOURCE_REQUIRED');
+  if (!Number.isFinite(Date.parse(value.generatedAt))) throw new Error('CONTEXT_CLOSURE_GENERATED_AT_INVALID');
+  if (value.provenance?.source !== 'rh_context' || !Number.isFinite(Date.parse(value.provenance.contextGeneratedAt))) throw new Error('CONTEXT_CLOSURE_PROVENANCE_INVALID');
+  if (!['ready', 'degraded', 'insufficient'].includes(value.readiness.status)) throw new Error('CONTEXT_CLOSURE_READINESS_INVALID');
+  if (value.receiptId !== contextClosureReceiptIdentity(value)) throw new Error('CONTEXT_CLOSURE_RECEIPT_ID_INVALID');
+  return value;
+}

package/packages/kernel/work/domain/engineering-contracts.ts

@@ -0,0 +1,157 @@
+import type {
+  DesignDecisionContractReceipt,
+  EngineeringBlockerDispositionReceipt,
+  EngineeringComplexityBudget,
+  EngineeringMutationClass,
+  IndependentCritiqueReceipt,
+  ProductDoDReceipt,
+} from './engineering-design';
+
+export const ENGINEERING_WORK_PROFILE_VERSION = 'engineering-work-profile-v1' as const;
+export const ENGINEERING_RISK_CLASSES = ['low', 'normal', 'high', 'critical'] as const;
+export type EngineeringRiskClass = (typeof ENGINEERING_RISK_CLASSES)[number];
+export const ENGINEERING_EVIDENCE_KINDS = [
+  'project_contract',
+  'context_closure',
+  'product_dod',
+  'design_decision',
+  'independent_critique',
+  'semantic_tools',
+  'focused_validation',
+  'real_journey',
+  'fresh_review',
+] as const;
+export type EngineeringEvidenceKind = (typeof ENGINEERING_EVIDENCE_KINDS)[number];
+export type EngineeringEvidenceRequirement = 'required' | 'conditional' | 'optional';
+
+/** Exact source-bound reference persisted on Work; the project file remains authority. */
+export interface ProjectEngineeringContractReceipt {
+  schemaVersion: 1;
+  contractPath: string;
+  projectId: string;
+  contractId: string;
+  contractVersion: string;
+  sourceRevision: string;
+  contentDigest: string;
+  provenance: {
+    source: 'repository';
+    loadedAt: string;
+  };
+}
+
+export interface EngineeringAdmissionEvidence {
+  projectContractReceipt?: ProjectEngineeringContractReceipt;
+  /** @deprecated Legacy audit-only id; does not satisfy enforced admission. */
+  contextClosureReceiptId?: string;
+  contextClosureReceipt?: ContextClosureReceipt;
+  /** @deprecated Legacy audit-only id; does not satisfy enforced admission. */
+  productDodReceiptId?: string;
+  /** @deprecated Legacy audit-only id; does not satisfy enforced admission. */
+  designDecisionReceiptId?: string;
+  /** @deprecated Legacy audit-only id; does not satisfy enforced admission. */
+  independentCritiqueReceiptId?: string;
+  productDodReceipt?: ProductDoDReceipt;
+  designDecisionReceipt?: DesignDecisionContractReceipt;
+  independentCritiqueReceipt?: IndependentCritiqueReceipt;
+  semanticToolReceiptIds?: string[];
+  validationReceiptIds?: string[];
+  journeyReceiptIds?: string[];
+  freshReviewReceiptId?: string;
+  conditions?: {
+    semanticToolsRequired?: boolean;
+    realJourneyRequired?: boolean;
+  };
+}
+
+export interface EngineeringContextReceipt {
+  schemaVersion: 1;
+  profileVersion: typeof ENGINEERING_WORK_PROFILE_VERSION;
+  riskClass: EngineeringRiskClass;
+  sourceIdentity: { kind: 'revision'; revision: string } | { kind: 'unborn' } | { kind: 'unknown' };
+  projectContractReceipt?: ProjectEngineeringContractReceipt;
+  evidence: {
+    contextClosureReceiptId?: string;
+    contextClosureReceipt?: ContextClosureReceipt;
+    productDodReceiptId?: string;
+    designDecisionReceiptId?: string;
+    independentCritiqueReceiptId?: string;
+    productDodReceipt?: ProductDoDReceipt;
+    designDecisionReceipt?: DesignDecisionContractReceipt;
+    independentCritiqueReceipt?: IndependentCritiqueReceipt;
+    semanticToolReceiptIds: string[];
+    validationReceiptIds: string[];
+    journeyReceiptIds: string[];
+    freshReviewReceiptId?: string;
+  };
+  conditions: {
+    semanticToolsRequired: boolean;
+    realJourneyRequired: boolean;
+  };
+  semanticScope?: { keys: string[]; mutationClass: EngineeringMutationClass };
+  complexityBudget?: EngineeringComplexityBudget;
+  designState?: 'ready' | 'revisit_required';
+  blockerDispositions?: EngineeringBlockerDispositionReceipt[];
+  missingAdmissionEvidence: EngineeringEvidenceKind[];
+  missingCompletionEvidence: EngineeringEvidenceKind[];
+  recordedAt: string;
+}
+
+
+export type ContextClosureReadinessStatus = 'ready' | 'degraded' | 'insufficient';
+export type ContextClosureSkillStatus = 'ready' | 'degraded' | 'unavailable' | 'not_required';
+export type ContextClosureSemanticStatus = 'ready' | 'degraded' | 'unavailable' | 'not_required';
+
+export interface ContextClosureSkillResolution {
+  id: string;
+  version?: string;
+  source: 'project_contract';
+  matchedKinds: string[];
+}
+
+export interface ContextClosureSemanticToolResolution {
+  providerId: string;
+  languages: string[];
+  status: 'ready' | 'registered' | 'degraded' | 'unavailable';
+  evidenceCount: number;
+}
+
+/** Exact-source, bounded Context Closure evidence. It is derived from source/runtime facts and is not a new persistence authority. */
+export interface ContextClosureReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  sourceRevision: string;
+  generatedAt: string;
+  contextPackSchemaVersion: number;
+  repository: {
+    branch: string | null;
+    dirty: boolean;
+    workId?: string;
+    activeWorkIds: string[];
+  };
+  projectContract?: ProjectEngineeringContractReceipt;
+  projectContractStatus: 'ready' | 'missing';
+  guidance: { status: 'none' | 'ready' | 'degraded'; paths: string[] };
+  detected: { languages: string[]; platforms: string[] };
+  skills: {
+    status: ContextClosureSkillStatus;
+    requiredKinds: string[];
+    resolved: ContextClosureSkillResolution[];
+    unresolvedKinds: string[];
+  };
+  semanticTools: {
+    required: boolean;
+    status: ContextClosureSemanticStatus;
+    providers: ContextClosureSemanticToolResolution[];
+    reasonCodes: string[];
+    compilerEvidenceRequired: boolean;
+  };
+  sourceEvidence: {
+    currentPaths: string[];
+    testPaths: string[];
+    recentChanges: Array<{ revision: string; committedAt: string; summary: string }>;
+    rawSourceStatus: 'current' | 'partial' | 'unavailable';
+    structuralStatus: 'disabled' | 'ready' | 'stale' | 'unavailable' | 'degraded';
+  };
+  readiness: { status: ContextClosureReadinessStatus; reasonCodes: string[] };
+  provenance: { source: 'rh_context'; contextGeneratedAt: string };
+}