pg-maker 0.1.0__py3-none-any.whl

pg_maker-0.1.0.data/data/share/doc/pg-maker/README.md

@@ -0,0 +1,163 @@
+# pg_maker
+
+A Python controller for building PostgreSQL distributions, packages and documentation
+in isolated Docker environments. It also provides Git development sessions for
+editing patches, recovering failed builds and rebuilding individual extensions.
+
+The current package is an **alpha**. The implemented platform is Debian 13 / x86_64,
+with release/debug builds and DEB packages. The PostgreSQL catalog covers majors
+14–19, including beta/RC identities; versions below 14 are unsupported. Catalog
+coverage is distinct from validation coverage: see the [major-version report](docs/validation/postgresql-majors.md).
+RPM, other platforms and distribution repository publishing remain on the
+[roadmap](docs/roadmap.md).
+
+## Installation
+
+Requires Linux and Python 3.10+. Container operations require a local Docker daemon;
+Git development sessions also require Git. Installing the Python package and reading
+capabilities do not require Docker.
+
+From PyPI:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install pg-maker
+.venv/bin/pg-maker --help
+```
+
+For development, from a source checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/pg-maker --help
+.venv/bin/pg-maker --component-capabilities
+.venv/bin/pg-maker doctor --machine
+```
+
+A built wheel can be installed with `python -m pip install /path/to/pg_maker-VERSION-py3-none-any.whl`.
+
+## Build a distribution
+
+```bash
+pg-maker init example
+pg-maker validate example/build.yaml
+pg-maker config show example/build.yaml --resolved
+pg-maker env prepare example/build.yaml --out example/environments.json --operations example/operations
+pg-maker resolve example/build.yaml --environments example/environments.json --out example/lock.json --input-store example/inputs --operations example/operations
+pg-maker plan example/lock.json --out example/plan.json --goal build
+pg-maker build example/lock.json --plan example/plan.json --operations example/operations --detach
+```
+
+`init` creates editable vendor/defaults/documentation YAML, a `my-feature` variant,
+component recipes, schemas and the built-in socket-directory patch. The initial
+target is PostgreSQL 18.1 / Debian 13 / x86_64 / DEB, without documentation.
+The default components are `pg_stat_statements`, `pg_stat_kcache 2.3.2` and
+`pg_wait_sampling 1.1.11`. External sources are pinned by commit SHA. Set
+`components: []` to omit additional extensions. See [component recipes](docs/interfaces/components.md).
+
+`env prepare` downloads missing base images and installs dependencies inside
+containers. Its result records build/test image IDs, package versions and toolchain
+inventory. `resolve` freezes source commits, submodules, snapshots, archive
+checksums and ChangeSets in a BuildLock. Offline resolution reuses stored inputs
+and reports missing ones. Both operations support `--detach` and `--request-id`.
+
+The build user defaults to `1000:1000` and must match the non-root owner of the
+workspace. Environment preparation creates this user inside the image. Build
+commands run with networking disabled. Outputs stay inside the operation directory.
+
+**Database tests are disabled by default while developing the utility.** A normal
+build compiles the candidate and components without `check`, `check-world`,
+component tests, acceptance tests or a baseline build. Reports remain `unverified`,
+with `db_tests=skipped` and `publication_eligible=false`. Tests of pg_maker itself
+remain enabled.
+
+Use `--goal package` to build server/client/libpq DEBs, manifests, installation
+instructions and HTML/JSON reports. A quick package build remains unverified.
+The long source/database test adapter currently supports major 18 only:
+
+```bash
+pg-maker build example/lock.json --run-db-tests --operations example/operations
+# Explicitly requests source and installed-package qualification:
+pg-maker build example/lock.json --goal verified --operations example/operations
+```
+
+A supplied plan controls the test mode; create it with `plan --run-db-tests` when
+needed. `--skip-db-tests` explicitly selects the quick path. Successful source
+suites grant at most `source-verified`; `package-verified` requires installed-package
+qualification too. See [build](docs/interfaces/build.md) and [packaging](docs/interfaces/packaging.md).
+
+## Build documentation only
+
+```bash
+pg-maker init docs-project --with-doc --doc-language en
+pg-maker env prepare docs-project/build.yaml --out docs-project/environments.json
+pg-maker resolve docs-project/build.yaml --environments docs-project/environments.json --out docs-project/lock.json
+pg-maker docs build docs-project/lock.json
+```
+
+`docs build` builds documentation without compiling the server or producing DEBs.
+It accepts official archive/Git sources or a snapshot of a locally modified source
+tree. Set `branding: none` for upstream PostgreSQL branding. The default HTML uses
+`sphinx_book_theme`, with an expandable sidebar, page contents and local search.
+The footer uses the selected product, version, feature, language and optional vendor
+links. `html_backend: docbook` selects the original DocBook layout explicitly.
+
+`config/documentation.yaml` selects HTML/man/PDF. The two external extensions'
+guides join the main Sphinx HTML/PDF manual when documentation is enabled.
+Russian PostgreSQL output requires a complete, current external translation bundle;
+the project's own Markdown documentation is English. HTML/PDF can be packaged in
+a separate docs DEB, with manpages assigned to the packages that own their commands.
+See the [documentation contract](docs/interfaces/documentation.md).
+
+## Develop code and patches
+
+```bash
+pg-maker dev open development --from-run example/operations/FAILED_RUN
+pg-maker dev status development
+# Edit the source paths returned by status, then record a patch:
+pg-maker dev patch development commit --scope component:pg-wait-sampling --id fix-build
+pg-maker dev explain development --component pg-wait-sampling
+pg-maker dev build development --component pg-wait-sampling
+```
+
+Each session owns real Git repositories. It can import an existing local repository
+with history, maintain intermediate commits, refresh patches, pop/push a series and
+resolve rebase conflicts. New iterations freeze changed inputs into new locks;
+`resume` retains its original meaning: retry the same operation with the same inputs.
+Independent extensions and the core can be reused when their inputs match. Header,
+ABI, toolchain and declared dependency changes invalidate affected results.
+[Development guide](docs/development.md) and [interface contract](docs/interfaces/development.md).
+
+## Observe and retain results
+
+```bash
+pg-maker status example/operations/RUN --machine
+pg-maker events example/operations/RUN --after-sequence 0 --limit 20 --machine
+pg-maker wait example/operations/RUN --timeout 120 --machine
+pg-maker cancel example/operations/RUN --machine
+pg-maker export example/operations/RUN --out exported-result
+```
+
+The detached worker owns the operation. Closing a waiting CLI does not cancel it;
+cancellation is explicit and repeatable. `status` returns success when it can read
+the operation, even if the operation failed; `wait` returns the operation's exit code.
+The [Python API](docs/interfaces/api.md) and optional pg_play CLI/MCP integration
+use the same service and machine contract.
+
+Source stores, workspaces, checkpoints and Docker caches consume disk space.
+Check `df -h`, workspace sizes and `docker system df` before long runs. Use explicit
+preview/apply cleanup and preserve needed outputs. See [storage and cleanup](docs/development-storage.md).
+
+## Project documentation
+
+- [Architecture](docs/architecture.md) and [reuse decisions](docs/reuse.md).
+- [Roadmap and implementation limits](docs/roadmap.md).
+- [Interface specifications](docs/interfaces/README.md).
+- [Validation reports](docs/validation/stage56.md), [documentation](docs/validation/stage7.md)
+  and [integration](docs/validation/integration.md).
+- [Contributing and local checks](CONTRIBUTING.md).
+- [Git and PyPI release procedure](docs/releasing.md).
+
+Distributed under the [MIT License](LICENSE). Third-party test fixtures retain their
+original copyright and license notices.

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+`pg_maker` is an independent Python controller. The CLI parses input and displays
+results; `MakerService` owns application operations; workers execute durable jobs.
+The pg_play MCP adapter uses the same service contract through the machine CLI.
+There are no runtime imports from sibling projects.
+
+```text
+src/pg_maker/
+  cli.py, api.py             CLI and application service
+  models.py, documents.py    Typed requests, schemas and semantic validation
+  errors.py, storage.py      Stable errors, strict JSON, hashes, atomic IO and locks
+  security.py, progress.py   Secret references, redaction and progress logging
+  assets.py                  Idempotent project initialization from package data
+  config.py, yamlio.py       Strict YAML, effective configuration and provenance
+  identity.py                Versions, names and installation paths
+  development/              Owned Git sessions, patch stacks, iteration CLI
+  execution/                Workers, state/events, cancellation, build and recovery
+  runners/                  Runner protocol and Docker implementation
+  planning/                 Environment preparation, resolution, locks, DAGs and reuse keys
+  sources/                  Git/archive/snapshot resolution and content-addressed inputs
+  changes/                  ChangeSets, application receipts and agent workspaces
+  builders/                 Autotools and component builders
+  packaging/                InstallTree, package roles and DEB output
+  validation/               Source, acceptance and installed-package checks
+  documentation/            Structural writer, translations, DocBook/Sphinx and theme
+  artifacts/                Manifests, output inventory and reports
+  integrations/             pg_play/component/v1 machine contract
+  schemas/                  Schemas for implemented documents
+  bundled/                  Editable files emitted by init
+  recipes/                  Platform and PostgreSQL major-version catalogs
+```
+
+`execution` contains process streaming and timeouts, a durable event journal,
+resource ownership, immutable checkpoints, component caches and disk preflight.
+A development iteration creates a new immutable BuildLock/BuildPlan; it does not
+change the inputs of an existing operation. Git checkouts remain private to the
+session and are separate from build scratch directories.
+
+## Extension rules
+
+Specify inputs, outputs, failure behavior and an MD contract before adding an
+adapter. Add contract tests at boundaries that can actually vary. `Runner` is a
+protocol because execution backends can be replaced. Built-in implementations use
+explicit registries. Ordinary service functions do not need an abstract base class,
+dependency injection container or automatic plugin discovery.
+
+Future adapters can extend source resolution, builders, package formats,
+qualification and publication. The current executable boundary is documented in
+[the roadmap](roadmap.md) and reported by `--component-capabilities`. Placeholder
+module directories do not imply that their adapters are implemented.
+
+The build DAG reuses runner/state/process primitives. Infrastructure
+`container_commands` requests remain a separate operation type, with their own
+schema; they must not silently acquire BuildPlan semantics.

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/development-storage.md

@@ -0,0 +1,72 @@
+# Disk use during development
+
+Check capacity before a build and after a series of debugging runs:
+
+```bash
+df -h /tmp .
+du -sh /tmp/pg-maker-*
+docker system df
+docker ps -a
+```
+
+Storage grows independently in InputStore, per-feature/language source/object/prefix
+workspaces, documentation output, recovery checkpoints, shared caches, previous
+attempt archives, exported results and Docker images/build cache. `--no-cache`
+disables shared reuse, but keeps private checkpoints for resume.
+
+`execution.limits.min_free_disk_bytes` is a free-space reserve checked before steps
+and checkpoint creation. Development snapshot/copy paths also estimate their copy
+size. This is a preflight guard, not a filesystem quota: a compiler or renderer can
+consume additional space within a step. Reserve enough space for expected working
+trees. Prefer a small fixture or documentation-only goal when a full build is
+unnecessary. Database tests remain opt-in.
+
+## Completed operations
+
+Check status and owned resources before cleanup. Cancel active operations through
+`pg-maker cancel` and wait for resource release. Export outputs first:
+
+```bash
+pg-maker export operations/RUN --out exported-result
+pg-maker cleanup operations/RUN --export exported-result --out cleanup.json
+pg-maker cleanup operations/RUN --apply cleanup.json
+```
+
+The verified preview targets only `workspace/build`, `workspace/source` and
+checkpoints. Packages, logs and reports remain. Resume is rejected after scratch
+cleanup. Removing InputStore or an image ID referenced by a lock also prevents an
+offline rebuild. Input stores can be shared through `transport.input_store`; inspect
+those references before removing an entire temporary project.
+
+## Development sessions
+
+```bash
+pg-maker dev pin development 000003
+pg-maker dev prune development --keep-last 2 --out prune.json
+pg-maker dev prune development --keep-last 2 --apply prune.json
+```
+
+Current and pinned iterations, working Git trees and patch stacks are retained.
+Old inactive iteration/debug scratch is removed only after the plan is revalidated.
+Locks, reports and input snapshots remain available. Cleaned iterations cannot be
+resumed. Use the separate cache preview/apply operation to reclaim unpinned entries:
+
+```bash
+pg-maker cache prune development/cache --out cache-prune.json
+pg-maker cache prune development/cache --apply cache-prune.json
+```
+
+Completed ordinary operations retain cache pins until their lifecycle cleanup
+releases them. InputStore garbage collection is not automatic.
+
+## Docker storage
+
+`docker image prune -a`, `docker builder prune` and `docker volume prune` affect the
+shared Docker daemon. They are manual administrative operations, never pg_maker
+finalizers. Prefer deleting specific unused images after checking saved locks.
+pg_maker removes only containers/resources owned by its operations, including their
+anonymous volumes; named volumes are retained.
+
+Historical observation: on 2026-10-17, removing completed stage-4 workspaces reduced
+that temporary directory from about 12 GB to 40 MB, releasing roughly 11 GB. State,
+logs and reports were retained; other projects' Docker images/volumes were untouched.

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/development.md

@@ -0,0 +1,86 @@
+# Developing PostgreSQL and extensions
+
+Start with prepared environments, a BuildLock and retained InputStore. Git commands
+operate inside repositories owned by the session. `--repository` copies a local
+PostgreSQL repository with history; the original checkout stays with its owner.
+
+```bash
+pg-maker dev open work --lock example/lock.json
+# Alternative: --from-run /path/to/operations/RUN
+# Preserve local history with --repository /path/to/repository.
+pg-maker dev status work
+```
+
+Status returns `trees.postgresql.source` and paths such as
+`trees.component:pg-wait-sampling.source`. Edit these with an ordinary editor.
+Bundled contrib lives under PostgreSQL's `contrib`; external components have their
+own Git trees. Recipe ID `pg-wait-sampling` differs from SQL name `pg_wait_sampling`.
+
+```bash
+pg-maker dev patch work commit --scope component:pg-wait-sampling --id fix-build
+pg-maker dev explain work --component pg-wait-sampling
+pg-maker dev build work --component pg-wait-sampling --detach
+pg-maker dev status work
+# After the iteration has stopped:
+pg-maker dev exec work --component pg-wait-sampling -- make -n
+pg-maker dev build work --goal package --detach
+```
+
+Build snapshots uncommitted edits too. Editing after startup cannot change that
+iteration's immutable inputs. Package/docs goals use the complete feature;
+documentation must be enabled in the initial lock. Debug execution uses a separate
+copy of the selected iteration's working results. The default is the latest iteration;
+`--iteration 000001` selects another and `--target` selects a platform.
+
+Use ordinary status/events/cancel commands with the returned operation_directory.
+Build iterations support ordinary resume; debug commands are repeated as new runs.
+A corrected source tree requires a new `dev build`. Resume retries the original
+operation with its original inputs.
+
+## Patch series
+
+```bash
+pg-maker dev patch work import --patch /path/to/series.json
+# A single patch: --patch /path/to/fix.patch --id fix-name
+pg-maker dev patch work pop --count 2
+# Edit the current patch; refresh replays the remaining series after it.
+pg-maker dev patch work refresh
+pg-maker dev patch work rebase --onto-lock /path/to/new-version-lock.json
+# Resolve conflicting files, then continue:
+pg-maker dev patch work continue
+# Or restore the state before the pending operation:
+pg-maker dev patch work abort
+pg-maker dev patch work export --out patch-series
+```
+
+Each patch has a Git commit. Ordinary Git commits can be imported into the linear
+series with `dev patch adopt`. Pop retains the unapplied tail; push reapplies it.
+An external-component rebase uses `--scope component:ID --onto-source HASH`, referring
+to a snapshot already in the session's InputStore. PostgreSQL rebase uses a new lock
+and requires the same component repository set. Conflicted imports retain the rest
+of the queue. Export writes format-patch files and `series.json`.
+
+Before full release qualification, incorporate exported source changes and acceptance
+tests into the regular release configuration and resolve again. Development snapshots
+remain unverified.
+
+## Retention
+
+```bash
+pg-maker dev pin work 000001
+pg-maker dev prune work --keep-last 2 --out cleanup.json
+pg-maker dev prune work --keep-last 2 --apply cleanup.json
+pg-maker cache prune work/cache --out cache-cleanup.json
+pg-maker cache prune work/cache --apply cache-cleanup.json
+```
+
+Prune retains working Git trees, current/pinned iterations, inputs, locks, journals
+and outputs. It removes selected old build/checkpoint/debug scratch and releases
+those runs' cache pins. A separate cache prune can reclaim unreferenced CAS files.
+Global Docker images/volumes and other projects' inputs are untouched.
+
+Core or bundled-contrib edits conservatively invalidate PostgreSQL's combined build.
+External components are separate. Core headers/ABI, flags or image changes invalidate
+affected extensions. Verified caches can supply successful results; partial object
+files only accelerate a new make invocation. See [session contract](interfaces/development.md)
+and [recovery](interfaces/recovery.md).

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/interfaces/README.md

@@ -0,0 +1,32 @@
+# Interface specifications
+
+These contracts describe implemented public behavior:
+
+- [API and CLI](api.md)
+- [Models and documents](documents.md)
+- [Runner and subprocesses](execution.md)
+- [State, events and cancellation](state.md)
+- [Errors, logs and secrets](observability.md)
+- [Files, hashes and package resources](storage.md)
+- [Machine contract](machine.md)
+- [Configuration and identity](configuration.md)
+- [PostgreSQL major-version catalog](postgresql.md)
+- [Sources and InputStore](sources.md)
+- [Environment preparation](environments.md)
+- [BuildLock and BuildPlan](planning.md)
+- [ChangeSets and agent workspaces](changes.md)
+- [Git sessions, patches and development iterations](development.md)
+- [Default components and their documentation](components.md)
+- [Documentation pipeline](documentation.md)
+- [Build backend, components and test evidence](build.md)
+- [InstallTree, PackageSpec, DEB and installation checks](packaging.md)
+- [Resume, cache, resource guards and export](recovery.md)
+- [Runtime image handoff](runtime.md)
+- [Scratch cleanup](cleanup.md)
+
+[Distribution publication](publication.md) is a design boundary with no executable
+adapter yet. Python package publication has a separate [release procedure](../releasing.md).
+
+Public behavior changes start with the corresponding MD contract and JSON Schema.
+Document compatibility explicitly. Private helpers need types, docstrings and
+validation at their public caller, rather than a separate specification per function.

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/interfaces/api.md

@@ -0,0 +1,75 @@
+# MakerService and CLI
+
+`api.MakerService(operations_directory: Path)` takes an absolute directory. The
+Python API does not read argparse state or change the working directory.
+
+| Method | Input | Result or effect |
+| --- | --- | --- |
+| doctor | None | Local Linux Docker version/architecture; unavailable daemon is a precondition failure |
+| start_operation | Typed request, optional operation/request IDs | Persist input, start worker, return OperationState |
+| status | Absolute operation directory | Read journal state; reconstruct snapshot when the owner is gone |
+| events | Directory, nonnegative cursor, limit 1–1000 | Events, last sequence and has-more flag |
+| cancel | Existing operation | Persist cancellation; clean verified orphan resources |
+| wait | Directory, optional positive timeout | Terminal state; waiting timeout does not cancel the worker |
+| config_show / validate | Manifest and overrides | Effective config/provenance/bindings or validated variants/requirements |
+| prepare_environments / resolve | Manifest and operation options | Durable operation producing EnvironmentManifest or BuildLock |
+| plan | Lock, goal, input store and test override | BuildPlan without downloads, Docker or compilation |
+| build | Lock or saved plan and execution options | Durable build operation |
+| resume / export / artifacts | Operation/result references | Verified retry or portable output references |
+| dev_open / dev_status / dev_patch | Session and patch inputs | Owned Git session and patch stack operations |
+| dev_build / dev_explain / dev_execute | Session and iteration/selection options | New iteration, reuse reasons or durable debug operation |
+| dev_pin / dev_prune | Session, iteration or retention plan | Preserve checkpoints or clean old scratch |
+
+```python
+from pathlib import Path
+from pg_maker.api import MakerService
+from pg_maker.models import CommandSpec, EnvironmentSpec, OperationRequest
+from pg_maker.runners.docker import current_user
+
+service = MakerService(Path("/absolute/project/operations"))
+request = OperationRequest(
+    EnvironmentSpec("sha256:" + "0" * 64, current_user()),  # Use a real local image ID.
+    (CommandSpec("kernel", ("uname", "-s"), timeout_seconds=30),),
+)
+state = service.start_operation(request, request_id="check-1")
+state = service.wait(service.directory / state["operation_id"])
+```
+
+Repeated request IDs with identical input hashes return the existing operation,
+including terminal operations. Different inputs produce `precondition_failed`;
+occupied operation IDs produce `ownership_error`. The request registry is locked.
+
+Preparation/resolve use the same worker, journal, cancellation and idempotency
+machinery. Inputs contain effective configuration and explicit bindings. Successful
+results contain document path, file SHA256 and semantic document hash. Their
+`--out` is a file; `--operations` selects the operations directory. `plan --out`
+writes JSON; otherwise it returns the document.
+
+`build(lock, goal=None, plan=None, plan_hash=None, run_db_tests=None,
+input_store=None, cache_store=None, use_cache=True, operation_id=None,
+request_id=None, components=None, reuse_from=None)` validates and starts BuildRequest.
+A supplied plan determines the default goal; otherwise it is build. The plan must
+match the reconstructed DAG and requested plan hash. Plan
+creation timestamps do not change request idempotency. The plan or lock controls
+the default test mode; explicit overrides must agree with a supplied plan. Changing
+that mode changes plan/input identity.
+
+Goals include source/build/package/verified and doc-source/translations/
+translated-docs/docs. Documentation commands use the same build service. Build-time
+feature/mode/documentation flags validate the lock instead of modifying it. Resolve
+again to change the locked configuration; development sessions create new locks for
+code edits. Results record reports, hashes, qualification, database tests, failures
+and publication eligibility. Only full successful qualification can grant eligibility.
+
+`runner check` exercises infrastructure commands using an existing immutable image;
+it is not a PostgreSQL build. `--detach` returns after worker startup; otherwise the
+CLI waits. `--machine` always uses the same envelope, including errors.
+
+Exit codes: invalid CLI/input 2, failed precondition 3, unsupported 4, partial 5,
+execution failure 6, cancellation 7, ownership 8. Status/events/cancel report the
+success of reading/requesting; operation status is in the result. SIGINT in a waiting
+CLI returns 130 without stopping the worker.
+
+New operation types require an input schema and explicit engine dispatch. New CLI
+commands call the same service. See [recovery](recovery.md), [documentation](documentation.md)
+and [development](development.md) for operation-specific contracts.

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/interfaces/build.md

@@ -0,0 +1,112 @@
+# PostgreSQL and component builds
+
+The initial backend is Autotools on Debian 13 / x86_64, with release/debug builds.
+The [catalog](postgresql.md) describes supported majors; the original end-to-end
+build target was PostgreSQL 18.1. `MakerService.build` creates a durable BuildRequest.
+Source only prepares sources. Without a supplied plan, the default goal is build;
+a supplied plan determines the goal unless explicitly overridden. Package, installed
+product harness and resume are implemented. Extended release-validation fixtures
+remain unsupported; build mode release is independently supported.
+
+## Quick mode and full tests
+
+`defaults.validation.run_db_tests=false` is the development default. Candidate core
+and components compile/install into a private prefix; expected test inventory,
+check/check-world, component tests/loading, acceptance and baseline are omitted.
+No test clusters are created. Reports say unverified, db_tests=skipped and
+publication_eligible=false. Utility tests are unaffected.
+
+`--run-db-tests` or Python true enables the full path; `--skip-db-tests`/false selects
+the quick path. None inherits a supplied plan or locked default. YAML changes require
+resolve. The effective boolean enters BuildPlan and its hash. An explicit flag that
+conflicts with a supplied plan fails before startup. The full evidence adapter currently
+supports PostgreSQL 18; other catalog majors support quick builds/docs only.
+
+`execution.build.execute_build(directory, token)` verifies immutable input, lock and
+implementation, reconstructs the selected DAG and compares plan hash. Removing a test
+step cannot preserve qualification. Branches run sequentially in separate containers
+and directories. Candidate receives common plus feature changes; full-test baseline
+receives common changes only. Selected components build in both branches.
+
+Full candidate order: sources → changes → integrated source components → configure →
+make → private prefix install → expected test inventory → check → world-bin →
+install-world-bin → check-world → components/tests → acceptance → report. Baseline
+runs core check and component/acceptance checks without check-world, recording
+source_test_scope=baseline-core. Acceptance without baseline expectations is candidate-only.
+
+Configure checks requested settings against Makefile.global/pg_config.h before compile,
+rejects unrecognized options and records its result. Compiler warnings are inventoried;
+a general warnings-as-errors filter is not implemented. Plans record argv/env/user/cwd,
+limits and timeouts; commands generated by native steps are recorded under branch
+output/commands.
+
+## Builders and components
+
+`builders.autotools` contains validate_build, extra_tests, expected_inventory,
+reconcile and required-test validation. Queries execute Make inside the container.
+A new backend needs a module, explicit dispatch, supported-settings schema and real
+source validation, not a plugin framework.
+
+Component integration copies source-tree inputs into unused source directories;
+overwriting existing PostgreSQL files requires a ChangeSet. Component build executes
+explicit make/install targets, with native/cluster tests only when enabled. Each
+component has a separate build_tools or build_and_test_tools step. A quick component
+reports built=true and tests=skipped, never passed.
+
+| Type | Build behavior |
+| --- | --- |
+| contrib | Selected PostgreSQL directory, explicit Make targets and optional load checks |
+| source-tree | Separate input copied into an unused source directory, then Make |
+| pgxs | Separate sources, USE_PGXS=1 and the exact private-prefix PG_CONFIG |
+| utility/library | Make; optional configure with prefix and explicit test targets |
+
+Full-test external components must declare test_targets. PGXS/contrib/source-tree
+REGRESS/ISOLATION/TAP inventory is collected before tests and reconciled afterward;
+empty inventory is not success. Build systems are not guessed. SQL extensions,
+shared libraries and preload settings are checked in fresh clusters. Internal
+headers/PGXS/ecpg support compilation but are excluded from distribution payloads.
+
+## Evidence and acceptance
+
+TAP is always configured and cannot be disabled by feature arguments. Full mode
+inventories configured SUBDIRS, REGRESS, ISOLATION, schedules and ECPG check.
+Check-world remains required for smoke qualification. OpenSSL enables ssl and
+libpq_encryption extras. GSSAPI/LDAP/OAuth and the extended release-validation profile
+require additional service fixtures and are explicitly unsupported when requested.
+
+TAP::Parser records each Perl script's plan, executed/failed/skipped assertions,
+exit/wait and skip_all. Unknown skip-all, empty or missing suites fail. Allowed
+not-applicable suites are declared in inventory before execution. Ordinary assertion
+SKIPs remain recorded. Successful PostgreSQL removes regression.out, so regression
+evidence comes from complete stdout grouped by make --output-sync=target, with
+name/count/TAP-plan reconciliation. Original logs, failure diffs and TAP logs remain.
+Configure/compiler warnings are recorded per step.
+
+Acceptance uses fresh PGDATA, private-prefix initdb/pg_ctl/psql, bounded readiness
+and ON_ERROR_STOP. Configuration and server.log live in PGDATA. SQL scripts are
+UTF-8 SQL; command scripts are YAML argv arrays without shell interpretation.
+Equals compares complete trimmed stdout; booleans map to psql t/f. Successful scripts
+have SQLSTATE 00000. Explicit SQLSTATE assertions may accept psql exit 3 with verbose
+stderr evidence; connection errors, timeouts and missing SQLSTATE remain failures.
+Prefix substitution works before and after packaging. Baseline assertion-failure
+is accepted only for the one named assertion ID.
+
+Required tests resolve to actual evidence IDs: acceptance ID, component.make-target,
+source/directory/regression-test or TAP script path. Skipped TAP cannot satisfy them;
+unknown IDs fail. Source builds grant at most source-verified and never publication
+eligibility. Quick/source-only runs remain unverified. Reports contain receipts,
+steps, counts, expectations, warnings and private prefix paths.
+
+## Execution and distribution continuation
+
+The non-root build user must match host mount ownership; environment preparation
+creates its passwd/group entries. The prefix is mounted below /opt only inside the
+container. Networking is off; memory/swap/CPU/shared memory are limited. Worker
+journal/process cleanup/cancellation are shared infrastructure. Keep-failed-environment
+retains only a stopped owned container, removable through cancel.
+
+Package uses InstallTree/PackageSpec/DEB. Verified adds isolated installation checks
+and can grant package-verified. Successful matrix branches survive failures elsewhere;
+partial reports list failures and return 5. Test steps are not ordinary cache hits.
+Command log references are relative to branch output and travel with caches/exports.
+See [packaging](packaging.md), [recovery](recovery.md) and [development](development.md).

pg_maker-0.1.0.data/data/share/doc/pg-maker/docs/interfaces/changes.md

@@ -0,0 +1,58 @@
+# Source changes
+
+`changes.loader.load_changes(references, base, version)` and `load_components(...)`
+validate documents, compatibility, requires/conflicts, unique IDs/revisions and
+explicit files. Stable topological order preserves available independent-node order.
+Operations and acceptance scripts have logical input names and hashes; resolve copies
+them into InputStore. Required tests merge without allowing different acceptance
+checks to share an ID.
+
+`changes.apply.apply_changes(source, feature, lock, store, branch, receipts, check)`
+applies changes; check observes cancellation. Each group works on a separate tree
+copy and publishes only after every operation and postcondition succeeds. Receipts
+record input/output hashes, diff, changed paths and applied/already_satisfied status.
+Already-satisfied is limited to the built-in socket patch's exact result.
+
+Resolve creates the common patch against current sources. The target full-line
+socket definition uses `/var/run/postgresql` and a comment describing shared server/
+libpq use. Existing configured lines are normalized to this representation; repeating
+the exact result does not change the tree.
+
+Groups and operations preserve explicit ordering. UTF-8 unified patches apply without
+shell, offsets or fuzz. Supported inputs include diff -u, git diff and git format-patch,
+with regular-file additions/deletions (100644/100755). Existing-file mode changes,
+binary changes, rename/copy and symlink patches are unsupported in this strict
+release ChangeSet adapter. The development Git stack has a separate Git-based adapter.
+
+Text insertion verifies cardinality, top/bottom order, context and optional input
+hash. Each top matches the first bottom before the next top; unrelated later table
+markers do not introduce ambiguity. Repeated insertion without a receipt fails.
+Changes cannot escape the source tree or traverse symlinks. Successful publication
+removes temporary source.before-N copies. Failure/cancellation preserves original
+inputs and never reapplies a partially modified group.
+
+New actions require explicit registry entries, versioned schemas and positive/negative
+fixtures. The only built-in source patch unifies the Unix socket directory; branding
+is explicit data.
+
+## Agent workspaces
+
+`changes.workspace.workspace(input_store, source_hash, destination)` copies a
+verified snapshot into a new destination/source and writes workspace.json. It checks
+source size plus a 4 GiB reserve and never hardlinks CAS. `export_changes(directory,
+output, id, postgresql)` compares against the verified base and emits ChangeSet plus
+unified diff. UTF-8 additions/deletions/edits, including no-final-newline files, are
+supported. Binary/symlink/mode changes are rejected. New file permissions follow umask
+when applying; empty directories do not appear in diffs.
+
+`validate_changes(file)` validates schema/referenced operation files and returns
+hashes with acceptance_executed=false. Export does not assert ABI/data/WAL compatibility;
+all remain unknown until separately specified and tested.
+
+With `workspace(..., lock=BuildLock, feature=ID)`, the base includes common and existing
+feature changes, stored as a separate CAS tree. `until="CHANGE_ID/OPERATION_ID"` stops
+before an operation for adapting it. Insert the resulting diff at that position;
+do not blindly append it. Without a lock, basis remains raw upstream. Export verifies
+the frozen base independently of later lock-file edits. Validation also checks
+insertion schemas and acceptance script hashes/existence; execution is separate.
+CLI workspace/export/validate and pg_play MCP share these fields.