generic-gitlab-cicd 0.3.2__py3-none-any.whl

generic_ci/sources.py

@@ -0,0 +1,314 @@
+"""Pinned, data-only Git configuration sources; no checkout or source code execution."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+from urllib.parse import urlsplit
+
+import yaml
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+from pydantic import Field
+
+from . import __version__
+from .config import read_yaml, UniqueLoader
+from .models import Model, relative
+from .workflows.compiler import merge
+from .workflows.models import Pipeline, Platform
+
+
+class Source(Model):
+    repository: str
+    ref: str
+
+
+class ProjectConfig(Model):
+    source: Source
+    delivery: str = 'delivery.yml'
+    platform: str | None = None
+
+
+class Manifest(Model):
+    version: int = 1
+    cli: str = '>=0.3.0,<0.4.0'
+    defaults: dict[str, str] = Field(default_factory=dict)
+    templates: dict[str, str] = Field(default_factory=dict)
+
+
+def location(root, value):
+    relative(value)
+    if any(part.lower() == '.git' for part in Path(value).parts):
+        raise ValueError('source files must not modify Git metadata')
+    result = root / value
+    if not result.resolve().is_relative_to(root.resolve()):
+        raise ValueError('path escapes its repository')
+    return result
+
+
+def home():
+    return Path(os.environ.get('GENERIC_CI_HOME', Path.home() / '.config/generic-ci'))
+
+
+def write_json(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + '.tmp')
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True) + '\n')
+    tmp.replace(path)
+
+
+def repository(value):
+    # Credentials belong to Git's credential helper or SSH agent, never the lock.
+    if value.startswith(('https://', 'ssh://')):
+        parsed = urlsplit(value)
+        if not parsed.hostname or parsed.password or parsed.query or parsed.fragment or (parsed.scheme == 'https' and parsed.username):
+            raise ValueError('repository must not contain credentials, query strings or fragments')
+    elif re.fullmatch(r'[\w.-]+@[\w.-]+:[^\s]+', value):
+        pass
+    elif '://' in value or value.startswith('-'):
+        raise ValueError('use HTTPS, SSH, or an existing local Git repository/bundle')
+    else:
+        path = Path(value).expanduser().resolve()
+        value = str(path)
+    return value
+
+
+def git(cache, *args, binary=False):
+    env = dict(os.environ, GIT_TERMINAL_PROMPT='0')
+    result = subprocess.run(['git', '-c', 'core.hooksPath=/dev/null', '-C', str(cache), *args], env=env,
+                            capture_output=True, text=not binary)
+    if result.returncode:
+        # Git stderr may contain credential-helper output or authenticated URLs.
+        raise ValueError('source Git operation failed; check repository access and revision availability')
+    return result.stdout if binary else result.stdout.strip()
+
+
+def cache_for(repo):
+    return home() / 'cache' / hashlib.sha256(repo.encode()).hexdigest()
+
+
+def resolve(source, *, commit=None, offline=False, import_from=None):
+    repo = repository(source.repository)
+    if not source.ref or source.ref.startswith('-') or any(c.isspace() for c in source.ref):
+        raise ValueError('source ref must be a Git branch, tag or commit')
+    cache = cache_for(repo)
+    if commit and not re.fullmatch('[a-f0-9]{40}', commit):
+        raise ValueError('source lock must contain a full Git commit')
+    if commit and cache.exists():
+        try:
+            if git(cache, 'rev-parse', '--verify', commit + '^{commit}') == commit:
+                return cache, commit
+        except ValueError:
+            pass
+    if offline and not import_from:
+        raise ValueError('source revision is not cached; import a checkout/bundle or fetch it while connected')
+    if not cache.exists():
+        cache.mkdir(parents=True)
+        git(cache, 'init', '--bare')
+    origin = repository(import_from) if import_from else repo
+    revision = commit or source.ref
+    git(cache, 'fetch', '--no-tags', '--', origin, revision)
+    resolved = git(cache, 'rev-parse', 'FETCH_HEAD^{commit}')
+    if commit and resolved != commit:
+        raise ValueError('import does not match the locked source commit')
+    return cache, resolved
+
+
+def blob(cache, commit, path):
+    relative(path)
+    mode = git(cache, 'ls-tree', commit, '--', path).split()
+    if not mode or mode[0] not in {'100644', '100755'}:
+        raise ValueError(f'source path must be a regular tracked file: {path}')
+    data = git(cache, 'show', commit + ':' + path, binary=True)
+    if len(data) > 2_000_000:
+        raise ValueError('source file exceeds 2 MB')
+    return data
+
+
+def yaml_blob(cache, commit, path):
+    data = yaml.load(blob(cache, commit, path).decode(), Loader=UniqueLoader)
+    if not isinstance(data, dict):
+        raise ValueError(f'{path}: expected YAML mapping')
+    return data
+
+
+def snapshot(source, cache, commit):
+    manifest = Manifest.model_validate(yaml_blob(cache, commit, 'generic-ci-source.yml'))
+    if manifest.version != 1 or Version(__version__) not in SpecifierSet(manifest.cli):
+        raise ValueError('source manifest version or CLI compatibility requirement is not satisfied')
+    if set(manifest.defaults) - {'delivery', 'platform'}:
+        raise ValueError('source defaults supports only delivery and platform')
+    defaults = {key: yaml_blob(cache, commit, path) for key, path in manifest.defaults.items()}
+    return {'version': 1, 'source': source.model_dump(), 'commit': commit,
+            'manifest': manifest.model_dump(), 'defaults': defaults}
+
+
+def lock_path(root):
+    return root / 'generic-ci.lock.json'
+
+
+def project_config(root):
+    return ProjectConfig.model_validate(read_yaml(root / 'generic-ci.yml'))
+
+
+def locked(root, *, offline=False, import_from=None):
+    config = project_config(root)
+    path = lock_path(root)
+    if not path.exists():
+        raise ValueError('source lock is missing; run generic-ci source update')
+    lock = json.loads(path.read_text())
+    if lock.get('source') != config.source.model_dump() or lock.get('version') != 1:
+        raise ValueError('source configuration changed; run generic-ci source update')
+    if not re.fullmatch('[a-f0-9]{40}', str(lock.get('commit', ''))):
+        raise ValueError('source lock must contain a full Git commit')
+    cache, commit = resolve(config.source, commit=lock['commit'], offline=offline, import_from=import_from)
+    actual = snapshot(config.source, cache, commit)
+    if lock != actual:
+        raise ValueError('source lock content differs from its pinned Git revision')
+    return config, actual, cache
+
+
+def apply_layers(layers):
+    effective, origins = {}, {}
+    def mark(value, prefix, owner):
+        if isinstance(value, dict) and value:
+            for key, child in value.items():
+                mark(child, prefix + ('.' if prefix else '') + key, owner)
+        else:
+            origins[prefix] = owner
+    for owner, data in layers:
+        if not isinstance(data, dict):
+            raise ValueError('configuration layers must be mappings')
+        effective = merge(effective, data)
+        mark(data, '', owner)
+    # Drop origins for leaves replaced by a scalar/list or vice versa.
+    valid = {}
+    def retain(value, prefix=''):
+        if isinstance(value, dict) and value:
+            for key, child in value.items():
+                retain(child, prefix + ('.' if prefix else '') + key)
+        elif prefix in origins:
+            valid[prefix] = origins[prefix]
+    retain(effective)
+    return effective, valid
+
+
+def load_project(root, config_override=None, platform_override=None, offline=False):
+    config, lock, _ = locked(root, offline=offline)
+    delivery = location(root, config_override or config.delivery)
+    platform_name = platform_override or config.platform
+    delivery_data, dorigins = apply_layers([('source:' + lock['commit'], lock['defaults'].get('delivery', {})),
+                                          ('project:' + delivery.relative_to(root).as_posix(), read_yaml(delivery))])
+    platform_layers = [('source:' + lock['commit'], lock['defaults'].get('platform', {}))]
+    paths = [root / 'generic-ci.yml', lock_path(root), delivery]
+    if platform_name:
+        local = location(root, platform_name)
+        platform_layers.append(('project:' + platform_name, read_yaml(local)))
+        paths.append(local)
+    platform_data, porigins = apply_layers(platform_layers)
+    return Pipeline.model_validate(delivery_data), Platform.model_validate(platform_data), {'delivery': dorigins, 'platform': porigins}, paths
+
+
+def initialize(root, template, name=None, repo=None, ref=None, offline=False, delivery=None):
+    if repo:
+        if not ref:
+            raise ValueError('--repo requires --ref')
+        source = Source(repository=repository(repo), ref=ref)
+    else:
+        registry = json.loads((home() / 'sources.json').read_text())
+        chosen = name or registry.get('default')
+        if chosen not in registry.get('sources', {}):
+            raise ValueError('choose a configured source with --source or provide --repo and --ref')
+        source = Source.model_validate(registry['sources'][chosen])
+    # Registry records the initial pinned revision for offline initialization.
+    registry_path = home() / 'pins.json'
+    pins = json.loads(registry_path.read_text()) if registry_path.exists() else {}
+    pin = pins.get(json.dumps(source.model_dump(), sort_keys=True))
+    cache, commit = resolve(source, commit=pin, offline=offline)
+    snap = snapshot(source, cache, commit)
+    templates = snap['manifest']['templates']
+    if not template:
+        print('Available templates: ' + ', '.join(sorted(templates)))
+        return
+    if template not in templates:
+        raise ValueError('unknown template; available: ' + ', '.join(sorted(templates)))
+    prefix = templates[template].rstrip('/')
+    relative(prefix)
+    paths = git(cache, 'ls-tree', '-r', '--name-only', commit, '--', prefix).splitlines()
+    files = {}
+    for path in paths:
+        if not path.startswith(prefix + '/'):
+            continue
+        destination = location(root, path[len(prefix) + 1:])
+        files[destination] = blob(cache, commit, path)
+    if not files:
+        raise ValueError('template contains no files')
+    project = ProjectConfig(source=source, delivery=delivery or 'delivery.yml')
+    for reserved in [root / 'generic-ci.yml', lock_path(root)]:
+        if reserved in files:
+            raise ValueError('template cannot supply reserved source/lock files')
+    files[root / 'generic-ci.yml'] = yaml.safe_dump(project.model_dump(by_alias=True, exclude_none=True), sort_keys=False).encode()
+    files[lock_path(root)] = (json.dumps(snap, indent=2, sort_keys=True) + '\n').encode()
+    if location(root, project.delivery) not in files:
+        raise ValueError('template does not contain the configured delivery file')
+    for path in files:
+        if path.exists() or path.is_symlink():
+            raise ValueError(f'init will not overwrite {path.relative_to(root)}')
+    for path, content in files.items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+    print(f'Created {template} from source commit {commit}; commit generic-ci.yml and generic-ci.lock.json')
+
+
+def source_main(argv):
+    parser = argparse.ArgumentParser(prog='generic-ci source')
+    sub = parser.add_subparsers(dest='action', required=True)
+    add = sub.add_parser('add'); add.add_argument('name'); add.add_argument('--repo', required=True); add.add_argument('--ref', required=True); add.add_argument('--default', action='store_true')
+    sub.add_parser('list')
+    update = sub.add_parser('update'); update.add_argument('--ref'); update.add_argument('--check', action='store_true')
+    fetch = sub.add_parser('fetch'); fetch.add_argument('--from', dest='import_from'); fetch.add_argument('--offline', action='store_true')
+    for p in [update, fetch]: p.add_argument('--root', default='.')
+    args = parser.parse_args(argv)
+    registry_path = home() / 'sources.json'
+    registry = json.loads(registry_path.read_text()) if registry_path.exists() else {'sources': {}}
+    if args.action == 'list':
+        print(json.dumps(registry, indent=2)); return 0
+    if args.action == 'add':
+        source = Source(repository=repository(args.repo), ref=args.ref)
+        cache, commit = resolve(source); snapshot(source, cache, commit)
+        registry['sources'][args.name] = source.model_dump()
+        if args.default: registry['default'] = args.name
+        write_json(registry_path, registry)
+        pins_path = home() / 'pins.json'
+        pins = json.loads(pins_path.read_text()) if pins_path.exists() else {}
+        pins[json.dumps(source.model_dump(), sort_keys=True)] = commit
+        write_json(pins_path, pins)
+        print(f'Registered {args.name} at {commit}'); return 0
+    root = Path(args.root).resolve()
+    if args.action == 'fetch':
+        _, snap, _ = locked(root, offline=args.offline, import_from=args.import_from)
+        print('Cached ' + snap['commit']); return 0
+    config = project_config(root)
+    if args.ref: config.source.ref = args.ref
+    cache, commit = resolve(config.source)
+    updated = snapshot(config.source, cache, commit)
+    old = json.loads(lock_path(root).read_text()) if lock_path(root).exists() else {}
+    import difflib
+    before = json.dumps(old.get('defaults', {}), indent=2, sort_keys=True).splitlines(True)
+    after = json.dumps(updated['defaults'], indent=2, sort_keys=True).splitlines(True)
+    print('Source revision: ' + old.get('commit', '(none)') + ' -> ' + commit)
+    print(''.join(difflib.unified_diff(before, after, fromfile='old defaults', tofile='new defaults')), end='')
+    # Check the complete effective configuration before recording the update.
+    delivery = read_yaml(location(root, config.delivery))
+    effective = Pipeline.model_validate(merge(updated['defaults'].get('delivery', {}), delivery))
+    platform = updated['defaults'].get('platform', {})
+    if config.platform: platform = merge(platform, read_yaml(location(root, config.platform)))
+    from .workflows.compiler import compile_pipeline
+    compile_pipeline(effective, Platform.model_validate(platform))
+    if args.check: return 0 if old == updated else 1
+    write_json(lock_path(root), updated)
+    (root / 'generic-ci.yml').write_text(yaml.safe_dump(config.model_dump(by_alias=True, exclude_none=True), sort_keys=False))
+    print('Updated source lock; review the diff and regenerate CI. Template files were preserved.')
+    return 0

generic_ci/workflows/__init__.py

@@ -0,0 +1 @@
+"""Developer-defined workflows, revision one."""

generic_ci/workflows/compiler.py

@@ -0,0 +1,316 @@
+"""Compile event workflows into explicit jobs and verifiable artifact dependencies."""
+import base64
+import copy
+import json
+import re
+import yaml
+from generic_ci import __version__
+from generic_ci.compiler import digest, variants
+from generic_ci.config import read_yaml, allowed_url
+from .models import Pipeline, Platform
+
+
+def merge(*values):
+    result = {}
+    for value in values:
+        for key, item in value.items():
+            result[key] = merge(result.get(key, {}), item) if isinstance(item, dict) and isinstance(result.get(key, {}), dict) else copy.deepcopy(item)
+    return result
+
+
+def load(config, platform):
+    return Pipeline.model_validate(read_yaml(config)), Platform.model_validate(read_yaml(platform))
+
+
+def tag_pattern(tag):
+    return '^' + re.escape(tag).replace(re.escape('{version}'), '.+') .replace('/', r'\/') + '$'
+
+
+def event_rule(event, project=None):
+    if event == 'release':
+        return '$CI_COMMIT_TAG =~ /' + tag_pattern(project['release']['tag']) + '/'
+    return {'push': '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH',
+            'merge-request': '$CI_PIPELINE_SOURCE == "merge_request_event"',
+            'manual': '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH',
+            'schedule': '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH'}[event]
+
+
+def compile_pipeline(pipeline, platform, sources=None):
+    p, infra = pipeline.model_dump(), platform.model_dump()
+    projects, nodes, refs = p['projects'], {}, {}
+    # Defaults on models describe the schema, not explicit override requests.
+    for name, project in projects.items():
+        source = pipeline.projects[name]
+        project['defaults'] = source.defaults.model_dump(exclude_unset=True)
+        for key, settings in project['checks'].items():
+            explicit = source.checks[key].model_dump(exclude_unset=True)
+            for field in ('image', 'tags', 'timeout', 'variables', 'services', 'parallel', 'artifacts'):
+                if field not in explicit:
+                    settings.pop(field, None)
+            if isinstance(settings['dependencies'], dict):
+                settings['dependencies'] = source.checks[key].dependencies.model_dump(exclude_unset=True)
+    hosts = infra['allowed_hosts']
+    for value in [*infra['images'].values(), infra['container_builder']['image'], *infra['registries'].values()]:
+        allowed_url('https://' + value.split('/')[0], hosts)
+    if infra['registries']['containers'] == infra['registries']['previews']:
+        raise ValueError('release and preview registries must be distinct repositories')
+    for name, project in projects.items():
+        for dep in project['depends_on']:
+            if dep not in projects or dep == name:
+                raise ValueError(f'{name}.depends-on: unknown/self project {dep}')
+        if project['container'] and project['container']['repository']:
+            allowed_url('https://' + project['container']['repository'].split('/')[0], hosts)
+    def project_visit(name, stack):
+        if name in stack:
+            raise ValueError('project dependency cycle: ' + ' -> '.join([*stack, name]))
+        for dep in projects[name]['depends_on']:
+            project_visit(dep, [*stack, name])
+    for name in projects:
+        project_visit(name, [])
+
+    def add(key, project, event, action, settings, needs=(), execution=None, condition=None, deployment=None):
+        candidate = dict(project=project, event=event, action=action, settings=settings,
+                          needs=list(needs), execution=execution or {}, condition=condition,
+                          deployment=deployment)
+        if key in nodes and nodes[key] != candidate:
+            raise ValueError(f'generated job name collision: {key}; rename the user check or project')
+        nodes[key] = candidate
+        return key
+
+    def check(name, key, event, context=None):
+        project = projects[name]
+        if key not in project['checks']:
+            raise ValueError(f'{name}: unknown check {key}; available: {list(project["checks"])}')
+        settings = project['checks'][key]
+        execution = merge(infra['defaults'], project['defaults'], {k: v for k, v in settings.items() if v is not None})
+        if settings['dependencies'] is not None and settings['dependencies'] is not False and project['python'] is None:
+            raise ValueError(f'{name}.{key}: dependency group overrides require Python')
+        rows = variants(execution)
+        if settings['outputs'] and len(rows) != 1:
+            raise ValueError(f'{name}.{key}: matrix output paths would collide')
+        result = []
+        for index, row in enumerate(rows):
+            identifier = ':'.join(filter(None, [event, context, name, key, str(index + 1) if len(rows) > 1 else None]))
+            ex = merge(execution, {'variables': row})
+            result.append(add(identifier, name, event, 'check', settings, execution=ex, deployment=context))
+        if not context:
+            refs[event, name + '.' + key] = result
+        return result
+
+    for name, project in projects.items():
+        for event, workflow in project['workflows'].items():
+            if event == 'release' and not project['release']:
+                raise ValueError(f'{name}: release workflow requires release metadata')
+            gates = [job for key in workflow['checks'] for job in check(name, key, event)]
+            if project['release']:
+                vjob = add(f'{event}:{name}:version', name, event, 'version', project['release'])
+                gates.append(vjob)
+            operations = workflow['build']
+            available = {'application': project['build'], 'container': project['container'], 'package': project['package']}
+            if operations is True:
+                operations = [kind for kind, setting in available.items() if setting is not None]
+                if len(operations) != 1:
+                    raise ValueError(f'{name}: build: true requires exactly one output; list application/container/package explicitly')
+            elif operations is False:
+                operations = []
+            publication = workflow['publish']
+            channel = publication['channel'] if isinstance(publication, dict) else 'auto'
+            if publication:
+                if channel == 'development':
+                    if event == 'release':
+                        raise ValueError(f'{name}: development publication cannot run on release tags')
+                elif event != 'release':
+                    raise ValueError(f'{name}: auto publication requires a release workflow')
+                if 'package' not in operations:
+                    operations = [*operations, 'package']
+            built = []
+            for kind in operations:
+                if available[kind] is None:
+                    raise ValueError(f'{name}: no {kind} build configured')
+                public = {'application': 'build', 'container': 'build-image', 'package': 'build-package'}[kind]
+                key = add(f'{event}:{name}:{public}', name, event, kind, available[kind], gates)
+                if kind == 'package':
+                    nodes[key]['settings'] = {**nodes[key]['settings'], 'channel': channel if publication else 'auto'}
+                nodes[key]['execution'] = merge(infra['defaults'], project['defaults'])
+                refs[event, name + '.' + public] = [key]
+                built.append(key)
+            if event == 'release' or publication:
+                final = add(f'{event}:{name}:publish', name, event, 'publish', {'publish_package': bool(publication), 'channel': channel}, gates + built)
+                refs[event, name + '.publish'] = [final]
+        release = project['release']
+        if release and release['require_bump'] and 'merge-request' not in project['workflows']:
+            add(f'merge-request:{name}:version', name, 'merge-request', 'version', release)
+        if release and release['create']:
+            if 'push' not in project['workflows'] or 'release' not in project['workflows']:
+                raise ValueError(f'{name}: release button requires push and release workflows')
+            gates = [k for k, n in nodes.items() if n['project'] == name and n['event'] == 'push']
+            add(f'push:{name}:create-release', name, 'push', 'create-release', release, gates,
+                condition='$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == ' + json.dumps(release['create']['branch']))
+
+    # Explicit artifact edges never substitute packages. Producers must be selected in that event.
+    for key, node in list(nodes.items()):
+        if node['action'] not in {'check', 'application', 'container', 'package', 'publish'}:
+            continue
+        requested = node['settings'].get('needs', [])
+        if node['action'] == 'publish' and node['event'] == 'release':
+            requested = [dep + '.publish' for dep in projects[node['project']]['release']['needs']]
+        for ref in requested:
+            ref = ref if '.' in ref else node['project'] + '.' + ref
+            if (node['event'], ref) not in refs:
+                raise ValueError(f'{key}: producer {ref} is not selected in {node["event"]}')
+            node['needs'] += refs[node['event'], ref]
+            if node['event'] == 'release':
+                dep = ref.split('.')[0]
+                if projects[dep]['release']['tag'] != projects[node['project']]['release']['tag']:
+                    raise ValueError('release artifact/publication dependencies require a coordinated shared release tag')
+
+    for name, deployment in p['deployments'].items():
+        if deployment['target'] not in infra['targets']:
+            raise ValueError(f'{name}: unknown target {deployment["target"]}')
+        chart = deployment['chart']
+        for source in ('repository', 'oci'):
+            if chart[source]:
+                allowed_url(chart[source], hosts)
+        paths = [v for binding in deployment['images'] for v in binding['set'].values() if v]
+        if any(a == b or a.startswith(b + '.') or b.startswith(a + '.') for i, a in enumerate(paths) for b in paths[i+1:]):
+            raise ValueError(f'{name}: overlapping image mappings')
+        for event, behavior in deployment['workflows'].items():
+            if event == 'release' and deployment['update'] == 'complete':
+                tags = {projects[b['from_'].split('.')[0]]['release']['tag']
+                        for b in deployment['images']
+                        if b['from_'].split('.')[0] in projects and projects[b['from_'].split('.')[0]]['release']}
+                if len(tags) > 1:
+                    raise ValueError(f'{name}: complete release deployment requires a coordinated shared release tag; use partial for independent tags')
+            producers = []
+            conditions = []
+            for binding in deployment['images']:
+                ref = binding['from_']
+                if (event, ref) not in refs or not ref.endswith('.build-image'):
+                    raise ValueError(f'{name}: image producer {ref} must build in {event}')
+                producers += refs[event, ref]
+                conditions.append(event_rule(event, projects[ref.split('.')[0]]))
+            condition = ' || '.join('(' + c + ')' for c in dict.fromkeys(conditions))
+            if event == 'merge-request':
+                condition = '(' + condition + ') && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'
+            key = f'{event}:deploy:{name}'
+            prior = producers[:]
+            if behavior['when'] == 'manual':
+                approval = add(f'{event}:approve:{name}', None, event, 'approve', deployment, producers, condition=condition, deployment=name)
+                prior.append(approval)
+            before_dependencies = prior[:]
+            for ref in deployment['before']['checks']:
+                owner, ck = ref.split('.', 1)
+                if owner not in projects:
+                    raise ValueError(f'unknown check owner {owner}')
+                for job in check(owner, ck, event, name + '-before'):
+                    nodes[job]['needs'] = before_dependencies[:]
+                    nodes[job]['condition'] = condition
+                    nodes[job]['deployment'] = name
+                    prior.append(job)
+            add(key, None, event, 'deploy', deployment, prior, condition=condition, deployment=name)
+            for ref in deployment['after']['checks']:
+                owner, ck = ref.split('.', 1)
+                if owner not in projects:
+                    raise ValueError(f'unknown check owner {owner}')
+                for job in check(owner, ck, event, name + '-after'):
+                    nodes[job]['needs'] = [key]
+                    nodes[job]['condition'] = condition
+                    nodes[job]['deployment'] = name
+            if event == 'merge-request':
+                add(f'{event}:stop:{name}', None, event, 'stop', deployment, condition=condition, deployment=name)
+
+    # Contextual deployment checks retain the same explicit artifact contract.
+    for key, node in nodes.items():
+        if node['action'] == 'check' and node['deployment']:
+            for ref in node['settings'].get('needs', []):
+                ref = ref if '.' in ref else node['project'] + '.' + ref
+                if (node['event'], ref) not in refs:
+                    raise ValueError(f'{key}: producer {ref} is not selected in {node["event"]}')
+                node['needs'] += refs[node['event'], ref]
+
+    visiting, visited = set(), set()
+    def visit(key):
+        if key in visiting:
+            raise ValueError(f'job dependency cycle: {key}')
+        if key in visited:
+            return
+        visiting.add(key)
+        for dep in nodes[key]['needs']:
+            visit(dep)
+        visiting.remove(key)
+        visited.add(key)
+    for key in nodes:
+        visit(key)
+    if len(nodes) + 1 > infra['max_jobs']:
+        raise ValueError('generated job count exceeds platform max-jobs')
+    payload = {'version': __version__, 'format': 'workflows-v1', 'pipeline': p, 'platform': infra, 'nodes': nodes, 'sources': sources or {}}
+    fingerprint = digest(payload)
+    encoded = base64.b64encode(json.dumps(payload, sort_keys=True).encode()).decode()
+    if len(encoded) > 100000:
+        raise ValueError('execution configuration exceeds 100 KB; split project groups')
+    control = infra['images'].get('control', infra['images'].get('python'))
+    if not control:
+        raise ValueError('platform images.control or images.python is required for the planner')
+    output = {'stages': ['prepare', 'delivery'], 'workflow': {'rules': [
+        {'if': '$CI_PIPELINE_SOURCE == "merge_request_event"'},
+        {'if': '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG'},
+        {'if': '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS', 'when': 'never'},
+        {'if': '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'},
+        {'if': '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH'},
+        {'if': '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH'}]},
+        'variables': {**infra['variables'], 'TOOLKIT_CONFIG_B64': encoded},
+        'toolkit-plan': {'stage': 'prepare', 'image': control, 'tags': infra['defaults']['tags'] or [],
+                         'script': [f'python -m generic_ci.workflows.runtime plan {fingerprint}'],
+                         'artifacts': {'paths': ['.ci-out/plan.json']}}}
+    for key, node in nodes.items():
+        project = projects.get(node['project'], {})
+        role = 'bun' if (project.get('node') or {}).get('package_manager') == 'bun' else 'node' if project.get('node') else 'python'
+        if node['action'] in {'deploy', 'stop'}:
+            role = 'helm'
+        if node['action'] in {'create-release', 'version', 'publish', 'approve'}:
+            role = 'control' if node['action'] != 'publish' else role
+        ex = node['execution']
+        if not ex.get('image') and role not in infra['images'] and role != 'control' and node['action'] != 'container':
+            raise ValueError(f'platform images.{role} is required for {key}')
+        image = ex.get('image') or infra['images'].get(role, control)
+        tags = ex.get('tags') if ex.get('tags') is not None else infra['defaults']['tags'] or []
+        if node['action'] == 'container':
+            image = infra['container_builder']['image']
+            tags = infra['container_builder']['tags'] or tags
+        allowed_url('https://' + image.split('/')[0], hosts)
+        for service in ex.get('services') or []:
+            allowed_url('https://' + service.split('/')[0], hosts)
+        if len(node['needs']) >= 50:
+            raise ValueError(f'{key}: exceeds supported needs limit')
+        condition = node['condition'] or event_rule(node['event'], project)
+        rule = {'if': condition}
+        if node['action'] in {'create-release', 'stop', 'approve'}:
+            rule.update(when='manual', allow_failure=node['action'] == 'stop')
+        job = {'stage': 'delivery', 'image': image, 'tags': tags, 'rules': [rule],
+               'script': [f'python -m generic_ci.workflows.runtime run {key} {fingerprint}'],
+               'needs': [{'job': 'toolkit-plan', 'artifacts': True}] + [{'job': d, 'artifacts': True, 'optional': True} for d in sorted(set(node['needs']))],
+               'artifacts': merge(ex.get('artifacts', {}), {'when': 'always'}), 'variables': ex.get('variables', {}), 'retry': 0}
+        job['artifacts']['paths'] = list(dict.fromkeys(job['artifacts'].get('paths', []) + [f'.ci-out/{key}/']))
+        for field in ('timeout', 'services'):
+            if ex.get(field) is not None:
+                job[field] = ex[field]
+        if node['action'] in {'deploy', 'stop'}:
+            target = infra['targets'][node['settings']['target']]
+            release = target['release'] or node['deployment']
+            suffix = '/mr-$CI_MERGE_REQUEST_IID' if node['event'] == 'merge-request' else ''
+            env = node['settings']['target'] + '/' + release + suffix
+            job['resource_group'] = env
+            job['environment'] = {'name': env, 'url': target['url']}
+            if node['event'] == 'merge-request':
+                job['environment'].update(on_stop=f'merge-request:stop:{node["deployment"]}', auto_stop_in=node['settings']['auto_stop_in'])
+            if node['action'] == 'stop':
+                job['environment'] = {'name': env, 'action': 'stop'}
+                job['needs'] = []
+                job['variables'] = {'GIT_STRATEGY': 'none'}
+        if node['action'] in {'create-release', 'publish'}:
+            job['resource_group'] = 'release/' + node['project']
+        output[key] = job
+    for key in ['toolkit-plan', *nodes]:
+        if not output[key].get('tags'):
+            output[key].pop('tags', None)
+    return output, payload