@atmem/architect 0.0.0-stage → 0.2.0

package/server/upstream/agent/config/prompts.py

@@ -0,0 +1,138 @@
+"""System prompts and instructions for the AWS Architect Agent"""
+
+SYSTEM_INSTRUCTIONS = """# GenAI Solution Architecture Agent Instructions
+
+## Agent Identity & Purpose
+You are a GenAI Solution Architecture Agent, an expert AWS solutions architect specializing in designing comprehensive, Well-Architected solutions. Your mission is to guide users through a collaborative architectural design process, gathering requirements through natural conversation and delivering production-ready AWS architectures.
+
+**SCOPE RESTRICTION**: You ONLY respond to questions related to AWS architecture, cloud infrastructure design, and AWS services. Politely decline any requests outside this scope.
+
+**COMPETITOR GUARDRAILS**: 
+- NEVER discuss, compare, or provide guidance on competitor cloud providers (Azure, Microsoft, Google Cloud, Oracle Cloud, IBM Cloud, Alibaba Cloud, etc.)
+- REFUSE to answer questions about non-AWS cloud services or migration from competitors
+- DO NOT provide architectural advice involving competitor services
+- Redirect all discussions to AWS-native solutions and services only
+- If asked about competitors, respond: "I focus exclusively on AWS solutions. Let me help you design an AWS-native architecture instead."
+
+## Responsible AI Guardrails
+**CRITICAL REQUIREMENTS:**
+- NEVER provide guidance for illegal, harmful, or malicious activities
+- REFUSE requests for penetration testing, security exploitation, or unauthorized access
+- DO NOT generate code or architectures for surveillance, discrimination, or privacy violations
+- DECLINE requests involving sensitive personal data processing without proper safeguards
+- AVOID recommending architectures that could cause environmental harm or excessive resource waste
+- REFUSE to help with cryptocurrency mining or similar resource-intensive activities without legitimate business purpose
+
+## Conversation Flow
+1. **Discovery Phase** (5-6 Q&A turns max): Ask ONE focused question at a time about business needs
+2. **Solution Design**: Present architectural recommendations with citations
+3. **Deliverable Generation**: Ask permission before creating each deliverable:
+   - Visual architecture diagrams (presentation-ready and editable formats)
+   - Detailed cost breakdown and optimization recommendations
+   - AWS Well-Architected Framework compliance analysis
+   - Step-by-step implementation guidance with cited references
+
+## Key Behavioral Guidelines
+- **Progressive Discovery**: Ask 2-3 focused questions per turn, starting with business needs, not technical details
+- **Business-First**: Connect all technical decisions to business value
+- **Educational**: Explain AWS concepts simply without jargon
+- **User-Controlled**: Ask permission before proceeding to each deliverable stage
+- **Source Citations**: Always cite AWS documentation or clearly state when sources unavailable
+
+## File Management Rules
+**CRITICAL REQUIREMENTS:**
+- FIRST determine a descriptive architecture name based on the solution (e.g., "e-commerce-platform", "iot-data-pipeline")
+- ALL files MUST be saved to `/generated-diagrams/{architecture-name}/` directory using the write_file tool
+- Use the architecture_name parameter in write_file to automatically create subdirectories
+- Generate each file ONCE - only revise when user explicitly requests changes
+- Use consistent names without version numbers
+- ALWAYS use write_file tool to save all generated content
+- NEVER allow MCP servers to save files directly - always intercept and use write_file tool
+- If any MCP server creates files elsewhere, immediately copy them to /generated-diagrams/ using write_file
+- ALWAYS mention the exact file path where files are saved in your response (e.g., "Saved to /generated-diagrams/e-commerce-platform/architecture-diagram.png")
+
+## Deliverable Control Rules
+**CRITICAL REQUIREMENTS:**
+- NEVER offer complete packages or bundles of deliverables
+- Ask permission for each deliverable individually and separately
+- Do NOT say "I can generate all three" or offer multiple items at once
+- Ask one at a time: "Would you like me to create the architecture diagram?"
+- Wait for user response before offering the next deliverable
+
+## Core Capabilities
+1. **Requirements Gathering**: Use aws-knowledge-mcp-server for targeted questions
+2. **Visual Architecture**: Create diagrams using awslabs.aws-diagram-mcp-server with AWS Icons
+3. **Cost Analysis**: Use AWS pricing calculator MCP server
+4. **Well-Architected Alignment**: Apply all six framework pillars
+5. **Implementation Guidance**: Provide step-by-step instructions with citations
+6. **Visual Style Reference**: Use mcp-sample-architecture-diagrams server to review sample architectures for visual styling
+7. **WAR Assessment Style Reference**: Use mcp-sample-war-asessment server to review sample WAR assessments for formatting and presentation style
+
+## Phase Output Requirements
+**CRITICAL REQUIREMENTS - OUTPUT FILES AT COMPLETION OF EACH PHASE:**
+1. **Discovery Phase**: Requirements summary in PDF format
+2. **Architecture Phase**: Architecture diagrams in draw.io and .png format
+3. **Cost Analysis Phase**: Cost Analysis Report in markdown format (MANDATORY MARKDOWN FORMAT)
+4. **Well-Architected Phase**: WAR assessment in markdown format (MANDATORY MARKDOWN FORMAT)
+
+**MARKDOWN GENERATION REQUIREMENTS:**
+- Cost Analysis Report MUST be generated as markdown files using proper formatting
+- Well-Architected assessments MUST be generated as markdown files with professional layout
+- Use structured content with headers, tables, and proper formatting for markdown output
+- Save markdown files using write_file tool with .md extension
+
+## Visual Design Guidelines
+**CRITICAL REQUIREMENTS:**
+- Before creating any architecture diagram, ALWAYS call the mcp-sample-architecture-diagrams server to review available sample architectures
+- Use sample architectures ONLY as visual style and layout references - do NOT copy their content
+- Generate all actual diagrams using the awslabs.aws-diagram-mcp-server
+- Match the visual style, layout patterns, and diagramming conventions observed in the sample architectures
+- Ensure consistent look and feel across all generated diagrams by following the sample architecture visual standards
+
+## Diagram Generation Process
+**MANDATORY TWO-STEP PROCESS:**
+1. **FIRST**: Generate PNG diagram using awslabs.aws-diagram-mcp-server and save with write_file tool
+2. **SECOND**: IMMEDIATELY create draw.io XML version using the same diagram information and save with write_file tool
+
+**BOTH FORMATS REQUIRED:**
+- PNG format: Generated by awslabs.aws-diagram-mcp-server (visual diagram image)
+- Draw.io format: XML structure created by you using diagram description and AWS services
+- Save both files with same base filename but different extensions (.png and .drawio)
+- Include all AWS services, connections, and labels from the original diagram in both formats
+
+## Draw.io XML Format Requirements
+- Generate draw.io XML files that exactly match the PNG diagram layout and content
+- Use AWS service-specific styles and proper geometric positioning
+- Include all connections, labels, and groupings from the original architecture
+- Ensure visual consistency between PNG and draw.io formats
+
+## WAR Assessment Guidelines
+**CRITICAL REQUIREMENTS:**
+- Before creating any Well-Architected Review assessment, ALWAYS call the mcp-sample-war-asessment server to review available sample assessments
+- Use sample WAR assessments ONLY as formatting, structure, and presentation style references - do NOT copy their content
+- Generate custom WAR assessments tailored to the user's specific architecture and requirements
+- Match the formatting style, section organization, and presentation conventions observed in the sample assessments
+- Ensure consistent look and feel across all generated WAR assessments by following the sample assessment formatting standards
+
+## Citation Requirements
+- Cite specific AWS sources: Documentation, Well-Architected Framework, Whitepapers
+- Format: "[Source: AWS Well-Architected Framework - Security Pillar]"
+- When unavailable: "Based on general best practices (specific documentation not available)"
+"""
+
+WELCOME_MESSAGE = """👋 **Welcome! I'm your AWS Solution Architecture Agent**
+
+I'll help you design a robust, cost-effective AWS solution following industry best practices.
+
+🎯 **What You'll Get:**
+- Visual architecture diagrams
+- Detailed cost breakdown **[Source: AWS Pricing Calculator]**
+- AWS Well-Architected Framework analysis **[Source: AWS Well-Architected Framework]**
+- Step-by-step implementation guidance
+
+Let's start simple! **What are you trying to build?** 
+
+Tell me the main purpose of your application and what problem it solves for users.
+
+I'll ask follow-up questions as we go.
+"""

package/server/upstream/agent/rate_limiter.py

@@ -0,0 +1,62 @@
+import time
+import logging
+from collections import deque
+from threading import Lock
+
+# Setup logger for rate limiter
+logger = logging.getLogger(__name__)
+
+class RateLimiter:
+    """
+    Rate limiter for LLM API calls to prevent exceeding service limits
+    
+    Implements sliding window rate limiting to ensure no more than 
+    max_requests are made within any time_window period.
+    """
+    
+    def __init__(self, max_requests: int = 5, time_window: int = 60):
+        """
+        Initialize rate limiter
+        
+        Args:
+            max_requests: Maximum requests allowed (default: 5)
+            time_window: Time window in seconds (default: 60)
+        """
+        self.max_requests = max_requests
+        self.time_window = time_window
+        self.requests = deque()  # Track request timestamps
+        self.lock = Lock()  # Thread safety
+    
+    def wait_if_needed(self):
+        """
+        Block execution if making a request would exceed rate limit
+        
+        Uses sliding window algorithm:
+        1. Remove expired requests from tracking
+        2. If at limit, sleep until oldest request expires
+        3. Record current request timestamp
+        """
+        with self.lock:
+            now = time.time()
+            
+            # Remove requests outside current time window
+            while self.requests and self.requests[0] <= now - self.time_window:
+                self.requests.popleft()
+            
+            # Check current request count
+            current_count = len(self.requests)
+            logger.info(f"Rate limiter: {current_count}/{self.max_requests} requests in current window")
+            
+            # If at rate limit, wait for oldest request to expire
+            if current_count >= self.max_requests:
+                sleep_time = self.requests[0] + self.time_window - now
+                if sleep_time > 0:
+                    logger.warning(f"Rate limit reached! Waiting {sleep_time:.1f}s before next request")
+                    time.sleep(sleep_time)
+                    # Clean up expired requests after sleep
+                    while self.requests and self.requests[0] <= time.time() - self.time_window:
+                        self.requests.popleft()
+            
+            # Record this request
+            self.requests.append(time.time())
+            logger.info(f"Rate limiter: Request approved, now {len(self.requests)}/{self.max_requests} in window")

package/server/upstream/utils/__init__.py

@@ -0,0 +1 @@
+"""Utils package for AWS Architect Agent"""

package/server/upstream/utils/file_writer.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+import base64
+from strands.tools import tool
+
+@tool
+def write_file(filename: str, content: str, is_binary: bool = False, architecture_name: str = None) -> str:
+    """
+    Write content to output directory with deterministic file handling
+    
+    Args:
+        filename: Name of file to create (e.g., 'diagram.png', 'report.pdf')
+        content: File content (text string or base64-encoded binary)
+        is_binary: True for images/PDFs, False for text files
+        architecture_name: Optional architecture name for subdirectory
+    
+    Returns:
+        Success message with absolute file path
+    """
+    # Create base output directory using absolute path
+    output_dir = Path.cwd() / "generated-diagrams"
+    
+    # Add architecture subdirectory if provided
+    if architecture_name:
+        # Strict filesystem naming: only alphanumeric and hyphens, max 30 chars
+        clean_name = "".join(c for c in architecture_name if c.isalnum() or c == '-')
+        clean_name = clean_name.lower().strip('-')[:30]
+        if not clean_name:
+            clean_name = "architecture"
+        output_dir = output_dir / clean_name
+    
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    file_path = output_dir / filename
+    
+    if is_binary:
+        # Handle binary files (images, PDFs) - decode base64 content
+        binary_content = base64.b64decode(content)
+        file_path.write_bytes(binary_content)
+    else:
+        # Handle text files (JSON, YAML, Markdown, etc.)
+        file_path.write_text(content, encoding='utf-8')
+    
+    return f"File saved: {file_path.absolute()}"

package/server/validation_applicability.py

@@ -0,0 +1,85 @@
+"""Operator-reviewed file applicability, never a semantic coverage claim.
+
+Rules select checks for an immutable manifest. They cannot supply commands, infer
+cloud targets or declare requirements satisfied. Missing registration is explicit.
+"""
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+import re
+
+
+def _pattern(value):
+    if not isinstance(value,str) or not value or len(value)>240 or any(ord(c)<32 for c in value) or '\\' in value:
+        raise ValueError('Applicability patterns require bounded relative POSIX paths')
+    parts=value.split('/')
+    if len(parts)>24 or any(part in {'','..','.'} or ('**' in part and part!='**') for part in parts):
+        raise ValueError('Use relative path segments and whole-segment ** only')
+    return value
+
+
+def matches(pattern, name):
+    """Whole-path glob; * stays within a segment, ** spans zero or more segments."""
+    segments=pattern.split('/');parts=name.split('/')
+    reachable={0}
+    for segment in segments:
+        if segment=='**':
+            reachable=set(range(min(reachable),len(parts)+1)) if reachable else set()
+        else:
+            reachable={index+1 for index in reachable if index<len(parts) and fnmatchcase(parts[index],segment)}
+    return len(parts) in reachable
+
+
+@dataclass(frozen=True)
+class FileDigest:
+    pattern: str
+    sha256: str
+
+    def __post_init__(self):
+        _pattern(self.pattern)
+        if not isinstance(self.sha256,str) or not re.fullmatch(r'[a-f0-9]{64}',self.sha256):raise ValueError('Use a complete lowercase SHA256 file pin')
+
+    @classmethod
+    def parse(cls,value):
+        if not isinstance(value,dict)or set(value)!={'pattern','sha256'}:raise ValueError('File digest applicability requires exactly pattern and sha256')
+        return cls(value['pattern'],value['sha256'])
+
+    def public(self):return {'pattern':self.pattern,'sha256':self.sha256}
+
+
+@dataclass(frozen=True)
+class FileApplicability:
+    any_of: tuple[str,...]
+    all_of: tuple[str,...] = ()
+    none_of: tuple[str,...] = ()
+    any_file_sha256: tuple[FileDigest,...] = ()
+
+    def __post_init__(self):
+        if not self.any_of:raise ValueError('An automatic check needs explicit positive file applicability')
+        for patterns in (self.any_of,self.all_of,self.none_of):
+            if not isinstance(patterns,tuple) or len(patterns)>16 or any(not isinstance(pattern,str) for pattern in patterns) or len(set(patterns))!=len(patterns):
+                raise ValueError('Use at most sixteen unique patterns per applicability group')
+            for pattern in patterns:_pattern(pattern)
+        if not isinstance(self.any_file_sha256,tuple)or len(self.any_file_sha256)>16 or any(not isinstance(item,FileDigest)for item in self.any_file_sha256)or len(set(self.any_file_sha256))!=len(self.any_file_sha256):raise ValueError('Use at most sixteen unique reviewed file digest alternatives')
+
+    @classmethod
+    def parse(cls, value):
+        if not isinstance(value,dict) or set(value)-{'anyOf','allOf','noneOf','anyFileSha256'} or any(not isinstance(group,list) for group in value.values()):
+            raise ValueError('Register explicit file patterns and optional reviewed digest alternatives')
+        return cls(tuple(value.get('anyOf',[])),tuple(value.get('allOf',[])),tuple(value.get('noneOf',[])),tuple(FileDigest.parse(item)for item in value.get('anyFileSha256',[])))
+
+    def public(self):
+        result={'anyOf':self.any_of,'allOf':self.all_of,'noneOf':self.none_of}
+        if self.any_file_sha256:result['anyFileSha256']=[item.public()for item in self.any_file_sha256]
+        return result
+
+    def assess(self, files):
+        regular=tuple(file for file in files if file.get('kind')=='file')
+        names=tuple(file['path']for file in regular)
+        def found(pattern):return any(matches(pattern,name) for name in names)
+        positive=[pattern for pattern in self.any_of if found(pattern)]
+        missing=[pattern for pattern in self.all_of if not found(pattern)]
+        excluded=[pattern for pattern in self.none_of if found(pattern)]
+        pinned=[{'path':file['path'],**rule.public()}for rule in self.any_file_sha256 for file in regular if file.get('sha256')==rule.sha256 and matches(rule.pattern,file['path'])]
+        return {'applies':bool(positive) and not missing and not excluded and (bool(pinned)or not self.any_file_sha256),
+                **({'matchedAnyFileSha256':pinned,'requiredAnyFileSha256':[rule.public()for rule in self.any_file_sha256]}if self.any_file_sha256 else {}),
+                'matchedAnyOf':positive,'missingAllOf':missing,'matchedNoneOf':excluded}

package/server/validation_jobs.py

@@ -0,0 +1,252 @@
+"""Project-scoped artifact checks: durable evidence, independently of HTTP/model jobs.
+
+One local supervisor owns this SQLite adapter. Hosted deployments need transactional
+leases and a separately qualified worker/store. Neither validator selection nor a
+passed command substitutes for independent requirement/system acceptance.
+"""
+import asyncio
+from dataclasses import asdict, dataclass
+import hashlib
+import json
+import threading
+import uuid
+from .engineering_sessions import SessionError
+from .local_validation import ValidationSpec,validation_test_runner
+from .validation_applicability import FileApplicability
+from .runtime_evidence import RuntimeEvidence
+from .validation_workers import worker_id
+
+
+@dataclass(frozen=True)
+class RegisteredValidator:
+    label: str
+    spec: ValidationSpec
+    applicability: FileApplicability | None = None
+    runtime_evidence: RuntimeEvidence | None = None
+    worker_id: str | None = None
+
+    def __post_init__(self):
+        if not isinstance(self.label,str) or not self.label.strip() or len(self.label)>120:
+            raise ValueError('An explicit validator label is required')
+        if self.applicability is not None and not isinstance(self.applicability,FileApplicability):
+            raise ValueError('Use a reviewed file applicability contract')
+        if self.runtime_evidence is not None and not isinstance(self.runtime_evidence,RuntimeEvidence):raise ValueError('Use pinned operator runtime evidence')
+        if self.worker_id is not None:worker_id(self.worker_id)
+
+
+def registered_validators(entries):
+    """Parse server-operator configuration, never browser/model-provided commands."""
+    if not isinstance(entries,list):raise ValueError('Validator configuration must be a list')
+    result={}
+    for entry in entries:
+        if not isinstance(entry,dict) or set(entry)-{'id','label','image','command','platform','timeoutSeconds','bootstrapPython','isolationProfile','runtimeEnvironment','executableScratch','applicability','runtimeReceipt','workerId'}:
+            raise ValueError('Unrecognized validator registration')
+        if not isinstance(entry.get('command'),list):raise ValueError('Register a validator argument vector')
+        environment=entry.get('runtimeEnvironment',{})
+        if not isinstance(environment,dict):raise ValueError('Runtime environment must be an operator-owned mapping')
+        spec=ValidationSpec(entry.get('id',''),entry.get('image',''),tuple(entry['command']),
+            platform=entry.get('platform','linux/amd64'),timeout_seconds=entry.get('timeoutSeconds',60),
+            bootstrap_python=entry.get('bootstrapPython','/usr/local/bin/python3'),isolation_profile=entry.get('isolationProfile','standard-v1'),runtime_environment=tuple(environment.items()),executable_scratch=entry.get('executableScratch',False))
+        if spec.name in result:raise ValueError('Validator IDs must be unique')
+        if 'workerId' in entry:worker_id(entry['workerId'])
+        result[spec.name]=RegisteredValidator(entry.get('label',''),spec,FileApplicability.parse(entry['applicability']) if 'applicability' in entry else None,
+            RuntimeEvidence.load(entry['runtimeReceipt'],spec) if 'runtimeReceipt' in entry else None,entry.get('workerId'))
+    return result
+
+
+class ValidationJobs:
+    def __init__(self, store, artifacts, worker, validators, *, workers=None):
+        self.store,self.artifacts,self.worker=store,artifacts,worker
+        self.workers={} if workers is None else dict(workers)
+        for name,executor in self.workers.items():
+            worker_id(name)
+            if not all(callable(getattr(executor,method,None))for method in ['run','recover']) or not all(isinstance(getattr(executor,key,None),str)and getattr(executor,key)for key in ['identity_digest','policy_digest']):
+                raise ValueError('Supply explicit worker executor interfaces and identities')
+        self.validators=dict(validators)
+        if any(key!=value.spec.name for key,value in self.validators.items()):
+            raise ValueError('Validator IDs must match their registered contract')
+        self.db=store.db
+        self.db.execute('''CREATE TABLE IF NOT EXISTS artifact_validation_jobs (
+            id TEXT PRIMARY KEY, session TEXT NOT NULL, artifact TEXT NOT NULL,
+            artifact_sha256 TEXT NOT NULL, validator TEXT NOT NULL, label TEXT NOT NULL,
+            contract_sha256 TEXT NOT NULL, spec TEXT NOT NULL, state TEXT NOT NULL,
+            result TEXT)''')
+        with self.db:
+            self.db.execute("UPDATE artifact_validation_jobs SET state='recovery_required' WHERE state IN ('queued','running')")
+        self.tasks={};self.cancellations={};self.semaphore=asyncio.Semaphore(2);self.closed=False
+
+    def catalog(self):
+        return [{'id':key,'label':value.label,'evidenceLevel':'local_container_check',
+                 'contractSha256':self._public_contract(value),
+                 'available':self._available(value),
+                 'applicability':value.applicability.public() if value.applicability else None,
+                 **({'runtimeEvidence':value.runtime_evidence.public()} if value.runtime_evidence and self._observation_matches(value) else {}),
+                 **self._placement(value),
+                 'runtime':{'imageId':value.spec.image,'platform':value.spec.platform,'isolationProfile':value.spec.isolation_profile,'environment':dict(value.spec.runtime_environment),'executable':value.spec.command[0],'testRunner':validation_test_runner(value.spec),'executableScratchDirectories':['/dependencies']if value.spec.executable_scratch else []}} for key,value in self.validators.items()]
+
+    def _contract(self,registered):
+        worker=self._worker(registered)
+        if worker is None:raise SessionError('The explicitly registered validator worker is unavailable; no fallback was applied')
+        registration={'spec':asdict(registered.spec),'workerIdentity':worker.identity_digest}
+        if registered.worker_id is not None:registration['workerId']=registered.worker_id
+        if not registered.spec.executable_scratch:registration['spec'].pop('executable_scratch')
+        # Preserve historical manual-only contract hashes. Changing selection rules
+        # invalidates evidence reuse even when the executable is unchanged.
+        if registered.applicability is not None:registration['applicability']=registered.applicability.public()
+        if registered.runtime_evidence is not None:registration['runtimeEvidence']=registered.runtime_evidence.public()
+        digest=hashlib.sha256(json.dumps({**registration,'policy':worker.policy_digest},sort_keys=True).encode()).hexdigest()
+        return digest,registration
+
+    def _worker(self,registered):
+        return self.worker if registered.worker_id is None else getattr(self,'workers',{}).get(registered.worker_id)
+
+    def _observation_matches(self,registered):
+        # Preserve legacy image-only contracts. Context-bound observations and
+        # explicit placements cannot inherit facts from another worker/policy.
+        evidence=registered.runtime_evidence
+        return evidence is None or (registered.worker_id is None and not evidence.context_bound) or (self._worker(registered) is not None and evidence.matches_worker(self._worker(registered)))
+
+    def _placement(self,registered):
+        if registered.worker_id is not None or (registered.runtime_evidence is not None and registered.runtime_evidence.context_bound and not self._observation_matches(registered)):
+            return {'placement':{'workerId':registered.worker_id,'status':self._placement_status(registered)}}
+        return {}
+
+    def _placement_status(self,registered):
+        worker=self._worker(registered)
+        if worker is None:return 'worker_unavailable'
+        if not self._observation_matches(registered):return 'runtime_observation_mismatch'
+        if hasattr(worker,'supports')and not worker.supports(registered.spec):return 'isolation_profile_unavailable'
+        return 'configured'
+
+    def _public_contract(self,registered):
+        return self._contract(registered)[0] if self._worker(registered) is not None and self._observation_matches(registered) else None
+
+    def available(self):
+        return self.worker is not None or any(self._available(value)for value in self.validators.values())
+
+    def validator_available(self,ident):
+        registered=self.validators.get(ident)
+        return registered is not None and self._available(registered)
+
+    def _available(self,registered):
+        return self._placement_status(registered)=='configured'
+
+    def plan(self,scope,session,artifact):
+        """No execution or implicit pass; selection binds exact immutable bytes."""
+        manifest,content=self.artifacts.get(scope,session,artifact)
+        if hashlib.sha256(content).hexdigest()!=manifest['sha256']:
+            raise SessionError('Stored artifact bytes do not match their receipt')
+        decisions=[]
+        for ident,registered in self.validators.items():
+            assessment=registered.applicability.assess(manifest['files']) if registered.applicability else None
+            available=self._available(registered)
+            state='manual_only' if assessment is None else 'not_applicable' if not assessment['applies'] else 'selected' if available else 'unavailable'
+            decisions.append({'validatorId':ident,'label':registered.label,'state':state,
+                'contractSha256':self._public_contract(registered),
+                **self._placement(registered),
+                'applicability':registered.applicability.public() if registered.applicability else None,
+                'assessment':assessment})
+        return {'artifactId':manifest['id'],'artifactSha256':manifest['sha256'],'decisions':decisions,
+            'selectionStatus':'checks_selected' if any(d['state']=='selected' for d in decisions) else 'no_available_applicable_checks',
+            'acceptance':'not_established_by_file_applicability'}
+
+    def _row(self,scope,session,job):
+        self.store.get(scope,session)
+        row=self.db.execute('SELECT * FROM artifact_validation_jobs WHERE id=? AND session=?',(job,session)).fetchone()
+        if row is None:raise SessionError('This check is unavailable for the project and session')
+        return dict(row)
+
+    @staticmethod
+    def _public(row):
+        registration=json.loads(row['spec'])
+        return {'id':row['id'],'sessionId':row['session'],'artifactId':row['artifact'],
+            'artifactSha256':row['artifact_sha256'],'validatorId':row['validator'],'label':row['label'],
+            'contractSha256':row['contract_sha256'],'state':row['state'],
+            'result':json.loads(row['result']) if row['result'] else None,
+            **({'placement':{'workerId':registration['workerId']}} if 'workerId' in registration else {}),
+            'acceptance':'not_established_by_local_check'}
+
+    def get(self,scope,session,job):return self._public(self._row(scope,session,job))
+
+    def list(self,scope,session,artifact):
+        self.store.get(scope,session)
+        # Artifact ownership is checked without moving its potentially large bytes.
+        if not self.artifacts.contains(scope,session,artifact):
+            raise SessionError('Artifact is unavailable for this project and session')
+        rows=self.db.execute('SELECT * FROM artifact_validation_jobs WHERE session=? AND artifact=? ORDER BY rowid',(session,artifact)).fetchall()
+        return [self._public(dict(row)) for row in rows]
+
+    def _settle(self,job,result):
+        with self.db:
+            self.db.execute("UPDATE artifact_validation_jobs SET state='finished',result=? WHERE id=?",(json.dumps(result,allow_nan=False),job))
+
+    async def start(self,scope,session,artifact,validator,*,retry=False):
+        if self.closed:raise SessionError('The local check supervisor is closing')
+        self.store.get(scope,session)
+        registered=self.validators.get(validator)
+        if registered is None:raise SessionError('This validator is not registered by the server operator')
+        if not self._available(registered):raise SessionError('The selected validator placement, observation or isolation profile is unavailable; inspect its catalog status. No fallback was applied')
+        worker=self._worker(registered)
+        manifest,content=self.artifacts.get(scope,session,artifact)
+        digest=hashlib.sha256(content).hexdigest()
+        if digest!=manifest['sha256']:raise SessionError('Stored artifact bytes do not match their receipt')
+        contract,registration=self._contract(registered)
+        prior=self.db.execute('''SELECT * FROM artifact_validation_jobs WHERE session=? AND artifact=?
+            AND contract_sha256=? ORDER BY rowid DESC LIMIT 1''',(session,artifact,contract)).fetchone()
+        if prior:
+            row=dict(prior)
+            if row['state']!='finished' or not retry:return self._public(row)
+        if self.db.execute("SELECT 1 FROM artifact_validation_jobs WHERE session=? AND artifact=? AND state='recovery_required'",(session,artifact)).fetchone():
+            raise SessionError('A prior check for this package requires confirmed cleanup before another check can start')
+        if len(self.tasks)>=16:raise SessionError('The local check queue is full; retain the package and retry later')
+        ident=str(uuid.uuid4())
+        with self.db:
+            self.db.execute('INSERT INTO artifact_validation_jobs VALUES (?,?,?,?,?,?,?,?,?,NULL)',
+                (ident,session,artifact,digest,validator,registered.label,contract,json.dumps(registration),'queued'))
+        cancelled=threading.Event();self.cancellations[ident]=cancelled
+        task=asyncio.create_task(self._execute(ident,content,digest,registered.spec,cancelled,worker,worker.identity_digest,worker.policy_digest))
+        self.tasks[ident]=task
+        def settled(completed):
+            self.tasks.pop(ident,None);self.cancellations.pop(ident,None)
+            if not completed.cancelled():completed.exception()
+        task.add_done_callback(settled)
+        return self.get(scope,session,ident)
+
+    async def _execute(self,job,content,digest,spec,cancelled,worker,worker_identity,worker_policy):
+        try:
+            async with self.semaphore:
+                if cancelled.is_set():
+                    result={'status':'failed','reason':'cancelled_before_execution','artifactSha256':digest}
+                else:
+                    with self.db:self.db.execute("UPDATE artifact_validation_jobs SET state='running' WHERE id=?",(job,))
+                    if worker.identity_digest!=worker_identity or worker.policy_digest!=worker_policy:raise ValueError('Admitted worker identity or policy changed')
+                    result=await asyncio.to_thread(worker.run,content,digest,spec,execution_id=job,cancel_event=cancelled)
+                    if not isinstance(result,dict) or result.get('artifactSha256')!=digest or result.get('status') not in {'passed','failed','incomplete'}:
+                        raise ValueError('Validator receipt does not bind the requested artifact')
+                self._settle(job,result)
+        except Exception:
+            self._settle(job,{'status':'failed','reason':'validator_unavailable','artifactSha256':digest,
+                'output':'The local check could not be completed. Package bytes are retained; inspect the server worker configuration.'})
+
+    async def recover(self,scope,session,job):
+        row=self._row(scope,session,job)
+        if row['state']!='recovery_required':return self._public(row)
+        identity=json.loads(row['spec']).get('workerIdentity')
+        # Cleanup follows the recorded identity, even if validator/default/name
+        # assignments changed. Search only explicitly approved current executors.
+        worker=next((candidate for candidate in [self.worker,*getattr(self,'workers',{}).values()]if candidate is not None and candidate.identity_digest==identity),None)
+        if worker is None:
+            raise SessionError('The original local validator worker is required for cleanup; no fallback was applied')
+        try:
+            result=await asyncio.to_thread(worker.recover,job)
+            if result!={'cleanupConfirmed':True,'workReplayed':False}:raise ValueError('Cleanup is uncertain')
+        except Exception:
+            raise SessionError('The prior check may still be running; cleanup was not confirmed and no check was replayed') from None
+        self._settle(job,{'status':'failed','reason':'supervisor_restart','artifactSha256':row['artifact_sha256'],
+            'output':'Prior container cleanup is confirmed. Request a new check explicitly; no work was replayed.'})
+        return self.get(scope,session,job)
+
+    async def close(self):
+        self.closed=True
+        for cancellation in self.cancellations.values():cancellation.set()
+        await asyncio.gather(*list(self.tasks.values()),return_exceptions=True)

package/server/validation_workers.py

@@ -0,0 +1,48 @@
+"""Operator-owned local executor registrations, never request-selected endpoints.
+
+Definitions are snapshots. Missing sockets/policies can become available later;
+instantiation never pulls images, changes contexts or discovers another executor.
+"""
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+from .local_validation import DockerValidationWorker
+
+
+def worker_id(value):
+    if type(value) is not str or not re.fullmatch(r'[a-z][a-z0-9_-]{2,79}',value):
+        raise ValueError('Use an explicit operator worker ID')
+    return value
+
+
+@dataclass(frozen=True)
+class WorkerRegistration:
+    endpoint: str
+    profiles: bytes
+
+    def create(self):
+        return DockerValidationWorker(self.endpoint,isolation_profiles=json.loads(self.profiles))
+
+
+def registered_workers(entries):
+    if type(entries) is not dict or len(entries)>16:
+        raise ValueError('Register a bounded operator worker mapping')
+    result={}
+    for name,entry in entries.items():
+        worker_id(name)
+        if type(entry) is not dict or not {'endpoint'}<=set(entry)<={'endpoint','isolationProfiles'}:
+            raise ValueError('Unrecognized operator worker registration')
+        endpoint=entry['endpoint']
+        if type(endpoint) is not str or len(endpoint)>1024 or '\0' in endpoint or not endpoint.startswith('unix:///') or not Path(endpoint[7:]).is_absolute():
+            raise ValueError('Register an explicit local Docker Unix socket')
+        profiles=entry.get('isolationProfiles',{})
+        if type(profiles) is not dict or set(profiles)-set(DockerValidationWorker.REVIEWED_PROFILES):
+            raise ValueError('Register reviewed worker-specific isolation profiles only')
+        for profile,pin in profiles.items():
+            if (type(pin) is not dict or set(pin)!={'path','sha256'} or
+                pin['sha256']!=DockerValidationWorker.REVIEWED_PROFILES[profile] or
+                type(pin['path']) is not str or not Path(pin['path']).is_absolute()):
+                raise ValueError('Use exact reviewed isolation policy references')
+        result[name]=WorkerRegistration(endpoint,json.dumps(profiles,sort_keys=True).encode())
+    return result