vcti-shader-foundry 3.0.0__tar.gz

vcti_shader_foundry-3.0.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_shader_foundry-3.0.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: vcti-shader-foundry
+Version: 3.0.0
+Summary: Shader artifact-set builder: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://github.com/vcollab/vcti-python-shader-foundry
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-shader-foundry/blob/main/CHANGELOG.md
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: vcti-shader-compiler>=4.1.0
+Requires-Dist: vcti-shader-base>=1.0.2
+Requires-Dist: vcti-shader-deform>=1.1.0
+Requires-Dist: vcti-shader-derive>=2.1.0
+Requires-Dist: vcti-shader-fringe>=1.1.0
+Requires-Dist: vcti-derived<5,>=4.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: gl
+Requires-Dist: vcti-shader-compiler[gl]>=4.1.0; extra == "gl"
+Requires-Dist: numpy>=1.26; extra == "gl"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-shader-foundry
+
+The shader artifact-set **builder**: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers.
+
+## Overview
+
+`vcti-shader-foundry` is the assembler of the shader system — the offline build
+tool that turns the installed shader features into the committed artifact set
+the runtime ships. It composes the features it lists (`vcti-shader-deform`,
+`-derive`, `-fringe`) into the pipeline matrix, drives `vcti-shader-compiler`
+to emit and validate GLSL ES, checks every result against its contract, and
+packs the shaders, one envelope per pipeline and the `registry.json` index into
+a single archive, written atomically, for a consumer to take as it likes.
+
+Composition is the whole job, and it is the part no feature can do: each
+feature declares its own fields and cannot see what it is combined with, so the
+builder is where the clip-space transform that belongs to nobody is added,
+where a field name two features declare differently is rejected, and where the
+manifest — the only contract the runtime reads — is written.
+
+It is **not** the toolchain and **not** the vocabulary: the `.slang → GLSL ES`
+machinery lives in `vcti-shader-compiler`, the specs you declare fields with in
+`vcti-shader-base`, and each shader feature in its own package. See
+[docs/design.md](docs/design.md) for the system design and
+[docs/extending.md](docs/extending.md) for adding a shader feature.
+
+## Installation
+
+```bash
+pip install vcti-shader-foundry
+```
+
+This is a build tool, not a runtime dependency; install it in the authoring
+environment alongside the feature packages you want built. The shader compilers
+(`slangc`, `spirv-cross`, `glslang`) are external and pinned — discovered via
+`SLANG_DIR` / `SPIRV_CROSS_DIR` / `GLSLANG_DIR` or `PATH`.
+
+## Quick Start
+
+Build the artifact set as one archive:
+
+```console
+$ shader-foundry emit
+wrote shaders-3.0.0-1fc4c3a7.zip: 15 pipeline(s), 531,073 bytes, sha256 1fc4c3a7f81222b59c74378dab9c5f46610b55276b319b5d200c62b0a6df9919
+  registry.json, pipelines/*.json (15), shaders/*.glsl (30)
+  toolchain slangc 2026.12.0.1, spirv-cross vulkan-sdk-1.4.357.0, glslang 11:16.5.0 (pinned)
+```
+
+One file, three kinds of content, because the same build is read three ways:
+`registry.json` for a consumer choosing a pipeline, one self-contained envelope
+per pipeline — contract, uniform layout and sources inline — for one rendering
+it, and the `.glsl` files for a person. The archive is written whole or not at
+all: everything is built and checked in memory, then written to a temporary
+file and renamed into place. It is also reproducible, so identical inputs give
+an identical file and the hash above identifies the set. The default name
+carries both facts a reader wants — the version that built it and the first
+eight digits of that hash — and `--out` takes any path, with `{version}` and
+`{sha8}` filled in wherever they appear; a plain `shaders.zip` is a fixed name.
+
+Give a directory instead of a `.zip` path and the same files are unpacked into
+it — to read them, or to build a subset with `--pipeline ID` (repeatable) while
+iterating on one shape. A subset carries no `registry.json`, because the index
+is what a consumer selects from and must not list a pipeline that was not
+built, and it cannot become an archive. `shader-foundry pipelines` lists the
+ids, and needs no toolchain installed.
+
+The executable versions a set is built with are pinned in the package. `emit`
+warns when the installed tools differ from the pins and refuses with
+`--strict-toolchain`; the manifest records what was actually used either way.
+
+The same from Python, when a build needs to do more around it:
+
+```python
+# requires: the shader toolchain (slangc, spirv-cross, glslang)
+from vcti.shader.compiler import discover_toolchain
+from vcti.shader.foundry import build_artifact_set, build_manifest, toolchain_info, write_archive
+
+toolchain = discover_toolchain()
+artifact_set = build_artifact_set(build_manifest(toolchain_info(toolchain)), toolchain)
+print(write_archive(artifact_set))          # shaders-<version>-<sha8>.zip, the default name
+```
+
+Inspect the matrix without compiling anything — 12 continuous-fringe pipelines
+over four data families and three vertex variants, plus 3 discrete-fringe ones:
+
+```python
+from vcti.shader.foundry import build_pipelines
+
+for pipeline in build_pipelines():
+    print(pipeline.id, list(pipeline.capabilities))
+# deform3.symtensor.fringe-float ['deform3', 'symtensor', 'fringe-float']
+```
+
+## Dependencies
+
+`vcti-shader-compiler`, `vcti-shader-base`, the feature packages
+(`vcti-shader-deform`, `-derive`, `-fringe`), plus `vcti-derived`. The shader
+toolchain executables (`slangc`, `spirv-cross`, `glslang`) are external, not pip
+dependencies. Nothing here needs a GL context: `moderngl` and `numpy` live in
+the `gl` extra, for the tests that prove each emitted pair links, draws, and
+computes what its file says it does; `pip install "vcti-shader-foundry[gl]"`
+pulls them in on a machine that has a GL stack.
+
+## Documentation
+
+| If you want to… | Read |
+|---|---|
+| Understand the system design and decisions | [docs/design.md](docs/design.md) |
+| Add a new shader feature | [docs/extending.md](docs/extending.md) |
+| See practical build workflows | [docs/patterns.md](docs/patterns.md) |
+| Navigate and modify the builder source | [docs/source-guide.md](docs/source-guide.md) |
+| Look up a specific function or type | [docs/api.md](docs/api.md) |

vcti_shader_foundry-3.0.0/README.md

@@ -0,0 +1,112 @@
+# vcti-shader-foundry
+
+The shader artifact-set **builder**: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers.
+
+## Overview
+
+`vcti-shader-foundry` is the assembler of the shader system — the offline build
+tool that turns the installed shader features into the committed artifact set
+the runtime ships. It composes the features it lists (`vcti-shader-deform`,
+`-derive`, `-fringe`) into the pipeline matrix, drives `vcti-shader-compiler`
+to emit and validate GLSL ES, checks every result against its contract, and
+packs the shaders, one envelope per pipeline and the `registry.json` index into
+a single archive, written atomically, for a consumer to take as it likes.
+
+Composition is the whole job, and it is the part no feature can do: each
+feature declares its own fields and cannot see what it is combined with, so the
+builder is where the clip-space transform that belongs to nobody is added,
+where a field name two features declare differently is rejected, and where the
+manifest — the only contract the runtime reads — is written.
+
+It is **not** the toolchain and **not** the vocabulary: the `.slang → GLSL ES`
+machinery lives in `vcti-shader-compiler`, the specs you declare fields with in
+`vcti-shader-base`, and each shader feature in its own package. See
+[docs/design.md](docs/design.md) for the system design and
+[docs/extending.md](docs/extending.md) for adding a shader feature.
+
+## Installation
+
+```bash
+pip install vcti-shader-foundry
+```
+
+This is a build tool, not a runtime dependency; install it in the authoring
+environment alongside the feature packages you want built. The shader compilers
+(`slangc`, `spirv-cross`, `glslang`) are external and pinned — discovered via
+`SLANG_DIR` / `SPIRV_CROSS_DIR` / `GLSLANG_DIR` or `PATH`.
+
+## Quick Start
+
+Build the artifact set as one archive:
+
+```console
+$ shader-foundry emit
+wrote shaders-3.0.0-1fc4c3a7.zip: 15 pipeline(s), 531,073 bytes, sha256 1fc4c3a7f81222b59c74378dab9c5f46610b55276b319b5d200c62b0a6df9919
+  registry.json, pipelines/*.json (15), shaders/*.glsl (30)
+  toolchain slangc 2026.12.0.1, spirv-cross vulkan-sdk-1.4.357.0, glslang 11:16.5.0 (pinned)
+```
+
+One file, three kinds of content, because the same build is read three ways:
+`registry.json` for a consumer choosing a pipeline, one self-contained envelope
+per pipeline — contract, uniform layout and sources inline — for one rendering
+it, and the `.glsl` files for a person. The archive is written whole or not at
+all: everything is built and checked in memory, then written to a temporary
+file and renamed into place. It is also reproducible, so identical inputs give
+an identical file and the hash above identifies the set. The default name
+carries both facts a reader wants — the version that built it and the first
+eight digits of that hash — and `--out` takes any path, with `{version}` and
+`{sha8}` filled in wherever they appear; a plain `shaders.zip` is a fixed name.
+
+Give a directory instead of a `.zip` path and the same files are unpacked into
+it — to read them, or to build a subset with `--pipeline ID` (repeatable) while
+iterating on one shape. A subset carries no `registry.json`, because the index
+is what a consumer selects from and must not list a pipeline that was not
+built, and it cannot become an archive. `shader-foundry pipelines` lists the
+ids, and needs no toolchain installed.
+
+The executable versions a set is built with are pinned in the package. `emit`
+warns when the installed tools differ from the pins and refuses with
+`--strict-toolchain`; the manifest records what was actually used either way.
+
+The same from Python, when a build needs to do more around it:
+
+```python
+# requires: the shader toolchain (slangc, spirv-cross, glslang)
+from vcti.shader.compiler import discover_toolchain
+from vcti.shader.foundry import build_artifact_set, build_manifest, toolchain_info, write_archive
+
+toolchain = discover_toolchain()
+artifact_set = build_artifact_set(build_manifest(toolchain_info(toolchain)), toolchain)
+print(write_archive(artifact_set))          # shaders-<version>-<sha8>.zip, the default name
+```
+
+Inspect the matrix without compiling anything — 12 continuous-fringe pipelines
+over four data families and three vertex variants, plus 3 discrete-fringe ones:
+
+```python
+from vcti.shader.foundry import build_pipelines
+
+for pipeline in build_pipelines():
+    print(pipeline.id, list(pipeline.capabilities))
+# deform3.symtensor.fringe-float ['deform3', 'symtensor', 'fringe-float']
+```
+
+## Dependencies
+
+`vcti-shader-compiler`, `vcti-shader-base`, the feature packages
+(`vcti-shader-deform`, `-derive`, `-fringe`), plus `vcti-derived`. The shader
+toolchain executables (`slangc`, `spirv-cross`, `glslang`) are external, not pip
+dependencies. Nothing here needs a GL context: `moderngl` and `numpy` live in
+the `gl` extra, for the tests that prove each emitted pair links, draws, and
+computes what its file says it does; `pip install "vcti-shader-foundry[gl]"`
+pulls them in on a machine that has a GL stack.
+
+## Documentation
+
+| If you want to… | Read |
+|---|---|
+| Understand the system design and decisions | [docs/design.md](docs/design.md) |
+| Add a new shader feature | [docs/extending.md](docs/extending.md) |
+| See practical build workflows | [docs/patterns.md](docs/patterns.md) |
+| Navigate and modify the builder source | [docs/source-guide.md](docs/source-guide.md) |
+| Look up a specific function or type | [docs/api.md](docs/api.md) |

vcti_shader_foundry-3.0.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-shader-foundry"
+version = "3.0.0"
+description = "Shader artifact-set builder: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    # The compiler, without its GL extra: the builder drives the toolchain as
+    # subprocesses and never opens a GL context. Only the render test does, and
+    # it asks for the extra itself. 4.1 is the API this builder calls:
+    # toolchain_versions, which fills the manifest's provenance, arrived there.
+    "vcti-shader-compiler>=4.1.0",
+    "vcti-shader-base>=1.0.2",
+    # The features this build composes, listed in features.py.
+    "vcti-shader-deform>=1.1.0",
+    "vcti-shader-derive>=2.1.0",
+    "vcti-shader-fringe>=1.1.0",
+    # The data family is what the pipeline matrix iterates, so the composer
+    # names the type even though every value it uses comes from derive's
+    # implemented set. Kept in step with derive's own floor.
+    "vcti-derived>=4.0,<5",
+]
+
+[project.urls]
+Repository = "https://github.com/vcollab/vcti-python-shader-foundry"
+Changelog = "https://github.com/vcollab/vcti-python-shader-foundry/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.shader.foundry", "vcti.shader.foundry.*"]
+
+[tool.setuptools.package-data]
+"vcti.shader.foundry" = ["py.typed", "slang/*.slang"]
+
+[project.scripts]
+shader-foundry = "vcti.shader.foundry.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+# The render test alone opens a GL context and builds vertex buffers; the
+# builder does neither. `gl` is the fleet's name for that extra, and it is
+# separate from `test` because moderngl's glcontext has no prebuilt wheel for
+# every platform and Python the matrix runs, and building it needs X11 headers
+# a plain runner lacks. ci.yml installs `test` and skips the render test for
+# want of a toolchain anyway; ci-shader.yml installs `test,gl`.
+gl = ["vcti-shader-compiler[gl]>=4.1.0", "numpy>=1.26"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.shader.foundry --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_shader_foundry-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_shader_foundry-3.0.0/src/vcti/shader/foundry/__init__.py

@@ -0,0 +1,111 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.shader.foundry — the shader artifact-set builder.
+
+The builder composes the installed features into shaders, compiles them, and
+writes the artifact set: the shader stages, one self-contained envelope per
+pipeline, and the ``registry.json`` index a consumer selects from. Its pieces:
+
+- :mod:`features` — the features this build composes, listed explicitly, and the
+  Slang search paths and capability vocabulary derived from them.
+- :mod:`manifest` — the artifact-set manifest and its serialization. It lives in
+  the builder because the builder is the only thing that produces one, so the
+  document and the code that assembles it stay together.
+- :mod:`compose` — the pipeline matrix: the two shapes the features combine
+  into, the clip transform no feature owns, and the cross-feature field-name
+  checks no feature can perform alone.
+- :mod:`emit` — compiles each composed pipeline through the toolchain, checks
+  the result against its contract, and publishes the staged set: the GLSL
+  stages, the envelopes, and the index.
+- :mod:`pins` — the toolchain versions a set is built with, and the drift
+  check an emit runs against them.
+- :mod:`cli` — the ``shader-foundry`` command.
+
+Nothing here opens a GL context. The builder drives the toolchain as
+subprocesses and emits files; rendering a pipeline to an image is a consumer's
+job, and the only GL in this repo is in the tests that prove each emitted pair
+links, rasterizes and computes what its file says it does.
+"""
+
+from importlib.metadata import version
+
+from .compose import (
+    CLIP_TRANSFORM,
+    VERTEX_STAGES,
+    build_manifest,
+    build_pipelines,
+    category_pipeline,
+    derived_value_pipeline,
+)
+from .emit import (
+    ARCHIVE_NAME,
+    SLANG_DIR,
+    SOURCES,
+    ArtifactSet,
+    CompiledPipeline,
+    SlangSource,
+    archive_bytes,
+    archive_name,
+    build_artifact_set,
+    compile_pipeline,
+    contract_problems,
+    toolchain_info,
+    write_archive,
+    write_tree,
+)
+from .features import FEATURES, capability_vocabulary, features_for, include_dirs
+from .manifest import (
+    SCHEMA_VERSION,
+    GeneratorInfo,
+    Manifest,
+    PipelineContract,
+    ToolchainInfo,
+    contract_sha256,
+    dump_envelope,
+    dump_manifest,
+    manifest_to_dict,
+    pipeline_envelope,
+)
+from .pins import PINNED_TOOLCHAIN, toolchain_drift
+
+__version__ = version("vcti-shader-foundry")
+
+__all__ = [
+    "ARCHIVE_NAME",
+    "CLIP_TRANSFORM",
+    "FEATURES",
+    "ArtifactSet",
+    "CompiledPipeline",
+    "GeneratorInfo",
+    "Manifest",
+    "PINNED_TOOLCHAIN",
+    "PipelineContract",
+    "SCHEMA_VERSION",
+    "SLANG_DIR",
+    "SOURCES",
+    "SlangSource",
+    "ToolchainInfo",
+    "VERTEX_STAGES",
+    "__version__",
+    "archive_bytes",
+    "archive_name",
+    "build_artifact_set",
+    "build_manifest",
+    "build_pipelines",
+    "capability_vocabulary",
+    "category_pipeline",
+    "compile_pipeline",
+    "contract_problems",
+    "contract_sha256",
+    "derived_value_pipeline",
+    "dump_envelope",
+    "dump_manifest",
+    "features_for",
+    "include_dirs",
+    "manifest_to_dict",
+    "pipeline_envelope",
+    "toolchain_drift",
+    "toolchain_info",
+    "write_archive",
+    "write_tree",
+]

vcti_shader_foundry-3.0.0/src/vcti/shader/foundry/cli.py

@@ -0,0 +1,212 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""The ``shader-foundry`` command.
+
+Emitting the artifact set is the builder's whole output, and it was reachable
+only by writing a Python script around the library. That is a poor front door
+for the thing every consumer of the set begins from — a CI job regenerating
+artifacts, or someone building a set to see what comes out.
+
+``emit --out shaders.zip`` writes the set as one archive, which is the form a
+consumer takes it in. ``emit --out some/dir`` unpacks the same files into a
+directory, for reading them or for ``--pipeline`` subsets while iterating; an
+archive is always the complete set, so the two options do not combine.
+
+Listing needs no toolchain, which is deliberate: ``--pipeline`` takes ids, and
+finding one should not require having slangc installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from vcti.shader.compiler import ToolchainError, discover_toolchain
+
+from .compose import build_manifest
+from .emit import (
+    ARCHIVE_NAME,
+    INDEX_FILE,
+    PIPELINES_DIR,
+    SHADERS_DIR,
+    SOURCES,
+    SlangSource,
+    build_artifact_set,
+    toolchain_info,
+    write_archive,
+    write_tree,
+)
+from .pins import toolchain_drift
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shader-foundry",
+        description="Compose and emit the shader artifact set.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    emit = sub.add_parser("emit", help="compile the artifact set and write it out")
+    emit.add_argument(
+        "-o",
+        "--out",
+        type=Path,
+        default=Path(ARCHIVE_NAME),
+        help=(
+            "where to write: a path ending in .zip is the set as one archive, written "
+            "atomically, and may carry {version} and {sha8}, filled from the set that "
+            f"was built (default: {ARCHIVE_NAME}); anything else is a directory the same "
+            "files are unpacked into"
+        ),
+    )
+    emit.add_argument(
+        "--pipeline",
+        action="append",
+        metavar="ID",
+        help=(
+            "build only this pipeline; repeatable, and the default is all of them. "
+            "Only for a directory: an archive is always the complete set"
+        ),
+    )
+    emit.add_argument(
+        "--strict-toolchain",
+        action="store_true",
+        help=(
+            "refuse to emit unless every tool is the pinned version; without it a "
+            "difference is a warning and the emit proceeds"
+        ),
+    )
+
+    sub.add_parser("pipelines", help="list the pipelines this build composes")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI; return the process exit code."""
+    args = _build_parser().parse_args(argv)
+
+    if args.command == "pipelines":
+        for pipeline_id in SOURCES:
+            print(pipeline_id)
+        return 0
+
+    return _emit(args)
+
+
+def _select(requested: Sequence[str] | None) -> dict[str, SlangSource] | None:
+    """The sources to emit, or ``None`` if an id was not recognized.
+
+    A typo'd id is refused rather than quietly emitting nothing: a build that
+    reports success having written no pipeline is the kind of thing a CI job
+    keeps doing for weeks.
+    """
+    if not requested:
+        return dict(SOURCES)
+    unknown = sorted(set(requested) - set(SOURCES))
+    if unknown:
+        print(
+            f"error: no pipeline(s) {', '.join(unknown)} in this build. "
+            "Run 'shader-foundry pipelines' for the list.",
+            file=sys.stderr,
+        )
+        return None
+    return {pipeline_id: SOURCES[pipeline_id] for pipeline_id in requested}
+
+
+def _is_archive(path: Path) -> bool:
+    return path.suffix.lower() == ".zip"
+
+
+def _emit(args: argparse.Namespace) -> int:
+    out: Path = args.out
+    if not _is_archive(out) and ("{" in str(out) or "}" in str(out)):
+        print(
+            "error: {version} and {sha8} are filled in an archive's name; a directory "
+            "target takes a plain path",
+            file=sys.stderr,
+        )
+        return 2
+    if _is_archive(out) and args.pipeline:
+        # Refused up front: an archive is the set, and a file that looked like
+        # one while holding three pipelines is the artefact this rule exists to
+        # make impossible.
+        print(
+            "error: an archive is always the complete set; drop --pipeline, or give a "
+            "directory to write a partial set into",
+            file=sys.stderr,
+        )
+        return 2
+    sources = _select(args.pipeline)
+    if sources is None:
+        return 2
+    try:
+        toolchain = discover_toolchain()
+    except ToolchainError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+
+    provenance = toolchain_info(toolchain)
+    drift = toolchain_drift(provenance)
+    for line in drift:
+        print(f"warning: toolchain is not the pinned one: {line}", file=sys.stderr)
+    if drift and args.strict_toolchain:
+        # Refused before anything is built: the point of --strict-toolchain is
+        # that a set from the wrong tools never exists to be committed.
+        print(
+            "error: --strict-toolchain given and the toolchain differs from the pins; "
+            "install the pinned versions or emit without --strict-toolchain",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        artifact_set = build_artifact_set(build_manifest(provenance), toolchain, sources=sources)
+        if _is_archive(out):
+            out = write_archive(artifact_set, out)
+        else:
+            write_tree(artifact_set, out)
+    except ValueError as error:
+        # A contract the shader does not honour, a partial set over an index:
+        # each is a refusal with a reason, and neither wrote anything.
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+
+    count = len(artifact_set.pipeline_ids)
+    if _is_archive(out):
+        data = out.read_bytes()
+        print(
+            f"wrote {out}: {count} pipeline(s), {len(data):,} bytes, "
+            f"sha256 {hashlib.sha256(data).hexdigest()}"
+        )
+        print(
+            f"  {INDEX_FILE}, {PIPELINES_DIR}/*.json ({count}), {SHADERS_DIR}/*.glsl ({count * 2})"
+        )
+    else:
+        print(f"wrote {count} pipeline(s) to {out}")
+        if artifact_set.complete:
+            print(f"  index     {INDEX_FILE}")
+        else:
+            # Said plainly, because a partial set that looked complete is the
+            # failure the rule exists to prevent: registry.json is what a
+            # consumer selects from, so only a complete set has one.
+            print(
+                f"  index     not written: {count} of {len(SOURCES)} pipelines; "
+                f"only a complete set has a {INDEX_FILE}"
+            )
+        print(f"  envelopes {PIPELINES_DIR}/*.json ({count})")
+        print(f"  shaders   {SHADERS_DIR}/*.glsl ({count * 2})")
+    # Printed because it is the moment provenance is captured: if the emitted
+    # GLSL moves and no shader source did, this line is the reason.
+    print(
+        f"  toolchain slangc {provenance.slangc}, "
+        f"spirv-cross {provenance.spirv_cross}, glslang {provenance.glslang}"
+        + (" (differs from the pins; see warnings)" if drift else " (pinned)")
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())