Architecture Overview

PSGenerator separates build-time analysis from generated-module runtime execution.

Directory inputs
      │
      ▼
Build-PSModule
      │
      ├── Inspectors
      ├── Validators
      ├── Object model processors
      ├── Runtime adapters
      ├── Code generators
      ├── Template renderers
      └── Packaging providers
      │
      ▼
Self-contained PowerShell module
      │
      ├── import locally
      └── embed at /PSModule

The Directory Is the Source of Truth

The authored PSD1 defines the public command surface. Inspectors add directory facts, but Version 1 does not guess container mappings from file names or paths.

Generated output is reproducible build output, not the authoritative definition.

Build Context

Every stage receives one mutable context:

Property	Purpose
SpecificationPath	Resolved source PSD1
OutputPath	Resolved generation directory
DirectoryPath	Inspected directory, inferred from the specification location
Specification	Imported data-file dictionary
Inspection	Ordered directory metadata
Model	Validated normalized model
Artifacts	Published generated files and package
RenderRequests	Source payloads awaiting rendering
PluginExecutions	Ordered timing and failure records

ForceOutputReset records an explicit request to adopt unowned output. It affects only ownership classification at the reset boundary.

When the specification is directly beneath PSModule, the inspected directory is its parent. For an alternate specification location, that file's directory is the inspection root.

Stage Responsibilities

Inspectors

Read directory artifacts and add typed, ordered metadata to Inspection. They do not create build output.

Validators

Reject invalid identity, command, parameter, help, object ID, validation, completion, mapping, and runtime definitions.

Object Model Processors

Create the normalized Model. The orchestrator fails immediately if this stage does not produce one.

Runtime Adapters

Select and attach runtime behavior. Version 1 uses Docker for container-backed commands and preserves packaged local execution for inferred PowerShell sources.

Code Generators

Assert and reset the validated output destination, then generate in-memory source and metadata requests. The assertion runs inside the destructive reset helper, after validation and model creation and immediately before deletion. It rejects roots, source relationships, files, linked leaves, and scripts-tree overlap; force bypasses only the unowned-directory decision. The helper rechecks the output leaf and resolved identity immediately before deletion.

After creating clean output, reset writes Metadata/output.json before later build stages can fail. A pre-reset validation failure does not mutate existing output; a post-reset failure leaves marker-owned partial output that can be retried.

Template Renderers

Write metadata, command source, Markdown references, loader, and manifest. The orchestrator requires the metadata artifact before packaging begins.

Packaging Providers

Verify required files, command pages, command source, artifact paths, and manifest validity, require a valid output ownership marker, then publish the completed package artifact.

Deterministic Boundaries

Determinism comes from:

• ordered arrays and dictionaries in the normalized model;
• ordinal plugin and input sorting;
• one generated file per responsibility;
• UTF-8 output conventions; and
• a full output reset at the generation boundary.

Plugin behavior and changing external directory inputs can affect output, so trusted plugins must impose their own deterministic ordering.

Runtime Behavior

Generated modules contain no dependency on PSGenerator.

Container-backed commands:

1. validate native parameters;
2. convert bound parameters into ordered Docker arguments;
3. support -WhatIf;
4. discover Docker only when executing;
5. invoke docker run --rm; and
6. report non-zero exits.

Inferred PowerShell commands resolve and execute packaged local source beneath the module's Scripts directory.

Installation Architecture

Install-PSModule uses docker create, not docker run, so application entry points are not started. It copies /PSModule into a staging directory, validates the manifest, replaces the destination only when safe, and always attempts to remove the temporary container.