pg-maker 0.1.0__py3-none-any.whl

pg_maker/bundled/documentation/README.md

@@ -0,0 +1,20 @@
+# Component manuals
+
+These editable DocBook guides accompany the component recipes in `../components`.
+They are included only when their component is selected and documentation is enabled.
+The writer adds them to the upstream `contrib` appendix, using the same HTML theme,
+navigation, full-text search, PDF and translation pipeline as the rest of the book.
+
+| Guide | Source release | Pinned commit |
+| --- | --- | --- |
+| pg-stat-kcache.sgml | pg_stat_kcache 2.3.2 | 1e39814453ab747a3817cfdf4f6f6bd5c0fb9507 |
+| pg-wait-sampling.sgml | pg_wait_sampling 1.1.11 (SQL version 1.1) | 7e3a5fc937393596c0a51c5881dd63d7208408d1 |
+
+Guides contain distribution-specific setup instructions and references to those
+exact upstream revisions. Review the matching guide when changing a recipe's pin;
+resolve fixes both source commits and documentation asset hashes in the lock.
+These are maintained guides, not automatic imports of arbitrary upstream README files.
+The pg_stat_statements manual already belongs to the selected PostgreSQL source tree.
+
+English is the source language. Russian builds require reviewed translation bundles
+for the new sections under the existing translation policy.

pg_maker/bundled/documentation/pg-stat-kcache.sgml

@@ -0,0 +1,99 @@
+<sect1 id="pg-stat-kcache">
+ <title>pg_stat_kcache — operating system resource statistics</title>
+ <para><filename>pg_stat_kcache</filename> supplements
+ <xref linkend="pgstatstatements"/> with CPU consumption and filesystem I/O
+ counters. Use the two extensions together to identify queries that consume
+ CPU or cause reads and writes beyond PostgreSQL's shared buffers.</para>
+ <para>This distribution includes release 2.3.2. Installing its server package
+ supplies the library and SQL files; statistics collection is enabled separately
+ for an initialized cluster.</para>
+
+ <sect2 id="pg-stat-kcache-enable">
+  <title>Enabling collection</title>
+  <para>Add the required libraries to <filename>postgresql.conf</filename> inside
+  <envar>PGDATA</envar>, keeping any libraries already needed by the cluster.
+  The following example enables all three bundled diagnostic extensions:</para>
+  <programlisting>shared_preload_libraries = 'pg_stat_statements,pg_stat_kcache,pg_wait_sampling'
+compute_query_id = auto</programlisting>
+  <para>Restart the server after changing <varname>shared_preload_libraries</varname>.
+  Then connect as an administrator to each database where the SQL interface is
+  needed and execute:</para>
+  <programlisting>CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+CREATE EXTENSION IF NOT EXISTS pg_stat_kcache;</programlisting>
+  <para>The matching client is <filename>${paths.runtime_prefix}/bin/psql</filename>.
+  Use libraries from the same PostgreSQL build and major version as the server.
+  Existing databases are not modified by installing the package.</para>
+ </sect2>
+
+ <sect2 id="pg-stat-kcache-settings">
+  <title>Configuration</title>
+  <variablelist>
+   <varlistentry><term><varname>pg_stat_kcache.track</varname></term><listitem>
+    <para><literal>top</literal>, the default, records top-level statements;
+    <literal>all</literal> also records nested statements; <literal>none</literal>
+    disables collection. Nested and parent totals can overlap.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_stat_kcache.track_planning</varname></term><listitem>
+    <para>Controls planning measurements. The default is <literal>off</literal>;
+    planning counters remain zero while disabled.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_stat_kcache.linux_hz</varname></term><listitem>
+    <para>Kernel clock frequency used to compensate for CPU measurement sampling.
+    The default, <literal>-1</literal>, requests automatic detection at startup.</para>
+   </listitem></varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2 id="pg-stat-kcache-views">
+  <title>Views, counters and reset</title>
+  <para><structname>pg_stat_kcache_detail</structname> joins kernel counters to
+  query statistics. Its identity fields are <structfield>query</structfield>,
+  <structfield>top</structfield>, <structfield>datname</structfield> and
+  <structfield>rolname</structfield>.
+  <structname>pg_stat_kcache</structname> aggregates top-level statistics by database.
+  The function <function>pg_stat_kcache()</function> exposes the underlying rows,
+  including query, user and database identifiers.</para>
+  <para>Most measurements have a <literal>plan_</literal> and an
+  <literal>exec_</literal> variant. For example,
+  <structfield>exec_user_time</structfield> is execution CPU time in user mode.</para>
+  <informaltable><tgroup cols="2"><thead><row><entry>Counter suffix</entry><entry>Meaning</entry></row></thead><tbody>
+   <row><entry><literal>user_time</literal>, <literal>system_time</literal></entry><entry>CPU time in seconds, in user and kernel mode.</entry></row>
+   <row><entry><literal>reads</literal>, <literal>writes</literal></entry><entry>Filesystem I/O bytes attributed by the operating system.</entry></row>
+   <row><entry><literal>reads_blks</literal>, <literal>writes_blks</literal></entry><entry>The corresponding byte values divided by PostgreSQL's configured <varname>block_size</varname> in the SQL views (normally 8 KiB).</entry></row>
+   <row><entry><literal>minflts</literal>, <literal>majflts</literal></entry><entry>Minor and major page faults.</entry></row>
+   <row><entry><literal>nswaps</literal></entry><entry>Swaps reported by the operating system.</entry></row>
+   <row><entry><literal>msgsnds</literal>, <literal>msgrcvs</literal>, <literal>nsignals</literal></entry><entry>IPC messages sent/received and delivered signals.</entry></row>
+   <row><entry><literal>nvcsws</literal>, <literal>nivcsws</literal></entry><entry>Voluntary and involuntary context switches.</entry></row>
+  </tbody></tgroup></informaltable>
+  <para><structfield>stats_since</structfield> records when an entry began collecting
+  statistics. Availability and precision of operating system counters vary by
+  platform. Filesystem counters are different from PostgreSQL buffer hit/read
+  counters; CPU time is different from elapsed query time.</para>
+  <para>A superuser can clear the extension's counters with
+  <literal>SELECT pg_stat_kcache_reset();</literal>. This changes the measurement
+  baseline for other monitoring clients; take a snapshot before resetting.</para>
+ </sect2>
+
+ <sect2 id="pg-stat-kcache-examples">
+  <title>Finding resource-intensive queries</title>
+  <programlisting>SELECT datname, rolname, query,
+       exec_user_time + exec_system_time AS cpu_seconds,
+       exec_reads, exec_writes
+FROM pg_stat_kcache_detail
+WHERE top
+ORDER BY cpu_seconds DESC
+LIMIT 20;</programlisting>
+  <para>Collect two snapshots over a known interval and compare counter deltas to
+  measure current activity. A row can disappear when associated query statistics
+  are evicted. Access to other users' query text follows PostgreSQL's statistics
+  privileges.</para>
+ </sect2>
+
+ <sect2 id="pg-stat-kcache-source">
+  <title>Source and license</title>
+  <para>The extension is maintained by the PoWA community and distributed under
+  the PostgreSQL license. This guide accompanies the pinned
+  <ulink url="https://github.com/powa-team/pg_stat_kcache/blob/1e39814453ab747a3817cfdf4f6f6bd5c0fb9507/README.rst">2.3.2 upstream documentation</ulink>.
+  Source licenses are included in the installed package's copyright directory.</para>
+ </sect2>
+</sect1>

pg_maker/bundled/documentation/pg-stat-kcache.yaml

@@ -0,0 +1,15 @@
+api_version: pg_maker/doc-rules/v1
+kind: DocumentationRules
+metadata:
+  id: pg-stat-kcache-manual
+  revision: 1
+spec:
+  rules:
+  - id: pg-stat-kcache-page
+    action: add-page
+    file: pg-maker-pg-stat-kcache.sgml
+    fragment: pg-stat-kcache.sgml
+    entity: pg-maker-pg-stat-kcache
+    include_file: contrib.sgml
+    selector: {id: contrib}
+    expect_matches: 0

pg_maker/bundled/documentation/pg-wait-sampling.sgml

@@ -0,0 +1,122 @@
+<sect1 id="pg-wait-sampling">
+ <title>pg_wait_sampling — sampled wait event statistics</title>
+ <para><filename>pg_wait_sampling</filename> periodically samples backend wait
+ events. It keeps a recent history in a ring buffer and accumulates a profile
+ by process, event and optionally query. This helps identify I/O, lock and other
+ waits that a single inspection of <structname>pg_stat_activity</structname>
+ could miss.</para>
+ <para>This distribution includes release 1.1.11. Its SQL extension version is
+ <literal>1.1</literal>; the SQL version and the source release number are different.</para>
+
+ <sect2 id="pg-wait-sampling-enable">
+  <title>Enabling collection</title>
+  <para>The collector uses shared memory and a background worker. Add it to
+  <varname>shared_preload_libraries</varname> in the cluster's
+  <filename>postgresql.conf</filename> under <envar>PGDATA</envar> and restart the
+  server. Keep existing required libraries. When using
+  <xref linkend="pgstatstatements"/>, put it before
+  <literal>pg_wait_sampling</literal> so utility query identifiers are preserved:</para>
+  <programlisting>shared_preload_libraries = 'pg_stat_statements,pg_stat_kcache,pg_wait_sampling'
+compute_query_id = auto</programlisting>
+  <para>After the restart, connect with
+  <filename>${paths.runtime_prefix}/bin/psql</filename> and create the SQL
+  interface in each database where it is needed:</para>
+  <programlisting>CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+CREATE EXTENSION IF NOT EXISTS pg_wait_sampling;</programlisting>
+  <para>The server package supplies the files but does not start the collector or
+  create extensions in existing databases. The collector can operate without
+  <literal>pg_stat_statements</literal>; combining them adds query statistics
+  useful for interpreting the sampled profile.</para>
+ </sect2>
+
+ <sect2 id="pg-wait-sampling-settings">
+  <title>Configuration</title>
+  <variablelist>
+   <varlistentry><term><varname>pg_wait_sampling.history_size</varname></term><listitem>
+    <para>Number of records retained in the history ring buffer. The default is
+    <literal>5000</literal>.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_wait_sampling.history_period</varname></term><listitem>
+    <para>History sampling interval in milliseconds. The default is
+    <literal>10</literal>.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_wait_sampling.profile_period</varname></term><listitem>
+    <para>Profile sampling interval in milliseconds. The default is
+    <literal>10</literal>.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_wait_sampling.profile_pid</varname></term><listitem>
+    <para>The default, <literal>true</literal>, keeps separate profile rows for
+    processes; <literal>false</literal> aggregates processes with pid zero.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_wait_sampling.profile_queries</varname></term><listitem>
+    <para>The default, <literal>top</literal>, records top-level query identifiers;
+    <literal>all</literal> includes nested queries; <literal>none</literal> records
+    queryid zero.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><varname>pg_wait_sampling.sample_cpu</varname></term><listitem>
+    <para>The default, <literal>true</literal>, also samples processes with no
+    reported wait. Their event fields are NULL.</para>
+   </listitem></varlistentry>
+  </variablelist>
+  <para>Configure these settings in <filename>postgresql.conf</filename> or with
+  <command>ALTER SYSTEM</command>, then reload the configuration. Shorter intervals
+  produce more samples and increase collection work. The history covers a variable
+  amount of time because its capacity is shared by sampled processes.</para>
+ </sect2>
+
+ <sect2 id="pg-wait-sampling-views">
+  <title>Views and functions</title>
+  <variablelist>
+   <varlistentry><term><structname>pg_wait_sampling_current</structname></term><listitem>
+    <para>Current process events: <structfield>pid</structfield>,
+    <structfield>event_type</structfield>, <structfield>event</structfield> and
+    <structfield>queryid</structfield>.
+    <function>pg_wait_sampling_get_current(pid)</function> restricts the result
+    to one process.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><structname>pg_wait_sampling_history</structname></term><listitem>
+    <para>Recent samples with the same identifiers and a sample timestamp
+    <structfield>ts</structfield>. Old rows are overwritten as the buffer fills.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><structname>pg_wait_sampling_profile</structname></term><listitem>
+    <para>Accumulated sample counts in <structfield>count</structfield> (bigint),
+    grouped by process, event and query according to the collection settings.</para>
+   </listitem></varlistentry>
+   <varlistentry><term><function>pg_wait_sampling_reset_profile()</function></term><listitem>
+    <para>Clear the accumulated profile. Coordinate resets with monitoring clients
+    and retain snapshots when historical comparison is required.</para>
+   </listitem></varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2 id="pg-wait-sampling-examples">
+  <title>Inspecting the profile</title>
+  <programlisting>SELECT event_type, event, sum(count) AS samples
+FROM pg_wait_sampling_profile
+GROUP BY event_type, event
+ORDER BY samples DESC;
+
+SELECT queryid, event_type, event, sum(count) AS samples
+FROM pg_wait_sampling_profile
+WHERE queryid &lt;&gt; 0
+GROUP BY queryid, event_type, event
+ORDER BY samples DESC
+LIMIT 20;</programlisting>
+  <para>Counts represent samples, not measured event durations. Short waits can
+  fall between samples, and simultaneous processes contribute independently.
+  NULL event fields indicate that no wait was reported at sampling time; they
+  do not prove that a process was executing on a CPU. Query identifiers alone
+  do not uniquely identify database/user rows in
+  <structname>pg_stat_statements</structname>; retain that context when correlating
+  results.</para>
+ </sect2>
+
+ <sect2 id="pg-wait-sampling-source">
+  <title>Source and license</title>
+  <para>The upstream project was authored by Alexander Korotkov and Ildus
+  Kurbangaliev and is distributed under the PostgreSQL license. This guide
+  accompanies the pinned
+  <ulink url="https://github.com/postgrespro/pg_wait_sampling/blob/7e3a5fc937393596c0a51c5881dd63d7208408d1/README.md">1.1.11 upstream documentation</ulink>.
+  Source licenses are included in the installed package's copyright directory.</para>
+ </sect2>
+</sect1>

pg_maker/bundled/documentation/pg-wait-sampling.yaml

@@ -0,0 +1,15 @@
+api_version: pg_maker/doc-rules/v1
+kind: DocumentationRules
+metadata:
+  id: pg-wait-sampling-manual
+  revision: 1
+spec:
+  rules:
+  - id: pg-wait-sampling-page
+    action: add-page
+    file: pg-maker-pg-wait-sampling.sgml
+    fragment: pg-wait-sampling.sgml
+    entity: pg-maker-pg-wait-sampling
+    include_file: contrib.sgml
+    selector: {id: contrib}
+    expect_matches: 0

pg_maker/bundled/patches/unix-socket-directory.patch

@@ -0,0 +1,5 @@
+--- a/src/include/pg_config_manual.h
++++ b/src/include/pg_config_manual.h
+@@ -193 +193 @@
+-#define DEFAULT_PGSOCKET_DIR  "/tmp"
++#define DEFAULT_PGSOCKET_DIR "/var/run/postgresql" /* Shared by server and libpq. */

pg_maker/changes/__init__.py

@@ -0,0 +1 @@
+"""ChangeSet loading, dependencies and frozen inputs; application follows in stage 4."""

pg_maker/changes/apply.py

@@ -0,0 +1,298 @@
+"""Strict, transactional text changes on private source copies; no shell or fuzz."""
+
+from __future__ import annotations
+
+import difflib
+import os
+import re
+import shutil
+from pathlib import Path
+
+from pg_maker.documents import relative_output
+from pg_maker.errors import PreconditionError, UnsupportedError, ValidationError
+from pg_maker.sources.store import inventory
+from pg_maker.storage import content_hash, file_hash, write_json
+from pg_maker.yamlio import load_yaml
+
+SOCKET_DEFAULT_LINE = (
+    '#define DEFAULT_PGSOCKET_DIR "/var/run/postgresql" /* Shared by server and libpq. */\n'
+)
+
+
+def target_path(root: Path, relative: str) -> Path:
+    if not relative_output(relative):
+        raise ValidationError("change path must be relative", details={"path": relative})
+    path = root / relative
+    if any(p.is_symlink() for p in (path, *path.parents)):
+        raise ValidationError(
+            "change target must not traverse a symlink", details={"path": relative}
+        )
+    if path.exists() and not path.is_file():
+        raise ValidationError("change target must be a regular file", details={"path": relative})
+    return path
+
+
+def insert_text(root: Path, document: dict) -> None:
+    path = target_path(root, document["target_file"])
+    if not path.is_file():
+        raise PreconditionError("insertion target is missing")
+    if document.get("input_sha256") and file_hash(path) != document["input_sha256"]:
+        raise PreconditionError("insertion input hash mismatch")
+    text = path.read_bytes().decode("utf-8")
+    for mod in document["modifications"]:
+        top, bot, addition = mod["top"], mod["bot"], mod["txt"]
+        if not top or not bot or any(c in top + bot for c in "\r\n") or not addition:
+            raise ValidationError("insertion requires nonempty, single-line anchors and text")
+        lines = text.splitlines(keepends=True)
+        tops = [i for i, line in enumerate(lines) if top in line]
+        pairs = []
+        for i, start in enumerate(tops):
+            end = tops[i + 1] if i + 1 < len(tops) else len(lines)
+            bottom = next((j for j in range(start + 1, end) if bot in lines[j]), None)
+            if bottom is None:
+                raise PreconditionError("insertion bottom anchor is missing")
+            pairs.append((start, bottom))
+        if len(pairs) != mod.get("expect_matches", 1):
+            raise PreconditionError("insertion anchor count mismatch")
+        for start, end in reversed(pairs):
+            if addition in "".join(lines[start + 1 : end]):
+                raise PreconditionError("insertion already present without a receipt")
+            index = start + 1 if mod["alignment"] == "top" else end
+            if index and not lines[index - 1].endswith("\n"):
+                raise PreconditionError("insertion anchor has no line terminator")
+            lines.insert(index, addition if addition.endswith("\n") else addition + "\n")
+        text = "".join(lines)
+    path.write_bytes(text.encode("utf-8"))
+
+
+def socket_patch(source: Path) -> str:
+    """Pin an exact-offset patch for this source, using one unique full-line anchor."""
+    relative = "src/include/pg_config_manual.h"
+    path = target_path(source, relative)
+    if not path.is_file():
+        raise PreconditionError("socket default header is missing")
+    upstream = '#define DEFAULT_PGSOCKET_DIR  "/tmp"\n'
+    configured = '#define DEFAULT_PGSOCKET_DIR  "/var/run/postgresql"\n'
+    lines = path.read_text().splitlines(keepends=True)
+    if sum(lines.count(line) for line in (upstream, configured, SOCKET_DEFAULT_LINE)) != 1:
+        raise PreconditionError("builtin socket patch requires one exact upstream/default line")
+    before = [upstream if line == SOCKET_DEFAULT_LINE else line for line in lines]
+    after = [SOCKET_DEFAULT_LINE if line in (upstream, configured) else line for line in lines]
+    return "".join(difflib.unified_diff(before, after, "a/" + relative, "b/" + relative, n=0))
+
+
+def apply_patch(root: Path, patch: str) -> None:
+    """Unified UTF-8 diffs, exact offsets/context, additions/deletions; reject other formats."""
+    lines = patch.splitlines(keepends=True)
+    if lines and re.match(r"From [0-9a-f]{40,64} Mon Sep 17 00:00:00 2001", lines[0]):
+        first = next((i for i, line in enumerate(lines) if line.startswith("diff --git ")), None)
+        if first is None:
+            raise ValidationError("format-patch contains no diff")
+        lines = lines[first:]
+        # git's mail signature is outside the diff; arbitrary trailing input is rejected.
+        if (
+            len(lines) >= 2
+            and lines[-2] == "-- \n"
+            and re.fullmatch(r"[0-9][A-Za-z0-9.+-]*\n?", lines[-1])
+        ):
+            lines = lines[:-2]
+        elif len(lines) >= 3 and not lines[-1].strip() and lines[-3] == "-- \n":
+            if not re.fullmatch(r"[0-9][A-Za-z0-9.+-]*\n?", lines[-2]):
+                raise ValidationError("invalid format-patch signature")
+            lines = lines[:-3]
+    index, applied = 0, 0
+    mode, mode_kind = None, None
+    while index < len(lines):
+        if lines[index].startswith("diff --git "):
+            match = re.fullmatch(r"diff --git a/(\S+) b/(\S+)\n?", lines[index])
+            if not match or match[1] != match[2] or not relative_output(match[1]):
+                raise UnsupportedError("patch requires safe unquoted paths without renames")
+            name = match[1]
+            mode, mode_kind = None, None
+            index += 1
+            while index < len(lines) and not lines[index].startswith(("--- ", "diff --git ")):
+                line = lines[index].rstrip("\n")
+                metadata = re.fullmatch(r"(new file|deleted file) mode (100644|100755)", line)
+                if metadata and mode is None:
+                    mode_kind, mode = metadata[1], int(metadata[2], 8) & 0o777
+                elif re.fullmatch(r"index [0-9a-f]+\.\.[0-9a-f]+(?: (?:100644|100755))?", line):
+                    pass
+                else:
+                    raise UnsupportedError("binary, rename, copy and mode changes are unsupported")
+                index += 1
+            if index == len(lines) or lines[index].startswith("diff --git "):
+                if mode_kind is None:
+                    raise ValidationError("patch has no file content")
+                old, new = (
+                    ("/dev/null", "b/" + name)
+                    if mode_kind == "new file"
+                    else ("a/" + name, "/dev/null")
+                )
+                lines[index:index] = [f"--- {old}\n", f"+++ {new}\n", "@@ -0,0 +0,0 @@\n"]
+            continue
+        if not lines[index].strip():
+            index += 1
+            continue
+        if not lines[index].startswith("--- ") or index + 1 >= len(lines):
+            raise UnsupportedError(
+                "only unified text patches without mode/rename changes are supported"
+            )
+        old = lines[index][4:].split("\t")[0].rstrip("\r\n")
+        if not lines[index + 1].startswith("+++ "):
+            raise ValidationError("patch lacks new file header")
+        new = lines[index + 1][4:].split("\t")[0].rstrip("\r\n")
+        for name in (old, new):
+            if name != "/dev/null" and (
+                not name.startswith(("a/", "b/")) or not relative_output(name[2:])
+            ):
+                raise ValidationError("patch requires safe a/ and b/ paths")
+        if old != "/dev/null" and new != "/dev/null" and old[2:] != new[2:]:
+            raise UnsupportedError("patch renames are not supported")
+        if (
+            (mode_kind == "new file" and old != "/dev/null")
+            or (mode_kind == "deleted file" and new != "/dev/null")
+            or old == new == "/dev/null"
+        ):
+            raise ValidationError("patch mode metadata differs from file headers")
+        path = target_path(root, (new if old == "/dev/null" else old)[2:])
+        if old == "/dev/null":
+            if path.exists():
+                raise PreconditionError("patch addition would overwrite an existing file")
+            original = []
+        else:
+            if not path.is_file():
+                raise PreconditionError("patch input is missing")
+            if mode is not None and bool(path.stat().st_mode & 0o111) != bool(mode & 0o111):
+                raise PreconditionError("patch input executable mode mismatch")
+            original = path.read_bytes().decode("utf-8").splitlines(keepends=True)
+        index += 2
+        output, cursor, hunks = [], 0, 0
+        while index < len(lines) and lines[index].startswith("@@ "):
+            match = re.fullmatch(
+                r"@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@[^\n]*\n?", lines[index]
+            )
+            if not match:
+                raise ValidationError("invalid patch hunk")
+            old_start, old_n, new_start, new_n = (
+                int(v) if v is not None else 1 for v in match.groups()
+            )
+            start = old_start - 1 if old_n else old_start
+            if start < cursor or start > len(original):
+                raise PreconditionError("patch hunk position mismatch")
+            output.extend(original[cursor:start])
+            if len(output) != (new_start - 1 if new_n else new_start):
+                raise PreconditionError("patch output position mismatch")
+            before, after = [], []
+            index += 1
+            while index < len(lines) and (len(before) < old_n or len(after) < new_n):
+                line = lines[index]
+                if not line or line[0] not in " +-":
+                    raise ValidationError("invalid patch hunk body")
+                value = line[1:]
+                index += 1
+                if index < len(lines) and lines[index].startswith("\"):
+                    value = value.removesuffix("\n")
+                    index += 1
+                if line[0] in " -":
+                    before.append(value)
+                if line[0] in " +":
+                    after.append(value)
+            if (
+                len(before) != old_n
+                or len(after) != new_n
+                or original[start : start + old_n] != before
+            ):
+                raise PreconditionError("patch context mismatch; offsets and fuzz are forbidden")
+            output.extend(after)
+            cursor = start + old_n
+            hunks += 1
+        if not hunks:
+            raise ValidationError("patch has no hunks")
+        output.extend(original[cursor:])
+        if new == "/dev/null":
+            if output:
+                raise ValidationError("file deletion leaves content")
+            path.unlink()
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes("".join(output).encode("utf-8"))
+            if old == "/dev/null" and mode is not None:
+                path.chmod(mode)
+        applied += 1
+        mode, mode_kind = None, None
+    if not applied:
+        raise ValidationError("empty patch")
+
+
+def change_receipt(before: Path, after: Path, identifier: str) -> dict:
+    left, right = inventory(before), inventory(after)
+    a = {e["path"]: e for e in left["entries"]}
+    b = {e["path"]: e for e in right["entries"]}
+    changed = [p for p in sorted(a.keys() | b.keys()) if a.get(p) != b.get(p)]
+    diffs = []
+    for p in changed:
+        if any(e.get("type") not in {None, "file"} for e in (a.get(p, {}), b.get(p, {}))):
+            continue
+        old = (before / p).read_text().splitlines(keepends=True) if p in a else []
+        new = (after / p).read_text().splitlines(keepends=True) if p in b else []
+        diffs.extend(difflib.unified_diff(old, new, fromfile="a/" + p, tofile="b/" + p))
+    return {
+        "id": identifier,
+        "input_hash": content_hash(left),
+        "output_hash": content_hash(right),
+        "changed_paths": changed,
+        "diff": "".join(diffs),
+    }
+
+
+def apply_changes(
+    source: Path, feature: dict, lock: dict, store, branch: str, receipts: Path, check=lambda: None
+) -> list[dict]:
+    changes = []
+    if lock["spec"]["config"]["defaults"]["common_changes"]:
+        changes.append(("builtin/unix-socket-directory", None))
+    if branch == "candidate":
+        changes.extend((c["metadata"]["id"], c) for c in feature["spec"]["changes"])
+    results = []
+    receipts.mkdir(parents=True, exist_ok=True)
+    for number, (identifier, change) in enumerate(changes):
+        check()
+        temporary = source.with_name("source.change-" + str(number))
+        shutil.copytree(source, temporary, symlinks=True)
+        if change is None:
+            path = temporary / "src/include/pg_config_manual.h"
+            value = SOCKET_DEFAULT_LINE.rstrip("\n")
+            if value not in path.read_text().splitlines():
+                digest = lock["spec"]["blobs"][identifier]
+                apply_patch(temporary, store.blob(digest).read_text())
+            if value not in path.read_text().splitlines():
+                raise PreconditionError("builtin socket postcondition failed")
+        else:
+            for operation in change["spec"]["operations"]:
+                check()
+                blob = store.blob(operation["file"]["sha256"])
+                if operation["kind"] == "patch":
+                    apply_patch(temporary, blob.read_text())
+                else:
+                    insert_text(temporary, load_yaml(blob, "insertions"))
+            expected = change["spec"].get("postconditions", {}).get("socket_directory")
+            if expected is not None:
+                actual = re.findall(
+                    r'^#define DEFAULT_PGSOCKET_DIR\s+"([^"]+)"',
+                    (temporary / "src/include/pg_config_manual.h").read_text(),
+                    re.M,
+                )
+                if [value for value in actual if value] != [expected]:
+                    raise PreconditionError("socket directory postcondition failed")
+        receipt = change_receipt(source, temporary, identifier)
+        receipt["status"] = "applied" if receipt["changed_paths"] else "already_satisfied"
+        if change is not None and not receipt["changed_paths"]:
+            raise PreconditionError("custom change has no effect")
+        check()
+        backup = source.with_name("source.before-" + str(number))
+        os.replace(source, backup)
+        os.replace(temporary, source)
+        write_json(receipts / (str(number) + ".json"), receipt)
+        shutil.rmtree(backup)
+        results.append(receipt)
+    return results