Adding upstream version 0.1.21.upstream/0.1.21

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

166 files changed, 59073 insertions, 0 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 0000000..45db529
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,49 @@
+tests-testing:
+  stage: test
+  image: debian:testing
+  script:
+    - apt-get update
+    - apt-get build-dep -y .
+    - dpkg-buildpackage -us -uc -tc
+
+tests-unstable:
+  stage: test
+  image: debian:unstable
+  script:
+    - apt-get update
+    - apt-get build-dep -Ppkg.debputy.ci -y .
+    - dpkg-buildpackage -us -uc -tc
+
+tests-unstable-coverage:
+  stage: test
+  image: debian:unstable
+  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
+  script:
+    - apt-get update
+    - apt-get build-dep -y .
+    - apt-get install -y python3-pytest-cov
+    - PYTHONPATH=. py.test-3 -v --cov --cov-branch --doctest-modules --junit-xml=xunit-report.xml --cov-report term --cov-report html:htmlcov --cov-report xml:coverage.xml
+  after_script:
+  - apt-get install python3-coverage
+  - python3-coverage html
+  artifacts:
+    paths:
+      - htmlcov
+    reports:
+      junit: xunit-report.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+pages:
+  stage: deploy
+  script:
+  - mkdir public
+  - mv htmlcov public/
+  dependencies:
+    - tests-unstable-coverage
+  artifacts:
+    paths:
+    - public
+  only:
+  - main
diff --git a/GETTING-STARTED-WITH-dh-debputy.md b/GETTING-STARTED-WITH-dh-debputy.md
new file mode 100644
index 0000000..5d5d253
--- /dev/null
+++ b/GETTING-STARTED-WITH-dh-debputy.md
@@ -0,0 +1,316 @@
+# Getting started with `dh-debputy`
+
+_This is [how-to guide] and is primarily aimed at getting a task done._
+
+<!-- To writers and reviewers: Check the documentation against https://documentation.divio.com/ -->
+
+This document will help you convert a Debian source package using the `dh` sequencer from debhelper to
+use `dh-debputy`.  Prerequisites for this how-to guide:
+
+ * You have a Debian source package using the `dh` sequencer.  Ideally a simple one as not all packages
+   can be converted at this time. Note that `debputy` does *not* interact well with most third-party
+   `dh` addons. You are recommended to start with source packages without third-party `dh` addons.
+ * It is strongly recommended that your package is bit-for-bit reproducible before starting the conversion
+   as that makes it easier to spot bugs introduced by the conversion!  The output of `debputy` will *not*
+   be bit-for-bit reproducible with `debhelper` in all cases. However, the differences should be easy to
+   review with `diffoscope` if the package was already bit-for-bit reproducible.
+   - Note that `debputy` does not use `strip-nondeterminism`. The bit-for-bit reproducible property should
+     ideally not rely on `strip-nondeterminism` for now.
+
+Note that during the conversion (particularly Step 1 and Step 2), you may find that `debputy` cannot
+support the requirements for your package for now.  Feel free to file an issue for what is holding you
+back in the [debputy issue tracker].
+
+Prerequisites
+-------------
+
+This guide assumes familiarity with Debian packaging in general.  Notably, you should understand
+the different between a (Debian) source package and a (Debian) binary package (e.g., `.deb`) plus
+how these concepts relates to `debian/control` (the source control file).
+
+Additionally, since this is about `debputy` integration with debhelper, the reader is expected to
+be familiar with `debhelper` (notably the `dh` style `debian/rules`).
+
+## Step 1: Have `debputy` convert relevant debhelper files
+
+The `debputy` integration with debhelper removes (replaces) some debhelper tools, but does **not**
+read their relevant config files.  These should instead be converted in to the new format. 
+
+You can have `debputy` convert these for you by using the following command:
+
+    # Dry-run conversion, creates `debian/debputy-manifest.new` if anything is migrated and prints a summary
+    # of what is done.  Remove the --no-act when you are ready to commit the conversion.
+    $ debputy migrate-from-dh --no-act
+
+If relevant, `debputy` may inform you that:
+
+ 1) the package is using an unsupported feature.  Unless that functionality can easily be removed (e.g., it is now
+    obsolete) or easily replaced, then you probably do not want to convert the package to `debputy` at this time.
+    * One common source of unsupported features are dh hook targets (such as override targets), which will be covered
+      in slightly more detail in the next section.  If `debputy` detected any hook targets, it is probably worth it to
+      check if these can be migrated before continuing.
+    * It is worth noting that the migration tool will update an existing manifest when re-run. You can safely "jump"
+      around in the order of the steps, when you try to migrate, if that better suits you.
+ 2) the migration would trigger a conflict.  This can occur for two reasons:
+    * The debhelper configuration has the conflict (example [#934499]), where debhelper is being lenient and ignores
+       the problem.  In this case, you need to resolve the conflict in the debhelper config and re-run `debputy`.
+    * The package has a manifest already with a similar (but not identical) definition of what the migration would
+       generate.  In this case, you need to reconcile the definitions manually (and removing one of them).  After that
+       you can re-run `debputy`.
+
+
+As an example, if you had a `debian/foo.links` (with `foo` being defined in `debian/control`) containing the following:
+
+    usr/share/foo/my-first-symlink usr/share/bar/symlink-target
+    usr/lib/{{DEB_HOST_MULTIARCH}}/my-second-symlink usr/lib/{{DEB_HOST_MULTIARCH}}/baz/symlink-target
+
+The `debputy migrate-from-dh` tool would generate a manifest looking something like this:
+
+    manifest-version: "0.1"
+    packages:
+        foo:
+            transformations:
+             - create-symlink:
+                  path: usr/share/foo/my-first-symlink
+                  target: /usr/share/bar/symlink-target
+             - create-symlink:
+                  path: usr/lib/{{DEB_HOST_MULTIARCH}}/my-second-symlink
+                  target: /usr/lib/{{DEB_HOST_MULTIARCH}}/baz/symlink-target
+
+## Step 2: Migrate override/hook-targets in debian/rules
+
+Once you activate the `debputy` debhelper integration (see Step 3), the following debhelper tools will be
+removed from the `dh` sequence.
+
+ * `dh_install`
+ * `dh_installdocs`
+ * `dh_installchangelogs`
+ * `dh_installexamples`
+ * `dh_installman`
+ * `dh_installcatalogs` **(!)**
+ * `dh_installcron`
+ * `dh_installifupdown`
+ * `dh_installdebconf` **(!)**
+ * `dh_installemacsen` **(!)**
+ * `dh_installinfo`
+ * `dh_installinit` **(!)**
+ * `dh_installsysusers`
+ * `dh_installtmpfiles`
+ * `dh_installsystemd` **(!)**
+ * `dh_installsystemduser` **(!)**
+ * `dh_installmenu` **(!)**
+ * `dh_installmime`
+ * `dh_installmodules`
+ * `dh_installlogcheck`
+ * `dh_installlogrotate`
+ * `dh_installpam`
+ * `dh_installppp`
+ * `dh_installudev`  **(!)**
+ * `dh_installgsettings`
+ * `dh_installinitramfs`
+ * `dh_installalternatives`
+ * `dh_bugfiles`
+ * `dh_ucf` **(!)**
+ * `dh_lintian`
+ * `dh_icons`
+ * `dh_perl`
+ * `dh_usrlocal` **(!)**
+ * `dh_links`
+ * `dh_installwm` **(!)**
+ * `dh_installxfonts`
+ * `dh_strip_nondeterminism`
+ * `dh_compress`
+ * `dh_fixperms`
+ * `dh_dwz`
+ * `dh_strip`
+ * `dh_makeshlibs`
+ * `dh_shlibdeps`
+ * `dh_missing`
+ * `dh_installdeb`
+ * `dh_gencontrol`
+ * `dh_md5sums`
+ * `dh_builddeb`
+
+Have a look at `debian/rules` and migrate any overrides you have for them to `debputy` features or other
+hook targets.  See also the subsections below for concrete advice on how to deal with override or hook targets
+for some of these tools. However, since `debhelper` hooks are arbitrary code execution hooks, there will be
+many cases that the guide will not be able to cover or where `debputy` may not have the feature to support your
+hook target.
+
+While you could manually force these tools to be run via a hook target, they are very likely to feature
+interact with `debputy`. Either causing `debputy` to replace their output completely or by having the tool
+overwrite what `debputy` did (depending on the exact order).  If you find, you *really* need to run one of these
+tools, because `debputy` is not supporting a particular feature they have, then you are probably better off waiting
+with migrating the package in question.
+
+Tools marked with **(!)** have no debputy support at all.  If you rely on these tools, migration is unlikely
+to succeed.  Other tools will have some form of support (often at least a commonly used flow/feature set).
+Where possible, `debputy migrate-from-dh --no-act` will detect these completely unsupported tools via existence
+of their config files or indirectly debhelper hook targets for these tools.  However, some tools may only be
+detected late into the build (which is the case with `dh_usrlocal`).
+
+### Review and migrate any installation code from `dh_install`, `dh_installdocs`, etc. (if any)
+
+All code in `debian/rules` that involves copying or moving files into packages or around in packages must
+be moved to the manifest's `installations` section.  The migration tool will attempt to auto-migrate
+any rules from `debian/install` (etc.). However, be aware of:
+
+ 1) The migration tool assumes none of install rules overlap.  Most packages do not have overlapping
+    install rules as it tends to lead to file conflicts.  If the install rules overlap, `debputy` will
+    detect it at runtime and stop with an error. In that case, you will have to tweak the migrated rules
+    manually.
+ 2) Any overrule target that copies or moves files around in packages must be moved to `installations`
+    (per source) or `transformations` (per package) depending on the case.
+    - For source packages installing content via `debian/tmp`, you can use `install` to rename paths as
+      you install them and `discard` (under `installations`) to ignore paths that should not be installed.
+    - For source packages installing content via `debian/<pkg>`, then everything in there is "auto-installed".
+      If you need to tweak that content, you can use `remove` or `move` transformations (under `transformations`)
+      for manipulation the content.
+
+Note that the migrator "blindly" appends new rules to the bottom of `installations` if you have any existing
+rules (per "none of the install rules overlap"-logic mentioned above).  If you cannot convert all debhelper config
+files in one go, or you manually created some installation rules before running the migrator, you may need to
+manually re-order the generated installation rules to avoid conflicts due to inadequate ordering.  You probably
+want to do so any way for readability/grouping purposes.
+
+
+#### Double-check the `language` settings on all `install-man` rules in `installations`
+
+The `dh_installman` tool auto-detects the language for manpages via two different methods:
+
+ 1) By path name (Does the installation path look like `man/<language>/man<section>/...`?)
+ 2) By basename (Does the basename look like `foo.<language>.<section>`?)
+
+Both methods are used in order with first match being the method of choice.  Unfortunately, the second
+method is prune to false-positives.  Does `foo.pl.1` mean a Polish translation of `foo.1` or is it the
+manpage for a Perl script called `foo.pl` (similar happens for languages/file extensions).
+
+To avoid this issue, `debputy` uses 1) by default and only that.  Option 2) can be chosen by setting
+`language: derive-from-basename` on the concrete install rule.  The problem is that the migration tool
+has to guess, and it is hard to tell if rules like `man/*.1` would need option 2) - especially when the
+migration tool does not attempt to resolve the glob (which it currently does not).
+
+Therefore, take a critical look at the generated `install-man` rules and the generated `language` property
+(or lack thereof).
+
+
+### Convert your overrides or excludes for `dh_fixperms` (if any)
+
+The `debputy` tool will normalize permissions like `dh_fixperms` during package build.  If you have
+any special requirements that `dh_fixperms` did not solve for you, you will have to tell `debputy`
+about them.
+
+If you had something like:
+
+    override_dh_fixperms:
+        dh_fixperms -X bin/sudo
+
+and the goal was to have `dh_fixperms` not touch the mode but the ownership (root:root) was fine, you
+would have the manifest `debian/debputy.manifest`:
+
+    manifest-version: "0.1"
+    packages:
+        foo:
+            transformations:
+             - path-metadata:
+                  path: usr/bin/sudo
+                  mode: "04755"
+
+Note you have to spell out the desired mode for this file.
+
+On the other hand, if your `debian/rules` had something like:
+
+    execute_after_dh_fixperms:
+        chown www-data:www-data debian/foo/var/lib/something-owned-by-www-data
+
+Then the manifest would look something like:
+
+    manifest-version: "0.1"
+    packages:
+        foo:
+            transformations:
+             - path-metadata:
+                  path: var/lib/something-owned-by-www-data
+                  owner: www-data
+                  group: www-data
+
+This can be combined with an explicit `mode: "02755"` if you also need a non-default mode.
+
+The paths provided here support substitution variables (`usr/lib/{{DEB_HOST_MULTIARCH}}/...`) and
+some _limited_ glob support (`usr/bin/sudo*`).
+
+_Remember to merge your manifest with previous steps rather than replacing it!_  Note that
+`debputy migrate-from-dh` will merge its changes into existing manifests and can safely be re-run
+after adding/writing this base manifest.
+
+### Convert your overrides for `dh_gencontrol` (if any)
+
+If the package uses an override to choose a custom version for a binary package, then it is possible in `debputy`
+by  using the `binary-version` key under the package.  Here is an example to force the package `foo` to have
+epoch `1`:
+
+    manifest-version: "0.1"
+    packages:
+        foo:
+            # The foo package needs a different epoch because we took it over from a different
+            # source package with higher epoch version
+            binary-version: '1:{{DEB_VERSION_UPSTREAM_REVISION}}'
+
+Useful if the source took over a binary package from a different source and that binary had a higher
+epoch version.
+
+Note that only limited manipulation of the version is supported, since your options are generally
+limited to expanding one of the following version related variables:
+
+ * `DEB_VERSION` - same definition as the one from `/usr/share/dpkg/pkg-info.mk` (from `dpkg`)
+ * `DEB_VERSION_EPOCH_UPSTREAM` - ditto
+ * `DEB_VERSION_UPSTREAM_REVISION` - ditto
+ * `DEB_VERSION_UPSTREAM` - ditto
+
+If the override is needed for dynamic substitution variables or binary versions that cannot be done with
+the above substitutions, then it might be better to hold off on the conversion.
+
+_Remember to merge your manifest with previous steps rather than replacing it!_  Note that
+`debputy migrate-from-dh` will merge its changes into existing manifests and can safely be re-run
+after adding/writing this base manifest.
+
+## Step 3: Adding the `dh-sequence-zz-debputy` sequence to Build-Depends
+
+The recommended way to do so is to add `dh-sequence-zz-debputy` to the `Build-Depends:` field.
+
+The `zz-` in `zz-debputy` is there to ensure the `debputy` add-on is loaded last by debhelper for
+the rare case there any other debhelper addons still active as the `debputy` sequence does not really
+play well with other `dh` addons. When there are other add-ons, it is generally better for `debputy` to
+be loaded last (as add-on order matters per [#885580]).
+
+## Step 4: Replace third-party dh add-ons to debputy plugins
+
+Packages using third-party `dh` add-ons may need to replace these with `debputy` plugins assuming the
+add-on has a `debputy` plugin to replace it in the first place.  To request a `debputy` plugin, you
+will have to add `debputy-plugin-X` into your `Build-Depends`, where `X` is the name of the plugin.
+
+Note that `debputy` does not support the same features as `debhelper` at the moment for conditional
+plugin loading.  Therefore, the plugins must be in `Build-Depends`.
+
+## Step 5: Verify the build
+
+At this stage, if there are no errors in your previous steps, you should be able to build your
+changed package with `debputy`.  We recommend that you take time to verify this.  For some packages,
+there was no conversion to do in the previous steps, and you would not even need a manifest at all
+in this case.  However, we still recommend that you verify the build is successful here and now.
+
+The `debputy` supports bit-for-bit reproducibility in its output. However, the output is not bit-for-bit
+reproducible with `debhelper`. You are recommended to use `diffoscope` to compare the `debhelper`
+built-version with the `debputy` built version to confirm that all the changes are benign.
+
+However, `debputy` is bit-for-bit reproducible in its output with `(fakeroot) dpkg-deb -b`. Should you
+spot a difference where `debputy` does not produce bit-for-bit identical results with `dpkg-deb` (tar
+format, file ordering, etc.), then please file a bug against `debputy` with a reproducing test case.
+
+Once you have verified your built, the conversion is done. :)  At this point, you can consider
+looking at other features that `debputy` supports that might be useful to you.
+
+[how-to guide]: https://documentation.divio.com/how-to-guides/
+[#885580]: https://bugs.debian.org/885580
+[#934499]: https://bugs.debian.org/934499
+[debputy issue tracker]: https://salsa.debian.org/debian/debputy/-/issues
diff --git a/MANIFEST-FORMAT.md b/MANIFEST-FORMAT.md
new file mode 100644
index 0000000..13bedf7
--- /dev/null
+++ b/MANIFEST-FORMAT.md
@@ -0,0 +1,1414 @@
+# The debputy manifest format
+
+_This is [reference guide] and is primarily useful if you have an idea of what you are looking for._
+_If you are new to `debputy`, maybe you want to read [GETTING-STARTED-WITH-dh-debputy.md](GETTING-STARTED-WITH-dh-debputy.md) first._
+
+<!-- To writers and reviewers: Check the documentation against https://documentation.divio.com/ -->
+
+
+## Prerequisites
+
+This guide assumes familiarity with Debian packaging in general.  Notably, you should understand
+the different between a (Debian) source package and a (Debian) binary package (e.g., `.deb`) plus
+how these concepts relates to `debian/control` (the source control file).
+
+Additionally, the reader is expected to have an understanding of globs and substitution variables.
+
+It is probably very useful to have an understanding on how a binary package is
+assembled.  While `debputy` handles the assembly for you, this document will not go in details
+with this. Prior experience with `debhelper` (notably the `dh`-style `debian/rules`) may be
+useful but should not be a strict requirement.
+
+
+# The basic manifest
+
+The manifest is a YAML document with a dictionary at the top level layer.  As usual with YAML
+versions, you can choose to leave it implicit.  All manifests must include a manifest version, which
+will enable the format to change over time.  For now, there is only one version (`0.1`) and you have
+to include the line:
+
+    manifest-version: "0.1"
+
+
+On its own, the manifest containing only `manifest-version: "..."` will not do anything.  So if you
+end up only having the `manifest-version` key in the manifest, you can just remove the manifest and
+rely entirely on the built-in rules.
+
+
+# Path matching rules
+
+Most of the manifest is about declaring rules for a given path such as "foo must be a symlink"
+or "bar must be owned by root:tty and have mode 02755".  
+
+The manifest contains the following types of matches:
+
+ 1) Exact path matches.  These specify the path inside the debian package exactly without any
+    form of wildcards (e.g., `*` or `?`).  However, they can use substitution variables.
+    Examples include:
+    * `usr/bin/sudo`
+    * `usr/lib/{{DEB_HOST_MULTIARCH}}/libfoo.so`
+
+    Having a leading `/` is optional.  I.e. `/usr/bin/sudo` and `usr/bin/sudo` are considered the
+    same path.
+
+ 2) Glob based path matches.  These specify a rule that match any path that matches a given
+    glob.  These rules must contain a glob character (e.g., `*`) _and_ a `/`. Examples include:
+
+    * `foo/*`
+    * `foo/*.txt`
+    * `usr/lib/{{DEB_HOST_MULTIARCH}}/lib*.so*`
+
+    Note that if the glob does not contain a `/`, then it falls into the Basename glob rule
+    below.
+
+ 3) Basename glob matches.  These specify a rule that match any path where the basename matches
+    a given glob.  They must contain a glob character (e.g., `*`) but either must not have a
+    `/` in them at all or start with `**/` and not have any `/` from there.
+    Examples include:
+
+    * `"*.la"`
+    * `"**/*.md"`
+    * `"**/LICENSE"`
+
+    The examples use explicit quoting because YAML often interprets `*` as an anchor rule in the
+    places where you are likely to use this kind of glob.  The use of the `**/`-prefix is
+    optional when the basename is a glob.  If you wanted to match all paths with the basename
+    of exactly `LICENSE`, then you have to use the prefix (that is, use `**/LICENSE`) as `LICENSE`
+    would be interpreted as an exact match for a top-level path.
+
+However, there are also cases where these matching rules can cause conflicts.  This is covered
+in the [Conflict resolution](#conflict-resolution) section below.
+
+
+## Limitations on debputy path rules
+
+Path rules:
+
+ 1) Must match relatively to the package root.
+ 2) Never resolves a symlink.
+    * If `bin/ls` is a symlink, then `bin/ls` matches the symlink (and never the target)
+    * If `bin` is a symlink, then `bin/ls` (or `bin/*`) would fail to match, because
+      matching would require resolving the symlink.
+
+These limitations are in place because of implementation details in `debputy`.
+
+
+## Conflict resolution
+
+The manifest can contain seemly mutually exclusive rules.  As an example, if you ask for
+`foo/symlink` to be a symlink but also state that you want to remove `foo` entirely
+from the debian package then the manifest now has two mutually exclusive requests.
+
+To resolve these problems, `debputy` relies on the following rules for conflict resolutions:
+
+  1. Requests are loosely-speaking ranked and applied from top to bottom:
+     1. `installations` (ordered; "first match wins")
+     2. `transformations` (ordered; "all matching rules applies")
+
+     The "first match wins" rule is exactly what it says.
+
+     The "all matching rules applies" rule means that each rule is applied in order.  Often
+     this behaves like a simple case of either "first match wins" or "last match wins" (depending
+     on the context).
+
+     Note for transformation rules, an early rule can change the file system layout, which will
+     affect whether a later rule matches.  This is similar to how shell globs commands work:
+
+          $ rm usr/lib/libfoo.la
+          $ chmod 0644 usr/lib/*
+
+     Here the glob used with `chmod` will not match `usr/lib/libfoo.la` because it was removed.
+     As noted, a similar logic applies to transformation rules.
+
+  2. The ordered rules (such as every transformation inside `transformations`) are applied in the
+     listed order (top to bottom). Due to the explicit ordering, such rules generally do not trigger
+     other conflict resolution rules.
+
+     Note keep in mind that all rules must in general apply to at least one path.
+
+Note that `debputy` will in some cases enforce that rules are not redundant.  This feature is currently
+only fully implemented for `installations`.
+
+## All definitions must be used
+
+Whenever you define a request or rule in the manifest, `debputy` will insist on it being used
+at least once.  The exception to this rule being conditional rules where the condition
+evaluates to `false` (in which case the rule never used and does not trigger an error).
+
+This is useful for several reasons:
+
+ 1. The definition may have been shadowed by another rule and would have been ignored otherwise
+ 2. The definition may no longer be useful, but its present might confuse a future reader of
+    the manifest.
+
+In all cases, `debputy` will tell you if a definition was unused and where you can find that
+definition.
+
+
+## debputy globs
+
+In general, the following rules applies to globs in `debputy`.
+
+ * The `*` match 0 or more times any characters except `/`.
+ * The `?` match exactly one character except `/`.
+ * The glob `foo/*` matches _everything_ inside `foo/` including hidden files (i.e., paths starting 
+   with `.`) unlike `bash`/`sh` globs. However, `foo/*` does _not_ match `foo/` itself (this latter
+   part matches `bash`/`sh` behaviour and should be unsurprising).
+ * For the special-cases where `**` is supported, then `**` matches zero or more levels of directories.
+   This means that `foo/**/*` match any path beneath `foo` (but still not `foo`).  This is mostly relevant
+   for built-in path matches as it is currently not possible to define `foo/**/...` patterns in the manifest.
+
+Note that individual rules (such as `clean-after-removal`) may impose special cases to how globs
+work. The rules will explicitly list if they divert from the above listed glob rules.
+
+# Rules for substituting manifest variables
+
+The `debputy` tool supports substitution in various places (usually paths) via the following
+rules.  That means:
+
+ 1) All substitutions must start with `{{` and end with `}}`.  The part inbetween is
+    the `MANIFEST_VARIABLE` and must match the regular expression `[A-Za-z0-9][-_:0-9A-Za-z]*`.
+    Note that you can use space around the variable name if you feel that increases readability.
+    (That is, `{{ FOO }}` can be used as an alternative to `{{FOO}}`).
+ 2) The `MANIFEST_VARIABLE` will be result from a set of built-in variables and the variables from
+    `dpkg-architecture`.
+ 3) You can use `{{token:DOUBLE_OPEN_CURLY_BRACE}}` and `{{token:DOUBLE_CLOSE_CURLY_BRACE}}` (built-in
+    variables)  if you want a literal `{{` or `}}`  would otherwise have triggered an undesired expansion.
+ 4) All `{{MANIFEST_VARIABLE}}` must refer to a defined variable.
+    - You can see the full list of `debputy` and plugin provided manifest variables via:
+      `debputy plugin list manifest-variables`. The manifest itself can declare its own variables
+      beyond that list. Please refer to the [Manifest Variables](#manifest-variables-variables)
+      section manifest variables declared inside the manifest.
+ 5) There are no expression syntax inside the `{{ ... }}` (unlike jinja2 and other template languages).
+    This rule may be changed in the future (with a new manifest version).
+
+Keep in mind that substitution _cannot_ be used everywhere.  There are specific places where
+it can be used.  Also, substitution _cannot be used_ to introduce globs into paths.  When a
+substitution occurs inside a path all characters inserted are treated as literal characters.
+
+Note: While manifest variables can be substituted into various places in the `debputy` manifest, they
+are distinct from `dpkg`'s "substvars" (`man 5 deb-substvars`) that are used in the `debian/control`
+file.
+
+## Built-in or common substitution variables
+
+ * `{{token:NEWLINE}}` or `{{token:NL}}` expands to a literal newline (LF) `\n`.
+ * `{{token:TAB}}` expands to a literal tab `\t`.
+ * `{{token:OPEN_CURLY_BRACE}}`  / `{{token:CLOSE_CURLY_BRACE}}` expand to `{` / `}`
+ * `{{token:DOUBLE_OPEN_CURLY_BRACE}}` / `{{token:DOUBLE_CLOSE_CURLY_BRACE}}` expands to `{{` / `}}`.
+ * `{{PACKAGE}}` expands to the binary package name of the current binary package. This substitution
+   only works/applies when the substitution occurs in the context of a concrete binary package.
+ * Plus any of the variables produced by `dpkg-architecture`, such as `{{DEB_HOST_MULTIARCH}}`.
+
+The following variables from `/usr/share/dpkg/pkg-info.mk` (`dpkg`) are also available:
+
+ * DEB_SOURCE (as `{{DEB_SOURCE}}`)
+ * DEB_VERSION (as `{{DEB_VERSION}}`)
+ * DEB_VERSION_EPOCH_UPSTREAM (as `{{DEB_VERSION_EPOCH_UPSTREAM}}`)
+ * DEB_VERSION_UPSTREAM_REVISION (as `{{DEB_VERSION_UPSTREAM_REVISION}}`)
+ * DEB_VERSION_UPSTREAM (as `{{DEB_VERSION_UPSTREAM}}`)
+ * SOURCE_DATE_EPOCH (as `{{SOURCE_DATE_EPOCH}}`)
+
+These have the same definition as those from the `dpkg` provided makefile.
+
+
+# Restrictions on defining ownership of paths
+
+In some parts of the manifest, you can specify which user or group should have ownership of
+a given path.  As an example, you can define a directory to be owned by `root` with group `tty`
+(think `chown root:tty <some/path>`).
+
+Ownership is generally defined via the keys `owner` and `group`.  For each of them, you can use
+one of the following formats:
+
+ 1) A name (e.g., `owner: root`).
+ 2) An id (e.g., `owner: 0`). Please avoid using quotes around the ID in YAML as that can
+    cause `debputy` to read the number as a name.
+ 3) A name and an id with a colon inbetween (e.g., `owner: "root:0"`).  The name must always
+    come first here.  You may have to quote the value to prevent the YAML parser from being
+    confused.
+
+All three forms are valid and provide the same result.  Unless you have a compelling reason to
+pick a particular form, the name-only is recommended for simplicity.  Notably, it does not
+require your co-maintainer or future you to remember what the IDs mean.
+
+Regardless of which form you pick:
+
+ 1) The provided owner must be defined by Debian `base-passwd` file, which are the only users guaranteed
+    to be present on every Debian system.
+    * Concretely, `debputy` verifies the input against `/usr/share/base-passwd/passwd.master` and
+      `/usr/share/base-passwd/group.master` (except for `root` / `0` as an optimization).
+
+ 2) If the `name:id` form is used, then the name and the id values must match.  I.e., `root:2` would
+    be invalid as the id for `root` is defined to be `0` in the `base-passwd` data files.
+
+ 3) The `debputy` tool maintains a `deny`-list of owners that it refuses even though `base-passwd`
+    defines them. As a notable non-exhaustive example, `debputy` considers `nobody` or id `65534` 
+    (the ID of `nobody` / `nogroup`) to be invalid owners.
+
+
+# Conditional rules
+
+There are cases, where a given rule should only apply in certain cases - such as only when a given
+build profile is active (`DEB_BUILD_PROFILES` / `dpkg-buildpackage -P`).  For rules that
+*support being conditional*, the condition is generally defined via the `when:` key and the condition
+is then described beneath the `when:`.
+
+As an example:
+
+    packages:
+        util-linux:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  when:
+                      # On Hurd, the package "hurd" ships "sbin/getty".
+                      arch-matches: '!hurd-any'
+
+
+When the condition under `when:` resolves to `true`, the rule will and must be used.  When the
+condition resolves to `false`, the rule will not be applied even if it could have been.  However,
+the rule may still be "partially" evaluated.  As an example, for installation rules, the source
+patterns will still be evaluated to reserve what it would have matched, so that following rules
+behave deterministically regardless of how the condition evaluates.
+
+Note that conditions are *not* used as a conflict resolution and as such two conditional rules
+can still cause conflicts even though their conditions are mutually exclusive.  This may be
+changed in a later version of `debputy` provided `debputy` can assert the two conditions
+are mutually exclusive.
+
+The `when:` key has either a mapping, a list or a string as value depending on the condition.
+Each supported condition is described in the following subsections.
+
+## Architecture match condition `arch-matches` (mapping)
+
+Sometimes, a rule needs to be conditional on the architecture.  This can be done by using the
+`arch-matches` rule. In 99.99% of the cases, `arch-matches` will be form you are looking for
+and practically behaves like a comparison against `dpkg-architecture -qDEB_HOST_ARCH`.
+
+As an example:
+
+    packages:
+        util-linux:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  when:
+                      # On Hurd, the package "hurd" ships "sbin/getty".
+                      arch-matches: '!hurd-any'
+
+The `arch-matches` must be defined as a part of a mapping, where `arch-matches` is the key. The
+value must be a string in the form of a space separated list architecture names or architecture
+wildcards (same syntax as the  architecture restriction in Build-Depends in debian/control except
+there is no enclosing `[]` brackets). The names/wildcards can optionally be prefixed by `!` to
+negate them.  However, either *all* names / wildcards must have negation or *none* of them may
+have it.
+
+For the cross-compiling specialists or curious people: The `arch-matches` rule behaves like a
+`package-context-arch-matches` in the context of a binary package and like
+`source-context-arch-matches` otherwise. The details of those are covered in their own section.
+
+## Explicit source or binary package context architecture match condition `source-context-arch-matches`, `package-context-arch-matches` (mapping)
+
+**These are special-case conditions**. Unless you know that you have a very special-case,
+you should probably use `arch-matches` instead. These conditions are aimed at people with
+corner-case special architecture needs. It also assumes the reader is familiar with the
+`arch-matches` condition.
+
+To understand these rules, here is a quick primer on `debputy`'s concept of "source context"
+vs "(binary) package context" architecture.  For a native build, these two contexts are the
+same except that in the package context an `Architecture: all` package always resolve to
+`all` rather than `DEB_HOST_ARCH`. As a consequence, `debputy` forbids `arch-matches` and
+`package-context-arch-matches` in the context of an `Architecture: all` package as a warning
+to the packager that condition does not make sense.
+
+In the very rare case that you need an architecture condition for an `Architecture: all` package,
+you can use `source-context-arch-matches`. However, this means your `Architecture: all` package
+is not reproducible between different build hosts (which has known to be relevant for some
+very special cases).
+
+Additionally, for the 0.0001% case you are building a cross-compiling compiler (that is,
+`DEB_HOST_ARCH != DEB_TARGET_ARCH` and you are working with `gcc` or similar) `debputy` can be
+instructed (opt-in) to use `DEB_TARGET_ARCH` rather than `DEB_HOST_ARCH` for certain packages when
+evaluating an architecture condition in context of a binary package. This can be useful if the
+compiler produces supporting libraries that need to be built for the `DEB_TARGET_ARCH` rather than
+the `DEB_HOST_ARCH`.  This is where `arch-matches` or `package-context-arch-matches` can differ
+subtly from `source-context-arch-matches` in how they evaluate the condition.  This opt-in currently
+relies on setting `X-DH-Build-For-Type: target` for each of the relevant packages in
+`debian/control`.  However, unless you are a cross-compiling specialist, you will probably never
+need to care about nor use any of this.
+
+Accordingly, the possible conditions are:
+
+ * `arch-matches`: This is the form recommended to laymen and as the default use-case. This
+   conditional acts `package-context-arch-matches` if the condition is used in the context
+   of a binary package. Otherwise, it acts as `source-context-arch-matches`.
+
+ * `source-context-arch-matches`: With this conditional, the provided architecture constraint is compared
+   against the build time provided host architecture (`dpkg-architecture -qDEB_HOST_ARCH`). This can
+   be useful when an `Architecture: all` package needs an architecture condition for some reason.
+
+ * `package-context-arch-matches`: With this conditional, the provided architecture constraint is compared
+   against the package's resolved architecture. This condition can only be used in the context of a binary
+   package (usually, under `packages.<name>.`).  If the package is an `Architecture: all` package, the
+   condition will fail with an error as the condition always have the same outcome. For all other
+   packages, the package's resolved architecture is the same as the build time provided host architecture
+   (`dpkg-architecture -qDEB_HOST_ARCH`).
+
+   - However, as noted above there is a special case for when compiling a cross-compiling compiler, where
+     this behaves subtly different from `source-context-arch-matches`.
+
+All conditions are used the same way as `arch-matches`. Simply replace `arch-matches` with the other
+condition. See the `arch-matches` description for an example.
+
+## Active build profile match condition `build-profiles-matches` (mapping)
+
+The `build-profiles-matches` condition is used to assert whether the active build profiles
+(`DEB_BUILD_PROFILES` / `dpkg-buildpackage -P`) matches a given build profile restriction.
+
+As an example:
+
+    # TODO: Not the best example (`create-symlink` is an unlikely use-case for this condition)
+    packages:
+        foo:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  when:
+                      build-profiles-matches: '<!pkg.foo.mycustomprofile>'
+
+The `build-profiles-matches` must be defined as a part of a mapping, where `build-profiles-matches`
+is the key.  The value is a string using the same syntax as the `Build-Profiles` field from `debian/control`
+(i.e., a space separated list of `<[!]profile ...>` groups).
+
+## Can run produced binaries `can-execute-compiled-binaries` (string)
+
+The `can-execute-compiled-binaries` condition is used to assert the build can assume
+that all compiled binaries can be run as-if they were native binaries. For native
+builds, this condition always evaluates to `true`.  For cross builds, the condition
+is generally evaluates to `false`.  However, there are special-cases where binaries
+can be run during cross-building. Accordingly, this condition is subtly different
+from the `cross-compiling` condition.
+
+Note this condition should *not* be used when you know the binary has been built
+for the build architecture (`DEB_BUILD_ARCH`) or for determining whether build-time tests
+should be run (for build-time tests, please use the `run-build-time-tests` condition instead).
+Some upstream build systems are advanced enough to distinguish building a final product vs.
+building a helper tool that needs to run during build.  The latter will often be compiled by
+a separate compiler (often using `$(CC_FOR_BUILD)`, `cc_for_build` or similar variable names
+in upstream build systems for that compiler).
+
+As an example:
+
+    # TODO: Not the best example (`create-symlink` is an unlikely use-case for this condition)
+    packages:
+        foo:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  # Only for native builds or when we can transparently run a compiled
+                  when: can-execute-compiled-binaries
+
+The `can-execute-compiled-binaries` condition is specified as a string.
+
+## Cross-Compiling condition `cross-compiling` (string)
+
+The `cross-compiling` condition is used to determine if the current build is performing a cross
+build (i.e., `DEB_BUILD_GNU_TYPE` != `DEB_HOST_GNU_TYPE`). Often this has consequences for what
+is possible to do.
+
+Note if you specifically want to know:
+
+ * whether build-time tests should be run, then please use the `run-build-time-tests` condition.
+ * whether compiled binaries can be run as if it was a native binary, please use the
+   `can-execute-compiled-binaries` condition instead.  That condition accounts for cross-building
+   in its evaluation.
+
+As an example:
+
+    # TODO: Not the best example (`create-symlink` is an unlikely use-case for this condition)
+    packages:
+        foo:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  when: cross-compiling
+
+The `cross-compiling` condition is specified as a string.
+
+## Whether build time tests should be run `run-build-time-tests` (string)
+
+The `run-build-time-tests` condition is used to determine whether (build time) tests should
+be run for this build.  This condition roughly translates into whether `nocheck` is present
+in `DEB_BUILD_OPTIONS`.
+
+In general, the manifest *should not* prevent build time tests from being run during cross-builds.
+
+As an example:
+
+    # TODO: Not the best example (`create-symlink` is an unlikely use-case for this condition)
+    packages:
+        foo:
+            transformations:
+            - create-symlink
+                  path: sbin/agetty
+                  target: /sbin/getty
+                  when: run-build-time-tests
+
+The `run-build-time-tests` condition is specified as a string.
+
+## Negated condition `not` (mapping)
+
+It is possible to negate a condition via the `not` condition.
+
+As an example:
+
+    packages:
+        util-linux:
+            transformations:
+            - create-symlink
+                  path: sbin/getty
+                  target: /sbin/agetty
+                  when:
+                      # On Hurd, the package "hurd" ships "sbin/getty".
+                      # This example happens to also be an alternative to `arch-marches: '!hurd-any`
+                      not:
+                          arch-matches: 'hurd-any'
+
+The `not` condition is specified as a mapping, where the key is `not` and the
+value is a nested condition.
+
+## All or any of a list of conditions `all-of`/`any-of` (list)
+
+It is possible to aggregate conditions using the `all-of` or `any-of` condition. This provide
+`X and Y` and `X or Y` semantics (respectively).
+
+As an example:
+
+    packages:
+        util-linux:
+            transformations:
+                - create-symlink
+                  path: sbin/getty
+                  target: /sbin/agetty
+                  when:
+                      # Only ship getty on linux except for s390(x)
+                      all-of:
+                          - arch-matches: 'linux-any'
+                          - arch-matches: '!s390 !s390x'
+
+The `all-of` and `any-of` conditions are specified as lists, where each entry is a nested condition.
+The lists need at least 2 entries as with fewer entries the `all-of` and `any-of` conditions are
+redundant.
+
+# Packager provided definitions
+
+For more complex manifests or packages, it is possible define some common attributes for reuse.
+
+## Manifest Variables (`variables`)
+
+It is possible to provide custom manifest variables via the `variables` attribute.  An example:
+
+    manifest-version: '0.1'
+    definitions:
+      variables:
+        LIBPATH: "/usr/lib/{{DEB_HOST_MULTIARCH}}"
+        SONAME: "1"
+    installations:
+      - install:
+           source: build/libfoo.so.{{SONAME}}*
+           # The quotes here is for the YAML parser's sake.
+           dest-dir: "{{LIBPATH}}"
+           into: libfoo{{SONAME}}
+
+The value of the `variables` key must be a mapping, where each key is a new variable name and
+the related value is the value of said key. The keys must be valid variable name and not shadow
+existing variables (that is, variables such as `PACKAGE` and `DEB_HOST_MULTIARCH` *cannot* be
+redefined). The value for each variable *can* refer to *existing* variables as seen in the
+example above.
+
+As usual, `debputy` will insist that all declared variables must be used.
+
+Limitations:
+ * When declaring variables that depends on another variable declared in the manifest, the
+   order is important. The variables are resolved from top to bottom.
+ * When a manifest variable depends on another manifest variable, the existing variable is
+   currently always resolved in source context. As a consequence, some variables such as
+  `{{PACKAGE}}` cannot be used when defining a variable. This restriction may be
+   lifted in the future.
+
+# Installations
+
+For source packages building a single binary, the `dh_auto_install` from debhelper will default to
+providing everything from upstream's install in the binary package.  The `debputy` tool matches this
+behaviour and accordingly, the `installations` feature is only relevant in this case when you need to
+manually specify something upstream's install did not cover.
+
+For sources, that build multiple binaries, where `dh_auto_install` does not detect anything to install,
+or when `dh_auto_install --destdir debian/tmp` is used, the `installations` section of the manifest is
+used to declare what goes into which binary package. An example:
+
+    installations:
+      - install:
+            sources: "usr/bin/foo"
+            into: foo
+      - install:
+            sources: "usr/*"
+            into: foo-extra
+
+
+All installation rules are processed in order (top to bottom).  Once a path has been matched, it can
+no longer be matched by future rules.  In the above example, then `usr/bin/foo` would be in the `foo`
+package while everything in `usr` *except* `usr/bin/foo` would be in `foo-extra`.  If these had been
+ordered in reverse, the `usr/bin/foo` rule would not have matched anything and caused `debputy`
+to reject the input as an error on that basis.  This behaviour is similar to "DEP-5" copyright files,
+except the order is reversed ("DEP-5" uses "last match wins", where here we are doing "first match wins")
+
+In the rare case that some path need to be installed into two packages at the same time, then this is
+generally done by changing `into` into a list of packages.
+
+All installations are currently run in *source* package context.  This implies that:
+
+  1) No package specific substitutions are available. Notably `{{PACKAGE}}` cannot be resolved.
+  2) All conditions are evaluated in source context.  For 99.9% of users, this makes no difference,
+     but there is a cross-build feature that changes the "per package" architecture which is affected.
+
+This is a limitation that should be fixed in `debputy`.
+
+**Attention debhelper users**: Note the difference between `dh_install` (etc.) vs. `debputy` on
+overlapping matches for installation.
+
+## Install rule search directories
+
+Most install rules apply their patterns against search directories such as `debian/tmp` by default.
+
+The default search directory order (highest priority first) is:
+
+ 1) The upstream install directory (usually, `debian/tmp`)
+ 2) The source package root directory (`.`)
+
+Each search directory is tried in order.  When a pattern matches an entry in a search directory (even
+if that entry is reserved by another package), further search directories will *not* be tried. As an example,
+consider the pattern `usr/bin/foo*` and the files:
+
+  `SOURCE_ROOT/debian/tmp/usr/bin/foo.sh`
+  `SOURCE_ROOT/usr/bin/foo.pl`
+
+Here the pattern will only match `SOURCE_ROOT/debian/tmp/usr/bin/foo.sh` and not `SOURCE_ROOT/usr/bin/foo.pl`.
+
+## Automatic discard rules
+
+The `debputy` framework provides some built-in discard rules that are applied by default during installation
+time.  These are always active and implicit, but can be overwritten by exact path matches for install rules.
+
+The `debputy` tool itself provides the following discard rules:
+
+ * Discard of `.la` files. Their use is rare but not unheard of. You may need to overwrite this.
+ * Discard of python byte code (such as `__pycache__` directories).
+ * Discard of editor backup files (such as `*~`, `*.bak`, etc.).
+ * Discard of Version control files (such as `.gitignore`, etc.).
+ * Discard of GNU info's `dir` (`usr/share/info/dir`) as it causes file conflicts with other packages.
+ * Discard of `DEBIAN` directory.
+
+Note: Third-party plugins may provide additional automatic discard rules. Please use
+`debputy plugin list automatic-discard-rules` to see all known automatic discard rules.
+
+If you find yourself needing a particular path installed that has been discarded by default, you can overrule
+the default discard by spelling out the path. As an example, if you needed to install a `libfoo.la` file,
+you could do:
+
+    installations:
+      - install:
+            sources:
+            # By-pass automatic discard of `libfoo.la` - no globs *cannot* be used!
+             - "usr/lib/libfoo.la"
+             - "usr/lib/libfoo*.so*"
+            into: libfoo1
+
+## Generic install (`install`)
+
+The generic `install` rule can be used to install arbitrary paths into packages and is *similar* to how
+`dh_install` from debhelper works.  It is a two "primary" uses.
+
+  1) The classic "install into directory" similar to the standard `dh_install`
+  2) The "install as" similar to `dh-exec`'s `foo => bar` feature.
+
+Examples:
+
+    installations:
+      - install:
+            source: "usr/bin/tool-a"
+            dest-dir: "usr/bin"
+            into: foo
+      - install:
+            source: "usr/bin/tool-b"
+            # Implicit dest-dir: "usr/bin
+            into: foo-extra
+      - install:
+            source: "usr/bin/tool-c.sh"
+            # Rename as a part of installing.
+            as: "usr/bin/tool-c"
+            into: foo-util
+
+
+The value for `install` is a string, a list of strings or mapping. When it is a mapping, the
+mapping has the following key/value pairs:
+
+ * `source` or `sources` (required): A path match (`source`) or a list of path matches (`sources`) defining
+   the source path(s) to be installed. The path match(es) can use globs.  Each match is tried against default
+   search directories.
+    - When a symlink is matched, then the symlink (not its target) is installed as-is.  When a directory is
+     matched, then the directory is installed along with all the contents that have not already been installed
+     somewhere.
+
+ * `into` (conditional): Either a package name or a list of package names for which these paths should be
+   installed. This key is conditional on whether there are multiple binary packages listed in
+   `debian/control`.  When there is only one binary package, then that binary is the default for `into`.
+   Otherwise, the key is required.
+
+ * `dest-dir` (optional): A path defining the destination *directory*.  The value *cannot* use globs, but can
+   use substitution.  If neither `as` nor `dest-dir` is given, then `dest-dir` defaults to the directory name
+   of the `source`.
+
+ * `as` (optional): A path defining the path to install the source as. This is a full path.  This option is
+   mutually exclusive with `dest-dir` and `sources` (but not `source`).  When `as` is given, then `source` must
+   match exactly one "not yet matched" path.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules).
+
+When the input is a string or a list of string, then that value is used as shorthand for `source`
+or `sources` (respectively).  This form can only be used when `into` is not required.
+
+
+## Install documentation (`install-docs`)
+
+This install rule resemble that of `dh_installdocs`.  It is a shorthand over the generic
+`install` rule with the following key features:
+
+ 1) The default `dest-dir` is to use the package's documentation directory (usually something
+    like `/usr/share/doc/{{PACKAGE}}`, though it respects the "main documentation package"
+    recommendation from Debian Policy). The `dest-dir` or `as` can be set in case the
+    documentation in question goes into another directory or with a concrete path.  In this
+    case, it is still "better" than `install` due to the remaining benefits.
+ 2) The rule comes with pre-defined conditional logic for skipping the rule under
+    `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself.
+ 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb` package
+    listed in `debian/control`.
+
+With these two things in mind, it behaves just like the `install` rule.
+
+Note: It is often worth considering to use a more specialized version of the `install-docs`
+rule when one such is available. If you are looking to install an example or a manpage,
+consider whether `install-examples` or `install-man` might be a better fit for your
+use-case.
+
+Examples:
+
+    installations:
+      - install-docs:
+            sources:
+              - "docs/README.some-topic.md"
+              - "docs/README.another-topic.md"
+            into: foo
+
+
+The value for `install-docs` is a string, a list of strings or mapping. When it is
+a mapping, the mapping has the following key/value pairs:
+
+ * `source` or `sources` (required): A path match (`source`) or a list of path matches (`sources`) defining
+   the source path(s) to be installed. The path match(es) can use globs.  Each match is tried against default
+   search directories.
+     - When a symlink is matched, then the symlink (not its target) is installed as-is.  When a directory is
+       matched, then the directory is installed along with all the contents that have not already been installed
+       somewhere.
+
+     - **CAVEAT**: Specifying `source: docs` where `docs` resolves to a directory for `install-docs`
+       will give you an `docs/docs` directory in the package, which is rarely what you want. Often, you
+       can solve this by using `docs/*` instead.
+
+ * `dest-dir` (optional): A path defining the destination *directory*.  The value *cannot* use globs, but can
+   use substitution.  If neither `as` nor `dest-dir` is given, then `dest-dir` defaults to the relevant package
+   documentation directory (a la `/usr/share/doc/{{PACKAGE}}`).
+
+ * `into` (conditional): Either a package name or a list of package names for which these paths should be
+   installed as docs.  This key is conditional on whether there are multiple (non-`udeb`) binary
+   packages  listed in `debian/control`.  When there is only one (non-`udeb`) binary package, then that binary
+   is the default for `into`. Otherwise, the key is required.
+
+ * `as` (optional): A path defining the path to install the source as. This is a full path.  This option is
+   mutually exclusive with `dest-dir` and `sources` (but not `source`).  When `as` is given, then `source` must
+   match exactly one "not yet matched" path.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules).  This condition will
+   be combined with the built-in condition provided by these rules (rather than replacing it).
+
+When the input is a string or a list of string, then that value is used as shorthand for `source`
+or `sources` (respectively).  This form can only be used when `into` is not required.
+
+Note: While the canonical name for this rule use plural, the `install-doc` variant is accepted as
+alternative name.
+
+## Install examples (`install-examples`)
+
+This install rule resemble that of `dh_installexamples`.  It is a shorthand over the generic `
+install` rule with the following key features:
+
+ 1) It pre-defines the `dest-dir` that respects the "main documentation package" recommendation from
+    Debian Policy. The `install-examples` will use the `examples` subdir for the package documentation
+    dir.
+ 2) The rule comes with pre-defined conditional logic for skipping the rule under
+    `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself.
+ 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb` package
+    listed in `debian/control`.
+
+With these two things in mind, it behaves just like the `install` rule.
+
+Examples:
+
+    installations:
+      - install-examples:
+            source: "examples/*"
+            into: foo
+
+
+The value for `install-examples` is a string, a list of strings or mapping. When it is
+a mapping, the mapping has the following key/value pairs:
+
+* `source` or `sources` (required): A path match (`source`) or a list of path matches (`sources`) defining
+  the source path(s) to be installed. The path match(es) can use globs.  Each match is tried against default
+  search directories.
+    - When a symlink is matched, then the symlink (not its target) is installed as-is.  When a directory is
+      matched, then the directory is installed along with all the contents that have not already been installed
+      somewhere.
+
+    - **CAVEAT**: Specifying `source: examples` where `examples` resolves to a directory for `install-examples`
+      will give you an `examples/examples` directory in the package, which is rarely what you want. Often, you
+      can solve this by using `examples/*` instead.
+
+* `into` (conditional): Either a package name or a list of package names for which these paths should be
+  installed as examples.  This key is conditional on whether there are multiple (non-`udeb`) binary
+  packages  listed in `debian/control`.  When there is only one (non-`udeb`) binary package, then that binary
+  is the default for `into`. Otherwise, the key is required.
+
+
+* `when` (optional): A condition as defined in [Conditional rules](#conditional-rules).  This condition will
+  be combined with the built-in condition provided by these rules (rather than replacing it).
+
+When the input is a string or a list of string, then that value is used as shorthand for `source`
+or `sources` (respectively).  This form can only be used when `into` is not required.
+
+Note: While the canonical name for this rule use plural, the `install-example` variant is accepted as
+alternative name.
+
+## Install manpages (`install-man`)
+
+Install rule for installing manpages similar to `dh_installman`. It is a shorthand over the generic
+`install` rule with the following key features:
+
+ 1) The rule can only match files (notably, symlinks cannot be matched by this rule).
+ 2) The `dest-dir` is computed per source file based on the manpage's section and language.
+ 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb` package
+    listed in `debian/control`.
+ 4) The rule comes with manpage specific attributes such as `language` and `section` for when the
+    auto-detection is insufficient.
+ 5) The rule comes with pre-defined conditional logic for skipping the rule under `DEB_BUILD_OPTIONS=nodoc`,
+    so you do not have to write that conditional yourself.
+
+With these things in mind, the rule behaves similar to the `install` rule.
+
+Examples:
+
+    installations:
+      - install-man:
+            source: "man/foo.1"
+            into: foo
+      - install-man:
+            source: "man/foo.de.1"
+            language: derive-from-basename
+            into: foo
+
+
+The value for `install-man` is a string, a list of strings or mapping. When it is a mapping, the mapping
+has the following key/value pairs:
+
+ * `source` or `sources` (required): A path match (`source`) or a list of path matches (`sources`) defining
+   the source path(s) to be installed. The path match(es) can use globs.  Each match is tried against default
+   search directories. Only files can be matched.
+
+ * `into` (conditional): Either a package name or a list of package names for which these paths should be
+   installed as manpages.  This key is conditional on whether there are multiple (non-`udeb`) binary
+   packages  listed in `debian/control`.  When there is only one (non-`udeb`) binary package, then that binary
+   is the default for `into`. Otherwise, the key is required.
+
+ * `section` (optional): If provided, it must be an integer between 1 and 9 (both inclusive), defining the
+    section the manpages belong overriding any auto-detection that `debputy` would have performed.
+
+ * `language` (optional): If provided, it must be either a 2 letter language code (such as `de`), a 5 letter
+   language + dialect code (such as `pt_BR`), or one of the special keywords `C`, `derive-from-path`, or
+   `derive-from-basename`.  The default is `derive-from-path`.
+   - When `language` is `C`, then the manpages are assumed to be "untranslated".
+   - When `language` is a language code (with or without dialect), then all manpages matched will be assumed
+     to be translated to that concrete language / dialect.
+   - When `language` is `derive-from-path`, then `debputy` attempts to derive the language from the path
+     (`man/<language>/man<section>`).  This matches the default of `dh_installman`. When no language can
+     be found for a given source, `debputy` behaves like language was `C`.
+   - When `language` is `derive-from-basename`, then `debputy` attempts to derive the language from the
+     basename (`foo.<language>.1`) similar to `dh_installman` previous default.  When no language can
+     be found for a given source, `debputy` behaves like language was `C`.  Note this is prone to
+     false positives where `.pl`, `.so` or similar two-letter extensions gets mistaken for a language
+     code (`.pl` can both be "Polish" or "Perl Script", `.so` can both be "Somali" and "Shared Object"
+     documentation).  In this configuration, such extensions are always assumed to be a language.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules).  This condition will
+   be combined with the built-in condition provided by these rules (rather than replacing it).
+
+
+When the input is a string or a list of string, then that value is used as shorthand for `source`
+or `sources` (respectively).  This form can only be used when `into` is not required.
+
+Comparison with debhelper: The `dh_installman` uses `derive-from-path` as default and then falls back
+to `derive-from-basename`.  The `debputy` tool does *not* feature the same fallback logic.  If you want
+the `derive-from-basename` with all of its false-positives, you have to explicitly request it.
+
+
+## Discard (or exclude) upstream provided paths (`discard`)
+
+When installing paths from `debian/tmp` into packages, it might be useful to ignore some paths that you never
+need installed.  This can be done with the `discard` rule.
+
+
+The value for `discard` is a string, a list of strings or mapping. When it is a mapping, the mapping
+has the following key/value pairs:
+
+ * `path` or `paths` (required): A path match (`path`) or a list of path matches (`paths`) defining the
+   source path(s) that should not be installed anywhere. The path match(es) can use globs.
+    - When a symlink is matched, then the symlink (not its target) is discarded as-is.  When a directory is
+     matched, then the directory is discarded along with all the contents that have not already been installed
+     somewhere.
+
+ * `search-dir` or `search-dirs` (optional): A path (`search-dir`) or a list to paths (`search-dirs`) that
+    defines which search directories apply to. This attribute is primarily useful for source packages that
+    uses [per package search dirs](#custom-installation-time-search-directories-installation-search-dirs),
+    and you want to restrict a discard rule to a subset of the relevant search dirs. Note all listed
+    search directories must be either an explicit search requested by the packager or a search directory
+    that `debputy` provided automatically (such as `debian/tmp`). Listing other paths will make `debputy`
+    report an error.
+
+    - Note that the `path` or `paths` must match at least one entry in any of the search directories unless
+      *none* of the search directories exist (or the condition in `required-when` evaluates to false). When
+      none of the search directories exist, the discard rule is silently skipped. This special-case enables
+      you to have discard rules only applicable to certain builds that are only performed conditionally.
+
+ * `required-when` (optional): A condition as defined in [Conditional rules](#conditional-rules). The discard
+   rule is always applied. When the conditional is present and evaluates to false, the discard rule can
+   silently match nothing. When the condition is absent, *or* it evaluates to true, then each pattern
+   provided must match at least one path.
+
+When the input is a string or a list of string, then that value is used as shorthand for `path`
+or `paths` (respectively).
+
+Once a path is discarded, it cannot be matched by any other install rules.  A path that is discarded, is
+considered handled when `debputy` checks for paths you might have forgotten to install.  The `discard`
+feature is therefore *also* replaces the `debian/not-installed` file used by `debhelper` and `cdbs`.
+
+Note: A discard rule applies to *all* relevant search directories at the same time (including the source
+root directory) unlike other install rules that only applies to the first search directory with a *match*.
+This is to match the intuition that if you discard something, you want it gone no matter which search
+directory it happened to be in.
+
+## Multi destination install (`multi-dest-install`)
+
+Special use install rule for installing the same source multiple times into the same package.
+
+It works similar to the `install` rule except:
+
+ 1) `dest-dir` is renamed to `dest-dirs` and is conditionally mandatory (either `as` or `dest-dirs`
+    must be provided).
+ 2) Both `as` and `dest-dirs` are now list of paths must have at least two paths when provided.
+
+Please see `debputy plugin show plugable-manifest-rules multi-dest-install` for the full documentation.
+
+# Binary package rules
+
+Inside the manifest, the `packages` mapping can be used to define requests for the binary packages
+you want `debputy` to produce.  Each key inside `packages` must be the name of a binary package
+defined in `debian/control`.  The value is a dictionary defining which features that `debputy`
+should apply to that binary package.  An example could be:
+
+
+    packages:
+        foo:
+            transformations:
+                - create-symlink:
+                      path: usr/share/foo/my-first-symlink
+                      target: /usr/share/bar/symlink-target
+                - create-symlink:
+                      path: usr/lib/{{DEB_HOST_MULTIARCH}}/my-second-symlink
+                      target: /usr/lib/{{DEB_HOST_MULTIARCH}}/baz/symlink-target
+        bar:
+            transformations:
+            - create-directories:
+               - some/empty/directory.d
+               - another/empty/integration-point.d
+            - create-directories:
+                 path: a/third-empty/directory.d
+                 owner: www-data
+                 group: www-data
+
+In this case, `debputy` will create some symlinks inside the `foo` package and some directories for
+the `bar` package.  The following subsections define the keys you can use under each binary package.
+
+
+## Transformations (`packages.{{PACKAGE}}.transformations`)
+
+You can define a `transformations` under the package definition, which is a list a transformation
+rules.  An example:
+
+    packages:
+        foo:
+            transformations:
+              - remove: 'usr/share/doc/{{PACKAGE}}/INSTALL.md'
+              - move:
+                    source: bar/*
+                    target: foo/
+
+
+Transformations are ordered and are applied in the listed order.  A path can be matched by multiple
+transformations; how that plays out depends on which transformations are applied and in which order.
+A quick summary:
+
+ - Transformations that modify the file system layout affect how path matches in later transformations.
+   As an example, `move` and `remove` transformations affects what globs and path matches expand to in
+   later transformation rules.
+
+ - For other transformations generally the latter transformation overrules the earlier one, when they
+   overlap or conflict.
+
+### Remove transformation rule (`remove`)
+
+The remove transformation rule is mostly only useful for single binary source packages, where
+everything from upstream's build system is installed automatically into the package.  In those case,
+you might find yourself with some files that are _not_ relevant for the Debian package (but would be
+relevant for other distros or for non-distro local builds).  Common examples include `INSTALL` files
+or `LICENSE` files (when they are just a subset of `debian/copyright`).
+
+In the manifest, you can ask `debputy` to remove paths from the debian package by using the `remove`
+transformation rule.  An example being:
+
+    packages:
+        foo:
+            transformations:
+              - remove: 'usr/share/doc/{{PACKAGE}}/INSTALL.md'
+
+
+The value for `remove` is a string, a list of strings or mapping. When it is a mapping, the mapping
+has the following key/value pairs:
+
+ * `path` or `paths` (required): A path match (`path`) or a list of path matches (`paths`) defining the
+   path(s) inside the package that should be removed. The path match(es) can use globs.
+    - When a symlink is matched, then the symlink (not its target) is removed as-is.  When a directory is
+      matched, then the directory is removed along with all the contents.
+
+ * `keep-empty-parent-dirs` (optional): A boolean determining whether to prune parent directories that become
+   empty as a consequence of this rule.  When provided and `true`, this rule will leave empty directories
+   behind. Otherwise, if this rule causes a directory to become empty that directory will be removed.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules).  This condition will
+   be combined with the built-in condition provided by these rules (rather than replacing it).
+
+When the input is a string or a list of string, then that value is used as shorthand for `path`
+or `paths` (respectively).
+
+Note that `remove` removes paths from future glob matches and transformation rules.
+
+This rule behaves roughly like the following shell snippet when applied:
+
+```shell
+set -e
+for p in ${paths}; do
+  rm -fr "${p}"
+  if [ "${keep_empty_parent_dirs}" != "true" ]; then
+    rmdir --ignore-fail-on-non-empty --parents "$(dirname "${p}")"
+  fi
+done
+```
+
+### Move transformation rule (`move`)
+
+The move transformation rule is mostly only useful for single binary source packages, where
+everything from upstream's build system is installed automatically into the package.  In those case,
+you might find yourself with some files that need to be renamed to match Debian specific requirements.
+
+This can be done with the `move` transformation rule, which is a rough emulation of the `mv` command
+line tool.  An example being:
+
+    packages:
+        foo:
+            transformations:
+              - move:
+                    source: bar/*
+                    target: foo/
+              # Note this example leaves bar/ as an empty directory. Real world usage would probably
+              # follow this with an remove rule for bar/ to avoid an empty directory
+
+The value for `move` is a mapping with the following key/value pairs:
+
+ * `source` (required): A path match defining the source path(s) to be renamed.  The value can use globs and
+   substitutions.
+
+ * `target` (required): A path defining the target path.  The value *cannot* use globs, but can use substitution.
+   If the target ends with a literal `/` (prior to substitution), the target will *always* be a directory.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules)
+
+There are two basic cases:
+ 1. If `source` match exactly one path and `target` is not a directory (including it does not exist),
+    then `target` is removed (if it existed) and `source` is renamed to `target`.
+    - If the `target` is a directory, and you intentionally want to replace it with a non-directory, please
+      add an explicit `remove` transformation for the directory prior to this transformation.
+
+ 2. If `source` match more than one path *or* `target` is a directory (or is specified with a trailing slash),
+    then all matching sources a moved into `target` retaining their basename.  If `target` already contains
+    overlapping basenames with `source`, then the transformation rule with abort with an error if the overlap
+    contains a directory. Otherwise, any overlapping paths in `target` will be implicitly removed first.
+
+    - If the replacement of a directory is intentional, please add an explicit `remove` rule for it first.
+    - In the case that the `source` glob is exotic enough to match two distinct paths with the same basename,
+      then `debputy` will reject the transformation on account of it being ambiguous.
+
+In either case, parent directories of `target` are created as necessary as long as they do not trigger a conflict
+(or require traversing symlinks or non-directories).  Additionally, the paths matched by `source` will no longer
+match anything (since they are now renamed/relocated), which may affect what path future path matches will apply
+to.
+
+Note that like the `mv`-command, while the `source` paths are no longer present, their parent directories
+will remain.
+
+### Create symlinks transformation rule (`create-symlink`)
+
+Often, the upstream build system will provide the symlinks for you.  However, in some cases, it is useful for
+the packager to define distribution specific symlinks. This can be done via the `create-symlink` transformation
+rule.  An example of how to do this is:
+
+    packages:
+        foo:
+            transformations:
+            - create-symlink:
+                  path: usr/share/foo/my-first-symlink
+                  target: /usr/share/bar/symlink-target
+            - create-symlink:
+                  path: usr/lib/{{DEB_HOST_MULTIARCH}}/my-second-symlink
+                  target: /usr/lib/{{DEB_HOST_MULTIARCH}}/baz/symlink-target
+
+The value for the `create-symlink` key is a mapping, which contains the following keys:
+
+ * `path` (required): The path that should be a symlink.  The path may contain substitution variables
+   such as `{{DEB_HOST_MULTIARCH}}` but _cannot_ use globs.  Parent directories are implicitly created
+   as necessary.
+   * Note that if `path` already exists, the behaviour of this transformation depends on the value of
+     `replacement-rule`.
+
+ * `target` (required): Where the symlink should point to. The target may contain substitution variables
+   such as `{{DEB_HOST_MULTIARCH}}` but _cannot_ use globs.  The link target is _not_ required to exist inside
+   the package.
+   * The `debputy` tool will normalize the target according to the rules of the Debian Policy.  Use absolute
+     or relative target at your own preference.
+
+ * `replacement-rule` (optional): This attribute defines how to handle if `path` already exists. It can be
+   set to one of the following values:
+   - `error-if-exists`: When `path` already exists, `debputy` will stop with an error.  This is similar to
+     `ln -s` semantics.
+   - `error-if-directory`: When `path` already exists, **and** it is a directory, `debputy` will stop with an
+     error. Otherwise, remove the `path` first and then create the symlink.  This is similar to `ln -sf`
+     semantics.
+   - `abort-on-non-empty-directory` (default): When `path` already exists, then it will be removed provided
+     it is a non-directory **or** an *empty* directory and the symlink will then be created.  If the path is
+     a *non-empty* directory, `debputy` will stop with an error.
+   - `discard-existing`: When `path` already exists, it will be removed. If the `path` is a directory, all
+     its contents will be removed recursively along with the directory. Finally, the symlink is created.
+     This is similar to having an explicit `remove` rule just prior to the `create-symlink` that is conditional
+     on `path` existing (plus the condition defined in `when` if any).
+
+   Keep in mind, that `replacement-rule` only applies if `path` exists.  If the symlink cannot be created,
+   because a part of `path` exist and is *not* a directory, then `create-symlink` will fail regardless of the
+   value in `replacement-rule`.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules)
+
+This rule behaves roughly like the following shell snippet when applied:
+
+```shell
+set -e
+case "${replacement_rule}" in
+  error-if-directory)
+    F_FLAG="-f"
+  ;;
+  abort-on-non-empty-directory)
+    if [ -d "${path}" ]; then
+      rmdir "${path}"
+    fi
+    F_FLAG="-f"
+  ;;
+  discard-existing)
+    rm -fr "${path}"
+  ;;
+esac
+install -o "root" -g "root" -m "755" -d "$(dirname "${path}")"
+ln -s ${F_FLAG} "${target}" "${path}"
+```
+
+### Create directories transformation rule (`create-directories`)
+
+NOTE: This transformation is only really needed if you need to create an empty directory somewhere
+in your package as an integration point.  All `debputy` transformations will create directories
+as required.
+
+In most cases, upstream build systems and `debputy` will create all the relevant directories.  However, in some
+rare cases you may want to explicitly define a path to be a directory.  Maybe to silence a linter that is
+warning you about a directory being empty, or maybe you need an empty directory that nothing else is creating
+for you. This can be done via the `create-directories` transformation rule. An example being:
+
+    packages:
+        bar:
+            create-directories:
+            - some/empty/directory.d
+            - another/empty/integration-point.d
+            - path: a/third-empty/directory.d
+              owner: www-data
+              group: www-data
+
+The value for the `create-directories` key is either a string, a list of string or a mapping. When it is a
+mapping, the mapping has the following key/value pairs:
+
+ * `path` or `paths` (required): A path (`path`) or a list of path (`paths`) defining the
+   path(s) inside the package that should be created as directories. The path(es) _cannot_ use globs
+   but can use substitution variables.  Parent directories are implicitly created (with owner `root:root`
+   and mode `0755` - only explicitly listed directories are affected by the owner/mode options)
+
+ * `owner` (optional, default `root`): Denotes the owner of the directory (but _not_ what is inside the directory).
+
+ * `group` (optional, default `root`): Denotes the group of the directory (but _not_ what is inside the directory).
+
+ * `mode` (optional, default `"0755"`): Denotes the mode of the directory (but _not_ what is inside the directory).
+   Note that numeric mode must always be given as a string (i.e., with quotes).  Symbolic mode can be used as well.
+   If symbolic mode uses a relative definition (e.g., `o-rx`), then it is relative to the directory's current mode
+   (if it already exists) or `0755` if the directory is created by this transformation.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules)
+
+When the input is a string or a list of string, then that value is used as shorthand for `path`
+or `paths` (respectively).
+
+Unless you have a specific need for the mapping form, you are recommended to use the shorthand form of
+just listing the directories you want created.
+
+
+Note that implicitly created directories (by this or other transformations) always have owner `root:root`
+and mode `"0755"`.  If you need a directory tree with special ownership/mode, you will have to list all the
+directories in that tree explicitly with the relevant attributes OR use `path-metadata` transformation rule
+to change their metadata after creation.
+
+
+This rule behaves roughly like the following shell snippet when applied:
+
+```shell
+set -e
+for p in ${paths}; do
+  install -o "root" -g "root" -m "755" -d "${p}"
+  chown "${owner}:${group}" "${p}"
+  chmod "${mode}" "${p}"
+done
+```
+
+### Change path owner/group or mode (`path-metadata`)
+
+The `debputy` normalizes the path metadata (such as ownership and mode) similar to `dh_fixperms`.
+For most packages, the default is what you want.  However, in some cases, the package has a special
+case or two that `debputy` does not cover.  In that case, you can tell `debputy` to use the metadata
+you want by using the `path-metadata` transformation.  An example being:
+
+    packages:
+        foo:
+            transformations:
+              - path-metadata:
+                  path: usr/bin/sudo
+                  mode: "0755"
+              - path-metadata:
+                  path: usr/bin/write:
+                  group: tty
+             - path-metadata:
+                  path: /usr/sbin/spine
+                  capabilities: cap_net_raw+ep
+
+
+The value for the `path-metadata` key is a mapping. The mapping has the following key/value pairs:
+Each key defines a path or a glob that may
+
+
+* `path` or `paths` (required): A path match (`path`) or a list of path matches (`paths`) defining the
+  path(s) inside the package that should be affected. The path match(es) can use globs and substitution
+  variables. Special-rules for matches:
+    - Symlinks are never followed and will never be matched by this rule.
+    - Directory handling depends on the `recursive` attribute.
+
+ * `owner` (conditional): Denotes the owner of the paths matched by `path` or `paths`. When omitted, no change of
+   owner is done.
+
+ * `group` (conditional): Denotes the group of the paths matched by `path` or `paths`. When omitted, no change of
+   group is done.
+
+ * `mode` (conditional): Denotes the mode of the paths matched by `path` or `paths`. When omitted, no change in
+   mode is done. Note that numeric mode must always be given as a string (i.e., with quotes).  Symbolic mode can
+   be used as well. If symbolic mode uses a relative definition (e.g., `o-rx`), then it is relative to the
+   directory's current mode.
+
+ * `capabilities` (conditional): Denotes a Linux capability that should be applied to the path. When provided,
+   `debputy` will cause the capability to be applied to all *files* denoted by the `path`/`paths` attribute
+   on install (via `postinst configure`) provided that `setcap` is installed on the system when the
+   `postinst configure` is run.
+   - If any non-file paths are matched, the `capabilities` will *not* be applied to those paths.
+
+ * `capability-mode` (optional): Denotes the mode to apply to the path *if* the Linux capability denoted in
+   `capabilities` was successfully applied. If omitted, it defaults to `a-s` as generally capabilities are
+   used to avoid "setuid"/"setgid" binaries. The `capability-mode` is relative to the *final* path mode
+   (the mode of the path in the produced `.deb`). The `capability-mode` attribute cannot be used if
+   `capabilities` is omitted.
+
+ * `recursive` (optional, default `false`): When a directory is matched, then the metadata changes are applied
+    to the directory itself. When `recursive` is `true`, then the transformation is *also* applied to all paths
+    beneath the directory.
+
+ * `when` (optional): A condition as defined in [Conditional rules](#conditional-rules)
+
+At least one of `owner`, `group`, `mode`, or `capabilities` must be provided.
+
+This rule behaves roughly like the following shell snippet when applied:
+
+```shell
+MAYBE_R_FLAG=$(${recursive} && printf "%s" "-R")
+
+for p in ${path}; do
+  if [ -n "${owner}" ] || [ -n "${group}" ]; then
+    chown $MAYBE_R_FLAG "${owner}:${group}" "${p}"
+  fi
+  if [ -n "${mode}" ]; then
+    chmod $MAYBE_R_FLAG "${mode}" "${p}"
+  fi
+done
+```
+
+(except all symlinks will be ignored)
+
+## Custom binary version (`binary-version`)
+
+In the *rare* case that you need a binary package to have a custom version, you can use the `binary-version:`
+key to describe the desired package version.  An example being:
+
+    packages:
+        foo:
+            # The foo package needs a different epoch because we took it over from a different
+            # source package with higher epoch version
+            binary-version: '1:{{DEB_VERSION_UPSTREAM_REVISION}}'
+
+Use this feature sparingly as it is generally not possible to undo as each version must be monotonously
+higher than the previous one.  This feature translates into `-v` option for `dpkg-gencontrol`.
+
+The value for the `binary-version` key is a string that defines the binary version.  Generally, you will
+want it to contain one of the versioned related substitution variables such as 
+`{{DEB_VERSION_UPSTREAM_REVISION}}`.  Otherwise, you will have to remember to bump the version manually
+with each upload as versions cannot be reused and the package would not support binNMUs either.
+
+
+## Remove runtime created paths on purge or post removal (`clean-after-removal`)
+
+For some packages, it is necessary to clean up some run-time created paths. Typical use cases are
+deleting log files, cache files, or persistent state. This can be done via the `clean-after-removal`.
+An example being:
+
+    packages:
+        foo:
+            clean-after-removal:
+            - /var/log/foo/*.log
+            - /var/log/foo/*.log.gz
+            - path: /var/log/foo/
+              ignore-non-empty-dir: true
+            - /etc/non-conffile-configuration.conf
+            - path: /var/cache/foo
+              recursive: true
+
+
+The `clean-after-removal` key accepts a list, where each element is either a mapping, a string or a list
+of strings. When an element is a mapping, then the following key/value pairs are applicable:
+
+ * `path` or `paths` (required): A path match (`path`) or a list of path matches (`paths`) defining the
+   path(s) that should be removed after clean. The path match(es) can use globs and manifest variables.
+   Every path matched will by default be removed via `rm -f` or `rmdir` depending on whether the path
+   provided ends with a *literal* `/`. Special-rules for matches:
+    - Glob is interpreted by the shell, so shell (`/bin/sh`) rules apply to globs rather than
+      `debputy`'s glob rules.  As an example, `foo/*` will **not** match `foo/.hidden-file`.
+    - `debputy` cannot evaluate whether these paths/globs will match the desired paths (or anything at
+      all). Be sure to test the resulting package.
+    - When a symlink is matched, it is not followed.
+    - Directory handling depends on the `recursive` attribute and whether the pattern ends with a literal
+      "/".
+    - `debputy` has restrictions on the globs being used to prevent rules that could cause massive damage
+      to the system.
+
+ * `recursive` (optional): When `true`, the removal rule will use `rm -fr` rather than `rm -f` or `rmdir`
+    meaning any directory matched will be deleted along with all of its contents.
+
+ * `ignore-non-empty-dir` (optional): When `true`, each path must be or match a directory (and as a
+   consequence each path must with a literal `/`). The affected directories will be deleted only if they
+   are empty. Non-empty directories will be skipped. This option is mutually exclusive with `recursive`.
+
+ * `delete-on` (optional, defaults to `purge`): This attribute defines when the removal happens. It can
+   be set to one of the following values:
+   - `purge`: The removal happens with the package is being purged. This is the default. At a technical
+     level, the removal occurs at `postrm purge`.
+   - `removal`: The removal happens immediately after the package has been removed. At a technical level,
+     the removal occurs at `postrm remove`.
+
+
+This feature resembles the concept of `rpm`'s `%ghost` files.
+
+## Custom installation time search directories (`installation-search-dirs`)
+
+For source packages that does multiple build, it can be an advantage to provide a custom list of
+installation-time search directories. This can be done via the `installation-search-dirs` key. A common
+example is building  the source twice with different optimization and feature settings where the second
+build is for the `debian-installer` (in the form of a `udeb` package). A sample manifest snippet could
+look something like:
+
+    installations:
+    - install:
+        # Because of the search order (see below), `foo` installs `debian/tmp/usr/bin/tool`,
+        # while `foo-udeb` installs `debian/tmp-udeb/usr/bin/tool` (assuming both paths are
+        # available). Note the rule can be split into two with the same effect if that aids
+        # readability or understanding.
+        source: usr/bin/tool
+        into:
+          - foo
+          - foo-udeb
+    packages:
+        foo-udeb:
+            installation-search-dirs:
+            - debian/tmp-udeb
+
+
+The `installation-search-dirs` key accepts a list, where each element is a path (str) relative from the
+source root to the directory that should be used as a search directory (absolute paths are still interpreted
+as relative to the source root).  This list should contain all search directories that should be applicable
+for this package (except the source root itself, which is always appended after the provided list). If the
+key is omitted, then `debputy` will provide a default  search order (In the `dh` integration, the default
+is the directory `debian/tmp`).
+
+If a non-existing or non-directory path is listed, then it will be skipped (info-level note). If the path
+exists and is a directory, it will also be checked for "not-installed" paths.
+
+
+[reference documentation]: https://documentation.divio.com/reference/
diff --git a/MIGRATING-A-DH-PLUGIN.md b/MIGRATING-A-DH-PLUGIN.md
new file mode 100644
index 0000000..3e4e227
--- /dev/null
+++ b/MIGRATING-A-DH-PLUGIN.md
@@ -0,0 +1,536 @@
+# Migrating a `debhelper` plugin to `debputy`
+
+_This is [how-to guide] and is primarily aimed at getting a task done._
+
+<!-- To writers and reviewers: Check the documentation against https://documentation.divio.com/ -->
+
+This document will help you convert a `debhelper` plugin / `debhelper` tool into a `debputy` plugin.
+Prerequisites for this how-to guide:
+
+ * You have a `debhelper` tool/plugin that you want to migrate.  Ideally a simple one as not all tools
+   can be migrated at this time.
+ * Many debhelper tools do not come with test cases, because no one has created a decent test framework
+   for them.  Therefore, consider how you intend to validate that the `debputy` plugin does not have any
+   (unplanned) regressions compared to `debhelper` tool.
+ * Depending on the features needed, you may need to provide a python hook for `debputy` to interact
+   with.
+   - Note: `debputy` will handle byte-compilation for you per
+     [Side note: Python byte-compilation](#side-note-python-byte-compilation)
+
+Note that during the conversion, you may find that `debputy` cannot support the requirements for your
+debhelper tool for now.  Feel free to file an issue for what is holding you back in the
+[debputy issue tracker].
+
+Prerequisites
+-------------
+
+This guide assumes familiarity with Debian packaging and the debhelper tool stack in general.  Notably,
+you are expected to be familiar with the `Dh_Lib.pm` API to the point of recognising references to said
+API and how to look up document for methods from said API.
+
+If the debhelper tool is not written in `Dh_Lib.pm`, then you will need to understand how to map the
+`Dh_Lib.pm` reference into the language/tool equivalent on your own.
+
+## Step 0: The approach taken
+
+The guide will assume you migrate one tool (a `dh_foo` command) at a time. If you have multiple tools
+that need to migrate together, you may want to review "Step 1" below for all tools before migrating to
+further steps.
+
+## Step 1: Analyze what features are required by the tools and the concept behind the helper
+
+For the purpose of this guide, we can roughly translate debhelper tools into one or more
+of the following categories.
+
+
+### Supported categories
+
+ * Install `debian/pkg.foo` *as-is* into a directory.
+    - This category uses a mix of `pkgfile` + `install_dir` + `install_file` / `install_prog`
+    - Example: `dh_installtmpfiles`
+ * If some file is installed in or beneath a directory, then (maybe) analyze the file, and apply metadata
+    (substvars, maintscripts, triggers, etc.). Note this does *not* apply to special-case of services.
+    While services follow this pattern, `debputy` will have special support for services.
+    - Typically, this category uses a bit of glob matching + (optionally) `open` +
+      `addsubstvars` / `autoscript` / `autotrigger`
+    - Example: `dh_installtmpfiles`
+    - *Counter* examples: `dh_installsystemd` (due to service rule, below).
+
+### Unsupported categories
+
+ * Read `debian/pkg.foo` and do something based on the content of said file.
+    - Typically, the category uses a mix of `pkgfile` + `filedoublearray` / `filearray` / `open(...)`.
+      The most common case of this is to install a list of files in the `debian/pkg.foo` file.
+    - In this scenario, the migration strategy should likely involve replacing `debian/pkg.foo` with
+      a section inside the `debian/debputy.manifest` file.
+    - Example: `dh_install`
+ * Any tool that manages services like `systemd`, `init.d` or `runit`.
+    - Typically, this category uses a bit of glob matching + (optionally) `open` +
+      `addsubstvars` / `autoscript` / `autotrigger`.
+    - This is unsupported because services will be a first-class feature in `debputy`, but the feature
+      is not fully developed yet.
+    - Example: `dh_installsystemd`
+ * Based on a set of rules, modify a set of files if certain criteria are met.
+    - Example: `dh_strip`, `dh_compress`, `dh_dwz`, `dh_strip_nondeterminism`, `dh_usrlocal`
+ * Run custom build system logic that cannot or has not been fit into the `debhelper` Buildsystem API.
+    - Example: `dh_cmake_install`, `dh_raku_build`, etc.
+ * "None of the above". There are also tools that have parts not fitting into any of the above
+    - Which just means the guide has no good help to offer you for migrating.
+    - Example: `dh_quilt_patch`
+
+As mentioned, a tool can have multiple categories at the same time.  As an example:
+
+ * The `dh_installtmpfiles` tool from debhelper is a mix between "installing `debian/pkg.tmpfiles` in to
+   `usr/lib/tmpfiles.d`" and "Generate a maintscript based on `<prefix>/tmpfiles.d/*.conf` globs".
+
+ * The `dh_usrlocal` tool from debhelper is a mix between "Generate a maintscript to create dirs in
+   `usr/local` as necessary on install and clean up on removal" and "Remove any directory from `usr/local`
+   installed into the package".
+
+
+When migrating a tool (or multiple tools), it is important to assert that all categories are supported by
+the `debputy` plugin API.  Otherwise, you will end with a half-finished plugin and realize you cannot
+complete the migration because you are missing a critical piece that `debputy` currently do not support.
+
+If your tool does not fit inside those two base categories, you cannot fully migrate the tool. You should
+consider whether it makes sense to continue without the missing features.
+
+## Step 2: Setup basic infrastructure
+
+This how-to guide assumes you will be using the debhelper integration via `dh-sequence-installdebputy`. To
+do that, add `dh-sequence-installdebputy` in the `Build-Depends` in `debian/control`. With this setup,
+any `debputy` plugin should be provided in the directory `debian/<package>.debputy-plugins` (replace `<package>`
+with the name of the package that should provide the plugin).
+
+In this directory, for each plugin, you can see the following files:
+
+    debian/package.debputy-plugins/my-plugin.json      # Metadata file (mandatory)
+    debian/package.debputy-plugins/my_plugin.py        # Python implementation (optional, note "_" rather than "_")
+    debian/package.debputy-plugins/my_plugin_check.py  # tests (optional, run with py.test, note "_" rather than "_")
+                                                       # Alternative names such as _test.py or _check_foo.py works too
+
+A basic version of the JSON plugin metadata file could be:
+
+
+```json
+{
+  "plugin-initializer": "initialize_my_plugin",
+  "api-compat-level": 1,
+  "packager-provided-files": [
+    {
+      "stem": "foo",
+      "installed-path": "/usr/share/foo/{name}.conf"
+    }
+  ]
+}
+```
+
+This example JSON assumes that you will be providing both python code (`plugin-intializer`, requires a Python
+implementation file) and packager provided files (`packager-provided-files`). In some cases, you will *not*
+need all of these features. Notably, if you find that you do not need any feature requiring python code,
+you are recommended to remove `plugin-initializer` from the plugin JSON file.
+
+A Python-based plugin for `debputy` plugin starts with an initialization function like this:
+
+```python
+from debputy.plugin.api import DebputyPluginInitializer
+
+def initialize_my_plugin(api: DebputyPluginInitializer):
+    pass
+```
+
+Remember to replace the values in the JSON, so they match your plugin. The keys are:
+
+ * `plugin-initializer`: (Python plugin-only) The function `debputy` should call to initialize your plugin. This is
+   the function we  just defined in the previous example). The plugin loader requires this initialization function to
+   be a top level function of the module (that is, `getattr(module, plugin_initializer)` must return the initializer
+   function).
+ * `module`: (Python plugin-only, optional) The python module the `plugin-initializer` function is defined in.
+   If omitted, `debputy` will derive the module name from the plugin name (replace `-` with `_`). When omitted,
+   the Python module can be placed next to the `.json` file.  This is useful single file plugins.
+ * `api-compat-level`: This is the API compat level of `debputy` required to load the
+   plugin. This defines how `debputy` will load the plugin and is to ensure that
+   `debputy`'s plugin API can evolve gracefully.  For now, only one version is supported
+   and that is `1`.
+ * `packager-provided-files`: Declares packager provided files. This keyword is covered in the section below.
+
+This file then has to be installed into the `debputy` plugin directory.
+
+With this you have an empty plugin that `debputy` can load, but it does not provide any features.
+
+## Step 3: Provide packager provided files (Category 1 tools)
+
+*This step only applies if the tool in question automatically installs `debian/pkg.foo` in some predefined path
+like `dh_installtmpfiles` does.  If not, please skip this section as it is not relevant to your case.*
+
+You can ask `debputy` to automatically detect `debian/pkg.foo` files and install them into a concrete directory
+via the plugin. You have two basic options for providing packager provided files.
+
+ 1) A pure-JSON plugin variant.
+ 2) A Python plugin variant.
+
+This guide will show you both. The pure-JSON variant is recommended assuming it satisfies your needs as it is
+the simplest to get started with and have fewer moving parts.  The Python plugin has slightly more features
+for the "1% special cases".
+
+### Packager provided files primer on naming convention
+
+This section will break the filename `debian/g++-3.0.name.segment.my.file.type.amd64` down into parts and name
+the terms `debputy` uses for them and how they are used. If you already know the terms, you can skip this section.
+
+This example breaks into 4 pieces, in order:
+
+ * An optional package name (`g++-3.0`). Decides which package the file applies to (defaulting to the main package
+   if omitted).  It is also used as the default "installed as name".
+
+ * An optional "name segment" (`name.segment`). Named so after the `--name` parameter from `debhelper` that is
+   needed for `debhelper` to detect files with the segment and because it also changes the default "installed as
+   name" (both in `debhelper` and `debputy`). When omitted, the package name decides the "installed as name".
+
+ * The "stem" (`my.file.type`). This part never had an official name in `debhelper` other than `filename`
+   or `basename`.
+
+ * An optional architecture restriction. It is used in special cases like `debian/foo.symbols.amd64` where you
+   have architecture specific details in the file.
+
+In `debputy`, when you register a packager provided file, you have some freedom in which of these should apply
+to your file.  The architecture restriction is rarely used and disabled by default, whereas the "name segment"
+is available by default. When the "name segment" is enabled, the packager is able to:
+
+ 1) choose a different filename than the package name (by using `debian/package.desired-name.foo` instead of
+    `debian/package.foo`)
+
+ 2) provide multiple files for the same package (`debian/package.foo` *and* `debian/package.some-name.foo`).
+
+If it is important that a package can provide at most one file, and it must be named after the package itself,
+you are advised to disable to name segment.
+
+### JSON-based packager provided files (Category 1 tools)
+
+With the pure JSON based method, the plugin JSON file should contain all the relevant details. A minimal
+example is:
+
+```json
+{
+  "api-compat-level": 1,
+  "packager-provided-files": [
+    {
+      "stem": "foo",
+      "installed-path": "/usr/share/foo/{name}.conf",
+      "reference-documentation": {
+        "description": "Some possibly multi-line description related to foo",
+        "format-documentation-uris": ["man:foo.conf(5)"]
+      }
+    }
+  ]
+}
+```
+(This file should be saved as `debian/package.debputy-plugins/my-plugin.json`.)
+
+This plugin snippet would provide one packager provided files and nothing else. When loading the plugin, `debputy`
+would detect files such as `debian/package.foo` and install them into `/usr/share/foo/package.conf`.
+
+As shown in the example. the packager provided files are declared as a list in the attribute
+`packager-provided-files`. Each element in that list is an object with the following keys:
+
+ * `name` (required): The "stem" of the file. In the example above, `"foo"` is used meaning that `debputy`
+   would detect `debian/package.foo`. Note that this value must be unique across all packager provided files known
+   by `debputy` and all loaded plugins.
+
+ * `installed-path` (required): A format string describing where the file should be installed. This is
+   `"/usr/share/foo/{name}.conf"` from the example above and leads to `debian/package.foo` being installed
+   as `/usr/share/foo/package.conf`.
+
+   The following placeholders are supported:
+
+     * `{name}` - The name in the name segment (defaulting the package name if no name segment is given)
+     * `{priority}` / `{priority:02}` - The priority of the file. Only provided priorities are used (that
+       is, `default-priority` is provided).  The latter variant ensuring that the priority takes at least
+       two characters and the `0` character is left-padded for priorities that takes less than two
+       characters.
+     * `{owning_package}` - The name of the package.  Should only be used when `{name}` alone is insufficient.
+       If you do not want the "name" segment in the first place, set `allow-name-segment` to `false` instead.
+
+     The path is always interpreted as relative to the binary package root.
+
+ * `default-mode` (optional): If provided, it must be an octal mode (such as `"0755"`), which defines the mode
+   that `debputy` will use by default for this kind of file. Note that the mode must be provided as a string.
+
+ * `default-priority` (optional): If provided, it must be an integer declaring the default priority of the file,
+   which will be a part of the filename.  The `installed-path` will be required to have the `{priority}` or
+   `{priority:02}` placeholder. This attribute is useful for directories where the files are read in "sorted"
+   and there is a convention of naming files like `20-foo.conf` to ensure files are processed in the correct
+   order.
+
+ * `allow-name-segment` (optional): If provided, it must be a boolean (defaults to `true`), which determines
+   whether `debputy` should allow a name segment for the file.
+
+ * `allow-architecture-segment` (optional): If provided, it must be a boolean (defaults to `false`), which determines
+   whether `debputy` should allow an architecture restriction for the file.
+
+ * `reference-documentation` (optional): If provided, the following keys can be used:
+
+    * `description` (optional): If provided, it is used as a description for the file if the user requests
+       documentation about the file.
+
+    * `format-documentation-uris` (optional): If provided, it must be a list of URIs that describes the format
+       of the file. `http`, `https` and `man` URIs are recommended.
+
+
+### Python-based packager provided files (Category 1 tools)  [NOT RECOMMENDED]
+
+**This section uses a Python-based API, which is not recommended at this time as the logistics are not finished**
+
+With the Python based method, the plugin JSON file should contain a reference to the python module. A minimal
+example is:
+
+```json
+{
+  "api-compat-level": 1,
+  "plugin-initializer": "initialize_my_plugin"
+}
+```
+(This file should be saved as `debian/package.debputy-plugins/my-plugin.json`.)
+
+The python module file should then provide the `initialize_my_plugin` function, which could look something like this:
+
+```python
+from debputy.plugin.api import DebputyPluginInitializer
+
+def initialize_my_plugin(api: DebputyPluginInitializer):
+    api.packager_provided_file(
+        "foo",  # This is the "foo" in "debian/pkg.foo"
+        "/usr/share/foo/{name}.conf",  # This is the directory to install them at.
+    )
+```
+(This file would be saved as `debian/package.debputy-plugins/my_plugin.py` assuming `my-plugin.json` was
+used for the metadata file)
+
+This example code would make `debputy` install `debian/my-pkg.foo` as `/usr/share/foo/my-pkg.conf` provided the
+plugin is  loaded. Please review the API docs for the full details of options.
+
+This can be done via the interactive python shell with:
+
+```python
+import sys
+sys.path.insert(0, "/usr/share/dh-debputy/")
+from debputy.plugin.api import DebputyPluginInitializer
+help(DebputyPluginInitializer.packager_provided_file)
+```
+
+### Testing your plugin
+
+If you are the type that like to provide tests for your code, the following `py.test` snippet can get you started:
+
+```python
+from debputy.plugin.api.test_api import initialize_plugin_under_test
+
+
+def test_packager_provided_files():
+    plugin = initialize_plugin_under_test()
+    ppf_by_stem = plugin.packager_provided_files_by_stem()
+    assert ppf_by_stem.keys() == {'foo'}
+    foo_file = ppf_by_stem['foo']
+
+    assert foo_file.stem == 'foo'
+
+    # Note, the discard part is the installed into directory, and it is skipped because `debputy`
+    # normalize the directory as an implementation detail and the test would depend on said detail
+    # for no good reason in this case.  If your case have the variable in the directory part, tweak
+    # the test as necessary.
+    _, basename = foo_file.compute_dest("my-package")
+    assert basename == 'my-package.conf'
+    # Test other things you might have configured:
+    #   assert foo_file.default_mode == 0o755   # ... if the file is to be executable
+    #   assert foo_file.default_priority == 20  # ... if the file has priority
+    #   ...
+```
+(This file would be saved as `debian/package.debputy-plugins/my_plugin_check.py` assuming `my-plugin.json` was
+used for the metadata file)
+
+This test works the same regardless of whether the JSON-based or Python-based method was chosen.
+
+## Step 4: Migrate metadata detection (Category 3 tools)  [NOT RECOMMENDED]
+
+*This step only applies if the tool in question generates substvars, maintscripts or triggers based on
+certain paths being present or having certain content like `dh_installtmpfiles` does.  However,
+this section does **NOT** apply to service management tools (such as `dh_installsystemd`). If not, please
+skip this section as it is not relevant to your case.*
+
+For dealing with substvars, maintscripts and triggers, the plugin will need to register a function that
+can perform the detection. The `debputy` API refers to it as a "detector" and functionally it behaves like
+a "callback" or "hook". The "detector" will be run once per package that it applies to with some context and
+is expected to register the changes it wants.
+
+A short example is:
+
+```python
+from debputy.plugin.api import (
+   DebputyPluginInitializer,
+   VirtualPath,
+   BinaryCtrlAccessor,
+   PackageProcessingContext,
+)
+
+
+def initialize_my_plugin(api: DebputyPluginInitializer):
+   # ... remember to preserve any existing code here that you may have had from previous steps.
+   api.metadata_or_maintscript_detector(
+      "foo-detector",  # This is an ID of the detector. It is part of the plugins API and should not change.
+      # Packagers see it if it triggers an error and will also be able to disable by this ID.
+      detect_foo_files,  # This is the detector (hook) itself.
+   )
+
+
+def detect_foo_files(fs_root: VirtualPath,
+                     ctrl: BinaryCtrlAccessor,
+                     context: PackageProcessingContext,
+                     ) -> None:
+   # If for some reason the hook should not apply to all packages, and `metadata_or_maintscript_detector` does not
+   # provide a filter for it, then you just do an `if <should not apply>: return`
+   if not context.binary_package.is_arch_all:
+      # For some reason, our hook only applies to arch:all packages.
+      return
+
+   foo_dir = fs_root.lookup("usr/share/foo")
+   if not foo_dir:
+      return
+
+   conf_files = [path.absolute for path in foo_dir.iterdir if path.is_file and path.name.endswith(".conf")]
+   if not conf_files:
+      return
+   ctrl.substvars.add_dependency("misc:Depends", "foo-utils")
+   conf_files_escaped = ctrl.maintscript.escape_shell_words(*conf_files)
+   # With multi-line snippets, consider:
+   #
+   # snippet = textwrap.dedent("""\
+   #     ... content here using {var}
+   # """).format(var=value)
+   #
+   # (As that tends to result in more readable snippets, when the dedent happens before formatting)
+   snippet = f"foo-analyze --install {conf_files_escaped}"
+   ctrl.maintscript.on_configure(snippet)
+```
+(This file would be saved as `debian/package.debputy-plugins/my_plugin.py`)
+
+This code would register the `detect_foo_files` function as a metadata hook. It would be run for all regular `deb`
+packages processed by `debputy` (`udeb` requires opt-in, auto-generated packages such as `-dbgsym` cannot be
+targeted).
+
+The hook conditionally generates a dependency (via the `${misc:Depends}` substvar) on `foo-utils` and a `postinst`
+snippet to be run when the package is configured.
+
+An important thing to note is that `debputy` have *NOT* materialized the package anywhere. Instead, `debputy`
+provides an in-memory view of the file system (`fs_root`) and related path metadata that the plugin should base its
+analysis of. The in-memory view of the file system can have virtual paths that are not backed by any real
+path on the file system.  This commonly happens for directories and symlinks - and during tests, also for files.
+
+
+In addition to the python code above, remember that the plugin JSON file should contain a reference to the python
+module. A minimal example for this is:
+
+```json
+{
+  "api-compat-level": 1,
+  "plugin-initializer": "initialize_my_plugin"
+}
+```
+(This file should be saved into `debian/package.debputy-plugins/my-plugin.json` assuming `my_plugin.py` was
+used for the module file)
+
+
+If you are the type that like to provide tests for your code, the following `py.test` snippet can get you started:
+
+```python
+from debputy.plugin.api.test_api import initialize_plugin_under_test, build_virtual_file_system, \
+    package_metadata_context
+
+
+def test_packager_provided_files():
+    plugin = initialize_plugin_under_test()
+    detector_id = 'foo-detector'
+
+    fs_root = build_virtual_file_system([
+        '/usr/share/foo/foo.conf'  # Creates a virtual (no-content) file.
+        # Use virtual_path_def(..., fs_path="/path") if your detector needs to read the file
+        # NB: You have to create that "/path" yourself.
+    ])
+
+    metadata = plugin.run_metadata_detector(
+        detector_id,
+        fs_root,
+        # Test with an arch:any package. The test framework will supply a minimum number of fields
+        # (e.g., "Package") so you do not *have* to provide them if you do not need them.
+        # That is also why providing `Architecture` alone works here.
+        context=package_metadata_context(package_fields={'Architecture': 'any'})
+    )
+    # Per definition of our detector, there should be no dependency added (even though the file is there)
+    assert 'misc:Depends' not in metadata.substvars
+    # Nor should any maintscripts have been added
+    assert metadata.maintscripts() == []
+
+    metadata = plugin.run_metadata_detector(
+        detector_id,
+        fs_root,
+        # This time, we test with an arch:all package
+        context=package_metadata_context(package_fields={'Architecture': 'all'})
+    )
+
+    assert metadata.substvars['misc:Depends'] == 'foo-utils'
+
+    # You could also have added `maintscript='postinst'` to filter by which script it was added to.
+    snippets = metadata.maintscripts()
+    # There should be exactly one snippet
+    assert len(snippets) == 1
+    snippet = snippets[0]
+    # And we can verify that the snippet is as expected.
+    assert snippet.maintscript == 'postinst'
+    assert snippet.registration_method == 'on_configure'
+    assert 'foo-analyze --install /usr/share/foo/foo.conf' in snippet.plugin_provided_script
+```
+(This file should be saved into `debian/package.debputy-plugins/my_plugin_check.json` assuming `my_plugin.py` was
+used for the module file)
+
+This test works the same regardless of whether the JSON-based or Python-based method was chosen.
+
+## Step 4: Have your package provide `debputy-plugin-X`
+
+All third-party `debputy` plugins are loaded by adding a build dependency on `debputy-plugin-X`,
+where `X` is the basename of the plugin JSON file.  Accordingly, any package providing a `debputy` plugin
+must either be named `debputy-plugin-X` or provide `debputy-plugin-X` (where `X` is replaced with the concrete
+plugin name).
+
+## Step 5: Running the tests
+
+To run the tests, you have two options:
+
+ 1) Add `python3-pytest <!nocheck>` to the `Build-Depends` in `debian/control`. This will cause
+    `dh_installdebputy` to run the tests when the package is built. The tests will be skipped
+    if `DEB_BUILD_OPTIONS` contains `nocheck` per Debian Policy.  You will also need to have
+    the `debputy` command in PATH. This generally happens as a side effect of the
+    `dh-sequence-installdebputy` build dependency.
+
+ 2) Add `autopkgtest-pkg-debputy` to the `Testsuite` field in `debian/control`.  This will cause
+    the Debian CI framework (via the `autodep8` command) to generate an autopkgtest that will
+    run the plugin tests against the installed plugin.
+
+Using both options where possible is generally preferable.
+
+If your upstream uses a Python test framework that auto-detects tests such as `py.test`, you may
+find that it picks up the `debputy` plugin or its tests. If this is causing you issues, please have
+a  look at the `dh_installdebputy` manpage, which have a section dedicated to how to resolve these
+issues.
+
+## Side note: Python byte-compilation
+
+When you install a `debputy` plugin into `/usr/share/debputy/debputy/plugins`, then `debputy` will
+manage the Python byte-compilation for you.
+
+## Closing
+
+You should now either have done all the basic steps of migrating the debhelper tool to `debputy`
+or discovered some feature that the guide did not cover. In the latter case, please have a look
+at the [debputy issue tracker] and consider whether you should file a feature request for it.
+
+[how-to guide]: https://documentation.divio.com/how-to-guides/
+[debputy issue tracker]: https://salsa.debian.org/debian/debputy/-/issues
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..eb54f26
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,39 @@
+#!/usr/bin/make -f
+
+DEBPUTY_INSTALLED_ROOT_DIR=/usr/share/dh-debputy
+DEBPUTY_INSTALLED_PLUGIN_ROOT_DIR=/usr/share/debputy/
+
+# Nothing to do by default
+all:
+
+check:
+	py.test -v
+
+install:
+	install -m0755 -d \
+	    $(DESTDIR)/usr/bin \
+	    $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR) \
+	    $(DESTDIR)/$(DEBPUTY_INSTALLED_PLUGIN_ROOT_DIR)/debputy \
+	    $(DESTDIR)/usr/share/perl5/Debian/Debhelper/Sequence \
+	    $(DESTDIR)/usr/share/man/man1
+	install -m0755 -t $(DESTDIR)/usr/bin dh_debputy dh_installdebputy assets/debputy
+	install -m0755 -t $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR) deb_packer.py deb_materialization.py
+	install -m0644 -t $(DESTDIR)/usr/share/perl5/Debian/Debhelper/Sequence lib/Debian/Debhelper/Sequence/*.pm
+	cp -a --reflink=auto src/debputy $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR)
+	cp -a --reflink=auto debputy $(DESTDIR)/$(DEBPUTY_INSTALLED_PLUGIN_ROOT_DIR)
+	sed -i "s/^__version__ =.*/__version__ = '$$(dpkg-parsechangelog -SVersion)'/; s/^__release_commit__ =.*/__release_commit__ = 'N\\/A'/;" \
+	   $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR)/debputy/version.py
+	perl -p -i -e 's{^DEBPUTY_ROOT_DIR =.*}{DEBPUTY_ROOT_DIR = pathlib.Path("$(DEBPUTY_INSTALLED_ROOT_DIR)")};' \
+	   $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR)/debputy/__init__.py
+	perl -p -i -e 's{^DEBPUTY_PLUGIN_ROOT_DIR =.*}{DEBPUTY_PLUGIN_ROOT_DIR = pathlib.Path("$(DEBPUTY_INSTALLED_PLUGIN_ROOT_DIR)")};' \
+	   $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR)/debputy/__init__.py
+	find $(DESTDIR)/usr/share/dh-debputy -type d -name '__pycache__' -exec rm -fr {} +
+	pod2man --utf8 --section=1 --name="debputy" -c "The debputy Debian packager helper stack" debputy.pod \
+	   $(DESTDIR)/usr/share/man/man1/debputy.1
+	pod2man --utf8 --section=1 --name="dh_debputy" -c "The debputy Debian packager helper stack" dh_debputy \
+	   $(DESTDIR)/usr/share/man/man1/dh_debputy.1
+	pod2man --utf8 --section=1 --name="dh_installdebputy" -c "The debputy Debian packager helper stack" dh_installdebputy \
+	   $(DESTDIR)/usr/share/man/man1/dh_installdebputy.1
+	chmod -R u=rwX,go=rX \
+	    $(DESTDIR)/$(DEBPUTY_INSTALLED_ROOT_DIR)/debputy \
+	    $(DESTDIR)/$(DEBPUTY_INSTALLED_PLUGIN_ROOT_DIR)/debputy
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3204766
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+debputy
+=======
+
+The debputy tool is a debian package builder that works with a declarative
+manifest format.
+
+The early versions will integrate into the debhelper sequencer dh and will replace
+several of debhelper's tools that are covered by debputy.  However, the goal is that
+debputy will be a standalone tool capable of packaging work from start to end.
+
+The debputy package builder aims to reduce cognitive load for the packager
+and provide better introspection to packagers, linters and the Debian janitor.
+
+For documentation, please see:
+ * [GETTING-STARTED-WITH-dh-debputy.md](GETTING-STARTED-WITH-dh-debputy.md) for getting started (how-to guide).
+ * [MANIFEST-FORMAT.md](MANIFEST-FORMAT.md) for details of the format (reference documentation).
+ * [MIGRATING-A-DH-PLUGIN.md](MIGRATING-A-DH-PLUGIN.md) for details on how to migrate a `dh` add-on
+   (how-to guide)
+
+
+Prerequisites
+-------------
+
+On a (modern) Debian system, you can install prerequisites via the following apt command.
+
+     apt build-deps -y .
+
+This includes the minimal development stack used to build the `debputy` package.  Have
+a look at `debian/control` if you want the minimal dependencies for running `debputy`
+directly.
+
+
+Running tests
+-------------
+
+From the top level directory, run `py.test`.
+
+
+Running debputy from source
+---------------------------
+
+While developing, it is useful to run `debputy` directly from the source tree without having
+to build first.  This can be done by invoking the `debputy.sh` command in the source root on
+any system that has `#!/bin/sh`.
+
+Otherwise, at the time of writing, you can use the following command:
+
+    PYTHONPATH=src python3 -m debputy.commands.debputy_cmd
+
+Which only relies on the `PYTHONPATH` environment variable being set correctly and having `python3`
+in `PATH`.
+
+You can also run the `dh_debputy` command in a similar fashion. It will require you to set the
+`DEBPUTY_CMD` to point to full path of `debputy.sh` (or a self-written script of similar
+functionality), or have wrapper called `debputy` in `PATH`.
+
+
+The naming
+----------
+
+The name debputy is a play on the word "deputy" (using the "assistant" or
+"authorized to act as substitute for another" definition) and the "deb"
+from deb packages.  The idea is that you tell debputy what you want
+(via the declarative manifest) and debputy handles the details of how to
+do it.
+
+
+# Communication channels:
+
+The following communication channels are available:
+
+ * Using the https://salsa.debian.org/debian/debputy features, such as issues. Generally, these
+   will be available to the public. While confidential issues can be filed, please note that
+   all Debian developers can read it.
+ * Filing bugs via `reportbug debputy` to the Debian bug tracker. Note all such bugs will have
+   public archives.
+ * Mail to Debputy Maintainers <debputy@packages.debian.org>. Please note that no public archive
+   is available but anyone can subscribe via tracker.debian.org.
+ * IRC chat on #debputy-devel on the irc.oftc.net server. No public archive will be kept but any
+   individual  in the channel will likely keep a history of the discussions.
+
+
+## Security issues
+
+For issues that should be embargoed, please report the issue to the Debian Security team, which
+has the relevant skill set, policies, and infrastructure to handle this. While the
+salsa.debian.org services provides support for **confidential** issues, all Debian Developers
+can read those for the `debputy` project. This makes it unsuitable for security bugs under embargo.
+
+Please review https://www.debian.org/security/faq#contact for how to contact the Debian security
+team.
diff --git a/THANKS.md b/THANKS.md
new file mode 100644
index 0000000..e21556e
--- /dev/null
+++ b/THANKS.md
@@ -0,0 +1,25 @@
+Supporters of debputy
+=====================
+
+The `debputy` tool would probably never have been anything
+other than some weird unused prototype without the following
+people, who supported me early on:
+
+ * Maria Thy Østengaard, who provided the name
+ * Russ Allbery and Lars Wirzenius, who provided early feedback and suggestions for the manifest format.
+ * Chris Hofstaedtler, who helped me during the `dh-rootless` phase and fixed the annoying "temp files".
+   in the `deb_packer.py` prototype.
+ * Paul Gevers, who was the first adopter of `dh-debputy` for packages in Debian. Also, Paul went above
+   and beyond for finding bugs in the early versions of `debputy`.
+
+
+<--
+Hi, if you are making a contribution and feel you should be listed here, please 
+uncomment and add yourself below.
+
+Additionally, thanks to the following:
+
+ * <your name/login/identification>, <for/who did ...>
+
+ * -->
+
diff --git a/assets/debputy b/assets/debputy
new file mode 100644
index 0000000..8f4b27a
--- /dev/null
+++ b/assets/debputy
@@ -0,0 +1,8 @@
+#!/usr/bin/python3
+import sys
+
+sys.path.insert(0, "/usr/share/dh-debputy")
+
+from debputy.commands.debputy_cmd.__main__ import main
+
+main()
diff --git a/deb_materialization.py b/deb_materialization.py
new file mode 100755
index 0000000..3572581
--- /dev/null
+++ b/deb_materialization.py
@@ -0,0 +1,11 @@
+#!/usr/bin/python3 -B
+import pathlib
+import sys
+
+DEBPUTY_ROOT_DIR = pathlib.Path(__file__).parent  # TODO: Subst during install
+
+if __name__ == '__main__':
+    # setup PYTHONPATH: add our installation directory.
+    sys.path.insert(0, str(DEBPUTY_ROOT_DIR))
+    from debputy.commands.deb_materialization import main
+    main()
diff --git a/deb_packer.py b/deb_packer.py
new file mode 100755
index 0000000..4b3410f
--- /dev/null
+++ b/deb_packer.py
@@ -0,0 +1,11 @@
+#!/usr/bin/python3 -B
+import pathlib
+import sys
+
+DEBPUTY_ROOT_DIR = pathlib.Path(__file__).parent  # TODO: Subst during install
+
+if __name__ == '__main__':
+    # setup PYTHONPATH: add our installation directory.
+    sys.path.insert(0, str(DEBPUTY_ROOT_DIR))
+    from debputy.commands.deb_packer import main
+    main()
diff --git a/debputy.pod b/debputy.pod
new file mode 100644
index 0000000..593f02d
--- /dev/null
+++ b/debputy.pod
@@ -0,0 +1,633 @@
+=encoding UTF-8
+
+=head1 NAME
+
+debputy - Manifest style Debian-based package builder
+
+=head1 SYNOPSIS
+
+B<debputy> [S<I<< general options >> >] B<command ...> [S< I<< command options >> >]
+
+B<debputy> B<migrate-from-dh> [B<--apply-changes>] [B<--acceptable-migration-issues=>I<issue>[,I<issue>,...]]
+
+B<debputy> B<check-manifest> [B<--debputy-manifest=>I<path/to/debputy.manifest>]
+
+B<debputy> B<annotate-packaging-files>
+
+B<debputy> B<lint>
+
+B<debputy> B<lsp> B<editor-config> B<NAME>
+
+B<debputy> B<lsp> B<server> [B<--tcp|--ws> [B<--host> I<BIND-ADDRESS>] [B<--port> I<PORT>]]
+
+=head1 DESCRIPTION
+
+The B<debputy> program is a manifest style Debian-based package builder. This manpage documents some of the
+user facing commands.
+
+If you are using B<debputy> with a screen reader, consider setting the environment variable
+B<OPTIMIZE_FOR_SCREEN_READER> to 1. This will make many B<debputy> commands remove a lot of
+irrelevant visual rendering. Especially ASCII art style rendering that will just be annoying
+to listen to. Additionally, some output will be described with text to replace the visual
+rendering.
+
+=head2 Commands
+
+=over 4
+
+=item check-manifest
+
+The B<check-manifest> command will cause B<debputy> to parse the manifest and examine it for obvious mistakes.
+
+Note that the command will I<not> catch all mistakes as some problems can only be detected during a build. As
+an example, B<check-manifest> can detect mistyped manifest variables but not typos in path names for
+installation rules.
+
+=item migrate-from-dh
+
+The B<migrate-from-dh> command will attempt to migrate the current package to B<debputy>.
+
+For this command to be successful, it must be run from the root of an unpacked Debian source package and the
+package should be using the B<dh> sequencer.
+
+The migration can rerun with newer version of B<debputy> that might provide more features since the previous
+one even inside the same level of adoption. As an example, B<debputy/0.1.21> added support for automatic
+relationship substvars. Re-running the migrator for an already migrated package can be used to detect any
+unnecessary explicit relationship substvars as unnecessary.
+
+The default migration target is based on existing features in the packaging where present. As an example,
+a build-dependency on B<dh-sequence-zz-debputy-rrr> will make the migration tool only run migrators relevant
+for B<dh-sequence-zz-debputy-rrr>. If the migration cannot identify any target markers, it has a built-in
+default target. The default target will change over time as B<debputy> and the migrator mature. The
+B<--migration-target> option can be used to overrule this automatic detection. This can be useful both to
+expand on the migration level without performing any changes or to choose a more conservative initial
+migration level.
+
+Generally, the migration tool can take you from "less adoption" towards "more adoption" of B<debputy> but
+not the inverse. As an example, migrating from B<dh-sequence-zz-debputy-rrr> towards B<dh-sequence-zz-debputy>
+is supposed, but the reverse is not.
+
+If any migrations involve creating a new or changing an existing F<debian/debputy.manifest>, the migration
+tool will first write a draft to F<debian/debputy.manifest.new>. From there, it may be renamed to
+F<debian/debputy.manifest> automatically depending on B<--apply-changes> or B<--no-apply-changes>.
+
+It supports the following options:
+
+=over 4
+
+=item B<--migration-target> I<TARGET-NAME>
+
+Explicitly define how far the migration should go. This will override the detected or built-in default as
+the desired migration target.
+
+See L</INTEGRATION LEVELS> for details about the concrete levels of integration that can be used.
+
+=item B<--acceptable-migration-issues> I<NAME[,...,NAME]>, B<--acceptable-migration-issues=ALL>
+
+The migration may detect unsupported features in the package. Some, but not all, of these can be reduced to
+a warning by passing B<--acceptable-migration-issues> with the name of the issue as provided in the error
+message. The special value B<ALL> in all upper case will cause all issues that can be reduced to a warning
+to be reduced to a warning.
+
+This is only useful to reduce issues to warnings if you are reasonable sure that you can remove the feature
+or convert it to something that B<debputy> supports.
+
+=item B<--apply-changes>, B<--no-act>, B<--no-apply-changes>
+
+These options decide whether the migration tool should perform destructive actions such as overwriting the
+existing B<debian/debputy.manifest> and deleting packaging files that have successfully migrated.
+
+The default is currently to not perform destructive actions as the migration tool does not detect version
+control systems. If support for detecting version control systems is added, this default may change.
+
+Note that the migration may replace B<debian/debputy.manifest.new> regardless of this option as that is its
+output for the updated draft manifest.
+
+The B<--no-act> is an alias of B<--no-apply-changes> to match the name that B<debhelper> command use.
+
+=back
+
+=item lint
+
+I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
+
+Run the linting tooling for Debian packaging files.  This will run a linter to check the Debian packaging
+files. This command is useful for CI or for when you cannot use the language server feature. It provides
+the same diagnostics as B<debputy lsp server> would but without requiring an LSP capable editor as intermediate.
+The output is only intended for human consumption.  Machine readable is not a goal at this time.
+
+Note that at the time of writing, the B<debputy.manifest> file is only B<partially> supported. If you
+have F<debian/debputy.manifest>, please also run B<debputy check-manifest> to get more thorough checks
+for that file for now. The B<lint> command will inform you about this issue in the output if a
+F<debian/debputy.manifest> file is detected.
+
+Some relevant options for this subcommand include:
+
+=over 4
+
+=item B<--auto-fix>
+
+If B<debputy> is aware of one "obvious" solution to the issue, just apply it. This will apply the
+changes directly to the file. Use of version control for the Debian packaging is recommended when
+using this option in case you want to undo the result.
+
+=item B<--spellcheck>
+
+Include spellchecking in the linting results. These are by default omitted, since they are slower
+and there are often false-positives.
+
+I<Caveat>: Currently, B<--auto-fix> with B<--spellcheck> will auto-correct all spelling mistakes
+with a single correction available.  This can be suboptimal behaviour in some cases and therefore
+combing these options are not always recommended.
+
+=item B<--linter-exit-code>, B<--no-linter-exit-code>
+
+There is a convention among linter tools to return a non-zero exit code for "severe issues".  The
+B<--linter-exit-code> will enforce this behaviour while the B<--no-linter-exit-code> will disable
+it.
+
+The B<debputy> program will use exit code B<2> for "severe issue" as a "linter exit code" when
+linting based exit codes are active.
+
+Not having a linter based exit code can be useful if you want to run the tool programmatically
+to display the results and you only want the exit code to tell whether there was a problem
+providing the results.
+
+If you rely on the exit code, you are recommended to explicitly pass the relevant variant of the
+flag even if the current default matches your wishes.
+
+=back
+
+A short comparison of B<debputy lint> vs. other tools:
+
+=over 4
+
+=item B<debputy lsp server>
+
+The language server feature from B<debputy lsp server> provides an interactive and online version of the linting
+from B<debputy lint> directly in any LSP capable editor (with the proper glue configuration). The LSP
+feature gives you instant gratification, some additional editor-only features and interactive choices of
+available quickfixes.
+
+The "downside" of the B<debputy lsp server> feature is that it requires a LSP capable editor and each editor has
+their own glue configuration. Since the B<debputy> language server is new, almost no editor has built-in
+glue configuration meaning it has a steeper "learning curve" to get started. Additionally, some times
+you want the checks for CI checks or the current state of the package (without having to open each
+file in an editor). Here B<debputy lint> covers the same issues without the need for anything else.
+
+=item B<lintian>
+
+The primary difference between the B<debputy> linter and B<lintian> is that B<lintian> works on "binary"
+artifacts. Even the source checks of B<lintian> checks the packaged version of the source rather than
+the files you are directly working. This means that you have to do a package "build" for lintian to spot
+any changes, which causes slow feedback loops. Additionally, B<debputy lint> can provide feedback regardless
+of whether your package can currently build. Accordingly, you can get help and hints even for problems
+that would prevent a package build. By nature of how B<lintian> works, you can only get hints from lintian
+on matters that does not break the package build.
+
+On the flip side, because B<lintian> is checking the assembled artifacts, it can check for issues that
+are only visible after a package build. Additionally, B<lintian> also checks for issues in the upstream
+sources to some extent. Checking upstream artifacts and the resulting Debian packages are not in scope for
+B<debputy lint> as the B<debputy lint> is intended to be a mirror of the language server diagnostics.
+
+In summary: Use B<debputy lint> (or B<debputy lsp server>) for short feedback loops. Use B<lintian> for
+slower but more thorough checks on resulting packages.
+
+=item B<lintian-brush>
+
+The B<lintian-brush> has a broader scope than B<debputy lint>. If you are a happy B<lintian-brush> user,
+odds are that B<debputy lint> will not do a lot for you. Though, B<debputy lsp server> might still be relevant
+as the language server provides additional editor related features.
+
+=back
+
+=item lsp server
+
+I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
+
+Start the B<debputy> language server (per B<Language Server Protocol> specification).
+
+Many modern editors can delegate language support to a B<Language Server> or indirectly via other
+features like supporting B<youcompleteme> (which in turn can delegate to a language server). The
+B<debputy> tool provides one for many common packaging formats via the B<lsp server> subcommand for file
+formats such as B<debian/control>, B<debian/changelog> and B<debian/copyright>.
+
+You will often need some editor specific glue configuration to link a given file format or name
+to the language server. The B<debputy lsp editor-config> might provide an example glue snippet for
+your editor. In that glue configuration, you will need to provide a command. Often,
+B<debputy lsp server> will suffice (using the stdio transport). See B<debputy lsp server --help>
+for other integration options such as TCP (B<--tcp>) or websocket (B<--ws>) plus related supporting
+options.
+
+If you need to debug an issue with the language server, the TCP integration (B<--tcp>) can be
+quite helpful. In this mode, you run B<debputy lsp server --tcp> in a terminal before starting your
+editor. This means you have direct and unfiltered access to the B<debputy> command and its output.
+Remember to update your editor to use TCP integration rather than stdio integration (and remember
+to swap back when you are done). Check the B<debputy lsp server --help> if you need a different
+bind address for the language server.
+
+If you can choose the language ID for a given file, you are recommended to use the file name
+relative to the source root (such as B<debian/control>). The service does account for some
+known variations such as B<debian-control> (as used by B<eglot> from B<emacs>) and
+B<debcontrol> (as used by B<vim>). See B<debputy lsp features> for a list of known language IDs
+along with their aliases.
+
+When properly set up, the language server will offer a variety of features such as:
+
+=over 4
+
+=item -
+
+Completion suggestion such as field names or values in deb822 based files.
+
+=item -
+
+Hover documentation for fields in deb822-based files.
+
+=item -
+
+Diagnostics ("linting"). In many cases, B<debputy> will also provide quickfixes for the issues.
+
+This feature is also (partly) available via the B<debputy lint> command. The primary limitation
+in B<debputy lint> is that you cannot interactively choose which quickfix to apply.
+
+=item -
+
+On save actions (currently only "prune trailing whitespace").
+
+=back
+
+=item lsp editor-config B<EDITOR>
+
+Provide an example configuration glue for using the B<debputy lsp server> with the given editor
+if known.
+
+The snippets are maintained on a basis effort basis for editors without built-in config glue
+for the B<debputy lsp server>. Please file an issue (or a merge request) at
+L<https://salsa.debian.org/debian/debputy> if a snippet needs to be updated, added or removed.
+
+=item lsp features
+
+List in a human readable format details about what language IDs are handled by the
+B<debputy lsp server> along with what features are provided for each file format/language ID.
+
+=item tool-support
+
+These commands are intended for other tools to consume the output. Output is generally JSON by default or
+supported via B<--output-format=json>.
+
+=over 4
+
+=item export-reference-data [DATASET]
+
+The B<export-reference-data> command export reference data. If provided, only the named dataset will be exported.
+Otherwise, all datasets will be exported.
+
+The reference data includes descriptions of the keywords used in the data set, which is helpful to understand the
+data.
+
+=item supports-tool-command <COMMAND>
+
+Tests whether B<debputy> knows about the named command. Returns successfully if known and unsuccessfully if not
+known.
+
+=item annotate-debian-directory
+
+The B<annotate-debian-directory> command will make B<debputy> scan the F<debian/> directory for known
+packaging files and annotate them with information.
+
+Identifying known packaging files is done on a best effort basis and B<debputy> has the following
+sources of information:
+
+=over 4
+
+=item Data from plugins
+
+Any installed B<debputy> plugin can provide data about known packaging files. Most of B<debputy>'s "built-in"
+rules are stored in the B<debputy-documentation> or the B<debhelper-documentation> plugin. These are installed
+in F</usr/share/debputy/debputy/plugins/> by default. If any of the data in there is wrong,
+please file a bug or a bug against the package providing the data (often B<debputy> or B<debhelper>).
+
+If the plugin provides the relevant data, B<debputy> will expose B<install-pattern> and B<install-path>, which
+are best-effort guesses for the file is installed (or where files listed in it will be installed). Please check
+the B<config-features> and B<file-categories> for the file to see when these field are applicable (and which
+case it is).
+
+Note that some files can be matched multiple times. As an example F<debian/changelog> and F<debian/copyright>
+will generally appear once per package, because they are installed in each package.
+
+=item Dynamic data from L<debhelper(7)> (via L<dh_assistant(1)>>)
+
+Additionally, B<debputy> will ask B<dh_assistant> to resolve all relevant helper commands and their relevant
+config snippets. This data will be cross referenced with the plugin provided data where possible. This will
+detect files that B<debputy> (and its plugins) does not know about, but it cannot provide any additional
+information.
+
+This part requires B<debhelper (>= 13.12~)> to work fully. With older versions, the output will include am
+B<issues> denoting that B<dh_assistant> returned non-zero.
+
+When B<dh_assistant list-guessed-dh-config-files> is missing a file, it is typically because the command
+that uses that config file is not introspectable. Typically, that can be fixed by patching the command
+to include a command line a la:
+
+    # INTROSPECTABLE: CONFIG-FILES pkgfile(foo)
+
+Assuming the command uses B<pkgfile($package, "foo")> from L<Debian::Debhelper::Dh_Lib> to look up the
+config file.
+
+Notable case that will never work is F<debian/foo.service> where there is no B<foo> package in
+F<debian/control> but F<debian/rules> calls B<dh_installsystemd --name foo>. This holds equally for
+all debhelper config files and related commands.
+
+=back
+
+=back
+
+=item plugin list [I<TOPIC>]
+
+=item plugin show B<TOPIC> B<identifier>
+
+These commands provides access to features that are provided by plugins (Note: many B<debputy> features are
+plugin provided, so these commands also covers a lot of "built-in" features).
+
+These commands will access features of all plugins B<available> even if the current package will not activate
+all of these plugins. Unless otherwise stated, all output is intended to be human readable rather than machine
+readable. Formatting may change between any version.
+
+Many of the B<list> subcommands also provide a csv format. Note this output is B<not> intended for scripting
+as the output is subject to change - both in form of format availability and content. The csv output is
+intended as an aid to users of screen readers for which csv files are easier to deal with than visually
+rendered tables. If you need a stable format of some particular output, please file a feature request
+at L<https://salsa.debian.org/debian/debputy/-/issues> or via B<reportbug debputy>.
+
+You can use B<debputy plugin list --help> and B<debputy plugin show --help> to see which topics are applicable
+for each subcommand.
+
+Noteworthy topics include:
+
+=over 4
+
+=item plugins
+
+This topic provides a listing of all plugins that B<debputy> is aware of.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+=item plugable-manifest-rules (aliases: pmr, p-m-r)
+
+The B<debputy> manifest provides a number of places where the packager can provide a number of different rules
+such as B<install> vs. B<install-doc> vs. B<install-examples> under B<installations:>. These are called
+plugable manifest rules and this topic provides insights to which rules are available where.
+
+When used with B<list>, B<debputy> will list all plugable manifest rules available. When used with B<show>,
+a rule name must be provided and B<debputy> will then provide details about the rule. These details include
+attributes available (where applicable) and any reference documentation provided by the plugin.
+
+As an example, here is how you get the details about the install rule:
+
+    debputy plugin show plugable-manifest-rules install
+
+When a rule name is ambiguous, B<debputy> will ask that you use B<rule-type::rule-name> instead of just B<rule-name>.
+As an example:
+
+    debputy plugin show plugable-manifest-rules TransformationRule::remove
+    debputy plugin show plugable-manifest-rules DpkgMaintscriptHelperCommand::remove
+
+Note the type names (such as B<TransformationRule>) are currently an implementation detail and may change in the
+future.
+
+=item packager-provided-files (aliases: ppf, p-p-f)
+
+This topic provides details about all "packager provided files". Packager provided files can be put into F<debian>
+from where B<debputy> will pick them up and install them somewhere in the package. While this command shows all
+possible variants (by their stems), the B<used-packager-provided-files> topic will B<list> real files matched.
+
+When used with B<list>, B<debputy> will list all the packager provided files that B<debputy> knows about. When
+used with B<show>, some additional details will be given.
+
+In a few cases, the packager provided file will be processed first (as an example F<debian/symbols> will be passed
+to B<dpkg-gensymbols> and the processed version will then be installed instead).
+
+=item used-packager-provided-files (aliases: uppf, u-p-p-f)
+
+This topic provides a list of all packager provided files used in this source package. This topic differs from
+B<packager-provided-files> in that it only shows files in actual use whereas the other topic lists all known
+stems.
+
+The listing will potentially include files that B<debputy> could have picked up, but will not do so during a
+package build because the relevant plugin is not explicitly requested (typically via a Build-Depends). These
+cases are placed in a separate table and will be clearly marked.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+This topic only works when the command is run from the root of an unpacked Debian source package (as
+B<debputy> needs to read F<debian/control> and scan the F<debian/> directory).
+
+=item metadata-detectors
+
+This topic provides a listing of all "metadata detectors". These are plugin provided code snippets that scan the
+final form of the package and add substvars (for B<dpkg-gencontrol>), generate maintscript snippets, or/and
+declare triggers.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+=item manifest-variables
+
+This topic covers B<plugin provided> manifest variables. The listing will list the common manifest variables by
+default along with their values in source context (if possible). Some of the special case manifest variables are
+hidden by default (use B<debputy plugin list manifest-variables --help> to see the filter options).
+
+When used with B<show VARIABLE>, B<debputy> will list the reference documentation (if provided by the plugin)
+related to the value along with a few other details.
+
+As implied above, this will only show B<plugin provided> variables. Any manifest variables provided directly
+in the manifest is B<not> covered by these commands.
+
+=item automatic-discard-rules
+
+This topic covers automatic discard rules, which are rules that automatically filters out (discards) sources
+from installation rules by default.  The listing will list all the available automatic discard rules. The
+B<show RULE> command will show reference documentation and an example of what the rule reacts to (if these
+have been provided by the plugin).
+
+As an example:
+
+    debputy plugin show automatic-discard-rules la-files
+
+=item type-mappings
+
+This topic cover type mappings that explains how some non-trivial types are interpreted. These covers
+types like B<FileSystemMatchRule> and B<FileSystemMode>, which are used by other features such as
+plugable manifest rules.
+
+When used with B<show NAME>, any plugin provided documentation and example inputs will be displayed
+for that rule.
+
+=back
+
+=item autopkgtest-test-runner
+
+The B<autopkgtest-test-runner> command is intended to be used by B<autodep8> or from autopkgtests to run the
+tests of plugins in installed mode.
+
+=item internal-command
+
+This is for internal-only usage only.  Any subcommand under B<internal-command> may disappear or change options
+between any release without any warning.
+
+=back
+
+=head1 GENERAL OPTIONS
+
+The following options general options or root level options are available.
+
+=over 4
+
+=item B<-h>, B<--help>
+
+Print usage information and exits.
+
+The information printed depends on which subcommands appear prior to this option.
+
+=item B<--version>
+
+Prints version information and exists.
+
+Cannot be used with subcommands.
+
+=item B<-d>, B<--debug>
+
+Enable debug logging and raw stack traces on errors.
+
+Some warnings become errors as a consequence.
+
+=item B<--no-pager>
+
+Some subcommands will in their default output format pipe it to a pager to give you a more pleasant
+experience if standard out is a terminal. Examples include many of the B<plugin list> commands. This
+option will disable the pager feature.
+
+Most option formats via B<--output-format> will imply B<--no-pager> as well for subcommands that
+support that option.
+
+Note: Assuming the environment has no pager configuration at all, B<debputy> will use L<less(1)>
+with the B<LESS> environment variable set to B<-FRMQSX>. Notable, the B<-F> option will cause B<less> to
+immediately terminate if the output fits on the screen.
+
+=item B<--plugin> I<REQUIRED_PLUGIN>
+
+This option causes I<REQUIRED_PLUGIN> to be loaded as a part of the commands execution if the command needs
+to load plugin data. For commands that load all plugins by default, this option causes the command to fail
+if I<REQUIRED_PLUGIN> cannot be loaded. For commands that are restrictive about which plugins are loaded,
+subcommand will load I<REQUIRED_PLUGIN> in addition other plugins that would normally be loaded.
+
+The I<REQUIRED_PLUGIN> can either be a plugin name or a filename. The B<debputy> program considers parameter
+with a forward slash as a filename. Otherwise, the parameter is interpreted as a plugin name. When given a
+plugin name, B<debputy> will search for the plugin in its plugin search path and load it from there. When
+given a file name, B<debputy> will read that file as a plugin and use the basename minus any B<.json> or
+B<.json.in> extension as the plugin name.
+
+For packages that need a plugin that they provide themselves during their build process, this option can
+be useful to tell B<debputy> about it. For the build itself, usually you want to use
+B<dh_debputy --plugin path/to/plugin.json>. But this option can still be useful for B<debputy check-manifest>
+etc.
+
+The other use-case is to load a plugin not installed into the plugin search directories. Notably, you can
+use this to shadow an existing plugin, which can be useful for debugging and developing your plugin changes.
+
+This option cannot be used with bundled plugins. As an example, both B<--plugin debputy> and
+B<--plugin path/to/a/debputy.json> will result in an error.
+
+=item B<--debputy-manifest> F<FILE>
+
+If the command needs to parse a manifest, have it read F<FILE> instead of B<debian/debputy.manifest>.
+
+Note this is mostly for testing as other features might not work correctly if the manifest is not aligned
+with the current working directory.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<debian/debputy.manifest>
+
+Please see F</usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz> for details on the format.
+
+If you are converting your first package, you may want to read
+F</usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz> first.
+
+Unlike most debhelper like tools, this file is per source package rather than
+per binary package.  Therefore, you I<cannot> use F<< debian/I<package>.debputy.manifest >>
+to provide a specialized manifest for I<package>. Instead, all the needed parts
+should be written into the manifest itself.
+
+The B<--debputy-manifest> option can be used to have B<debputy> process manifest other
+than F<debian/debputy.manifest>, which may be useful for testing or running
+B<debputy check-manifest> but not much else.
+
+=back
+
+=head1 INTEGRATION LEVELS
+
+The B<debputy> has multiple levels of integrations, which defines how much of the packaging
+that B<debputy> is handling relative to the default B<dh> sequence. The following integrations
+levels are available:
+
+=over 4
+
+=item dh-sequence-zz-debputy-rrr
+
+This integration level replaces the minimal number of commands necessary to provide B<Rules-Requires-Root: no>
+support for B<any> package (even those needing static ownership). The sequence is often compatible with
+other B<debhelper> sequences. To use this B<debputy> integration level, any custom file ownership and
+mode I<should> be migrated to the B<debian/debputy.manifest>. Custom binary package version (B<-v> to
+B<dpkg-gencontrol>) is supported via the manifest. In this integration level, the B<installations>
+keyword and all B<install rules> cannot be used. Installing files into the package is still done via
+helpers such as B<dh_install>.
+
+This migration level corresponds to a B<Build-Depends> on B<dh-sequence-zz-debputy-rrr>.
+
+The following debhelper commands are removed:
+
+=over 4
+
+=item -
+
+dh_fixperms
+
+=item -
+
+dh_gencontrol
+
+=item -
+
+dh_md5sums
+
+=item -
+
+dh_builddeb
+
+=back
+
+=item dh-sequence-zz-debputy
+
+With this integration level, B<debputy> will take over all installation of files into the packages.
+This will replace basically all commands after the B<dh_auto_install> command in the standard B<dh> sequence.
+This also makes the integration level incompatible with many debhelper add-ons, since they expect to run after
+B<dh_auto_install> and assume contents will be materialized into F<< debian/I<package> >>.
+
+This migration level corresponds to a B<Build-Depends> on B<dh-sequence-debputy> or B<dh-sequence-zz-debputy>.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_debputy(1)>
+
+=head1 AUTHOR
+
+Niels Thykier <niels@thykier.net>
+
+=cut
diff --git a/debputy.sh b/debputy.sh
new file mode 100755
index 0000000..0efc286
--- /dev/null
+++ b/debputy.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+
+DEBPUTY_PATH="$(dirname "$(readlink -f "$0")")/src"
+if [ -z "${PYTHONPATH}" ]; then
+  PYTHONPATH="${DEBPUTY_PATH}"
+else
+  PYTHONPATH="${DEBPUTY_PATH}:${PYTHONPATH}"
+fi
+
+export PYTHONPATH
+python3 -m debputy.commands.debputy_cmd "$@"
diff --git a/debputy/disabled-plugins/lua.json b/debputy/disabled-plugins/lua.json
new file mode 100644
index 0000000..00f63be
--- /dev/null
+++ b/debputy/disabled-plugins/lua.json
@@ -0,0 +1,4 @@
+{
+  "api-compat-version": 1,
+  "plugin-initializer": "initialize"
+}
diff --git a/debputy/disabled-plugins/lua.py b/debputy/disabled-plugins/lua.py
new file mode 100644
index 0000000..7d49c6e
--- /dev/null
+++ b/debputy/disabled-plugins/lua.py
@@ -0,0 +1,77 @@
+import itertools
+from typing import Any, Optional, Tuple, IO, Iterable
+
+from debputy.plugin.api import DebputyPluginInitializer, VirtualPath
+
+_BUF_SIZE = 8096
+
+
+def initialize(api: DebputyPluginInitializer) -> None:
+    register_processing_steps_via_non_public_api(api)
+
+
+def register_processing_steps_via_non_public_api(api: Any) -> None:
+    api.package_processor(
+        "deduplicate-lua-files",
+        deduplicate_lua_files,
+    )
+
+
+def find_lowest_lua5_version_dir(fs_root: VirtualPath) -> Optional[Tuple[int, VirtualPath]]:
+    for lua5_minor_version in range(1, 9):
+        lua_dir = fs_root.lookup(f"/usr/share/lua/5.{lua5_minor_version}/")
+        if not lua_dir:
+            continue
+        return lua5_minor_version, lua_dir
+    return None
+
+
+def _compute_rel_path(reference_point: VirtualPath, target_file: VirtualPath) -> str:
+    assert target_file.path.startswith(reference_point.path + "/")
+    return target_file.path[len(reference_point.path) + 1:]
+
+
+def _chunk(fd: IO[bytes]) -> Iterable[bytes]:
+    c = fd.read(_BUF_SIZE)
+    while c:
+        yield c
+        c = fd.read(_BUF_SIZE)
+
+
+def _same_content(a: VirtualPath, b: VirtualPath) -> bool:
+    if a.size != b.size:
+        return False
+    # It might be tempting to use `cmp {a.fs_path} {b.fs_path}`, but this method makes it easier to test
+    # as the test will not have to create physical files.
+    #
+    # We could also replace this with a checksum check, then we could store them in a table and deduplicate
+    # between multiple versions (not just against the lowest version). Decided against it because this is
+    # are more faithful translation of the original code.
+    with a.open(byte_io=True, buffering=_BUF_SIZE) as afd, b.open(byte_io=True, buffering=_BUF_SIZE) as bfd:
+        for a_chunk, b_chunk in itertools.zip_longest(afd, bfd, fillvalue=None):
+            if a_chunk is None or b_chunk is None or a_chunk != b_chunk:
+                return False
+    return True
+
+
+def deduplicate_lua_files(fs_root: VirtualPath, _unused1: Any, _unused2: Any) -> None:
+    res_tuple = find_lowest_lua5_version_dir(fs_root)
+    if res_tuple is None:
+        return
+    lua5_minor_version, lua5_reference_dir = res_tuple
+    all_lua5_ref_files = [
+        lua_file
+        for lua_file in lua5_reference_dir.all_paths()
+        if lua_file.is_file and lua_file.name.endswith(".lua")
+    ]
+    for lua_file in all_lua5_ref_files:
+        rel_path = _compute_rel_path(lua5_reference_dir, lua_file)
+        for newer_lua_minor_version in range(lua5_minor_version + 1, 9):
+            alt_lua_file = fs_root.lookup(f"/usr/share/lua/5.{newer_lua_minor_version}/{rel_path}")
+            if alt_lua_file is None or not alt_lua_file.is_file or not _same_content(lua_file, alt_lua_file):
+                continue
+            parent_dir = alt_lua_file.parent_dir
+            assert parent_dir is not None
+            alt_lua_file.unlink()
+            # We do not have to normalize the link; debputy will handle that later.
+            parent_dir.add_symlink(alt_lua_file.name, lua_file.absolute)
diff --git a/debputy/disabled-plugins/lua_test.py b/debputy/disabled-plugins/lua_test.py
new file mode 100644
index 0000000..96f9c83
--- /dev/null
+++ b/debputy/disabled-plugins/lua_test.py
@@ -0,0 +1,74 @@
+from typing import Optional
+
+from debputy.plugin.api import virtual_path_def, VirtualPath
+from debputy.plugin.api.test_api import (
+    initialize_plugin_under_test,
+    build_virtual_file_system,
+)
+
+
+def test_lua_plugin_deduplicate_lua_files_no_lua() -> None:
+    plugin = initialize_plugin_under_test()
+    no_lua_files_fs = build_virtual_file_system(
+        [
+            "usr/bin/foo",
+            "usr/share/lua5.2/foo/",  # Said no lua files, not no lua paths :)
+        ]
+    )
+    path_count = sum((1 for _ in no_lua_files_fs.all_paths()), start=0)
+    plugin.run_package_processor("deduplicate-lua-files", no_lua_files_fs)
+    # The plugin does nothing if there are no lua files
+    assert path_count == sum((1 for _ in no_lua_files_fs.all_paths()), start=0)
+    assert not any(f.is_symlink for f in no_lua_files_fs.all_paths())
+
+
+def _resolve_lua_symlink(v: VirtualPath) -> Optional[VirtualPath]:
+    # TODO: This should probably be in the VirtualPath API (after some corner case tests/improvements)
+    assert v.is_symlink
+    target = v.readlink()
+    parent = v.parent_dir
+    assert parent is not None
+    return parent.lookup(target)
+
+
+def test_lua_plugin_deduplicate_lua_files_lua_differ() -> None:
+    plugin = initialize_plugin_under_test()
+    # Long to test more than one iteration
+    base_content = "a" * 10000
+    fs = build_virtual_file_system(
+        [
+            virtual_path_def("usr/share/lua/5.2/foo.lua", content=base_content),
+            virtual_path_def("usr/share/lua/5.3/foo.lua", content=base_content),
+            virtual_path_def("usr/share/lua/5.4/foo.lua", content=base_content),
+            virtual_path_def("usr/share/lua/5.2/bar.lua", content=base_content + "unique for 5.2"),
+            virtual_path_def("usr/share/lua/5.3/bar.lua", content=base_content + "unique for 5.3"),
+            # Deliberately shorter to test different parse lengths
+            virtual_path_def("usr/share/lua/5.4/bar.lua", content="unique for 5.4"),
+            virtual_path_def("usr/share/lua/5.2/foo5.2.lua", content="unrelated"),
+            virtual_path_def("usr/share/lua/5.3/foo5.3.lua", content="unrelated"),
+            virtual_path_def("usr/share/lua/5.4/foo5.4.lua", content="unrelated"),
+        ]
+    )
+    plugin.run_package_processor("deduplicate-lua-files", fs)
+
+    foo52_lua = fs.lookup("/usr/share/lua/5.2/foo.lua")
+    # This should be there and unchanged
+    assert foo52_lua is not None and foo52_lua.is_file
+    # These should be symlinks to foo52_lua
+    for foo5x_lua_path in ["/usr/share/lua/5.3/foo.lua", "/usr/share/lua/5.4/foo.lua"]:
+        foo5x_lua = fs.lookup(foo5x_lua_path)
+        assert foo5x_lua_path is not None and foo5x_lua.is_symlink
+        target_path = _resolve_lua_symlink(foo5x_lua)
+        assert target_path.path == foo52_lua.path
+
+    # These should be unchanged
+    for path_stem in [
+        "5.2/bar.lua",
+        "5.3/bar.lua",
+        "5.4/bar.lua",
+        "5.2/foo5.2.lua",
+        "5.3/foo5.3.lua",
+        "5.4/foo5.4.lua",
+    ]:
+        unique_file = fs.lookup(f"/usr/share/lua/{path_stem}")
+        assert unique_file is not None and unique_file.is_file
diff --git a/debputy/plugins/debputy-documentation.json b/debputy/plugins/debputy-documentation.json
new file mode 100644
index 0000000..4017e2c
--- /dev/null
+++ b/debputy/plugins/debputy-documentation.json
@@ -0,0 +1,113 @@
+{
+  "api-compat-version": 1,
+  "known-packaging-files": [
+    {
+      "path": "debian/control",
+      "documentation-uris": [
+        "man:deb-src-control(5)",
+        "https://www.debian.org/doc/debian-policy/ch-controlfields.html#source-package-control-files-debian-control"
+      ],
+      "file-categories": ["pkg-metadata"]
+    },
+    {
+      "path": "debian/debputy.manifest",
+      "debputy-cmd-templates": [
+        [
+          "debputy",
+          "plugin",
+          "list",
+          "p-m-r"
+        ],
+        [
+          "debputy",
+          "plugin",
+          "show",
+          "p-m-r",
+          "{{TOPIC}}"
+        ]
+      ],
+      "documentation-uris": [
+        "@DEBPUTY_DOC_ROOT_DIR@/MANIFEST-FORMAT.md"
+      ],
+      "file-categories": ["pkg-helper-config"]
+    },
+    {
+      "path": "debian/rules",
+      "documentation-uris": [
+        "man:deb-src-rules(5)",
+        "https://www.debian.org/doc/debian-policy/ch-source.html#main-building-script-debian-rules"
+      ]
+    },
+    {
+      "path": "debian/gbp.conf",
+      "documentation-uris": [
+        "man:gbp.conf(5)"
+      ],
+      "file-categories": ["maint-config"]
+    },
+    {
+      "path": "debian/source/options",
+      "documentation-uris": [
+        "man:dpkg-source(1)"
+      ]
+    },
+    {
+      "path": "debian/source/local-options",
+      "documentation-uris": [
+        "man:dpkg-source(1)"
+      ]
+    },
+    {
+      "path": "debian/source/format",
+      "documentation-uris": [
+        "man:dpkg-source(1)"
+      ],
+      "file-categories": ["pkg-metadata"]
+    },
+    {
+      "path": "debian/salsa-ci.yml",
+      "file-categories": ["testing"]
+    },
+    {
+      "path": "debian/source/lintian-overrides",
+      "documentation-uris": [
+        "man:lintian(1)"
+      ],
+      "file-categories": ["lint-config"]
+    },
+    {
+      "path": "debian/source.lintian-overrides",
+      "documentation-uris": [
+        "man:lintian(1)"
+      ],
+      "file-categories": ["lint-config"]
+    },
+    {
+      "path": "debian/tests/control",
+      "documentation-uris": [
+        "https://salsa.debian.org/ci-team/autopkgtest/raw/master/doc/README.package-tests.rst",
+        "https://ci.debian.net/doc/file.TUTORIAL.html"
+      ],
+      "file-categories": ["testing"]
+    },
+    {
+      "path": "debian/watch",
+      "documentation-uris": [
+        "https://www.debian.org/doc/debian-policy/ch-source.html#upstream-source-location-debian-watch"
+      ]
+    },
+    {
+      "path": "debian/README.source",
+      "documentation-uris": [
+        "https://www.debian.org/doc/debian-policy/ch-source.html#source-package-handling-debian-readme-source"
+      ]
+    },
+    {
+      "path": "debian/shlibs.local",
+      "documentation-uris": [
+        "man:deb-shlibs(5)",
+        "man:dpkg-shlibdeps(1)"
+      ]
+    }
+  ]
+}
diff --git a/debputy/plugins/gnome.json b/debputy/plugins/gnome.json
new file mode 100644
index 0000000..00f63be
--- /dev/null
+++ b/debputy/plugins/gnome.json
@@ -0,0 +1,4 @@
+{
+  "api-compat-version": 1,
+  "plugin-initializer": "initialize"
+}
diff --git a/debputy/plugins/gnome.py b/debputy/plugins/gnome.py
new file mode 100644
index 0000000..6ea56eb
--- /dev/null
+++ b/debputy/plugins/gnome.py
@@ -0,0 +1,71 @@
+import re
+from typing import Any
+
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.util import _error
+
+GNOME_VERSION1_RE = re.compile(r"^(\d+:)?(\d+)\.(\d+)\.[\d.]+.*$")
+GNOME_VERSION2_RE = re.compile(
+    r"^(\d+:)?(\d+)(?:\.[\d.]+|~(alpha|beta|rc)[\d.]*|[+~])?.*$"
+)
+
+
+def initialize(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector(
+        "gnome-versions",
+        gnome_versions,
+        # Probably not necessary, but this is the most faithful conversion
+        package_type=["deb", "udeb"],
+    )
+    # Looking for "clean_la_files"? The `debputy` plugin provides a replacement
+    # feature.
+
+
+def gnome_versions(
+    _unused: Any,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    # Conversion note: In debhelper, $dh{VERSION} is actually the "source" version
+    # (though sometimes it has a binNMU version too).  In `debputy`, we have access
+    # to the "true" binary version (dpkg-gencontrol -v<VERSION>). In 99% of all cases,
+    # the difference is irrelevant as people rarely use dpkg-gencontrol -v<VERSION>.
+    version = context.binary_package_version
+    m = GNOME_VERSION1_RE.match(version)
+    epoch = ""
+    gnome_version = ""
+    gnome_next_version = ""
+    if m:
+        major_version = int(m.group(2))
+        if major_version < 40:
+            epoch = m.group(1)
+            minor_version = int(m.group(3))
+            gnome_version = f"{major_version}.{minor_version}"
+            if major_version == 3 and minor_version == 38:
+                prefix = ""
+            else:
+                prefix = f"{major_version}."
+            gnome_next_version = f"{prefix}{minor_version + 2}"
+    if gnome_version == "":
+        m = GNOME_VERSION2_RE.match(version)
+        if not m:
+            _error(
+                f"Unable to determine the GNOME major version from {version} for package"
+                f" {context.binary_package.name}. If this is not a GNOME package or it does"
+                f" not follow the GNOME version standard, please disable the GNOME plugin"
+                f" (debputy-plugin-gnome)."
+            )
+        epoch = m.group(1)
+        version = int(m.group(2))
+        gnome_version = f"{version}~"
+        gnome_next_version = f"{version + 1}~"
+    if epoch is None:
+        epoch = ""
+    ctrl.substvars["gnome:Version"] = f"{epoch}{gnome_version}"
+    ctrl.substvars["gnome:UpstreamVersion"] = f"{gnome_version}"
+    ctrl.substvars["gnome:NextVersion"] = f"{epoch}{gnome_next_version}"
+    ctrl.substvars["gnome:NextUpstreamVersion"] = f"{gnome_next_version}"
diff --git a/debputy/plugins/numpy3.json b/debputy/plugins/numpy3.json
new file mode 100644
index 0000000..00f63be
--- /dev/null
+++ b/debputy/plugins/numpy3.json
@@ -0,0 +1,4 @@
+{
+  "api-compat-version": 1,
+  "plugin-initializer": "initialize"
+}
diff --git a/debputy/plugins/numpy3.py b/debputy/plugins/numpy3.py
new file mode 100644
index 0000000..5cb9a85
--- /dev/null
+++ b/debputy/plugins/numpy3.py
@@ -0,0 +1,62 @@
+import functools
+import os
+from typing import Any, Tuple
+
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.util import _error
+
+
+def initialize(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector(
+        "numpy-depends",
+        numpy3_versions,
+        # Probably not necessary, but this is the most faithful conversion
+        package_type=["deb", "udeb"],
+    )
+
+
+@functools.lru_cache
+def _parse_numpy3_versions(versions_file: str) -> Tuple[str, str]:
+    attributes = {}
+    try:
+        with open(versions_file, "rt", encoding="utf-8") as fd:
+            for line in fd:
+                if line.startswith("#") or line.isspace():
+                    continue
+                k, v = line.split()
+                attributes[k] = v
+    except FileNotFoundError:
+        _error(
+            f"Missing Build-Dependency on python3-numpy to ensure {versions_file}"
+            " is present."
+        )
+
+    try:
+        api_min_version = attributes["api-min-version"]
+        abi_version = attributes["abi"]
+    except KeyError as e:
+        k = e.args[0]
+        _error(f'Expected {versions_file} to contain the key "{k}"')
+        assert False
+
+    return api_min_version, abi_version
+
+
+def numpy3_versions(
+    _unused: Any,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    if context.binary_package.is_arch_all:
+        dep = "python3-numpy"
+    else:
+        # Note we do not support --strict; codesearch.d.n suggests it is not used
+        # anywhere and this saves us figuring out how to support it here.
+        versions_file = os.environ.get("_NUMPY_TEST_PATH", "/usr/share/numpy3/versions")
+        api_min_version, abi_version = _parse_numpy3_versions(versions_file)
+        dep = f"python3-numpy (>= {api_min_version}), python3-numpy-abi{abi_version}"
+    ctrl.substvars.add_dependency("python3:Depends", dep)
diff --git a/debputy/plugins/perl-openssl.json b/debputy/plugins/perl-openssl.json
new file mode 100644
index 0000000..00f63be
--- /dev/null
+++ b/debputy/plugins/perl-openssl.json
@@ -0,0 +1,4 @@
+{
+  "api-compat-version": 1,
+  "plugin-initializer": "initialize"
+}
diff --git a/debputy/plugins/perl_openssl.py b/debputy/plugins/perl_openssl.py
new file mode 100644
index 0000000..f11cec0
--- /dev/null
+++ b/debputy/plugins/perl_openssl.py
@@ -0,0 +1,43 @@
+import functools
+import os
+import subprocess
+from typing import Any
+
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.util import _error
+
+
+def initialize(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector(
+        "perl-openssl-abi",
+        detect_perl_openssl_abi,
+    )
+
+
+@functools.lru_cache
+def _resolve_libssl_abi(cmd: str) -> str:
+    try:
+        return subprocess.check_output([cmd]).strip().decode("utf-8")
+    except FileNotFoundError:
+        _error(
+            f"The perl-openssl plugin requires that perl-openssl-defaults + libssl-dev is installed"
+        )
+    except subprocess.CalledProcessError as e:
+        _error(f"")
+
+
+def detect_perl_openssl_abi(
+    _unused: Any,
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    cmd = os.environ.get(
+        "_PERL_SSL_DEFAULTS_TEST_PATH",
+        "/usr/share/perl-openssl-defaults/get-libssl-abi",
+    )
+    abi = _resolve_libssl_abi(cmd)
+    ctrl.substvars.add_dependency("perl:Depends", f"perl-openssl-abi-{abi}")
diff --git a/dh_debputy b/dh_debputy
new file mode 100755
index 0000000..4b9edee
--- /dev/null
+++ b/dh_debputy
@@ -0,0 +1,175 @@
+#!/usr/bin/perl
+
+=encoding UTF-8
+
+=head1 NAME
+
+dh_debputy - build Debian binary packages using debputy
+
+=cut
+
+use strict;
+use warnings;
+use Debian::Debhelper::Dh_Lib;
+
+our $VERSION = DH_BUILTIN_VERSION;
+
+=head1 SYNOPSIS
+
+B<dh_debputy> [S<I<debhelper options>>] [B<--destdir=>I<directory>] [S<B<--> I<params>>]
+
+=head1 DESCRIPTION
+
+B<dh_debputy> is a tool for integrating B<debputy> with debhelper as an interim solution
+until B<debputy> covers enough features to be a standalone packaging tool.
+
+The B<debputy> toolstack can built I<any> deb without requiring root or fakeroot.  It is
+always possible to use B<Rules-Requires-Root: no> with B<dh_debputy>/B<debputy> (given no
+non-debputy parts of F<debian/rules> or the upstream build system require root).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--destdir=>I<directory>
+
+Use this if you want the generated F<.deb> files to be put in a directory
+other than the default of "F<..>".
+
+=item B<--plugin=>I<name>
+
+Have `debputy` load the given I<name>.  The I<name> can be a name, in which case
+the plugin must be installed into the proper plugin path (and in that case, you can
+I<often> just have a build dependency on B<< debputy-plugin-I<name> >> ).
+
+Alternatively, the I<name> can be a path (must contain B</> and should end with
+B<.json> or B<.json.in>).  In this case, that file is loaded as a plugin.  This
+case is useful for plugin providers to use their own plugin.
+
+=item B<--> I<params>
+
+Pass I<params> to L<dpkg-deb(1)> when it is used to build the
+package.
+
+Restrict I<params> to compression options as the B<dpkg-deb> options may be
+emulated and not all of the B<dpkg-deb> parameters are supported.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<debian/debputy.manifest>
+
+Please see F</usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz>.
+
+If you are converting your first package, you may want to read
+F</usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz> first.
+
+Unlike most debhelper like tools, this file is per source package rather than
+per binary package.  Therefore, you I<cannot> use F<< debian/I<package>.debputy.manifest >>
+to provide a specialized manifest for I<package>.  Instead, all the needed parts
+should be written into the manifest itself.
+
+=back
+
+=cut
+
+my (@plugins, $integration_mode);
+
+init(options => {
+	"destdir=s"          => \$dh{DESTDIR},
+	"plugin=s"           => \@plugins,
+	"integration-mode=s" => \$integration_mode,
+});
+
+# Set the default destination directory.
+if (! defined $dh{DESTDIR}) {
+	$dh{DESTDIR}='..';
+}
+
+my $debputy_cmd = $ENV{'DEBPUTY_CMD'} // 'debputy';
+
+my @debputy_cmdline = ($debputy_cmd);
+for my $plugin (@plugins) {
+	push(@debputy_cmdline, '--plugin', $plugin);
+}
+push(@debputy_cmdline,
+	'internal-command',
+	'dh-integration-generate-debs',
+);
+push(@debputy_cmdline, "--integration-mode=${integration_mode}")
+	if defined($integration_mode);
+for my $package (@{$dh{DOPACKAGES}}) {
+	push(@debputy_cmdline, '-p', $package);
+}
+push(@debputy_cmdline, $dh{DESTDIR});
+if (@{$dh{U_PARAMS}}) {
+	push(@debputy_cmdline, '--', @{$dh{U_PARAMS}});
+}
+doit(@debputy_cmdline);
+
+=head1 ON DEB ASSEMBLY
+
+The B<dh_debputy> will often use B<dpkg-deb> for assembling the output. However, there are a few cases
+where B<dpkg-deb> does not have the required features for 100% rootless assembly and B<debputy> will
+use a different assembly method when needed.  Generally, this special-case only triggers with
+B<Rules-Requires-Root: no> I<and> when using a feature that requires root with B<dpkg-deb> (such as
+static file ownership).
+
+If you experience, that a B<dh_debputy> produced binary via its internal assembly method that
+is B<not> 100% bit-for-bit reproducible with the equivalent B<root> + B<dpkg-deb> built deb
+and that is not caused by an inaccurate manifest in your end, please file a bug.  See the
+subsection L</How to ensure the dpkg-deb assembly method is being used> for how you
+control which assembly method is being used.
+
+By producing exactly the same deb as B<dpkg-deb> would have with B<fakeroot>, we reduce the risk of bugs
+or bad behaviour during installation.
+
+Note that 100% bit-for-bit reproducible is not compared to debhelper.  Packages generated by debputy may
+differ from those built by debhelper. As an example, auto-generated shell snippets for maintainer scripts
+identifies the tool that generated them and it would be wrong for debputy to identify itself as debhelper
+in this case. This in turn creates a minor difference between packages generated by the two tools.
+Consider using B<diffoscope> to compare your B<debhelper> generated deb to your B<debputy> generated debs.
+
+=head2 How to ensure the dpkg-deb assembly method is being used
+
+The B<debputy> tool stack has two assembly methods: B<dpkg-deb> and the internal B<debputy> method.
+
+By default, the B<dpkg-deb> is used. The B<debputy> tool will only switch to its internal method when:
+
+=over 4
+
+=item -
+
+The package uses a feature that requires (fake)root when assembly via B<dpkg-deb>. At the time of
+writing, this is only triggered by having static ownership in the deb (paths where ownership such as
+B<root:tty> is recorded directly in the F<data.tar>), AND
+
+=item -
+
+The package does not run nor permit B<debputy> to use (fake)root.  This part comes down to
+B<Rules-Requires-Root>. When set to B<no>, B<debputy> will automatically fallback to the
+internal method as necessary.
+
+If you would like to avoid using root during package assembly but also do not want a custom
+assembly method, then you can set B<Rules-Requires-Root: debputy/deb-assembly> and B<debputy>
+will always use B<dpkg-deb> for the assembly.  However, depending on your version of B<dpkg-dev>
+you may run into L<#1036865|https://bugs.debian.org/1036865>.  In that case, you will have to
+choose between using classic root (B<Rules-Requires-Root: binary-targets>) or the internal
+rootless assembly method.
+
+=back
+
+=head1 SEE ALSO
+
+L<debhelper(7)>
+
+This program integrates into the debhelper suite.
+
+=head1 AUTHOR
+
+Niels Thykier <niels@thykier.net>
+
+=cut
diff --git a/dh_installdebputy b/dh_installdebputy
new file mode 100755
index 0000000..50c157f
--- /dev/null
+++ b/dh_installdebputy
@@ -0,0 +1,137 @@
+#!/usr/bin/perl
+
+=encoding UTF-8
+
+=head1 NAME
+
+dh_installdebputy - install debputy plugins for debhelper packages
+
+=cut
+
+use strict;
+use warnings;
+use Debian::Debhelper::Dh_Lib;
+
+our $VERSION = DH_BUILTIN_VERSION;
+
+=head1 SYNOPSIS
+
+B<dh_installdebputy> [S<I<debhelper options>>] [S<B<--> I<params>>]
+
+=head1 DESCRIPTION
+
+B<dh_installdebputy> is a tool for installing B<debputy> plugins from a package built
+using B<debhelper>
+
+=head1 OPTIONS
+
+Standard debhelper options (such as B<-p>). Please see L<debhelper(7)>.
+
+=head1 DIRECTORIES
+
+=over 4
+
+=item F<debian/debputy-plugins/>, F<< debian/I<PACKAGE>.debputy-plugins/ >>
+
+These directories will contain the plugin(s) and related support files.
+Unlike most debhelper like tools, these must be directories (not files).
+
+Inside each directory, place the JSON descriptor file and (if relevant)
+related Python code and tests.  For a plugin named I<my-plugin> installed
+into I<package>, you might see:
+
+
+    debian/package.debputy-plugins/my-plugin.json
+	debian/package.debputy-plugins/my_plugin.py
+	debian/package.debputy-plugins/my_plugin_check.py
+
+If any tests are provided, they will be run when the plugin is installed
+provided that B<py.test> is available. Consider adding
+B<< python3-pytest <!nocheck> >> to B<Build-Depends> for this purpose.
+Additionally, the tests can be picked up by the B<autopkgtests> framework
+if you add B<autopkgtest-pkg-debputy> to the B<Testsuite> field in
+F<debian/control>.
+
+It is possible to have multiple test files:
+
+
+    debian/package.debputy-plugins/my-plugin.json
+	debian/package.debputy-plugins/my_plugin.py
+	debian/package.debputy-plugins/my_plugin_check_foo.py
+	debian/package.debputy-plugins/my_plugin_check_bar.py
+
+If you find yourself fighting with upstream's Python test runner picking up the
+B<debputy> test, then please review the
+L</DEALING WITH UPSTREAM'S PYTHON TEST RUNNER> sections for ways to deal with it.
+
+=back
+
+=cut
+
+init();
+
+my $debputy_cmd = $ENV{'DEBPUTY_CMD'} // 'debputy';
+my @debputy_cmdline = (
+	$debputy_cmd,
+	'internal-command',
+	'dh-integration-install-plugin',
+);
+for my $package (@{$dh{DOPACKAGES}}) {
+	push(@debputy_cmdline, '-p', $package);
+}
+doit(@debputy_cmdline);
+
+=head1 DEALING WITH UPSTREAM'S PYTHON TEST RUNNER
+
+There are multiple ways to deal with upstream's python test runner picking up the
+B<debputy> test. This section is written assuming upstream is using B<py.test>
+(sometimes invoked as B<python3 -m pytest>). While the concepts should carry over
+to other test runners, the examples and configuration names will probably not
+be directly reusable.
+
+The "least" effort option is to use B<_check> instead B<_test> in the naming
+of the B<debputy> tests.  This will work for clean builds as long as the
+B<py.test> run can still I<load> the modules (which often assumes that B<debputy>
+is installed). However, on unclean (B<dpkg-buildpackage -nc>) builds, B<py.test>
+can get confused because the module implementation file is both in
+B<debian/I<pkg>.debputy-plugins> and in B<< debian/I<pkg> >>. You can `rm` the
+version under B<< debian/I<pkg> >> manually, but it gets tedious.
+
+A more involved fix is to tell B<py.test> to either stay away from the
+F<debian> directory via B<norecursedirs> OR explicitly tell it where to
+find the source and tests (B<pythonpath> + B<testpaths>). If upstream uses
+B<pyproject.toml>, this could look something like:
+
+
+	[tool.pytest.ini_options]
+	# Option A: Stay out of the "debian" dir.
+	norecursedirs = [
+		"debian",
+	]
+	# Option B: Explicitly lists where the source and tests are.
+	# In this case, `py.test` will work out of the box (without resorting
+	# to "python3 -m pytest" or similar tricks). This approach may have
+	# value for upstream for that particular reason.
+	pythonpath = [
+		"src",
+	]
+	testpaths = [
+		"tests",
+		# You may need "src" here if upstream uses --doctest-modules
+	]
+
+The upstream fix will also prevent B<py.test> from picking up the plugin
+inside B<< debian/I<package> >> directory, which makes it more robust for
+B<dpkg-buildpackage -nc> builds.
+
+=head1 SEE ALSO
+
+L<debhelper(7)>
+
+This program integrates into the debhelper suite.
+
+=head1 AUTHOR
+
+Niels Thykier <niels@thykier.net>
+
+=cut
diff --git a/docs/IMPLEMENTATION-DECISIONS.md b/docs/IMPLEMENTATION-DECISIONS.md
new file mode 100644
index 0000000..a5fad33
--- /dev/null
+++ b/docs/IMPLEMENTATION-DECISIONS.md
@@ -0,0 +1,206 @@
+# Implementation decisions for debputy
+
+This document logs important decisions taken during the design of `debputy` along with the
+rationale and alternatives considered at the time.  This tech note collects decisions, analysis,
+and trade-offs made in the implementation of the system that may be of future interest. It also
+collects a list of intended future work. The historical background here may be useful for
+understanding design and implementation decisions, but would clutter other documents and distract
+from the details of the system as implemented.
+
+## Border between "installation" and "transformation"
+
+In `debputy`, a contributor can request certain actions to be performed such as `install foo into pkg`
+or `ensure bar in pkg is a symlink to baz`.  While the former is clearly an installation rule, is the
+latter an installation rule or a transformation rule?
+
+Answering this was important to ensure that actions were placed where people would expect them or would
+find it logical to look for them.  This is complicated by the fact that `install` (the command line tool)
+can perform mode and ownership transformation, create directories, whereas `dh_install` deals only with
+installing (copying) paths into packages and mode/ownership changes is related to a separate helper.
+
+The considered options were:
+
+### Install upstream bits and then apply packaging modification (chosen)
+
+In this line of thinking, the logic conceptually boils down to the following rule of thumb:
+
+  > If a path does not come from upstream, then it is a transform.
+
+Expanding a bit, anything that would install paths from upstream (usually `debian/tmp/...`) into a
+package is considered part of `installation`.  If further mutations are needed (such as, `create an
+empty dir at X as integration point`), they are transformations.
+
+All path metadata modifications (owner, group or mode) are considered transformations.  Even in the
+case, where the transformation is "disabling" a built-in normalization.  The logic here is that the
+packager's transform rule is undoing a built-in transformation rule.
+
+This option was chosen because it fit the perceived idea of how a packager views their own work
+per the following 4-step list:
+
+   1. Do any upstream build required.
+   2. Install files to build the initial trees for each Debian package.
+   3. Transform those trees for any additional fixes required.
+   4. Turn those trees into debs.
+
+Note: The `debhelper` stack has all transformations (according to this definition) under its
+installation phase as defined by `dh`'s `install` target. Concretely, the `dh install` target covers
+`dh_installdirs`, `dh_link` and `dh_fixperms`. However, it is less important what `debhelper` is
+doing as long as the definition is simple and not counter-intuitive to packagers.
+
+### Define the structural and then apply non-structural modifications
+
+Another proposal was to see the `file layout` phase as anything that did structural changes to the
+content of the package.  By the end of the `file layout` phase, all paths would be present where
+they were expected. So any mutation by the packager that changed the deb structurally would be a
+part of the `file layout` phase.
+
+Note file compression (and therefore renaming of files) could occur after `file layout` when this
+model was discussed.
+
+The primary advantage was that it works without having an upstream build system. However, even
+native packages tend to have an "upstream-like" build system, so it is not as much of an advantage
+in practice.
+
+Note this definition is not a 1:1 match with debhelper either.  As an example, file mode
+modification would be a transformation in this definition, whereas `debhelper` has it under
+`dh install`.
+
+## Stateless vs. Stateful installation rules
+
+A key concept in packaging is to "install" paths provided by upstream's build system into one or
+more packages.  In source packages producing multiple binary packages, the packager will want to
+divide the content across multiple packages and `debputy` should facilitate this in the best
+possible fashion.
+
+There were two "schools of thought" considered here, which is easiest to illustrate with the
+following example:
+
+  Assume that the upstream build system provides 4 programs in `debian/tmp/usr/bin`.  One of
+  these (`foo`) would have to be installed into the package `pkg` and the other would be more
+  special purpose and go into `foo-utils`.
+
+
+For a "stateless" ruleset, the packager would have to specify the request as:
+
+   * install `usr/bin/foo` into `pkg`
+   * install `usr/bin/*` except `usr/bin/foo` into `pkg-utils`
+
+Whereas with a "stateful" ruleset, the packager would have to specify the request as:
+
+   1. install `usr/bin/foo` into `pkg`
+   2. install `usr/bin/*` into `pkg-utils`
+      - Could be read as "install everything remaining in `usr/bin` into `pkg-utils`".
+
+
+### Stateful installation rules (chosen)
+
+The chosen model ended up being "stateful" patterns.
+
+Pros:
+
+ 1. Stateful rules provides a "natural" way to say "install FILE1 in DIR into A,
+    FILE2 from DIR into B, and the rest of DIR into C" without having to accumulating
+    "excludes" or replacing a glob with "subglobs" to avoid double matching.
+
+ 2. There is a "natural" way to define that something should *not* be installed
+    via the `discard` rule, which interfaces nicely with the `dh_missing`-like
+    behaviour (detecting things that might have been overlooked).
+
+ 3. Avoids the complexity of having a glob expansion with a "per-rule" `exclude`,
+    where the `exclude` itself contains globs (`usr/lib/*` except `usr/bin/*.la`).
+
+Cons:
+ 1. Stateful parsing requires `debputy` to track what has already been matched.
+ 2. Rules cannot be interpreted in isolation nor out of order.
+ 3. Naming does not (always) imply the "destructiveness" or state of the action.
+    - The `install` term is commonly understood to have `copy` semantics rather
+      than `move` semantics.
+ 4. It is a step away from default `debhelper` mechanics and might cause
+    surprises for people assuming `debhelper` semantics.
+
+
+The 1st con would have applied anyway, as to avoid accidental RC bugs the
+contributor is required to explicitly list multiple packages for any install
+rule that would install the same path into two distinct packages or to provide
+`dh_missing` functionality.  Therefore, the tracking would have existed in
+some form regardless.
+
+The 2nd con can be mitigated by leveraging the tracking to report if the
+rules appear to run in opposite order.
+
+The 3rd con is partly mitigated by using `discard` rather than `exclude` (which
+was the original name). Additionally, the mitigation for the 2nd con generally
+covers the most common cases as well. The only "surprising" case if you have
+one tool path you want installed into two packages at the same time, where you
+use two matches and the second one is a glob. However, the use-case is rare and
+was considered an acceptable risk given its probability.
+
+The 4th con is less of a problem when migrating from `debhelper` to `debputy`.
+Any `debhelper` based package will not have (unintentional) overlapping matches
+causing file conflicts.  There might be some benign double matching that the
+packager will have to clean up post migration, because `debhelper` is more
+forgiving. Migration from `debputy` to `debhelper` might be more difficult but
+not a goal for `debputy`, so it was not considered relevant.
+
+Prior art: `dh-exec` supports a similar feature via `=> usr/bin/foo`.
+
+
+### Stateless installation rules
+
+Pros:
+
+  1. It matches the default helper, so it requires less cognitive effort for
+     people migrating.
+
+  2. The `install` term would effectively have `copy` semantics.
+
+  3. In theory, `debputy` could do with simpler tracking mechanics.
+     - In practice, the tracked used for the error reporting required was 80%
+       of the complexity. This severely limits any practical benefit.
+
+
+Cons:
+
+ 1. No obvious way to deliberately ignore content that are not of a glob + exclude.
+    - While the `usr/bin/* except <matches>` could work, the default is "new appearances"
+      gets installed rather than aborting the built with a "there is a new tool for you
+      to consider".  Alternatives such as including a stand-alone `exclude` or `discard`
+      rule would imply stateful parsing, but would not actually be stateful for `install`
+      and therefore being a potential source of confusion.  Therefore, such a feature
+      would have to require a separate configuration next to installations.
+
+ 2. Install rules with globs would have to accumulate excludes or degenerate to the "magic
+    sub-matching globs" to avoid overlaps. The latter is the pattern supported by debhelper.
+
+# Plugin integration
+
+Looking at `debhelper`, one of its major sources of success is that "anyone" could extend it
+to solve their specific need and that it was easy to do so.  When looking at the debhelper
+extensions, it seems a vast majority of Debian packages do the debhelper extension "on the
+side" (such as a bundle it inside an existing `-dev` package).  Having package dedicated
+to the debhelper tooling does happen but seems to be very rare.
+
+With this in mind, using python's `entry_points` API was ruled out. It would require packagers
+to do a Python project inside their existing package with double build-systems, which basically
+no existing package helper does well (CDBS a possible exception but CDBS is generally frowned
+upon by the general Debian contributor population).
+
+Instead, a "drop a .json file here" approach was chosen instead to get a more "light-weight"
+integration up and running.  When designing it, the following things were important:
+
+ * It should be possible to extract the metadata of the plugin *without* running any code from it
+   as running code could "taint" the process and break "list all plugins" features.
+   (This ruled out loading python code directly)
+
+ * Simple features would ideally not require code at all.  Packager provided files as an example
+   can basically be done as a configuration rather than code.  This means that `debputy` can provide
+   automated plugin upgrades from the current format to a future one if needed be.
+
+ * Being able to re-use the declarative parser to handle the error messages and data normalization
+   (this implies `JSON`, `YAML` or similar formats that is easily parsed in to mappings and lists).
+
+ * It is important that there is a plugin API compat level that enables us to change the format or
+   API between `debputy` and the plugins if we learn that the current API is inadequate.
+
+At the time of writing, the plugin integration is still in development.  What is important can change
+as we get actual users.
diff --git a/lib/Debian/Debhelper/Sequence/debputy.pm b/lib/Debian/Debhelper/Sequence/debputy.pm
new file mode 100644
index 0000000..0f485c4
--- /dev/null
+++ b/lib/Debian/Debhelper/Sequence/debputy.pm
@@ -0,0 +1,68 @@
+use Debian::Debhelper::Dh_Lib qw(error);
+
+insert_after('dh_builddeb', 'dh_debputy');
+if (exists($INC{"Debian/Debhelper/Sequence/zz_debputy_rrr.pm"})) {
+    error("The (zz-)debputy sequence cannot be used with the zz-debputy-rrr sequence");
+}
+# Prune commands that debputy takes over; align with migrators_impl.py
+remove_command('dh_install');
+remove_command('dh_installdocs');
+remove_command('dh_installchangelogs');
+remove_command('dh_installexamples');
+remove_command('dh_installman');
+remove_command('dh_installcatalogs');
+remove_command('dh_installcron');
+remove_command('dh_installdebconf');
+remove_command('dh_installemacsen');
+remove_command('dh_installifupdown');
+remove_command('dh_installinfo');
+remove_command('dh_installinit');
+remove_command('dh_installsysusers');
+remove_command('dh_installtmpfiles');
+remove_command('dh_installsystemd');
+remove_command('dh_installsystemduser');
+remove_command('dh_installmenu');
+remove_command('dh_installmime');
+remove_command('dh_installmodules');
+remove_command('dh_installlogcheck');
+remove_command('dh_installlogrotate');
+remove_command('dh_installpam');
+remove_command('dh_installppp');
+remove_command('dh_installudev');
+remove_command('dh_installgsettings');
+remove_command('dh_installinitramfs');
+remove_command('dh_installalternatives');
+remove_command('dh_bugfiles');
+remove_command('dh_ucf');
+remove_command('dh_lintian');
+remove_command('dh_icons');
+remove_command('dh_usrlocal');
+remove_command('dh_perl');
+remove_command('dh_link');
+remove_command('dh_installwm');
+remove_command('dh_installxfonts');
+remove_command('dh_strip_nondeterminism');
+remove_command('dh_compress');
+remove_command('dh_fixperms');
+remove_command('dh_dwz');
+remove_command('dh_strip');
+remove_command('dh_makeshlibs');
+remove_command('dh_shlibdeps');
+remove_command('dh_missing');
+remove_command('dh_installdeb');
+remove_command('dh_gencontrol');
+remove_command('dh_md5sums');
+remove_command('dh_builddeb');
+
+# Remove commands from add-ons where partial migration is possible
+
+# sequence: gnome; we remove dh_gnome but not dh_gnome_clean for now.
+remove_command('dh_gnome');
+# sequence: lua; kept for its dependencies
+remove_command('dh_lua');
+# sequence: numpy; kept for its dependencies
+remove_command('dh_numpy3');
+# sequence: perl_openssl; kept for its dependencies
+remove_command('dh_perl_openssl');
+
+1;
diff --git a/lib/Debian/Debhelper/Sequence/installdebputy.pm b/lib/Debian/Debhelper/Sequence/installdebputy.pm
new file mode 100644
index 0000000..d564585
--- /dev/null
+++ b/lib/Debian/Debhelper/Sequence/installdebputy.pm
@@ -0,0 +1,3 @@
+insert_after('dh_installalternatives', 'dh_installdebputy');
+
+1;
diff --git a/lib/Debian/Debhelper/Sequence/zz_debputy.pm b/lib/Debian/Debhelper/Sequence/zz_debputy.pm
new file mode 100644
index 0000000..d9c8ac5
--- /dev/null
+++ b/lib/Debian/Debhelper/Sequence/zz_debputy.pm
@@ -0,0 +1,4 @@
+# This is just a different name for the debputy sequence for people that use other add-ons.
+require Debian::Debhelper::Sequence::debputy;
+
+1;
diff --git a/lib/Debian/Debhelper/Sequence/zz_debputy_rrr.pm b/lib/Debian/Debhelper/Sequence/zz_debputy_rrr.pm
new file mode 100644
index 0000000..53971e8
--- /dev/null
+++ b/lib/Debian/Debhelper/Sequence/zz_debputy_rrr.pm
@@ -0,0 +1,13 @@
+use Debian::Debhelper::Dh_Lib qw(error);
+
+insert_after('dh_builddeb', 'dh_debputy');
+if (exists($INC{"Debian/Debhelper/Sequence/debputy.pm"})) {
+    error("The zz-debputy-rrr sequence cannot be used with the (zz-)debputy sequence");
+}
+add_command_options('dh_debputy', '--integration-mode=rrr');
+
+remove_command('dh_fixperms');
+remove_command('dh_gencontrol');
+remove_command('dh_md5sums');
+remove_command('dh_builddeb');
+1;
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..73119d7
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,45 @@
+[tool.coverage.run]
+branch = true
+source = ["."]
+omit = [
+  "*/lib/python*/*",
+  "*/dist-packages/*",
+  "*/tests/*",
+]
+
+[tool.coverage.report]
+# Lets not force ourselves to sprinkle "pragma: no cover" in the following cases
+exclude_lines = [
+    # Have to re-enable the standard pragma
+    "pragma: no cover",
+
+    # Ignore code that is not intended to be run
+    "if TYPE_CHECKING:",
+    "raise AssertionError",
+
+    # Ignore "..." (overload)
+    "^\\s+[.][.][.]\\s*$",
+
+    # We cannot hit this via tests.  On the flip-side, we should ensure this
+    # only call a main() (or a similar function).
+    "if __name__ == .__main__.:",
+
+    # Do not complain about abstract methods as they are not run
+    "@(abc\\.)?abstractmethod",
+    "raise NotImplementedError([(][)]|\\s*$)",
+]
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+norecursedirs = [
+    "local",
+    "debian",
+]
+pythonpath = [
+    "src"
+]
+testpaths = [
+    "src",
+    "tests",
+    "self-hosting-plugins",
+]
diff --git a/self-hosting-plugins/debputy-self-hosting.json b/self-hosting-plugins/debputy-self-hosting.json
new file mode 100644
index 0000000..fa02d72
--- /dev/null
+++ b/self-hosting-plugins/debputy-self-hosting.json
@@ -0,0 +1,4 @@
+{
+  "plugin-initializer": "initializer",
+  "api-compat-version": 1
+}
diff --git a/self-hosting-plugins/debputy_self_hosting.py b/self-hosting-plugins/debputy_self_hosting.py
new file mode 100644
index 0000000..4db4e05
--- /dev/null
+++ b/self-hosting-plugins/debputy_self_hosting.py
@@ -0,0 +1,61 @@
+import textwrap
+
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    VirtualPath,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.util import POSTINST_DEFAULT_CONDITION
+
+
+def _maintscript_generator(
+    _path: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    maintscript = ctrl.maintscript
+
+    # When `debputy` becomes a stand-alone package, it should have these maintscripts instead of dh-debputy
+    # Admittedly, I hope to get rid of this plugin before then, but ...
+    assert context.binary_package.name != "debputy", "Update the self-hosting plugin"
+    dirname = "/usr/share/debputy"
+
+    if context.binary_package.name == "dh-debputy":
+        ctrl.dpkg_trigger("interest-noawait", dirname)
+        maintscript.unconditionally_in_script(
+            "postinst",
+            textwrap.dedent(
+                f"""\
+            if {POSTINST_DEFAULT_CONDITION} || [ "$1" = "triggered" ] ; then
+                # Ensure all plugins are byte-compiled (plus uninstalled plugins are cleaned up)
+                py3clean {dirname}
+                if command -v py3compile >/dev/null 2>&1; then
+                    py3compile {dirname}
+                fi
+                if command -v pypy3compile >/dev/null 2>&1; then
+                    pypy3compile {dirname} || true
+                fi
+            fi
+        """
+            ),
+        )
+        maintscript.unconditionally_in_script(
+            "prerm",
+            textwrap.dedent(
+                f"""\
+        if command -v py3clean >/dev/null 2>&1; then
+            py3clean {dirname}
+        else
+            find {dirname}/ -type d -name __pycache__ -empty -print0 | xargs --null --no-run-if-empty rmdir
+        fi
+        """
+            ),
+        )
+
+
+def initializer(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector(
+        "debputy-self-hosting",
+        _maintscript_generator,
+    )
diff --git a/self-hosting-plugins/debputy_self_hosting_test.py b/self-hosting-plugins/debputy_self_hosting_test.py
new file mode 100644
index 0000000..c8da6cc
--- /dev/null
+++ b/self-hosting-plugins/debputy_self_hosting_test.py
@@ -0,0 +1,10 @@
+from debputy.plugin.api.test_api import (
+    initialize_plugin_under_test,
+    build_virtual_file_system,
+)
+
+
+def test_plugin():
+    plugin = initialize_plugin_under_test()
+    fs = build_virtual_file_system([])
+    plugin.run_metadata_detector("debputy-self-hosting", fs)
diff --git a/src/debputy/__init__.py b/src/debputy/__init__.py
new file mode 100644
index 0000000..23ebc5f
--- /dev/null
+++ b/src/debputy/__init__.py
@@ -0,0 +1,16 @@
+import pathlib
+
+from .version import IS_RELEASE_BUILD, __version__
+
+# Replaced during install; must be a single line
+# fmt: off
+DEBPUTY_ROOT_DIR = pathlib.Path(__file__).parent.parent.parent
+DEBPUTY_PLUGIN_ROOT_DIR = pathlib.Path(__file__).parent.parent.parent
+# fmt: on
+
+if IS_RELEASE_BUILD:
+    DEBPUTY_DOC_ROOT_DIR = (
+        f"https://salsa.debian.org/debian/debputy/-/blob/debian/{__version__}"
+    )
+else:
+    DEBPUTY_DOC_ROOT_DIR = "https://salsa.debian.org/debian/debputy/-/blob/main"
diff --git a/src/debputy/_deb_options_profiles.py b/src/debputy/_deb_options_profiles.py
new file mode 100644
index 0000000..fddb1b7
--- /dev/null
+++ b/src/debputy/_deb_options_profiles.py
@@ -0,0 +1,91 @@
+import os
+from functools import lru_cache
+
+from typing import FrozenSet, Optional, Mapping, Dict
+
+
+def _parse_deb_build_options(value: str) -> Mapping[str, Optional[str]]:
+    res: Dict[str, Optional[str]] = {}
+    for kvish in value.split():
+        if "=" in kvish:
+            key, value = kvish.split("=", 1)
+            res[key] = value
+        else:
+            res[kvish] = None
+    return res
+
+
+class DebBuildOptionsAndProfiles:
+    """Accessor to common environment related values
+
+    >>> env = DebBuildOptionsAndProfiles(environ={'DEB_BUILD_PROFILES': 'noudeb nojava'})
+    >>> 'noudeb' in env.deb_build_profiles
+    True
+    >>> 'nojava' in env.deb_build_profiles
+    True
+    >>> 'nopython' in env.deb_build_profiles
+    False
+    >>> sorted(env.deb_build_profiles)
+    ['nojava', 'noudeb']
+    """
+
+    def __init__(self, *, environ: Optional[Mapping[str, str]] = None) -> None:
+        """Provide a view of the options. Though consider using DebBuildOptionsAndProfiles.instance() instead
+
+        :param environ: Alternative to os.environ. Mostly useful for testing purposes
+        """
+        if environ is None:
+            environ = os.environ
+        self._deb_build_profiles = frozenset(
+            x for x in environ.get("DEB_BUILD_PROFILES", "").split()
+        )
+        self._deb_build_options = _parse_deb_build_options(
+            environ.get("DEB_BUILD_OPTIONS", "")
+        )
+
+    @staticmethod
+    @lru_cache(1)
+    def instance() -> "DebBuildOptionsAndProfiles":
+        return DebBuildOptionsAndProfiles()
+
+    @property
+    def deb_build_profiles(self) -> FrozenSet[str]:
+        """A set-like view of all build profiles active during the build
+
+        >>> env = DebBuildOptionsAndProfiles(environ={'DEB_BUILD_PROFILES': 'noudeb nojava'})
+        >>> 'noudeb' in env.deb_build_profiles
+        True
+        >>> 'nojava' in env.deb_build_profiles
+        True
+        >>> 'nopython' in env.deb_build_profiles
+        False
+        >>> sorted(env.deb_build_profiles)
+        ['nojava', 'noudeb']
+
+        """
+        return self._deb_build_profiles
+
+    @property
+    def deb_build_options(self) -> Mapping[str, Optional[str]]:
+        """A set-like view of all build profiles active during the build
+
+        >>> env = DebBuildOptionsAndProfiles(environ={'DEB_BUILD_OPTIONS': 'nostrip parallel=4'})
+        >>> 'nostrip' in env.deb_build_options
+        True
+        >>> 'parallel' in env.deb_build_options
+        True
+        >>> 'noautodbgsym' in env.deb_build_options
+        False
+        >>> env.deb_build_options['nostrip'] is None
+        True
+        >>> env.deb_build_options['parallel']
+        '4'
+        >>> env.deb_build_options['noautodbgsym']
+        Traceback (most recent call last):
+            ...
+        KeyError: 'noautodbgsym'
+        >>> sorted(env.deb_build_options)
+        ['nostrip', 'parallel']
+
+        """
+        return self._deb_build_options
diff --git a/src/debputy/_manifest_constants.py b/src/debputy/_manifest_constants.py
new file mode 100644
index 0000000..3ed992b
--- /dev/null
+++ b/src/debputy/_manifest_constants.py
@@ -0,0 +1,49 @@
+from typing import Literal
+
+DEFAULT_MANIFEST_VERSION = "0.1"
+SUPPORTED_MANIFEST_VERSIONS = frozenset(["0.1"])
+ManifestVersion = Literal["0.1"]
+assert DEFAULT_MANIFEST_VERSION in SUPPORTED_MANIFEST_VERSIONS
+
+MK_MANIFEST_VERSION = "manifest-version"
+MK_PACKAGES = "packages"
+
+MK_INSTALLATIONS = "installations"
+MK_INSTALLATIONS_INSTALL = "install"
+MK_INSTALLATIONS_MULTI_DEST_INSTALL = "multi-dest-install"
+MK_INSTALLATIONS_INSTALL_DOCS = "install-docs"
+MK_INSTALLATIONS_INSTALL_EXAMPLES = "install-examples"
+MK_INSTALLATIONS_INSTALL_MAN = "install-man"
+MK_INSTALLATIONS_DISCARD = "discard"
+
+MK_INSTALLATIONS_INSTALL_SOURCE = "source"
+MK_INSTALLATIONS_INSTALL_SOURCES = "sources"
+MK_INSTALLATIONS_INSTALL_DEST_DIR = "dest-dir"
+MK_INSTALLATIONS_INSTALL_AS = "as"
+MK_INSTALLATIONS_INSTALL_INTO = "into"
+
+MK_INSTALLATIONS_INSTALL_MAN_LANGUAGE = "language"
+
+MK_CONDITION_WHEN = "when"
+MK_CONDITION_ARCH_MATCHES = "arch-matches"
+MK_CONDITION_BUILD_PROFILES_MATCHES = "build-profiles-matches"
+
+MK_TRANSFORMATIONS = "transformations"
+
+MK_TRANSFORMATIONS_CREATE_SYMLINK = "create-symlink"
+MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_PATH = "path"
+MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_TARGET = "target"
+
+MK_CONFFILE_MANAGEMENT = "conffile-management"
+MK_CONFFILE_MANAGEMENT_REMOVE = "remove"
+MK_CONFFILE_MANAGEMENT_RENAME = "rename"
+
+MK_CONFFILE_MANAGEMENT_REMOVE_PATH = "path"
+MK_CONFFILE_MANAGEMENT_RENAME_SOURCE = "source"
+MK_CONFFILE_MANAGEMENT_RENAME_TARGET = "target"
+
+MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION = "prior-to-version"
+MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE = "owning-package"
+
+MK_MANIFEST_DEFINITIONS = "definitions"
+MK_MANIFEST_VARIABLES = "variables"
diff --git a/src/debputy/architecture_support.py b/src/debputy/architecture_support.py
new file mode 100644
index 0000000..e190722
--- /dev/null
+++ b/src/debputy/architecture_support.py
@@ -0,0 +1,233 @@
+import os
+import subprocess
+from functools import lru_cache
+from typing import Dict, Optional, Iterator, Tuple
+
+
+class DpkgArchitectureBuildProcessValuesTable:
+    """Dict-like interface to dpkg-architecture values"""
+
+    def __init__(self, *, mocked_answers: Optional[Dict[str, str]] = None) -> None:
+        """Create a new dpkg-architecture table; NO INSTANTIATION
+
+        This object will be created for you; if you need a production instance
+        then call dpkg_architecture_table().  If you need a testing instance,
+        then call mock_arch_table(...)
+
+        :param mocked_answers: Used for testing purposes.  Do not use directly;
+        instead use mock_arch_table(...) to create the table you want.
+        """
+        self._architecture_cache: Dict[str, str] = {}
+        self._has_run_dpkg_architecture = False
+        if mocked_answers is None:
+            self._architecture_cache = {}
+            self._respect_environ: bool = True
+            self._has_run_dpkg_architecture = False
+        else:
+            self._architecture_cache = mocked_answers
+            self._respect_environ = False
+            self._has_run_dpkg_architecture = True
+
+    def __contains__(self, item: str) -> bool:
+        try:
+            self[item]
+        except KeyError:
+            return False
+        else:
+            return True
+
+    def __getitem__(self, item: str) -> str:
+        if item not in self._architecture_cache:
+            if self._respect_environ:
+                value = os.environ.get(item)
+                if value is not None:
+                    self._architecture_cache[item] = value
+                    return value
+            if not self._has_run_dpkg_architecture:
+                self._load_dpkg_architecture_values()
+            # Fall through and look it up in the cache
+        return self._architecture_cache[item]
+
+    def __iter__(self) -> Iterator[str]:
+        if not self._has_run_dpkg_architecture:
+            self._load_dpkg_architecture_values()
+        yield from self._architecture_cache
+
+    @property
+    def current_host_arch(self) -> str:
+        """The architecture we are building for
+
+        This is the architecture name you need if you are in doubt.
+        """
+        return self["DEB_HOST_ARCH"]
+
+    @property
+    def current_host_multiarch(self) -> str:
+        """The multi-arch path basename
+
+        This is the multi-arch basename name you need if you are in doubt.  It
+        goes here:
+
+            "/usr/lib/{MA}".format(table.current_host_multiarch)
+
+        """
+        return self["DEB_HOST_MULTIARCH"]
+
+    @property
+    def is_cross_compiling(self) -> bool:
+        """Whether we are cross-compiling
+
+        This is defined as DEB_BUILD_GNU_TYPE != DEB_HOST_GNU_TYPE and
+        affects whether we can rely on being able to run the binaries
+        that are compiled.
+        """
+        return self["DEB_BUILD_GNU_TYPE"] != self["DEB_HOST_GNU_TYPE"]
+
+    def _load_dpkg_architecture_values(self) -> None:
+        env = dict(os.environ)
+        # For performance, disable dpkg's translation later
+        env["DPKG_NLS"] = "0"
+        kw_pairs = _parse_dpkg_arch_output(
+            subprocess.check_output(
+                ["dpkg-architecture"],
+                env=env,
+            )
+        )
+        for k, v in kw_pairs:
+            self._architecture_cache[k] = os.environ.get(k, v)
+        self._has_run_dpkg_architecture = True
+
+
+def _parse_dpkg_arch_output(output: bytes) -> Iterator[Tuple[str, str]]:
+    text = output.decode("utf-8")
+    for line in text.splitlines():
+        k, v = line.strip().split("=", 1)
+        yield k, v
+
+
+def _rewrite(value: str, from_pattern: str, to_pattern: str) -> str:
+    assert value.startswith(from_pattern)
+    return to_pattern + value[len(from_pattern) :]
+
+
+def faked_arch_table(
+    host_arch: str,
+    *,
+    build_arch: Optional[str] = None,
+    target_arch: Optional[str] = None,
+) -> DpkgArchitectureBuildProcessValuesTable:
+    """Creates a mocked instance of DpkgArchitectureBuildProcessValuesTable
+
+
+    :param host_arch: The dpkg architecture to mock answers for.  This affects
+      DEB_HOST_* values and defines the default for DEB_{BUILD,TARGET}_* if
+      not overridden.
+    :param build_arch: If set and has a different value than host_arch, then
+      pretend this is a cross-build.  This value affects the DEB_BUILD_* values.
+    :param target_arch: If set and has a different value than host_arch, then
+      pretend this is a build _of_ a cross-compiler.  This value affects the
+      DEB_TARGET_* values.
+    """
+
+    if build_arch is None:
+        build_arch = host_arch
+
+    if target_arch is None:
+        target_arch = host_arch
+    return _faked_arch_tables(host_arch, build_arch, target_arch)
+
+
+@lru_cache
+def _faked_arch_tables(
+    host_arch: str, build_arch: str, target_arch: str
+) -> DpkgArchitectureBuildProcessValuesTable:
+    mock_table = {}
+
+    env = dict(os.environ)
+    # Set CC to /bin/true avoid a warning from dpkg-architecture
+    env["CC"] = "/bin/true"
+    # For performance, disable dpkg's translation later
+    env["DPKG_NLS"] = "0"
+    # Clear environ variables that might confuse dpkg-architecture
+    for k in os.environ:
+        if k.startswith("DEB_"):
+            del env[k]
+
+    if build_arch == host_arch:
+        # easy / common case - we can handle this with a single call
+        kw_pairs = _parse_dpkg_arch_output(
+            subprocess.check_output(
+                ["dpkg-architecture", "-a", host_arch, "-A", target_arch],
+                env=env,
+            )
+        )
+        for k, v in kw_pairs:
+            if k.startswith(("DEB_HOST_", "DEB_TARGET_")):
+                mock_table[k] = v
+            # Clone DEB_HOST_* into DEB_BUILD_* as well
+            if k.startswith("DEB_HOST_"):
+                k2 = _rewrite(k, "DEB_HOST_", "DEB_BUILD_")
+                mock_table[k2] = v
+    elif build_arch != host_arch and host_arch != target_arch:
+        # This will need two dpkg-architecture calls because we cannot set
+        # DEB_BUILD_* directly.  But we can set DEB_HOST_* and then rewrite
+        # it
+        # First handle the build arch
+        kw_pairs = _parse_dpkg_arch_output(
+            subprocess.check_output(
+                ["dpkg-architecture", "-a", build_arch],
+                env=env,
+            )
+        )
+        for k, v in kw_pairs:
+            if k.startswith("DEB_HOST_"):
+                k = _rewrite(k, "DEB_HOST_", "DEB_BUILD_")
+                mock_table[k] = v
+
+        kw_pairs = _parse_dpkg_arch_output(
+            subprocess.check_output(
+                ["dpkg-architecture", "-a", host_arch, "-A", target_arch],
+                env=env,
+            )
+        )
+        for k, v in kw_pairs:
+            if k.startswith(("DEB_HOST_", "DEB_TARGET_")):
+                mock_table[k] = v
+    else:
+        # This is a fun special case.  We know that:
+        # * build_arch != host_arch
+        # * host_arch == target_arch
+        # otherwise we would have hit one of the previous cases.
+        #
+        # We can do this in a single call to dpkg-architecture by
+        # a bit of "cleaver" rewriting.
+        #
+        # - Use -a to set DEB_HOST_* and then rewrite that as
+        #   DEB_BUILD_*
+        # - use -A to set DEB_TARGET_* and then use that for both
+        #   DEB_HOST_* and DEB_TARGET_*
+
+        kw_pairs = _parse_dpkg_arch_output(
+            subprocess.check_output(
+                ["dpkg-architecture", "-a", build_arch, "-A", target_arch], env=env
+            )
+        )
+        for k, v in kw_pairs:
+            if k.startswith("DEB_HOST_"):
+                k2 = _rewrite(k, "DEB_HOST_", "DEB_BUILD_")
+                mock_table[k2] = v
+                continue
+            if k.startswith("DEB_TARGET_"):
+                mock_table[k] = v
+                k2 = _rewrite(k, "DEB_TARGET_", "DEB_HOST_")
+                mock_table[k2] = v
+
+    table = DpkgArchitectureBuildProcessValuesTable(mocked_answers=mock_table)
+    return table
+
+
+_ARCH_TABLE = DpkgArchitectureBuildProcessValuesTable()
+
+
+def dpkg_architecture_table() -> DpkgArchitectureBuildProcessValuesTable:
+    return _ARCH_TABLE
diff --git a/src/debputy/builtin_manifest_rules.py b/src/debputy/builtin_manifest_rules.py
new file mode 100644
index 0000000..c8e6557
--- /dev/null
+++ b/src/debputy/builtin_manifest_rules.py
@@ -0,0 +1,261 @@
+import re
+from typing import Iterable, Tuple, Optional
+
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.exceptions import PureVirtualPathError, TestPathWithNonExistentFSPathError
+from debputy.intermediate_manifest import PathType
+from debputy.manifest_parser.base_types import SymbolicMode, OctalMode, FileSystemMode
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.path_matcher import (
+    MATCH_ANYTHING,
+    MatchRule,
+    ExactFileSystemPath,
+    DirectoryBasedMatch,
+    MatchRuleType,
+    BasenameGlobMatch,
+)
+from debputy.substitution import Substitution
+from debputy.types import VP
+from debputy.util import _normalize_path, perl_module_dirs
+
+# Imported from dh_fixperms
+_PERMISSION_NORMALIZATION_SOURCE_DEFINITION = "permission normalization"
+attribute_path = AttributePath.builtin_path()[
+    _PERMISSION_NORMALIZATION_SOURCE_DEFINITION
+]
+_STD_FILE_MODE = OctalMode(0o644)
+_PATH_FILE_MODE = OctalMode(0o755)
+_HAS_BIN_SHBANG_RE = re.compile(rb"^#!\s*/(?:usr/)?s?bin", re.ASCII)
+
+
+class _UsrShareDocMatchRule(DirectoryBasedMatch):
+    def __init__(self) -> None:
+        super().__init__(
+            MatchRuleType.ANYTHING_BENEATH_DIR,
+            _normalize_path("usr/share/doc", with_prefix=True),
+            path_type=PathType.FILE,
+        )
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        doc_dir = fs_root.lookup(self._directory)
+        if doc_dir is None:
+            return
+        for path_in_doc_dir in doc_dir.iterdir:
+            if ignore_paths is not None and ignore_paths(path_in_doc_dir):
+                continue
+            if path_in_doc_dir.is_file:
+                yield path_in_doc_dir
+            for subpath in path_in_doc_dir.iterdir:
+                if subpath.name == "examples" and subpath.is_dir:
+                    continue
+                if ignore_paths is not None:
+                    yield from (
+                        f
+                        for f in subpath.all_paths()
+                        if f.is_file and not ignore_paths(f)
+                    )
+                else:
+                    yield from (f for f in subpath.all_paths() if f.is_file)
+
+    def describe_match_short(self) -> str:
+        return f"All files beneath {self._directory}/ except .../<pkg>/examples"
+
+    def describe_match_exact(self) -> str:
+        return self.describe_match_short()
+
+
+class _ShebangScriptFiles(MatchRule):
+    def __init__(self) -> None:
+        super().__init__(MatchRuleType.GENERIC_GLOB)
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        for p in fs_root.all_paths():
+            if not p.is_file or (ignore_paths and ignore_paths(p)):
+                continue
+            try:
+                with p.open(byte_io=True) as fd:
+                    c = fd.read(32)
+            except (PureVirtualPathError, TestPathWithNonExistentFSPathError):
+                continue
+            if _HAS_BIN_SHBANG_RE.match(c):
+                yield p
+
+    @property
+    def path_type(self) -> Optional[PathType]:
+        return PathType.FILE
+
+    def _full_pattern(self) -> str:
+        return "built-in - not a valid pattern"
+
+    def describe_match_short(self) -> str:
+        return "All scripts with a absolute #!-line for /(s)bin or /usr/(s)bin"
+
+    def describe_match_exact(self) -> str:
+        return self.describe_match_short()
+
+
+USR_SHARE_DOC_MATCH_RULE = _UsrShareDocMatchRule()
+SHEBANG_SCRIPTS = _ShebangScriptFiles()
+del _UsrShareDocMatchRule
+del _ShebangScriptFiles
+
+
+def builtin_mode_normalization_rules(
+    dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+    dctrl_bin: BinaryPackage,
+    substitution: Substitution,
+) -> Iterable[Tuple[MatchRule, FileSystemMode]]:
+    yield from (
+        (
+            MatchRule.from_path_or_glob(
+                x,
+                _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+                path_type=PathType.FILE,
+            ),
+            _STD_FILE_MODE,
+        )
+        for x in (
+            "*.so.*",
+            "*.so",
+            "*.la",
+            "*.a",
+            "*.js",
+            "*.css",
+            "*.scss",
+            "*.sass",
+            "*.jpeg",
+            "*.jpg",
+            "*.png",
+            "*.gif",
+            "*.cmxs",
+            "*.node",
+        )
+    )
+
+    yield from (
+        (
+            MatchRule.recursive_beneath_directory(
+                x,
+                _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+                path_type=PathType.FILE,
+            ),
+            _STD_FILE_MODE,
+        )
+        for x in (
+            "usr/share/man",
+            "usr/include",
+            "usr/share/applications",
+            "usr/share/lintian/overrides",
+        )
+    )
+
+    # The dh_fixperms tool recuses for these directories, but probably should not (see #1006927)
+    yield from (
+        (
+            MatchRule.from_path_or_glob(
+                f"{x}/*",
+                _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+                path_type=PathType.FILE,
+            ),
+            _PATH_FILE_MODE,
+        )
+        for x in (
+            "usr/bin",
+            "usr/bin/mh",
+            "bin",
+            "usr/sbin",
+            "sbin",
+            "usr/games",
+            "usr/libexec",
+            "etc/init.d",
+        )
+    )
+
+    yield (
+        # Strictly speaking, dh_fixperms does a recursive search but in practice, it does not matter.
+        MatchRule.from_path_or_glob(
+            "etc/sudoers.d/*",
+            _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+            path_type=PathType.FILE,
+        ),
+        OctalMode(0o440),
+    )
+
+    # The reportbug rule
+    yield (
+        ExactFileSystemPath(
+            substitution.substitute(
+                _normalize_path("usr/share/bug/{{PACKAGE}}"),
+                _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+            )
+        ),
+        OctalMode(0o755),
+    )
+
+    yield (
+        MatchRule.recursive_beneath_directory(
+            "usr/share/bug/{{PACKAGE}}",
+            _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+            path_type=PathType.FILE,
+            substitution=substitution,
+        ),
+        OctalMode(0o644),
+    )
+
+    yield (
+        ExactFileSystemPath(
+            substitution.substitute(
+                _normalize_path("usr/share/bug/{{PACKAGE}}/script"),
+                _PERMISSION_NORMALIZATION_SOURCE_DEFINITION,
+            )
+        ),
+        OctalMode(0o755),
+    )
+
+    yield (
+        USR_SHARE_DOC_MATCH_RULE,
+        OctalMode(0o0644),
+    )
+
+    yield from (
+        (
+            BasenameGlobMatch(
+                "*.pm",
+                only_when_in_directory=perl_dir,
+                path_type=PathType.FILE,
+                recursive_match=True,
+            ),
+            SymbolicMode.parse_filesystem_mode(
+                "a-x",
+                attribute_path['"*.pm'],
+            ),
+        )
+        for perl_dir in perl_module_dirs(dpkg_architecture_variables, dctrl_bin)
+    )
+
+    yield (
+        BasenameGlobMatch(
+            "*.ali",
+            only_when_in_directory=_normalize_path("usr/lib"),
+            path_type=PathType.FILE,
+            recursive_match=True,
+        ),
+        SymbolicMode.parse_filesystem_mode(
+            "a-w",
+            attribute_path['"*.ali"'],
+        ),
+    )
+
+    yield (
+        SHEBANG_SCRIPTS,
+        _PATH_FILE_MODE,
+    )
+
+    yield (
+        MATCH_ANYTHING,
+        SymbolicMode.parse_filesystem_mode(
+            "go=rX,u+rw,a-s",
+            attribute_path["**/*"],
+        ),
+    )
diff --git a/src/debputy/commands/__init__.py b/src/debputy/commands/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/commands/__init__.py
diff --git a/src/debputy/commands/deb_materialization.py b/src/debputy/commands/deb_materialization.py
new file mode 100644
index 0000000..58764d0
--- /dev/null
+++ b/src/debputy/commands/deb_materialization.py
@@ -0,0 +1,587 @@
+#!/usr/bin/python3 -B
+import argparse
+import collections
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import textwrap
+from datetime import datetime
+from typing import Optional, List, Iterator, Dict, Tuple
+
+from debputy import DEBPUTY_ROOT_DIR
+from debputy.intermediate_manifest import (
+    TarMember,
+    PathType,
+    output_intermediate_manifest,
+    output_intermediate_manifest_to_fd,
+)
+from debputy.util import (
+    _error,
+    _info,
+    compute_output_filename,
+    resolve_source_date_epoch,
+    ColorizedArgumentParser,
+    setup_logging,
+    detect_fakeroot,
+    print_command,
+    program_name,
+)
+from debputy.version import __version__
+
+
+def parse_args() -> argparse.Namespace:
+    description = textwrap.dedent(
+        """\
+    This is a low level tool for materializing deb packages from intermediate debputy manifests or assembling
+    the deb from a materialization.
+
+    The tool is not intended to be run directly by end users.
+    """
+    )
+
+    parser = ColorizedArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+        prog=program_name(),
+    )
+
+    parser.add_argument("--version", action="version", version=__version__)
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    materialize_deb_parser = subparsers.add_parser(
+        "materialize-deb",
+        allow_abbrev=False,
+        help="Generate .deb/.udebs structure from a root directory and"
+        " a *intermediate* debputy manifest",
+    )
+    materialize_deb_parser.add_argument(
+        "control_root_dir",
+        metavar="control-root-dir",
+        help="A directory that contains the control files (usually debian/<pkg>/DEBIAN)",
+    )
+    materialize_deb_parser.add_argument(
+        "materialization_output",
+        metavar="materialization_output",
+        help="Where to place the resulting structure should be placed. Should not exist",
+    )
+    materialize_deb_parser.add_argument(
+        "--discard-existing-output",
+        dest="discard_existing_output",
+        default=False,
+        action="store_true",
+        help="If passed, then the output location may exist."
+        " If it does, it will be *deleted*.",
+    )
+    materialize_deb_parser.add_argument(
+        "--source-date-epoch",
+        dest="source_date_epoch",
+        action="store",
+        type=int,
+        default=None,
+        help="Source date epoch (can also be given via the SOURCE_DATE_EPOCH environ"
+        " variable",
+    )
+    materialize_deb_parser.add_argument(
+        "--may-move-control-files",
+        dest="may_move_control_files",
+        action="store_true",
+        default=False,
+        help="Whether the command may optimize by moving (rather than copying) DEBIAN files",
+    )
+    materialize_deb_parser.add_argument(
+        "--may-move-data-files",
+        dest="may_move_data_files",
+        action="store_true",
+        default=False,
+        help="Whether the command may optimize by moving (rather than copying) when materializing",
+    )
+
+    materialize_deb_parser.add_argument(
+        "--intermediate-package-manifest",
+        dest="package_manifest",
+        metavar="JSON_FILE",
+        action="store",
+        default=None,
+        help="INTERMEDIATE package manifest (JSON!)",
+    )
+
+    materialize_deb_parser.add_argument(
+        "--udeb",
+        dest="udeb",
+        default=False,
+        action="store_true",
+        help="Whether this is udeb package.  Affects extension and default compression",
+    )
+
+    materialize_deb_parser.add_argument(
+        "--build-method",
+        dest="build_method",
+        choices=["debputy", "dpkg-deb"],
+        type=str,
+        default=None,
+        help="Immediately assemble the deb as well using the selected method",
+    )
+    materialize_deb_parser.add_argument(
+        "--assembled-deb-output",
+        dest="assembled_deb_output",
+        type=str,
+        default=None,
+        help="Where to place the resulting deb. Only applicable with --build-method",
+    )
+
+    # Added for "help only" - you cannot trigger this option in practice
+    materialize_deb_parser.add_argument(
+        "--",
+        metavar="DPKG_DEB_ARGS",
+        action="extend",
+        nargs="+",
+        dest="unused",
+        help="Arguments to be passed to dpkg-deb"
+        " (same as you might pass to dh_builddeb).",
+    )
+
+    build_deb_structure = subparsers.add_parser(
+        "build-materialized-deb",
+        allow_abbrev=False,
+        help="Produce a .deb from a directory produced by the"
+        " materialize-deb-structure command",
+    )
+    build_deb_structure.add_argument(
+        "materialized_deb_root_dir",
+        metavar="materialized-deb-root-dir",
+        help="The output directory of the materialize-deb-structure command",
+    )
+    build_deb_structure.add_argument(
+        "build_method",
+        metavar="build-method",
+        choices=["debputy", "dpkg-deb"],
+        type=str,
+        default="dpkg-deb",
+        help="Which tool should assemble the deb",
+    )
+    build_deb_structure.add_argument(
+        "--output", type=str, default=None, help="Where to place the resulting deb"
+    )
+
+    argv = sys.argv
+    try:
+        i = argv.index("--")
+        upstream_args = argv[i + 1 :]
+        argv = argv[:i]
+    except (IndexError, ValueError):
+        upstream_args = []
+    parsed_args = parser.parse_args(argv[1:])
+    setattr(parsed_args, "upstream_args", upstream_args)
+
+    return parsed_args
+
+
+def _run(cmd: List[str]) -> None:
+    print_command(*cmd)
+    subprocess.check_call(cmd)
+
+
+def strip_path_prefix(member_path: str) -> str:
+    if not member_path.startswith("./"):
+        _error(
+            f'Invalid manifest: "{member_path}" does not start with "./", but all paths should'
+        )
+    return member_path[2:]
+
+
+def _perform_data_tar_materialization(
+    output_packaging_root: str,
+    intermediate_manifest: List[TarMember],
+    may_move_data_files: bool,
+) -> List[Tuple[str, TarMember]]:
+    start_time = datetime.now()
+    replacement_manifest_paths = []
+    _info("Materializing data.tar part of the deb:")
+
+    directories = ["mkdir"]
+    symlinks = []
+    bulk_copies: Dict[str, List[str]] = collections.defaultdict(list)
+    copies = []
+    renames = []
+
+    for tar_member in intermediate_manifest:
+        member_path = strip_path_prefix(tar_member.member_path)
+        new_fs_path = (
+            os.path.join("deb-root", member_path) if member_path else "deb-root"
+        )
+        materialization_path = (
+            f"{output_packaging_root}/{member_path}"
+            if member_path
+            else output_packaging_root
+        )
+        replacement_tar_member = tar_member
+        materialization_parent_dir = os.path.dirname(materialization_path.rstrip("/"))
+        if tar_member.path_type == PathType.DIRECTORY:
+            directories.append(materialization_path)
+        elif tar_member.path_type == PathType.SYMLINK:
+            symlinks.append((tar_member.link_target, materialization_path))
+        elif tar_member.fs_path is not None:
+            if tar_member.link_target:
+                # Not sure if hardlinks gets here yet as we do not support hardlinks
+                _error("Internal error; hardlink not supported")
+
+            if may_move_data_files and tar_member.may_steal_fs_path:
+                renames.append((tar_member.fs_path, materialization_path))
+            elif os.path.basename(tar_member.fs_path) == os.path.basename(
+                materialization_path
+            ):
+                bulk_copies[materialization_parent_dir].append(tar_member.fs_path)
+            else:
+                copies.append((tar_member.fs_path, materialization_path))
+        else:
+            _error(f"Internal error; unsupported path type {tar_member.path_type}")
+
+        if tar_member.fs_path is not None:
+            replacement_tar_member = tar_member.clone_and_replace(
+                fs_path=new_fs_path, may_steal_fs_path=False
+            )
+
+        replacement_manifest_paths.append(
+            (materialization_path, replacement_tar_member)
+        )
+
+    if len(directories) > 1:
+        _run(directories)
+
+    for dest_dir, files in bulk_copies.items():
+        cmd = ["cp", "--reflink=auto", "-t", dest_dir]
+        cmd.extend(files)
+        _run(cmd)
+
+    for source, dest in copies:
+        _run(["cp", "--reflink=auto", source, dest])
+
+    for source, dest in renames:
+        print_command("mv", source, dest)
+        os.rename(source, dest)
+
+    for link_target, link_path in symlinks:
+        print_command("ln", "-s", link_target, link_path)
+        os.symlink(link_target, link_path)
+
+    end_time = datetime.now()
+
+    _info(f"Materialization of data.tar finished, took: {end_time - start_time}")
+
+    return replacement_manifest_paths
+
+
+def materialize_deb(
+    control_root_dir: str,
+    intermediate_manifest_path: Optional[str],
+    source_date_epoch: int,
+    dpkg_deb_options: List[str],
+    is_udeb: bool,
+    output_dir: str,
+    may_move_control_files: bool,
+    may_move_data_files: bool,
+) -> None:
+    if not os.path.isfile(f"{control_root_dir}/control"):
+        _error(
+            f'The directory "{control_root_dir}" does not look like a package root dir (there is no control file)'
+        )
+    intermediate_manifest: List[TarMember] = parse_manifest(intermediate_manifest_path)
+
+    output_packaging_root = os.path.join(output_dir, "deb-root")
+    os.mkdir(output_dir)
+
+    replacement_manifest_paths = _perform_data_tar_materialization(
+        output_packaging_root, intermediate_manifest, may_move_data_files
+    )
+    for materialization_path, tar_member in reversed(replacement_manifest_paths):
+        # TODO: Hardlinks should probably skip these commands
+        if tar_member.path_type != PathType.SYMLINK:
+            os.chmod(materialization_path, tar_member.mode, follow_symlinks=False)
+        os.utime(
+            materialization_path,
+            (tar_member.mtime, tar_member.mtime),
+            follow_symlinks=False,
+        )
+
+    materialized_ctrl_dir = f"{output_packaging_root}/DEBIAN"
+    if may_move_control_files:
+        print_command("mv", control_root_dir, materialized_ctrl_dir)
+        os.rename(control_root_dir, materialized_ctrl_dir)
+    else:
+        os.mkdir(materialized_ctrl_dir)
+        copy_cmd = ["cp", "-a"]
+        copy_cmd.extend(
+            os.path.join(control_root_dir, f) for f in os.listdir(control_root_dir)
+        )
+        copy_cmd.append(materialized_ctrl_dir)
+        _run(copy_cmd)
+
+    output_intermediate_manifest(
+        os.path.join(output_dir, "deb-structure-intermediate-manifest.json"),
+        [t[1] for t in replacement_manifest_paths],
+    )
+
+    with open(os.path.join(output_dir, "env-and-cli.json"), "w") as fd:
+        serial_format = {
+            "env": {
+                "SOURCE_DATE_EPOCH": str(source_date_epoch),
+                "DPKG_DEB_COMPRESSOR_LEVEL": os.environ.get(
+                    "DPKG_DEB_COMPRESSOR_LEVEL"
+                ),
+                "DPKG_DEB_COMPRESSOR_TYPE": os.environ.get("DPKG_DEB_COMPRESSOR_TYPE"),
+                "DPKG_DEB_THREADS_MAX": os.environ.get("DPKG_DEB_THREADS_MAX"),
+            },
+            "cli": {"dpkg-deb": dpkg_deb_options},
+            "udeb": is_udeb,
+        }
+        json.dump(serial_format, fd)
+
+
+def apply_fs_metadata(
+    materialized_path: str,
+    tar_member: TarMember,
+    apply_ownership: bool,
+    is_using_fakeroot: bool,
+) -> None:
+    if apply_ownership:
+        os.chown(
+            materialized_path, tar_member.uid, tar_member.gid, follow_symlinks=False
+        )
+    # To avoid surprises, align these with the manifest. Just in case the transport did not preserve the metadata.
+    # Also, unsure whether metadata changes cause directory mtimes to change, so resetting them unconditionally
+    # also prevents that problem.
+    if tar_member.path_type != PathType.SYMLINK:
+        os.chmod(materialized_path, tar_member.mode, follow_symlinks=False)
+    os.utime(
+        materialized_path, (tar_member.mtime, tar_member.mtime), follow_symlinks=False
+    )
+    if is_using_fakeroot:
+        st = os.stat(materialized_path, follow_symlinks=False)
+        if st.st_uid != tar_member.uid or st.st_gid != tar_member.gid:
+            _error(
+                'Change of ownership failed. The chown call "succeeded" but stat does not give the right result.'
+                " Most likely a fakeroot bug. Note, when verifying this, use os.chown + os.stat from python"
+                " (the chmod/stat shell commands might use a different syscall that fakeroot accurately emulates)"
+            )
+
+
+def _dpkg_deb_root_requirements(
+    intermediate_manifest: List[TarMember],
+) -> Tuple[List[str], bool, bool]:
+    needs_root = any(tm.uid != 0 or tm.gid != 0 for tm in intermediate_manifest)
+    if needs_root:
+        if os.getuid() != 0:
+            _error(
+                'Must be run as root/fakeroot when using the method "dpkg-deb" due to the contents'
+            )
+        is_using_fakeroot = detect_fakeroot()
+        deb_cmd = ["dpkg-deb"]
+        _info("Applying ownership, mode, and utime from the intermediate manifest...")
+    else:
+        # fakeroot does not matter in this case
+        is_using_fakeroot = False
+        deb_cmd = ["dpkg-deb", "--root-owner-group"]
+        _info("Applying mode and utime from the intermediate manifest...")
+    return deb_cmd, needs_root, is_using_fakeroot
+
+
+@contextlib.contextmanager
+def maybe_with_materialized_manifest(
+    content: Optional[List[TarMember]],
+) -> Iterator[Optional[str]]:
+    if content is not None:
+        with tempfile.NamedTemporaryFile(
+            prefix="debputy-mat-build",
+            mode="w+t",
+            suffix=".json",
+            encoding="utf-8",
+        ) as fd:
+            output_intermediate_manifest_to_fd(fd, content)
+            fd.flush()
+            yield fd.name
+    else:
+        yield None
+
+
+def _prep_assembled_deb_output_path(
+    output_path: Optional[str],
+    materialized_deb_structure: str,
+    deb_root: str,
+    method: str,
+    is_udeb: bool,
+) -> str:
+    if output_path is None:
+        ext = "udeb" if is_udeb else "deb"
+        output_dir = os.path.join(materialized_deb_structure, "output")
+        if not os.path.isdir(output_dir):
+            os.mkdir(output_dir)
+        output = os.path.join(output_dir, f"{method}.{ext}")
+    elif os.path.isdir(output_path):
+        output = os.path.join(
+            output_path,
+            compute_output_filename(os.path.join(deb_root, "DEBIAN"), is_udeb),
+        )
+    else:
+        output = output_path
+    return output
+
+
+def _apply_env(env: Dict[str, Optional[str]]) -> None:
+    for name, value in env.items():
+        if value is not None:
+            os.environ[name] = value
+        else:
+            try:
+                del os.environ[name]
+            except KeyError:
+                pass
+
+
+def assemble_deb(
+    materialized_deb_structure: str,
+    method: str,
+    output_path: Optional[str],
+    combined_materialization_and_assembly: bool,
+) -> None:
+    deb_root = os.path.join(materialized_deb_structure, "deb-root")
+
+    with open(os.path.join(materialized_deb_structure, "env-and-cli.json"), "r") as fd:
+        serial_format = json.load(fd)
+
+    env = serial_format.get("env") or {}
+    cli = serial_format.get("cli") or {}
+    is_udeb = serial_format.get("udeb")
+    source_date_epoch = env.get("SOURCE_DATE_EPOCH")
+    dpkg_deb_options = cli.get("dpkg-deb") or []
+    intermediate_manifest_path = os.path.join(
+        materialized_deb_structure, "deb-structure-intermediate-manifest.json"
+    )
+    original_intermediate_manifest = TarMember.parse_intermediate_manifest(
+        intermediate_manifest_path
+    )
+    _info(
+        "Rebasing relative paths in the intermediate manifest so they are relative to current working directory ..."
+    )
+    intermediate_manifest = [
+        (
+            tar_member.clone_and_replace(
+                fs_path=os.path.join(materialized_deb_structure, tar_member.fs_path)
+            )
+            if tar_member.fs_path is not None and not tar_member.fs_path.startswith("/")
+            else tar_member
+        )
+        for tar_member in original_intermediate_manifest
+    ]
+    materialized_manifest = None
+    if method == "debputy":
+        materialized_manifest = intermediate_manifest
+
+    if source_date_epoch is None:
+        _error(
+            "Cannot reproduce the deb. No source date epoch provided in the materialized deb root."
+        )
+    _apply_env(env)
+
+    output = _prep_assembled_deb_output_path(
+        output_path,
+        materialized_deb_structure,
+        deb_root,
+        method,
+        is_udeb,
+    )
+
+    with maybe_with_materialized_manifest(materialized_manifest) as tmp_file:
+        if method == "dpkg-deb":
+            deb_cmd, needs_root, is_using_fakeroot = _dpkg_deb_root_requirements(
+                intermediate_manifest
+            )
+            if needs_root or not combined_materialization_and_assembly:
+                for tar_member in reversed(intermediate_manifest):
+                    p = os.path.join(
+                        deb_root, strip_path_prefix(tar_member.member_path)
+                    )
+                    apply_fs_metadata(p, tar_member, needs_root, is_using_fakeroot)
+        elif method == "debputy":
+            deb_packer = os.path.join(DEBPUTY_ROOT_DIR, "deb_packer.py")
+            assert tmp_file is not None
+            deb_cmd = [
+                deb_packer,
+                "--intermediate-package-manifest",
+                tmp_file,
+                "--source-date-epoch",
+                source_date_epoch,
+            ]
+        else:
+            _error(f"Internal error: Unsupported assembly method: {method}")
+
+        if is_udeb:
+            deb_cmd.extend(["-z6", "-Zxz", "-Sextreme"])
+        deb_cmd.extend(dpkg_deb_options)
+        deb_cmd.extend(["--build", deb_root, output])
+        start_time = datetime.now()
+        _run(deb_cmd)
+        end_time = datetime.now()
+        _info(f"  - assembly command took {end_time - start_time}")
+
+
+def parse_manifest(manifest_path: "Optional[str]") -> "List[TarMember]":
+    if manifest_path is None:
+        _error("--intermediate-package-manifest is mandatory for now")
+    return TarMember.parse_intermediate_manifest(manifest_path)
+
+
+def main() -> None:
+    setup_logging()
+    parsed_args = parse_args()
+    if parsed_args.command == "materialize-deb":
+        mtime = resolve_source_date_epoch(parsed_args.source_date_epoch)
+        dpkg_deb_args = parsed_args.upstream_args or []
+        output_dir = parsed_args.materialization_output
+        if os.path.exists(output_dir):
+            if not parsed_args.discard_existing_output:
+                _error(
+                    "The output path already exists. Please either choose a non-existing path, delete the path"
+                    " or use --discard-existing-output (to have this command remove it as necessary)."
+                )
+            _info(
+                f'Removing existing path "{output_dir}" as requested by --discard-existing-output'
+            )
+            _run(["rm", "-fr", output_dir])
+
+        materialize_deb(
+            parsed_args.control_root_dir,
+            parsed_args.package_manifest,
+            mtime,
+            dpkg_deb_args,
+            parsed_args.udeb,
+            output_dir,
+            parsed_args.may_move_control_files,
+            parsed_args.may_move_data_files,
+        )
+
+        if parsed_args.build_method is not None:
+            assemble_deb(
+                output_dir,
+                parsed_args.build_method,
+                parsed_args.assembled_deb_output,
+                True,
+            )
+
+    elif parsed_args.command == "build-materialized-deb":
+        assemble_deb(
+            parsed_args.materialized_deb_root_dir,
+            parsed_args.build_method,
+            parsed_args.output,
+            False,
+        )
+    else:
+        _error(f'Internal error: Unimplemented command "{parsed_args.command}"')
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/debputy/commands/deb_packer.py b/src/debputy/commands/deb_packer.py
new file mode 100644
index 0000000..8c61099
--- /dev/null
+++ b/src/debputy/commands/deb_packer.py
@@ -0,0 +1,557 @@
+#!/usr/bin/python3 -B
+import argparse
+import errno
+import operator
+import os
+import stat
+import subprocess
+import tarfile
+import textwrap
+from typing import Optional, List, FrozenSet, Iterable, Callable, BinaryIO, cast
+
+from debputy.intermediate_manifest import TarMember, PathType
+from debputy.util import (
+    _error,
+    compute_output_filename,
+    resolve_source_date_epoch,
+    ColorizedArgumentParser,
+    setup_logging,
+    program_name,
+    assume_not_none,
+)
+from debputy.version import __version__
+
+
+# AR header / start of a deb file for reference
+# 00000000  21 3c 61 72 63 68 3e 0a  64 65 62 69 61 6e 2d 62  |!<arch>.debian-b|
+# 00000010  69 6e 61 72 79 20 20 20  31 36 36 38 39 37 33 36  |inary   16689736|
+# 00000020  39 35 20 20 30 20 20 20  20 20 30 20 20 20 20 20  |95  0     0     |
+# 00000030  31 30 30 36 34 34 20 20  34 20 20 20 20 20 20 20  |100644  4       |
+# 00000040  20 20 60 0a 32 2e 30 0a  63 6f 6e 74 72 6f 6c 2e  |  `.2.0.control.|
+# 00000050  74 61 72 2e 78 7a 20 20  31 36 36 38 39 37 33 36  |tar.xz  16689736|
+# 00000060  39 35 20 20 30 20 20 20  20 20 30 20 20 20 20 20  |95  0     0     |
+# 00000070  31 30 30 36 34 34 20 20  39 33 36 38 20 20 20 20  |100644  9368    |
+# 00000080  20 20 60 0a fd 37 7a 58  5a 00 00 04 e6 d6 b4 46  |  `..7zXZ......F|
+
+
+class ArMember:
+    def __init__(
+        self,
+        name: str,
+        mtime: int,
+        fixed_binary: Optional[bytes] = None,
+        write_to_impl: Optional[Callable[[BinaryIO], None]] = None,
+    ) -> None:
+        self.name = name
+        self._mtime = mtime
+        self._write_to_impl = write_to_impl
+        self.fixed_binary = fixed_binary
+
+    @property
+    def is_fixed_binary(self) -> bool:
+        return self.fixed_binary is not None
+
+    @property
+    def mtime(self) -> int:
+        return self.mtime
+
+    def write_to(self, fd: BinaryIO) -> None:
+        writer = self._write_to_impl
+        assert writer is not None
+        writer(fd)
+
+
+AR_HEADER_LEN = 60
+AR_HEADER = b" " * AR_HEADER_LEN
+
+
+def write_header(
+    fd: BinaryIO,
+    member: ArMember,
+    member_len: int,
+    mtime: int,
+) -> None:
+    header = b"%-16s%-12d0     0     100644  %-10d\x60\n" % (
+        member.name.encode("ascii"),
+        mtime,
+        member_len,
+    )
+    fd.write(header)
+
+
+def generate_ar_archive(
+    output_filename: str,
+    mtime: int,
+    members: Iterable[ArMember],
+    prefer_raw_exceptions: bool,
+) -> None:
+    try:
+        with open(output_filename, "wb", buffering=0) as fd:
+            fd.write(b"!<arch>\n")
+            for member in members:
+                if member.is_fixed_binary:
+                    fixed_binary = assume_not_none(member.fixed_binary)
+                    write_header(fd, member, len(fixed_binary), mtime)
+                    fd.write(fixed_binary)
+                else:
+                    header_pos = fd.tell()
+                    fd.write(AR_HEADER)
+                    member.write_to(fd)
+                    current_pos = fd.tell()
+                    fd.seek(header_pos, os.SEEK_SET)
+                    content_len = current_pos - header_pos - AR_HEADER_LEN
+                    assert content_len >= 0
+                    write_header(fd, member, content_len, mtime)
+                    fd.seek(current_pos, os.SEEK_SET)
+    except OSError as e:
+        if prefer_raw_exceptions:
+            raise
+        if e.errno == errno.ENOSPC:
+            _error(
+                f"Unable to write {output_filename}.  The file system device reported disk full: {str(e)}"
+            )
+        elif e.errno == errno.EIO:
+            _error(
+                f"Unable to write {output_filename}.  The file system reported a generic I/O error: {str(e)}"
+            )
+        elif e.errno == errno.EROFS:
+            _error(
+                f"Unable to write {output_filename}.  The file system is read-only: {str(e)}"
+            )
+        raise
+    print(f"Generated {output_filename}")
+
+
+def _generate_tar_file(
+    tar_members: Iterable[TarMember],
+    compression_cmd: List[str],
+    write_to: BinaryIO,
+) -> None:
+    with (
+        subprocess.Popen(
+            compression_cmd, stdin=subprocess.PIPE, stdout=write_to
+        ) as compress_proc,
+        tarfile.open(
+            mode="w|",
+            fileobj=compress_proc.stdin,
+            format=tarfile.GNU_FORMAT,
+            errorlevel=1,
+        ) as tar_fd,
+    ):
+        for tar_member in tar_members:
+            tar_info: tarfile.TarInfo = tar_member.create_tar_info(tar_fd)
+            if tar_member.path_type == PathType.FILE:
+                with open(assume_not_none(tar_member.fs_path), "rb") as mfd:
+                    tar_fd.addfile(tar_info, fileobj=mfd)
+            else:
+                tar_fd.addfile(tar_info)
+    compress_proc.wait()
+    if compress_proc.returncode != 0:
+        _error(
+            f"Compression command {compression_cmd} failed with code {compress_proc.returncode}"
+        )
+
+
+def generate_tar_file_member(
+    tar_members: Iterable[TarMember],
+    compression_cmd: List[str],
+) -> Callable[[BinaryIO], None]:
+    def _impl(fd: BinaryIO) -> None:
+        _generate_tar_file(
+            tar_members,
+            compression_cmd,
+            fd,
+        )
+
+    return _impl
+
+
+def _xz_cmdline(
+    compression_rule: "Compression",
+    parsed_args: Optional[argparse.Namespace],
+) -> List[str]:
+    compression_level = compression_rule.effective_compression_level(parsed_args)
+    cmdline = ["xz", "-T2", "-" + str(compression_level)]
+    strategy = None if parsed_args is None else parsed_args.compression_strategy
+    if strategy is None:
+        strategy = "none"
+    if strategy != "none":
+        cmdline.append("--" + strategy)
+    cmdline.append("--no-adjust")
+    return cmdline
+
+
+def _gzip_cmdline(
+    compression_rule: "Compression",
+    parsed_args: Optional[argparse.Namespace],
+) -> List[str]:
+    compression_level = compression_rule.effective_compression_level(parsed_args)
+    cmdline = ["gzip", "-n" + str(compression_level)]
+    strategy = None if parsed_args is None else parsed_args.compression_strategy
+    if strategy is not None and strategy != "none":
+        raise ValueError(
+            f"Not implemented: Compression strategy {strategy}"
+            " for gzip is currently unsupported (but dpkg-deb does)"
+        )
+    return cmdline
+
+
+def _uncompressed_cmdline(
+    _unused_a: "Compression",
+    _unused_b: Optional[argparse.Namespace],
+) -> List[str]:
+    return ["cat"]
+
+
+class Compression:
+    def __init__(
+        self,
+        default_compression_level: int,
+        extension: str,
+        allowed_strategies: FrozenSet[str],
+        cmdline_builder: Callable[
+            ["Compression", Optional[argparse.Namespace]], List[str]
+        ],
+    ) -> None:
+        self.default_compression_level = default_compression_level
+        self.extension = extension
+        self.allowed_strategies = allowed_strategies
+        self.cmdline_builder = cmdline_builder
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} {self.extension}>"
+
+    def effective_compression_level(
+        self, parsed_args: Optional[argparse.Namespace]
+    ) -> int:
+        if parsed_args and parsed_args.compression_level is not None:
+            return cast("int", parsed_args.compression_level)
+        return self.default_compression_level
+
+    def as_cmdline(self, parsed_args: Optional[argparse.Namespace]) -> List[str]:
+        return self.cmdline_builder(self, parsed_args)
+
+    def with_extension(self, filename: str) -> str:
+        return filename + self.extension
+
+
+COMPRESSIONS = {
+    "xz": Compression(6, ".xz", frozenset({"none", "extreme"}), _xz_cmdline),
+    "gzip": Compression(
+        9,
+        ".gz",
+        frozenset({"none", "filtered", "huffman", "rle", "fixed"}),
+        _gzip_cmdline,
+    ),
+    "none": Compression(0, "", frozenset({"none"}), _uncompressed_cmdline),
+}
+
+
+def _normalize_compression_args(parsed_args: argparse.Namespace) -> argparse.Namespace:
+    if (
+        parsed_args.compression_level == 0
+        and parsed_args.compression_algorithm == "gzip"
+    ):
+        print(
+            "Note: Mapping compression algorithm to none for compatibility with dpkg-deb (due to -Zgzip -z0)"
+        )
+        setattr(parsed_args, "compression_algorithm", "none")
+
+    compression = COMPRESSIONS[parsed_args.compression_algorithm]
+    strategy = parsed_args.compression_strategy
+    if strategy is not None and strategy not in compression.allowed_strategies:
+        _error(
+            f'Compression algorithm "{parsed_args.compression_algorithm}" does not support compression strategy'
+            f' "{strategy}".  Allowed values: {", ".join(sorted(compression.allowed_strategies))}'
+        )
+    return parsed_args
+
+
+def parse_args() -> argparse.Namespace:
+    try:
+        compression_level_default = int(os.environ["DPKG_DEB_COMPRESSOR_LEVEL"])
+    except (KeyError, ValueError):
+        compression_level_default = None
+
+    try:
+        compression_type = os.environ["DPKG_DEB_COMPRESSOR_TYPE"]
+    except (KeyError, ValueError):
+        compression_type = "xz"
+
+    try:
+        threads_max = int(os.environ["DPKG_DEB_THREADS_MAX"])
+    except (KeyError, ValueError):
+        threads_max = None
+
+    description = textwrap.dedent(
+        """\
+    THIS IS A PROTOTYPE "dpkg-deb -b" emulator with basic manifest support
+
+    DO NOT USE THIS TOOL DIRECTLY.  It has not stability guarantees and will be removed as
+    soon as "dpkg-deb -b" grows support for the relevant features. 
+
+    This tool is a prototype "dpkg-deb -b"-like interface for compiling a Debian package
+    without requiring root even for static ownership.  It is a temporary stand-in for
+    "dpkg-deb -b" until "dpkg-deb -b" will get support for a manifest.
+
+    The tool operates on an internal JSON based manifest for now, because it was faster
+    than building an mtree parser (which is the format that dpkg will likely end up
+    using).
+    
+    As the tool is not meant to be used directly, it is full of annoying paper cuts that
+    I refuse to fix or maintain. Use the high level tool instead.
+
+    """
+    )
+
+    parser = ColorizedArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+        prog=program_name(),
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "package_root_dir",
+        metavar="PACKAGE_ROOT_DIR",
+        help="Root directory of the package. Must contain a DEBIAN directory",
+    )
+    parser.add_argument(
+        "package_output_path",
+        metavar="PATH",
+        help="Path where the package should be placed.  If it is directory,"
+        " the base name will be determined from the package metadata",
+    )
+
+    parser.add_argument(
+        "--intermediate-package-manifest",
+        dest="package_manifest",
+        metavar="JSON_FILE",
+        action="store",
+        default=None,
+        help="INTERMEDIATE package manifest (JSON!)",
+    )
+    parser.add_argument(
+        "--root-owner-group",
+        dest="root_owner_group",
+        action="store_true",
+        help="Ignored. Accepted for compatibility with dpkg-deb -b",
+    )
+    parser.add_argument(
+        "-b",
+        "--build",
+        dest="build_param",
+        action="store_true",
+        help="Ignored. Accepted for compatibility with dpkg-deb",
+    )
+    parser.add_argument(
+        "--source-date-epoch",
+        dest="source_date_epoch",
+        action="store",
+        type=int,
+        default=None,
+        help="Source date epoch (can also be given via the SOURCE_DATE_EPOCH environ variable",
+    )
+    parser.add_argument(
+        "-Z",
+        dest="compression_algorithm",
+        choices=COMPRESSIONS,
+        default=compression_type,
+        help="The compression algorithm to be used",
+    )
+    parser.add_argument(
+        "-z",
+        dest="compression_level",
+        metavar="{0-9}",
+        choices=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+        default=compression_level_default,
+        type=int,
+        help="The compression level to be used",
+    )
+    parser.add_argument(
+        "-S",
+        dest="compression_strategy",
+        # We have a different default for xz when strategy is unset and we are building a udeb
+        action="store",
+        default=None,
+        help="The compression algorithm to be used. Concrete values depend on the compression"
+        ' algorithm, but the value "none" is always allowed',
+    )
+    parser.add_argument(
+        "--uniform-compression",
+        dest="uniform_compression",
+        action="store_true",
+        default=True,
+        help="Whether to use the same compression for the control.tar and the data.tar."
+        " The default is to use uniform compression.",
+    )
+    parser.add_argument(
+        "--no-uniform-compression",
+        dest="uniform_compression",
+        action="store_false",
+        default=True,
+        help="Disable uniform compression (see --uniform-compression)",
+    )
+    parser.add_argument(
+        "--threads-max",
+        dest="threads_max",
+        default=threads_max,
+        # TODO: Support this properly
+        type=int,
+        help="Ignored; accepted for compatibility",
+    )
+    parser.add_argument(
+        "-d",
+        "--debug",
+        dest="debug_mode",
+        action="store_true",
+        default=False,
+        help="Enable debug logging and raw stack traces on errors",
+    )
+
+    parsed_args = parser.parse_args()
+    parsed_args = _normalize_compression_args(parsed_args)
+
+    return parsed_args
+
+
+def _ctrl_member(
+    member_path: str,
+    fs_path: Optional[str] = None,
+    path_type: PathType = PathType.FILE,
+    mode: int = 0o644,
+    mtime: int = 0,
+) -> TarMember:
+    if fs_path is None:
+        assert member_path.startswith("./")
+        fs_path = "DEBIAN" + member_path[1:]
+    return TarMember(
+        member_path=member_path,
+        path_type=path_type,
+        fs_path=fs_path,
+        mode=mode,
+        owner="root",
+        uid=0,
+        group="root",
+        gid=0,
+        mtime=mtime,
+    )
+
+
+CTRL_MEMBER_SCRIPTS = {
+    "postinst",
+    "preinst",
+    "postrm",
+    "prerm",
+    "config",
+    "isinstallable",
+}
+
+
+def _ctrl_tar_members(package_root_dir: str, mtime: int) -> Iterable[TarMember]:
+    debian_root = os.path.join(package_root_dir, "DEBIAN")
+    dir_st = os.stat(debian_root)
+    dir_mtime = int(dir_st.st_mtime)
+    yield _ctrl_member(
+        "./",
+        debian_root,
+        path_type=PathType.DIRECTORY,
+        mode=0o0755,
+        mtime=min(mtime, dir_mtime),
+    )
+    with os.scandir(debian_root) as dir_iter:
+        for ctrl_member in sorted(dir_iter, key=operator.attrgetter("name")):
+            st = os.stat(ctrl_member)
+            if not stat.S_ISREG(st.st_mode):
+                _error(
+                    f"{ctrl_member.path} is not a file and all control.tar members ought to be files!"
+                )
+            file_mtime = int(st.st_mtime)
+            yield _ctrl_member(
+                f"./{ctrl_member.name}",
+                path_type=PathType.FILE,
+                fs_path=ctrl_member.path,
+                mode=0o0755 if ctrl_member.name in CTRL_MEMBER_SCRIPTS else 0o0644,
+                mtime=min(mtime, file_mtime),
+            )
+
+
+def parse_manifest(manifest_path: "Optional[str]") -> "List[TarMember]":
+    if manifest_path is None:
+        _error(f"--intermediate-package-manifest is mandatory for now")
+    return TarMember.parse_intermediate_manifest(manifest_path)
+
+
+def main() -> None:
+    setup_logging()
+    parsed_args = parse_args()
+    root_dir: str = parsed_args.package_root_dir
+    output_path: str = parsed_args.package_output_path
+    mtime = resolve_source_date_epoch(parsed_args.source_date_epoch)
+
+    data_compression: Compression = COMPRESSIONS[parsed_args.compression_algorithm]
+    data_compression_cmd = data_compression.as_cmdline(parsed_args)
+    if parsed_args.uniform_compression:
+        ctrl_compression = data_compression
+        ctrl_compression_cmd = data_compression_cmd
+    else:
+        ctrl_compression = COMPRESSIONS["gzip"]
+        ctrl_compression_cmd = COMPRESSIONS["gzip"].as_cmdline(None)
+
+    if output_path.endswith("/") or os.path.isdir(output_path):
+        deb_file = os.path.join(
+            output_path,
+            compute_output_filename(os.path.join(root_dir, "DEBIAN"), False),
+        )
+    else:
+        deb_file = output_path
+
+    pack(
+        deb_file,
+        ctrl_compression,
+        data_compression,
+        root_dir,
+        parsed_args.package_manifest,
+        mtime,
+        ctrl_compression_cmd,
+        data_compression_cmd,
+        prefer_raw_exceptions=not parsed_args.debug_mode,
+    )
+
+
+def pack(
+    deb_file: str,
+    ctrl_compression: Compression,
+    data_compression: Compression,
+    root_dir: str,
+    package_manifest: "Optional[str]",
+    mtime: int,
+    ctrl_compression_cmd: List[str],
+    data_compression_cmd: List[str],
+    prefer_raw_exceptions: bool = False,
+) -> None:
+    data_tar_members = parse_manifest(package_manifest)
+    members = [
+        ArMember("debian-binary", mtime, fixed_binary=b"2.0\n"),
+        ArMember(
+            ctrl_compression.with_extension("control.tar"),
+            mtime,
+            write_to_impl=generate_tar_file_member(
+                _ctrl_tar_members(root_dir, mtime),
+                ctrl_compression_cmd,
+            ),
+        ),
+        ArMember(
+            data_compression.with_extension("data.tar"),
+            mtime,
+            write_to_impl=generate_tar_file_member(
+                data_tar_members,
+                data_compression_cmd,
+            ),
+        ),
+    ]
+    generate_ar_archive(deb_file, mtime, members, prefer_raw_exceptions)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/debputy/commands/debputy_cmd/__init__.py b/src/debputy/commands/debputy_cmd/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/__init__.py
diff --git a/src/debputy/commands/debputy_cmd/__main__.py b/src/debputy/commands/debputy_cmd/__main__.py
new file mode 100644
index 0000000..d894731
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/__main__.py
@@ -0,0 +1,1576 @@
+#!/usr/bin/python3 -B
+import argparse
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import textwrap
+import traceback
+from tempfile import TemporaryDirectory
+from typing import (
+    List,
+    Dict,
+    Iterable,
+    Any,
+    Tuple,
+    Sequence,
+    Optional,
+    NoReturn,
+    Mapping,
+    Union,
+    NamedTuple,
+    Literal,
+    Set,
+    Iterator,
+    TypedDict,
+    NotRequired,
+    cast,
+)
+
+from debputy import DEBPUTY_ROOT_DIR, DEBPUTY_PLUGIN_ROOT_DIR
+from debputy.commands.debputy_cmd.context import (
+    CommandContext,
+    add_arg,
+    ROOT_COMMAND,
+    CommandArg,
+)
+from debputy.commands.debputy_cmd.dc_util import flatten_ppfs
+from debputy.commands.debputy_cmd.output import _stream_to_pager
+from debputy.dh_migration.migrators import MIGRATORS
+from debputy.exceptions import (
+    DebputyRuntimeError,
+    PluginNotFoundError,
+    PluginAPIViolationError,
+    PluginInitializationError,
+    UnhandledOrUnexpectedErrorFromPluginError,
+    SymlinkLoopError,
+)
+from debputy.package_build.assemble_deb import (
+    assemble_debs,
+)
+from debputy.packager_provided_files import (
+    detect_all_packager_provided_files,
+    PackagerProvidedFile,
+)
+from debputy.plugin.api.spec import (
+    VirtualPath,
+    packager_provided_file_reference_documentation,
+)
+
+try:
+    from argcomplete import autocomplete
+except ImportError:
+
+    def autocomplete(_parser: argparse.ArgumentParser) -> None:
+        pass
+
+
+from debputy.version import __version__
+from debputy.filesystem_scan import (
+    FSROOverlay,
+)
+from debputy.plugin.api.impl_types import (
+    PackagerProvidedFileClassSpec,
+    DebputyPluginMetadata,
+    PluginProvidedKnownPackagingFile,
+    KNOWN_PACKAGING_FILE_CATEGORY_DESCRIPTIONS,
+    KNOWN_PACKAGING_FILE_CONFIG_FEATURE_DESCRIPTION,
+    expand_known_packaging_config_features,
+    InstallPatternDHCompatRule,
+    KnownPackagingFileInfo,
+)
+from debputy.plugin.api.impl import (
+    find_json_plugin,
+    find_tests_for_plugin,
+    find_related_implementation_files_for_plugin,
+    parse_json_plugin_desc,
+    plugin_metadata_for_debputys_own_plugin,
+)
+from debputy.dh_migration.migration import migrate_from_dh
+from debputy.dh_migration.models import AcceptableMigrationIssues
+from debputy.packages import BinaryPackage
+from debputy.debhelper_emulation import (
+    dhe_pkgdir,
+    parse_drules_for_addons,
+    extract_dh_addons_from_control,
+)
+
+from debputy.deb_packaging_support import (
+    usr_local_transformation,
+    handle_perl_code,
+    detect_systemd_user_service_files,
+    fixup_debian_changelog_and_news_file,
+    install_upstream_changelog,
+    relocate_dwarves_into_dbgsym_packages,
+    run_package_processors,
+    cross_package_control_files,
+)
+from debputy.util import (
+    _error,
+    _warn,
+    ColorizedArgumentParser,
+    setup_logging,
+    _info,
+    escape_shell,
+    program_name,
+    integrated_with_debhelper,
+    assume_not_none,
+)
+
+REFERENCE_DATA_TABLE = {
+    "config-features": KNOWN_PACKAGING_FILE_CONFIG_FEATURE_DESCRIPTION,
+    "file-categories": KNOWN_PACKAGING_FILE_CATEGORY_DESCRIPTIONS,
+}
+
+
+class SharedArgument(NamedTuple):
+    """
+    Information about an argument shared between a parser and its subparsers
+    """
+
+    action: argparse.Action
+    args: Tuple[Any, ...]
+    kwargs: Dict[str, Any]
+
+
+class Namespace(argparse.Namespace):
+    """
+    Hacks around a namespace to allow merging of values set multiple times
+
+    Based on: https://www.enricozini.org/blog/2022/python/sharing-argparse-arguments-with-subcommands/
+    """
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        arg = self._shared_args.get(name)
+        if arg is not None:
+            action_type = arg.kwargs.get("action")
+            if action_type == "store_true":
+                # OR values
+                old = getattr(self, name, False)
+                super().__setattr__(name, old or value)
+            elif action_type == "store_false":
+                # AND values
+                old = getattr(self, name, True)
+                super().__setattr__(name, old and value)
+            elif action_type == "append":
+                old = getattr(self, name, None)
+                if old is None:
+                    old = []
+                    super().__setattr__(name, old)
+                if isinstance(value, list):
+                    old.extend(value)
+                elif value is not None:
+                    old.append(value)
+            elif action_type == "store":
+                old = getattr(self, name, None)
+                if old is None:
+                    super().__setattr__(name, value)
+                elif old != value and value is not None:
+                    raise argparse.ArgumentError(
+                        None,
+                        f"conflicting values provided for {arg.action.dest!r} ({old!r} and {value!r})",
+                    )
+            else:
+                raise NotImplementedError(
+                    f"Action {action_type!r} for {arg.action.dest!r} is not supported"
+                )
+        else:
+            return super().__setattr__(name, value)
+
+
+class DebputyArgumentParser(ColorizedArgumentParser):
+    """
+    Hacks around a standard ArgumentParser to allow to have a limited set of
+    options both outside and inside subcommands
+
+    Based on: https://www.enricozini.org/blog/2022/python/sharing-argparse-arguments-with-subcommands/
+    """
+
+    def __init__(self, *args: Any, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+
+        if not hasattr(self, "shared_args"):
+            self.shared_args: dict[str, SharedArgument] = {}
+
+        # Add arguments from the shared ones
+        for a in self.shared_args.values():
+            super().add_argument(*a.args, **a.kwargs)
+
+    def add_argument(self, *args: Any, **kw: Any) -> Any:
+        shared = kw.pop("shared", False)
+        res = super().add_argument(*args, **kw)
+        if shared:
+            action = kw.get("action")
+            if action not in ("store", "store_true", "store_false", "append"):
+                raise NotImplementedError(
+                    f"Action {action!r} for {args!r} is not supported"
+                )
+            # Take note of the argument if it was marked as shared
+            self.shared_args[res.dest] = SharedArgument(res, args, kw)
+        return res
+
+    def add_subparsers(self, *args: Any, **kw: Any) -> Any:
+        if "parser_class" not in kw:
+            kw["parser_class"] = type(
+                "ArgumentParser",
+                (self.__class__,),
+                {"shared_args": dict(self.shared_args)},
+            )
+        return super().add_subparsers(*args, **kw)
+
+    def parse_args(self, *args: Any, **kw: Any) -> Any:
+        if "namespace" not in kw:
+            # Use a subclass to pass the special action list without making it
+            # appear as an argument
+            kw["namespace"] = type(
+                "Namespace", (Namespace,), {"_shared_args": self.shared_args}
+            )()
+        return super().parse_args(*args, **kw)
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--debputy-manifest",
+        dest="debputy_manifest",
+        action="store",
+        default=None,
+        help="Specify another `debputy` manifest (default: debian/debputy.manifest)",
+        shared=True,
+    )
+
+    parser.add_argument(
+        "-d",
+        "--debug",
+        dest="debug_mode",
+        action="store_true",
+        default=False,
+        help="Enable debug logging and raw stack traces on errors. Some warnings become errors as a consequence.",
+        shared=True,
+    )
+
+    parser.add_argument(
+        "--no-pager",
+        dest="pager",
+        action="store_false",
+        default=True,
+        help="For subcommands that can use a pager, disable the use of pager. Some output formats implies --no-pager",
+        shared=True,
+    )
+
+    parser.add_argument(
+        "--plugin",
+        dest="required_plugins",
+        action="append",
+        type=str,
+        default=[],
+        help="Request the plugin to be loaded. Can be used multiple time."
+        " Ignored for some commands (such as autopkgtest-test-runner)",
+        shared=True,
+    )
+
+
+def _add_packages_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-p",
+        "--package",
+        dest="packages",
+        action="append",
+        type=str,
+        default=[],
+        help="The package(s) to act on.  Affects default permission normalization rules",
+    )
+
+
+internal_commands = ROOT_COMMAND.add_dispatching_subcommand(
+    "internal-command",
+    dest="internal_command",
+    metavar="command",
+    help_description="Commands used for internal purposes. These are implementation details and subject to change",
+)
+tool_support_commands = ROOT_COMMAND.add_dispatching_subcommand(
+    "tool-support",
+    help_description="Tool integration commands. These are intended to have stable output and behaviour",
+    dest="tool_subcommand",
+    metavar="command",
+)
+
+
+def parse_args() -> argparse.Namespace:
+    description = textwrap.dedent(
+        """\
+    The `debputy` program is a manifest-based Debian packaging tool.
+
+    It is used as a part of compiling a source package and transforming it into one or
+    more binary (.deb) packages.
+
+    If you are using a screen reader, consider exporting setting the environment variable
+    OPTIMIZE_FOR_SCREEN_READER=1. This will remove some of the visual formatting and some
+    commands will render the output in a purely textual manner rather than visual layout.
+    """
+    )
+
+    parser: argparse.ArgumentParser = DebputyArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+        prog=program_name(),
+    )
+
+    parser.add_argument("--version", action="version", version=__version__)
+
+    _add_common_args(parser)
+    from debputy.commands.debputy_cmd.plugin_cmds import (
+        ensure_plugin_commands_are_loaded,
+    )
+    from debputy.commands.debputy_cmd.lint_and_lsp_cmds import (
+        ensure_lint_and_lsp_commands_are_loaded,
+    )
+
+    ensure_plugin_commands_are_loaded()
+    ensure_lint_and_lsp_commands_are_loaded()
+
+    ROOT_COMMAND.configure(parser)
+
+    autocomplete(parser)
+
+    argv = sys.argv
+    try:
+        i = argv.index("--")
+        upstream_args = argv[i + 1 :]
+        argv = argv[:i]
+    except (IndexError, ValueError):
+        upstream_args = []
+    parsed_args: argparse.Namespace = parser.parse_args(argv[1:])
+
+    setattr(parsed_args, "upstream_args", upstream_args)
+    if hasattr(parsed_args, "packages"):
+        setattr(parsed_args, "packages", frozenset(parsed_args.packages))
+
+    return parsed_args
+
+
+@ROOT_COMMAND.register_subcommand(
+    "check-manifest",
+    help_description="Check the manifest for obvious errors, but do not run anything",
+    requested_plugins_only=True,
+)
+def _check_manifest(context: CommandContext) -> None:
+    context.parse_manifest()
+    _info("No errors detected.")
+
+
+def _install_plugin_from_plugin_metadata(
+    plugin_metadata: DebputyPluginMetadata,
+    dest_dir: str,
+) -> None:
+    related_files = find_related_implementation_files_for_plugin(plugin_metadata)
+    install_dir = os.path.join(
+        f"{dest_dir}/{DEBPUTY_PLUGIN_ROOT_DIR}".replace("//", "/"),
+        "debputy",
+        "plugins",
+    )
+
+    os.umask(0o022)
+    os.makedirs(install_dir, exist_ok=True)
+    cmd = ["cp", "--reflink=auto", "-t", install_dir]
+    cmd.extend(related_files)
+    cmd.append(plugin_metadata.plugin_path)
+    _info(f"   {escape_shell(*cmd)}")
+    subprocess.check_call(
+        cmd,
+        stdin=subprocess.DEVNULL,
+    )
+
+
+@internal_commands.register_subcommand(
+    "install-plugin",
+    help_description="[Internal command] Install a plugin and related files",
+    requested_plugins_only=True,
+    argparser=[
+        add_arg("target_plugin", metavar="PLUGIN", action="store"),
+        add_arg(
+            "--dest-dir",
+            dest="dest_dir",
+            default="",
+            action="store",
+        ),
+    ],
+)
+def _install_plugin(context: CommandContext) -> None:
+    target_plugin = context.parsed_args.target_plugin
+    if not os.path.isfile(target_plugin):
+        _error(
+            f'The value "{target_plugin}" must be a file. It should be the JSON descriptor of'
+            f" the plugin."
+        )
+    plugin_metadata = parse_json_plugin_desc(target_plugin)
+    _install_plugin_from_plugin_metadata(
+        plugin_metadata,
+        context.parsed_args.dest_dir,
+    )
+
+
+_DH_PLUGIN_PKG_DIR = "debputy-plugins"
+
+
+def _find_plugins_and_tests_in_source_package(
+    context: CommandContext,
+) -> Tuple[bool, List[Tuple[DebputyPluginMetadata, str]], List[str]]:
+    debian_dir = context.debian_dir
+    binary_packages = context.binary_packages()
+    installs = []
+    all_tests = []
+    had_plugin_dir = False
+    for binary_package in binary_packages.values():
+        if not binary_package.should_be_acted_on:
+            continue
+        debputy_plugins_dir = dhe_pkgdir(debian_dir, binary_package, _DH_PLUGIN_PKG_DIR)
+        if debputy_plugins_dir is None:
+            continue
+        if not debputy_plugins_dir.is_dir:
+            continue
+        had_plugin_dir = True
+        dest_dir = os.path.join("debian", binary_package.name)
+        for path in debputy_plugins_dir.iterdir:
+            if not path.is_file or not path.name.endswith((".json", ".json.in")):
+                continue
+            plugin_metadata = parse_json_plugin_desc(path.path)
+            if (
+                plugin_metadata.plugin_name.startswith("debputy-")
+                or plugin_metadata.plugin_name == "debputy"
+            ):
+                _error(
+                    f"The plugin name {plugin_metadata.plugin_name} is reserved by debputy. Please rename"
+                    " the plugin to something else."
+                )
+            installs.append((plugin_metadata, dest_dir))
+            all_tests.extend(find_tests_for_plugin(plugin_metadata))
+    return had_plugin_dir, installs, all_tests
+
+
+@ROOT_COMMAND.register_subcommand(
+    "autopkgtest-test-runner",
+    requested_plugins_only=True,
+    help_description="Detect tests in the debian dir and run them against installed plugins",
+)
+def _autodep8_test_runner(context: CommandContext) -> None:
+    ad_hoc_run = "AUTOPKGTEST_TMP" not in os.environ
+    _a, _b, all_tests = _find_plugins_and_tests_in_source_package(context)
+
+    source_package = context.source_package()
+    explicit_test = (
+        "autopkgtest-pkg-debputy" in source_package.fields.get("Testsuite", "").split()
+    )
+
+    if not shutil.which("py.test"):
+        if ad_hoc_run:
+            extra_context = ""
+            if not explicit_test:
+                extra_context = (
+                    " Remember to add python3-pytest to the Depends field of your autopkgtests field if"
+                    " you are writing your own test case for autopkgtest. Note you can also add"
+                    ' "autopkgtest-pkg-debputy" to the "Testsuite" field in debian/control if you'
+                    " want the test case autogenerated."
+                )
+            _error(
+                f"Please install the py.test command (apt-get install python3-pytest).{extra_context}"
+            )
+        _error("Please add python3-pytest to the Depends field of your autopkgtests.")
+
+    if not all_tests:
+        extra_context = ""
+        if explicit_test:
+            extra_context = (
+                " If the package no longer provides any plugin or tests, please remove the "
+                ' "autopkgtest-pkg-debputy" test from the "Testsuite" in debian/control'
+            )
+        _error(
+            "There are no tests to be run. The autodep8 feature should not have generated a test for"
+            f" this case.{extra_context}"
+        )
+
+    if _run_tests(
+        context,
+        all_tests,
+        test_plugin_location="installed",
+        on_error_return=False,
+    ):
+        return
+    extra_context = ""
+    if not ad_hoc_run:
+        extra_context = (
+            ' These tests can be run manually via the "debputy autopkgtest-test-runner" command without any'
+            ' autopkgtest layering. To do so, install "dh-debputy python3-pytest" plus the packages'
+            " being tested and relevant extra dependencies required for the tests. Then open a shell in"
+            f' the unpacked source directory of {source_package.name} and run "debputy autopkgtest-test-runner"'
+        )
+    _error(f"The tests were not successful.{extra_context}")
+
+
+@internal_commands.register_subcommand(
+    "dh-integration-install-plugin",
+    help_description="[Internal command] Install a plugin and related files via debhelper integration",
+    requested_plugins_only=True,
+    argparser=_add_packages_args,
+)
+def _dh_integration_install_plugin(context: CommandContext) -> None:
+    had_plugin_dir, installs, all_tests = _find_plugins_and_tests_in_source_package(
+        context
+    )
+
+    if not installs:
+        if had_plugin_dir:
+            _warn(
+                "There were plugin dirs, but no plugins were detected inside them. Please ensure that "
+                f" the plugin dirs (debian/<pkg>.{_DH_PLUGIN_PKG_DIR} or debian/{_DH_PLUGIN_PKG_DIR})"
+                f" contains a .json or .json.in file, or remove them (plus drop the"
+                f" dh-sequence-installdebputy build dependency) if they are no longer useful."
+            )
+        else:
+            _info(
+                f"No plugin directories detected (debian/<pkg>.{_DH_PLUGIN_PKG_DIR} or debian/{_DH_PLUGIN_PKG_DIR})"
+            )
+        return
+
+    if all_tests:
+        if "nocheck" in context.deb_build_options_and_profiles.deb_build_options:
+            _info("Skipping tests due to DEB_BUILD_OPTIONS=nocheck")
+        elif not shutil.which("py.test"):
+            _warn("Skipping tests because py.test is not available")
+        else:
+            _run_tests(context, all_tests)
+    else:
+        _info("No tests detected for any of the plugins. Skipping running tests.")
+
+    for plugin_metadata, dest_dir in installs:
+        _info(f"Installing plugin {plugin_metadata.plugin_name} into {dest_dir}")
+        _install_plugin_from_plugin_metadata(plugin_metadata, dest_dir)
+
+
+def _run_tests(
+    context: CommandContext,
+    test_paths: List[str],
+    *,
+    cwd: Optional[str] = None,
+    tmpdir_root: Optional[str] = None,
+    test_plugin_location: Literal["installed", "uninstalled"] = "uninstalled",
+    on_error_return: Optional[Any] = None,
+    on_success_return: Optional[Any] = True,
+) -> Any:
+    env = dict(os.environ)
+    env["DEBPUTY_TEST_PLUGIN_LOCATION"] = test_plugin_location
+    if "PYTHONPATH" in env:
+        env["PYTHONPATH"] = f"{DEBPUTY_ROOT_DIR}:{env['PYTHONPATH']}"
+    else:
+        env["PYTHONPATH"] = str(DEBPUTY_ROOT_DIR)
+
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    _info("Running debputy plugin tests.")
+    _info("")
+    _info("Environment settings:")
+    for envname in [
+        "PYTHONPATH",
+        "PYTHONDONTWRITEBYTECODE",
+        "DEBPUTY_TEST_PLUGIN_LOCATION",
+    ]:
+        _info(f"    {envname}={env[envname]}")
+
+    with TemporaryDirectory(dir=tmpdir_root) as tmpdir:
+        cmd = [
+            "py.test",
+            "-vvvvv" if context.parsed_args.debug_mode else "-v",
+            "--config-file=/dev/null",
+            f"--rootdir={cwd if cwd is not None else '.'}",
+            "-o",
+            f"cache_dir={tmpdir}",
+        ]
+        cmd.extend(test_paths)
+
+        _info(f"Test Command: {escape_shell(*cmd)}")
+        try:
+            subprocess.check_call(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                env=env,
+                cwd=cwd,
+            )
+        except subprocess.CalledProcessError:
+            if on_error_return is None:
+                _error("The tests were not successful.")
+            return on_error_return
+    return True
+
+
+@internal_commands.register_subcommand(
+    "run-tests-for-plugin",
+    help_description="[Internal command] Run tests for a plugin",
+    requested_plugins_only=True,
+    argparser=[
+        add_arg("target_plugin", metavar="PLUGIN", action="store"),
+        add_arg(
+            "--require-tests",
+            dest="require_tests",
+            default=True,
+            action=argparse.BooleanOptionalAction,
+        ),
+    ],
+)
+def _run_tests_for_plugin(context: CommandContext) -> None:
+    target_plugin = context.parsed_args.target_plugin
+    if not os.path.isfile(target_plugin):
+        _error(
+            f'The value "{target_plugin}" must be a file. It should be the JSON descriptor of'
+            f" the plugin."
+        )
+    try:
+        plugin_metadata = find_json_plugin(
+            context.plugin_search_dirs,
+            target_plugin,
+        )
+    except PluginNotFoundError as e:
+        _error(e.message)
+
+    tests = find_tests_for_plugin(plugin_metadata)
+
+    if not tests:
+        if context.parsed_args.require_tests:
+            plugin_name = plugin_metadata.plugin_name
+            plugin_dir = os.path.dirname(plugin_metadata.plugin_path)
+
+            _error(
+                f"Cannot find any tests for {plugin_name}: Expected them to be in "
+                f' "{plugin_dir}". Use --no-require-tests to consider missing tests'
+                " a non-error."
+            )
+        _info(
+            f"No tests found for {plugin_metadata.plugin_name}. Use --require-tests to turn"
+            " this into an error."
+        )
+        return
+
+    if not shutil.which("py.test"):
+        _error(
+            f"Cannot run the tests for {plugin_metadata.plugin_name}: This feature requires py.test"
+            f" (apt-get install python3-pytest)"
+        )
+    _run_tests(context, tests, cwd="/")
+
+
+@internal_commands.register_subcommand(
+    "dh-integration-generate-debs",
+    help_description="[Internal command] Generate .deb/.udebs packages from debian/<pkg> (Not stable API)",
+    requested_plugins_only=True,
+    argparser=[
+        _add_packages_args,
+        add_arg(
+            "--integration-mode",
+            dest="integration_mode",
+            default=None,
+            choices=["rrr"],
+        ),
+        add_arg(
+            "output",
+            metavar="output",
+            help="Where to place the resulting packages. Should be a directory",
+        ),
+        # Added for "help only" - you cannot trigger this option in practice
+        add_arg(
+            "--",
+            metavar="UPSTREAM_ARGS",
+            action="extend",
+            nargs="+",
+            dest="unused",
+        ),
+    ],
+)
+def _dh_integration_generate_debs(context: CommandContext) -> None:
+    integrated_with_debhelper()
+    parsed_args = context.parsed_args
+    is_dh_rrr_only_mode = parsed_args.integration_mode == "rrr"
+    if is_dh_rrr_only_mode:
+        problematic_plugins = list(context.requested_plugins())
+        problematic_plugins.extend(context.required_plugins())
+        if problematic_plugins:
+            plugin_names = ", ".join(problematic_plugins)
+            _error(
+                f"Plugins are not supported in the zz-debputy-rrr sequence. Detected plugins: {plugin_names}"
+            )
+
+    plugins = context.load_plugins().plugin_data
+    for plugin in plugins.values():
+        _info(f"Loaded plugin {plugin.plugin_name}")
+    manifest = context.parse_manifest()
+
+    package_data_table = manifest.perform_installations(
+        enable_manifest_installation_feature=not is_dh_rrr_only_mode
+    )
+    source_fs = FSROOverlay.create_root_dir("..", ".")
+    source_version = manifest.source_version()
+    is_native = "-" not in source_version
+
+    if not is_dh_rrr_only_mode:
+        for dctrl_bin in manifest.active_packages:
+            package = dctrl_bin.name
+            dctrl_data = package_data_table[package]
+            fs_root = dctrl_data.fs_root
+            package_metadata_context = dctrl_data.package_metadata_context
+
+            assert dctrl_bin.should_be_acted_on
+
+            detect_systemd_user_service_files(dctrl_bin, fs_root)
+            usr_local_transformation(dctrl_bin, fs_root)
+            handle_perl_code(
+                dctrl_bin,
+                manifest.dpkg_architecture_variables,
+                fs_root,
+                dctrl_data.substvars,
+            )
+            if "nostrip" not in manifest.build_env.deb_build_options:
+                dbgsym_ids = relocate_dwarves_into_dbgsym_packages(
+                    dctrl_bin,
+                    fs_root,
+                    dctrl_data.dbgsym_info.dbgsym_fs_root,
+                )
+                dctrl_data.dbgsym_info.dbgsym_ids = dbgsym_ids
+
+            fixup_debian_changelog_and_news_file(
+                dctrl_bin,
+                fs_root,
+                is_native,
+                manifest.build_env,
+            )
+            if not is_native:
+                install_upstream_changelog(
+                    dctrl_bin,
+                    fs_root,
+                    source_fs,
+                )
+            run_package_processors(manifest, package_metadata_context, fs_root)
+
+        cross_package_control_files(package_data_table, manifest)
+    for binary_data in package_data_table:
+        if not binary_data.binary_package.should_be_acted_on:
+            continue
+        # Ensure all fs's are read-only before we enable cross package checks.
+        # This ensures that no metadata detector will never see a read-write FS
+        cast("FSRootDir", binary_data.fs_root).is_read_write = False
+
+    package_data_table.enable_cross_package_checks = True
+    assemble_debs(
+        context,
+        manifest,
+        package_data_table,
+        is_dh_rrr_only_mode,
+    )
+
+
+PackagingFileInfo = TypedDict(
+    "PackagingFileInfo",
+    {
+        "path": str,
+        "binary-package": NotRequired[str],
+        "install-path": NotRequired[str],
+        "install-pattern": NotRequired[str],
+        "file-categories": NotRequired[List[str]],
+        "config-features": NotRequired[List[str]],
+        "likely-generated-from": NotRequired[List[str]],
+        "related-tools": NotRequired[List[str]],
+        "documentation-uris": NotRequired[List[str]],
+        "debputy-cmd-templates": NotRequired[List[List[str]]],
+        "generates": NotRequired[str],
+        "generated-from": NotRequired[str],
+    },
+)
+
+
+def _scan_debian_dir(debian_dir: VirtualPath) -> Iterator[VirtualPath]:
+    for p in debian_dir.iterdir:
+        yield p
+        if p.is_dir and p.path in ("debian/source", "debian/tests"):
+            yield from p.iterdir
+
+
+_POST_FORMATTING_REWRITE = {
+    "period-to-underscore": lambda n: n.replace(".", "_"),
+}
+
+
+def _fake_PPFClassSpec(
+    debputy_plugin_metadata: DebputyPluginMetadata,
+    stem: str,
+    doc_uris: Sequence[str],
+    install_pattern: Optional[str],
+    *,
+    default_priority: Optional[int] = None,
+    packageless_is_fallback_for_all_packages: bool = False,
+    post_formatting_rewrite: Optional[str] = None,
+    bug_950723: bool = False,
+) -> PackagerProvidedFileClassSpec:
+    if install_pattern is None:
+        install_pattern = "not-a-real-ppf"
+    if post_formatting_rewrite is not None:
+        formatting_hook = _POST_FORMATTING_REWRITE[post_formatting_rewrite]
+    else:
+        formatting_hook = None
+    return PackagerProvidedFileClassSpec(
+        debputy_plugin_metadata,
+        stem,
+        install_pattern,
+        allow_architecture_segment=True,
+        allow_name_segment=True,
+        default_priority=default_priority,
+        default_mode=0o644,
+        post_formatting_rewrite=formatting_hook,
+        packageless_is_fallback_for_all_packages=packageless_is_fallback_for_all_packages,
+        reservation_only=False,
+        formatting_callback=None,
+        bug_950723=bug_950723,
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=doc_uris,
+        ),
+    )
+
+
+def _relevant_dh_compat_rules(
+    compat_level: Optional[int],
+    info: KnownPackagingFileInfo,
+) -> Iterable[InstallPatternDHCompatRule]:
+    if compat_level is None:
+        return
+    dh_compat_rules = info.get("dh_compat_rules")
+    if not dh_compat_rules:
+        return
+    for dh_compat_rule in dh_compat_rules:
+        rule_compat_level = dh_compat_rule.get("starting_with_compat_level")
+        if rule_compat_level is not None and compat_level < rule_compat_level:
+            continue
+        yield dh_compat_rule
+
+
+def _kpf_install_pattern(
+    compat_level: Optional[int],
+    ppkpf: PluginProvidedKnownPackagingFile,
+) -> Optional[str]:
+    for compat_rule in _relevant_dh_compat_rules(compat_level, ppkpf.info):
+        install_pattern = compat_rule.get("install_pattern")
+        if install_pattern is not None:
+            return install_pattern
+    return ppkpf.info.get("install_pattern")
+
+
+def _resolve_debhelper_config_files(
+    debian_dir: VirtualPath,
+    binary_packages: Mapping[str, BinaryPackage],
+    debputy_plugin_metadata: DebputyPluginMetadata,
+    dh_ppf_docs: Dict[str, PluginProvidedKnownPackagingFile],
+    dh_rules_addons: Iterable[str],
+    dh_compat_level: int,
+) -> Tuple[List[PackagerProvidedFile], Optional[object], int]:
+    dh_ppfs = {}
+    commands, exit_code = _relevant_dh_commands(dh_rules_addons)
+    dh_commands = set(commands)
+
+    cmd = ["dh_assistant", "list-guessed-dh-config-files"]
+    if dh_rules_addons:
+        addons = ",".join(dh_rules_addons)
+        cmd.append(f"--with={addons}")
+    try:
+        output = subprocess.check_output(
+            cmd,
+            stderr=subprocess.DEVNULL,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        config_files = []
+        issues = None
+        if isinstance(e, subprocess.CalledProcessError):
+            exit_code = e.returncode
+        else:
+            exit_code = 127
+    else:
+        result = json.loads(output)
+        config_files: List[Union[Mapping[str, Any], object]] = result.get(
+            "config-files", []
+        )
+        issues = result.get("issues")
+    for config_file in config_files:
+        if not isinstance(config_file, dict):
+            continue
+        if config_file.get("file-type") != "pkgfile":
+            continue
+        stem = config_file.get("pkgfile")
+        if stem is None:
+            continue
+        internal = config_file.get("internal")
+        if isinstance(internal, dict):
+            bug_950723 = internal.get("bug#950723", False) is True
+        else:
+            bug_950723 = False
+        commands = config_file.get("commands")
+        documentation_uris = []
+        related_tools = []
+        seen_commands = set()
+        seen_docs = set()
+        ppkpf = dh_ppf_docs.get(stem)
+        if ppkpf:
+            dh_cmds = ppkpf.info.get("debhelper_commands")
+            doc_uris = ppkpf.info.get("documentation_uris")
+            default_priority = ppkpf.info.get("default_priority")
+            if doc_uris is not None:
+                seen_docs.update(doc_uris)
+                documentation_uris.extend(doc_uris)
+            if dh_cmds is not None:
+                seen_commands.update(dh_cmds)
+                related_tools.extend(dh_cmds)
+            install_pattern = _kpf_install_pattern(dh_compat_level, ppkpf)
+            post_formatting_rewrite = ppkpf.info.get("post_formatting_rewrite")
+            packageless_is_fallback_for_all_packages = ppkpf.info.get(
+                "packageless_is_fallback_for_all_packages",
+                False,
+            )
+        else:
+            install_pattern = None
+            default_priority = None
+            post_formatting_rewrite = None
+            packageless_is_fallback_for_all_packages = False
+        for command in commands:
+            if isinstance(command, dict):
+                command_name = command.get("command")
+                if isinstance(command_name, str) and command_name:
+                    if command_name not in seen_commands:
+                        related_tools.append(command_name)
+                        seen_commands.add(command_name)
+                    manpage = f"man:{command_name}(1)"
+                    if manpage not in seen_docs:
+                        documentation_uris.append(manpage)
+                        seen_docs.add(manpage)
+        dh_ppfs[stem] = _fake_PPFClassSpec(
+            debputy_plugin_metadata,
+            stem,
+            documentation_uris,
+            install_pattern,
+            default_priority=default_priority,
+            post_formatting_rewrite=post_formatting_rewrite,
+            packageless_is_fallback_for_all_packages=packageless_is_fallback_for_all_packages,
+            bug_950723=bug_950723,
+        )
+    for ppkpf in dh_ppf_docs.values():
+        stem = ppkpf.detection_value
+        if stem in dh_ppfs:
+            continue
+
+        default_priority = ppkpf.info.get("default_priority")
+        commands = ppkpf.info.get("debhelper_commands")
+        install_pattern = _kpf_install_pattern(dh_compat_level, ppkpf)
+        post_formatting_rewrite = ppkpf.info.get("post_formatting_rewrite")
+        packageless_is_fallback_for_all_packages = ppkpf.info.get(
+            "packageless_is_fallback_for_all_packages",
+            False,
+        )
+        if commands and not any(c in dh_commands for c in commands):
+            continue
+        dh_ppfs[stem] = _fake_PPFClassSpec(
+            debputy_plugin_metadata,
+            stem,
+            ppkpf.info.get("documentation_uris"),
+            install_pattern,
+            default_priority=default_priority,
+            post_formatting_rewrite=post_formatting_rewrite,
+            packageless_is_fallback_for_all_packages=packageless_is_fallback_for_all_packages,
+        )
+    dh_ppfs = list(
+        flatten_ppfs(
+            detect_all_packager_provided_files(
+                dh_ppfs,
+                debian_dir,
+                binary_packages,
+                allow_fuzzy_matches=True,
+            )
+        )
+    )
+    return dh_ppfs, issues, exit_code
+
+
+def _merge_list(
+    existing_table: Dict[str, Any],
+    key: str,
+    new_data: Optional[List[str]],
+) -> None:
+    if not new_data:
+        return
+    existing_values = existing_table.get(key, [])
+    if isinstance(existing_values, tuple):
+        existing_values = list(existing_values)
+    assert isinstance(existing_values, list)
+    seen = set(existing_values)
+    existing_values.extend(x for x in new_data if x not in seen)
+    existing_table[key] = existing_values
+
+
+def _merge_ppfs(
+    identified: List[PackagingFileInfo],
+    seen_paths: Set[str],
+    ppfs: List[PackagerProvidedFile],
+    context: Mapping[str, PluginProvidedKnownPackagingFile],
+    dh_compat_level: Optional[int],
+) -> None:
+    for ppf in ppfs:
+        key = ppf.path.path
+        ref_doc = ppf.definition.reference_documentation
+        documentation_uris = (
+            ref_doc.format_documentation_uris if ref_doc is not None else None
+        )
+
+        if not ppf.definition.installed_as_format.startswith("not-a-real-ppf"):
+            try:
+                parts = ppf.compute_dest()
+            except RuntimeError:
+                dest = None
+            else:
+                dest = "/".join(parts).lstrip(".")
+        else:
+            dest = None
+        seen_paths.add(key)
+        details: PackagingFileInfo = {
+            "path": key,
+            "binary-package": ppf.package_name,
+        }
+        if ppf.fuzzy_match and key.endswith(".in"):
+            _merge_list(details, "file-categories", ["generic-template"])
+            details["generates"] = key[:-3]
+        elif assume_not_none(ppf.path.parent_dir).get(ppf.path.name + ".in"):
+            _merge_list(details, "file-categories", ["generated"])
+            details["generated-from"] = key + ".in"
+        if dest is not None:
+            details["install-path"] = dest
+        identified.append(details)
+
+        extra_details = context.get(ppf.definition.stem)
+        if extra_details is not None:
+            _add_known_packaging_data(details, extra_details, dh_compat_level)
+
+        _merge_list(details, "documentation-uris", documentation_uris)
+
+
+def _is_debputy_package(context: CommandContext, dh_rules_addons: Set[str]) -> bool:
+    drules = context.debian_dir.get("rules")
+    sequences = set()
+    source_package = context.source_package()
+    if drules is not None and not drules.is_dir:
+        parse_drules_for_addons(drules, dh_rules_addons)
+    extract_dh_addons_from_control(source_package.fields, sequences)
+    sequences.update(dh_rules_addons)
+    return (
+        "debputy" in sequences or "zz-debputy" in sequences or "zz_debputy" in sequences
+    )
+
+
+def _extract_dh_compat_level() -> Tuple[Optional[int], int]:
+    try:
+        output = subprocess.check_output(
+            ["dh_assistant", "active-compat-level"],
+            stderr=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError) as e:
+        exit_code = 127
+        if isinstance(e, subprocess.CalledProcessError):
+            exit_code = e.returncode
+        return None, exit_code
+    else:
+        data = json.loads(output)
+        active_compat_level = data.get("active-compat-level")
+        exit_code = 0
+        if not isinstance(active_compat_level, int) or active_compat_level < 1:
+            active_compat_level = None
+            exit_code = 255
+        return active_compat_level, exit_code
+
+
+def _relevant_dh_commands(dh_rules_addons: Iterable[str]) -> Tuple[List[str], int]:
+    cmd = ["dh_assistant", "list-commands", "--output-format=json"]
+    if dh_rules_addons:
+        addons = ",".join(dh_rules_addons)
+        cmd.append(f"--with={addons}")
+    try:
+        output = subprocess.check_output(
+            cmd,
+            stderr=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError) as e:
+        exit_code = 127
+        if isinstance(e, subprocess.CalledProcessError):
+            exit_code = e.returncode
+        return [], exit_code
+    else:
+        data = json.loads(output)
+        commands_json = data.get("commands")
+        commands = []
+        for command in commands_json:
+            if isinstance(command, dict):
+                command_name = command.get("command")
+                if isinstance(command_name, str) and command_name:
+                    commands.append(command_name)
+        return commands, 0
+
+
+@tool_support_commands.register_subcommand(
+    "supports-tool-command",
+    help_description="Test where a given tool-support command exists",
+    argparser=add_arg(
+        "test_command",
+        metavar="name",
+        default=None,
+        help="The name of the command",
+    ),
+)
+def _supports_tool_command(context: CommandContext) -> None:
+    command_name = context.parsed_args.test_command
+    if tool_support_commands.has_command(command_name):
+        sys.exit(0)
+    else:
+        sys.exit(2)
+
+
+@tool_support_commands.register_subcommand(
+    "export-reference-data",
+    help_description="Export reference data for other tool-support commands",
+    argparser=[
+        add_arg(
+            "--output-format",
+            default="text",
+            choices=["text", "json"],
+            help="Output format of the reference data",
+        ),
+        add_arg(
+            "dataset",
+            metavar="name",
+            default=None,
+            nargs="?",
+            help="The dataset to export (if any)",
+            choices=REFERENCE_DATA_TABLE,
+        ),
+    ],
+)
+def _export_reference_data(context: CommandContext) -> None:
+    dataset_name = context.parsed_args.dataset
+    output_format = context.parsed_args.output_format
+    if dataset_name is not None:
+        subdata_set = REFERENCE_DATA_TABLE.get(dataset_name)
+        if subdata_set is None:
+            _error(f"Unknown data set: {dataset_name}")
+        reference_data = {
+            dataset_name: subdata_set,
+        }
+    else:
+        subdata_set = None
+        reference_data = REFERENCE_DATA_TABLE
+    if output_format == "text":
+        if subdata_set is None:
+            _error(
+                "When output format is text, then the dataset name is required (it is optional for JSON formats)."
+            )
+        with _stream_to_pager(context.parsed_args) as (fd, fo):
+            header = ["key", "description"]
+            rows = [(k, v["description"]) for k, v in subdata_set.items()]
+            fo.print_list_table(header, rows)
+            fo.print()
+            fo.print("If you wanted this as JSON, please use --output-format=json")
+    elif output_format == "json":
+        _json_output(
+            {
+                "reference-data": reference_data,
+            }
+        )
+    else:
+        raise AssertionError(f"Unsupported output format {output_format}")
+
+
+def _add_known_packaging_data(
+    details: PackagingFileInfo,
+    plugin_data: PluginProvidedKnownPackagingFile,
+    dh_compat_level: Optional[int],
+):
+    install_pattern = _kpf_install_pattern(
+        dh_compat_level,
+        plugin_data,
+    )
+    config_features = plugin_data.info.get("config_features")
+    if config_features:
+        config_features = expand_known_packaging_config_features(
+            dh_compat_level or 0,
+            config_features,
+        )
+        _merge_list(details, "config-features", config_features)
+
+    if dh_compat_level is not None:
+        extra_config_features = []
+        for dh_compat_rule in _relevant_dh_compat_rules(
+            dh_compat_level, plugin_data.info
+        ):
+            cf = dh_compat_rule.get("add_config_features")
+            if cf:
+                extra_config_features.extend(cf)
+        if extra_config_features:
+            extra_config_features = expand_known_packaging_config_features(
+                dh_compat_level,
+                extra_config_features,
+            )
+            _merge_list(details, "config-features", extra_config_features)
+    if "install-pattern" not in details and install_pattern is not None:
+        details["install-pattern"] = install_pattern
+    for mk, ok in [
+        ("file_categories", "file-categories"),
+        ("documentation_uris", "documentation-uris"),
+        ("debputy_cmd_templates", "debputy-cmd-templates"),
+    ]:
+        value = plugin_data.info.get(mk)
+        if value and ok == "debputy-cmd-templates":
+            value = [escape_shell(*c) for c in value]
+        _merge_list(details, ok, value)
+
+
+@tool_support_commands.register_subcommand(
+    "annotate-debian-directory",
+    log_only_to_stderr=True,
+    help_description="Scan debian/* for known package files and annotate them with information."
+    " Output is evaluated and may change. Please get in touch if you want to use it"
+    " or want additional features.",
+)
+def _annotate_debian_directory(context: CommandContext) -> None:
+    # Validates that we are run from a debian directory as a side effect
+    binary_packages = context.binary_packages()
+    feature_set = context.load_plugins()
+    known_packaging_files = feature_set.known_packaging_files
+    debputy_plugin_metadata = plugin_metadata_for_debputys_own_plugin()
+
+    reference_data_set_names = [
+        "config-features",
+        "file-categories",
+    ]
+    for n in reference_data_set_names:
+        assert n in REFERENCE_DATA_TABLE
+
+    annotated: List[PackagingFileInfo] = []
+    seen_paths = set()
+
+    drules_sequences = set()
+    is_debputy_package = _is_debputy_package(context, drules_sequences)
+    dh_compat_level, dh_assistant_exit_code = _extract_dh_compat_level()
+    dh_issues = []
+
+    static_packaging_files = {
+        kpf.detection_value: kpf
+        for kpf in known_packaging_files.values()
+        if kpf.detection_method == "path"
+    }
+    dh_pkgfile_docs = {
+        kpf.detection_value: kpf
+        for kpf in known_packaging_files.values()
+        if kpf.detection_method == "dh.pkgfile"
+    }
+
+    if is_debputy_package:
+        all_debputy_ppfs = list(
+            flatten_ppfs(
+                detect_all_packager_provided_files(
+                    feature_set.packager_provided_files,
+                    context.debian_dir,
+                    binary_packages,
+                    allow_fuzzy_matches=True,
+                )
+            )
+        )
+    else:
+        all_debputy_ppfs = []
+
+    if dh_compat_level is not None:
+        (
+            all_dh_ppfs,
+            dh_issues,
+            dh_assistant_exit_code,
+        ) = _resolve_debhelper_config_files(
+            context.debian_dir,
+            binary_packages,
+            debputy_plugin_metadata,
+            dh_pkgfile_docs,
+            drules_sequences,
+            dh_compat_level,
+        )
+
+    else:
+        all_dh_ppfs = []
+
+    for ppf in all_debputy_ppfs:
+        key = ppf.path.path
+        ref_doc = ppf.definition.reference_documentation
+        documentation_uris = (
+            ref_doc.format_documentation_uris if ref_doc is not None else None
+        )
+        details: PackagingFileInfo = {
+            "path": key,
+            "debputy-cmd-templates": [
+                ["debputy", "plugin", "show", "p-p-f", ppf.definition.stem]
+            ],
+        }
+        if ppf.fuzzy_match and key.endswith(".in"):
+            _merge_list(details, "file-categories", ["generic-template"])
+            details["generates"] = key[:-3]
+        elif assume_not_none(ppf.path.parent_dir).get(ppf.path.name + ".in"):
+            _merge_list(details, "file-categories", ["generated"])
+            details["generated-from"] = key + ".in"
+        seen_paths.add(key)
+        annotated.append(details)
+        static_details = static_packaging_files.get(key)
+        if static_details is not None:
+            # debhelper compat rules does not apply to debputy files
+            _add_known_packaging_data(details, static_details, None)
+        if documentation_uris:
+            details["documentation-uris"] = list(documentation_uris)
+
+    _merge_ppfs(annotated, seen_paths, all_dh_ppfs, dh_pkgfile_docs, dh_compat_level)
+
+    for virtual_path in _scan_debian_dir(context.debian_dir):
+        key = virtual_path.path
+        if key in seen_paths:
+            continue
+        if virtual_path.is_symlink:
+            try:
+                st = os.stat(virtual_path.fs_path)
+            except FileNotFoundError:
+                continue
+            else:
+                if not stat.S_ISREG(st.st_mode):
+                    continue
+        elif not virtual_path.is_file:
+            continue
+
+        static_match = static_packaging_files.get(virtual_path.path)
+        if static_match is not None:
+            details: PackagingFileInfo = {
+                "path": key,
+            }
+            annotated.append(details)
+            if assume_not_none(virtual_path.parent_dir).get(virtual_path.name + ".in"):
+                details["generated-from"] = key + ".in"
+                _merge_list(details, "file-categories", ["generated"])
+            _add_known_packaging_data(details, static_match, dh_compat_level)
+
+    data = {
+        "result": annotated,
+        "reference-datasets": reference_data_set_names,
+    }
+    if dh_issues is not None or dh_assistant_exit_code != 0:
+        data["issues"] = [
+            {
+                "source": "dh_assistant",
+                "exit-code": dh_assistant_exit_code,
+                "issue-data": dh_issues,
+            }
+        ]
+    _json_output(data)
+
+
+def _json_output(data: Any) -> None:
+    format_options = {}
+    if sys.stdout.isatty():
+        format_options = {
+            "indent": 4,
+            # sort_keys might be tempting but generally insert order makes more sense in practice.
+        }
+    json.dump(data, sys.stdout, **format_options)
+    if sys.stdout.isatty():
+        # Looks better with a final newline.
+        print()
+
+
+@ROOT_COMMAND.register_subcommand(
+    "migrate-from-dh",
+    help_description='Generate/update manifest from a "dh $@" using package',
+    argparser=[
+        add_arg(
+            "--acceptable-migration-issues",
+            dest="acceptable_migration_issues",
+            action="append",
+            type=str,
+            default=[],
+            help="Continue the migration even if this/these issues are detected."
+            " Can be set to ALL (in all upper-case) to accept all issues",
+        ),
+        add_arg(
+            "--migration-target",
+            dest="migration_target",
+            action="store",
+            choices=MIGRATORS,
+            type=str,
+            default=None,
+            help="Continue the migration even if this/these issues are detected."
+            " Can be set to ALL (in all upper-case) to accept all issues",
+        ),
+        add_arg(
+            "--no-act",
+            "--no-apply-changes",
+            dest="destructive",
+            action="store_false",
+            default=None,
+            help="Do not perform changes.  Existing manifest will not be overridden",
+        ),
+        add_arg(
+            "--apply-changes",
+            dest="destructive",
+            action="store_true",
+            default=None,
+            help="Perform changes.  The debian/debputy.manifest will updated in place if exists",
+        ),
+    ],
+)
+def _migrate_from_dh(context: CommandContext) -> None:
+    parsed_args = context.parsed_args
+    manifest = context.parse_manifest()
+    acceptable_migration_issues = AcceptableMigrationIssues(
+        frozenset(
+            i for x in parsed_args.acceptable_migration_issues for i in x.split(",")
+        )
+    )
+    migrate_from_dh(
+        manifest,
+        acceptable_migration_issues,
+        parsed_args.destructive,
+        parsed_args.migration_target,
+        lambda p: context.parse_manifest(manifest_path=p),
+    )
+
+
+def _setup_and_parse_args() -> argparse.Namespace:
+    is_arg_completing = "_ARGCOMPLETE" in os.environ
+    if not is_arg_completing:
+        setup_logging()
+    parsed_args = parse_args()
+    if is_arg_completing:
+        # We could be asserting at this point; but lets just recover gracefully.
+        setup_logging()
+    return parsed_args
+
+
+def main() -> None:
+    parsed_args = _setup_and_parse_args()
+    plugin_search_dirs = [str(DEBPUTY_PLUGIN_ROOT_DIR)]
+    try:
+        cmd_arg = CommandArg(
+            parsed_args,
+            plugin_search_dirs,
+        )
+        ROOT_COMMAND(cmd_arg)
+    except PluginInitializationError as e:
+        _error_w_stack_trace(
+            "Failed to load a plugin - full stack strace:",
+            e.message,
+            e,
+            parsed_args.debug_mode,
+            follow_warning=[
+                "Please consider filing a bug against the plugin in question"
+            ],
+        )
+    except UnhandledOrUnexpectedErrorFromPluginError as e:
+        trace = e.__cause__ if e.__cause__ is not None else e
+        # TODO: Reframe this as an internal error if `debputy` is the misbehaving plugin
+        if isinstance(trace, SymlinkLoopError):
+            _error_w_stack_trace(
+                "Error in `debputy`:",
+                e.message,
+                trace,
+                parsed_args.debug_mode,
+                orig_exception=e,
+                follow_warning=[
+                    "Please consider filing a bug against `debputy` in question"
+                ],
+            )
+        else:
+            _error_w_stack_trace(
+                "A plugin misbehaved:",
+                e.message,
+                trace,
+                parsed_args.debug_mode,
+                orig_exception=e,
+                follow_warning=[
+                    "Please consider filing a bug against the plugin in question"
+                ],
+            )
+    except PluginAPIViolationError as e:
+        trace = e.__cause__ if e.__cause__ is not None else e
+        # TODO: Reframe this as an internal error if `debputy` is the misbehaving plugin
+        _error_w_stack_trace(
+            "A plugin misbehaved:",
+            e.message,
+            trace,
+            parsed_args.debug_mode,
+            orig_exception=e,
+            follow_warning=[
+                "Please consider filing a bug against the plugin in question"
+            ],
+        )
+    except DebputyRuntimeError as e:
+        if parsed_args.debug_mode:
+            _warn(
+                "Re-raising original exception to show the full stack trace due to debug mode being active"
+            )
+            raise e
+        _error(e.message)
+    except AssertionError as e:
+        _error_w_stack_trace(
+            "Internal error in debputy",
+            str(e),
+            e,
+            parsed_args.debug_mode,
+            orig_exception=e,
+            follow_warning=["Please file a bug against debputy with the full output."],
+        )
+    except subprocess.CalledProcessError as e:
+        cmd = escape_shell(*e.cmd) if isinstance(e.cmd, list) else str(e.cmd)
+        _error_w_stack_trace(
+            f"The command << {cmd} >> failed and the code did not explicitly handle that exception.",
+            str(e),
+            e,
+            parsed_args.debug_mode,
+            orig_exception=e,
+            follow_warning=[
+                "The output above this error and the stacktrace may provide context to why the command failed.",
+                "Please file a bug against debputy with the full output.",
+            ],
+        )
+    except Exception as e:
+        _error_w_stack_trace(
+            "Unhandled exception (Re-run with --debug to see the raw stack trace)",
+            str(e),
+            e,
+            parsed_args.debug_mode,
+            orig_exception=e,
+            follow_warning=["Please file a bug against debputy with the full output."],
+        )
+
+
+def _error_w_stack_trace(
+    warning: str,
+    error_msg: str,
+    stacktrace: BaseException,
+    debug_mode: bool,
+    orig_exception: Optional[BaseException] = None,
+    follow_warning: Optional[List[str]] = None,
+) -> "NoReturn":
+    if debug_mode:
+        _warn(
+            "Re-raising original exception to show the full stack trace due to debug mode being active"
+        )
+        raise orig_exception if orig_exception is not None else stacktrace
+    _warn(warning)
+    _warn("  ----- 8< ---- BEGIN STACK TRACE ---- 8< -----")
+    traceback.print_exception(stacktrace)
+    _warn("  ----- 8< ---- END STACK TRACE ---- 8< -----")
+    if follow_warning:
+        for line in follow_warning:
+            _warn(line)
+    _error(error_msg)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/debputy/commands/debputy_cmd/context.py b/src/debputy/commands/debputy_cmd/context.py
new file mode 100644
index 0000000..3363e96
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/context.py
@@ -0,0 +1,607 @@
+import argparse
+import dataclasses
+import errno
+import os
+from typing import (
+    Optional,
+    Tuple,
+    Mapping,
+    FrozenSet,
+    Set,
+    Union,
+    Sequence,
+    Iterable,
+    Callable,
+    Dict,
+    TYPE_CHECKING,
+)
+
+from debian.debian_support import DpkgArchTable
+
+from debputy._deb_options_profiles import DebBuildOptionsAndProfiles
+from debputy.architecture_support import (
+    DpkgArchitectureBuildProcessValuesTable,
+    dpkg_architecture_table,
+)
+from debputy.exceptions import DebputyRuntimeError
+from debputy.filesystem_scan import FSROOverlay
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.packages import SourcePackage, BinaryPackage, parse_source_debian_control
+from debputy.plugin.api import VirtualPath
+from debputy.plugin.api.impl import load_plugin_features
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.substitution import (
+    Substitution,
+    VariableContext,
+    SubstitutionImpl,
+    NULL_SUBSTITUTION,
+)
+from debputy.util import _error, PKGNAME_REGEX, resolve_source_date_epoch, setup_logging
+
+if TYPE_CHECKING:
+    from argparse import _SubParsersAction
+
+
+CommandHandler = Callable[["CommandContext"], None]
+ArgparserConfigurator = Callable[[argparse.ArgumentParser], None]
+
+
+def add_arg(
+    *name_or_flags: str,
+    **kwargs,
+) -> Callable[[argparse.ArgumentParser], None]:
+    def _configurator(argparser: argparse.ArgumentParser) -> None:
+        argparser.add_argument(
+            *name_or_flags,
+            **kwargs,
+        )
+
+    return _configurator
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class CommandArg:
+    parsed_args: argparse.Namespace
+    plugin_search_dirs: Sequence[str]
+
+
+@dataclasses.dataclass
+class Command:
+    handler: Callable[["CommandContext"], None]
+    require_substitution: bool = True
+    requested_plugins_only: bool = False
+
+
+class CommandContext:
+    def __init__(
+        self,
+        parsed_args: argparse.Namespace,
+        plugin_search_dirs: Sequence[str],
+        require_substitution: bool = True,
+        requested_plugins_only: bool = False,
+    ) -> None:
+        self.parsed_args = parsed_args
+        self.plugin_search_dirs = plugin_search_dirs
+        self._require_substitution = require_substitution
+        self._requested_plugins_only = requested_plugins_only
+        self._debputy_plugin_feature_set: PluginProvidedFeatureSet = (
+            PluginProvidedFeatureSet()
+        )
+        self._debian_dir = FSROOverlay.create_root_dir("debian", "debian")
+        self._mtime: Optional[int] = None
+        self._source_variables: Optional[Mapping[str, str]] = None
+        self._substitution: Optional[Substitution] = None
+        self._requested_plugins: Optional[Sequence[str]] = None
+        self._plugins_loaded = False
+        self._dctrl_data: Optional[
+            Tuple[
+                DpkgArchitectureBuildProcessValuesTable,
+                DpkgArchTable,
+                DebBuildOptionsAndProfiles,
+                "SourcePackage",
+                Mapping[str, "BinaryPackage"],
+            ]
+        ] = None
+
+    @property
+    def debian_dir(self) -> VirtualPath:
+        return self._debian_dir
+
+    @property
+    def mtime(self) -> int:
+        if self._mtime is None:
+            self._mtime = resolve_source_date_epoch(
+                None,
+                substitution=self.substitution,
+            )
+        return self._mtime
+
+    def source_package(self) -> SourcePackage:
+        _a, _b, _c, source, _d = self._parse_dctrl()
+        return source
+
+    def binary_packages(self) -> Mapping[str, "BinaryPackage"]:
+        _a, _b, _c, _source, binary_package_table = self._parse_dctrl()
+        return binary_package_table
+
+    def requested_plugins(self) -> Sequence[str]:
+        if self._requested_plugins is None:
+            self._requested_plugins = self._resolve_requested_plugins()
+        return self._requested_plugins
+
+    def required_plugins(self) -> Set[str]:
+        return set(getattr(self.parsed_args, "required_plugins") or [])
+
+    @property
+    def deb_build_options_and_profiles(self) -> "DebBuildOptionsAndProfiles":
+        _a, _b, deb_build_options_and_profiles, _c, _d = self._parse_dctrl()
+        return deb_build_options_and_profiles
+
+    @property
+    def deb_build_options(self) -> Mapping[str, Optional[str]]:
+        return self.deb_build_options_and_profiles.deb_build_options
+
+    def _create_substitution(
+        self,
+        parsed_args: argparse.Namespace,
+        plugin_feature_set: PluginProvidedFeatureSet,
+        debian_dir: VirtualPath,
+    ) -> Substitution:
+        requested_subst = self._require_substitution
+        if hasattr(parsed_args, "substitution"):
+            requested_subst = parsed_args.substitution
+        if requested_subst is False and self._require_substitution:
+            _error(f"--no-substitution cannot be used with {parsed_args.command}")
+        if self._require_substitution or requested_subst is not False:
+            variable_context = VariableContext(debian_dir)
+            return SubstitutionImpl(
+                plugin_feature_set=plugin_feature_set,
+                unresolvable_substitutions=frozenset(["PACKAGE"]),
+                variable_context=variable_context,
+            )
+        return NULL_SUBSTITUTION
+
+    def load_plugins(self) -> PluginProvidedFeatureSet:
+        if not self._plugins_loaded:
+            requested_plugins = None
+            required_plugins = self.required_plugins()
+            if self._requested_plugins_only:
+                requested_plugins = self.requested_plugins()
+            debug_mode = getattr(self.parsed_args, "debug_mode", False)
+            load_plugin_features(
+                self.plugin_search_dirs,
+                self.substitution,
+                requested_plugins_only=requested_plugins,
+                required_plugins=required_plugins,
+                plugin_feature_set=self._debputy_plugin_feature_set,
+                debug_mode=debug_mode,
+            )
+            self._plugins_loaded = True
+        return self._debputy_plugin_feature_set
+
+    @staticmethod
+    def _plugin_from_dependency_field(dep_field: str) -> Iterable[str]:
+        package_prefix = "debputy-plugin-"
+        for dep_clause in (d.strip() for d in dep_field.split(",")):
+            dep = dep_clause.split("|")[0].strip()
+            if not dep.startswith(package_prefix):
+                continue
+            m = PKGNAME_REGEX.search(dep)
+            assert m
+            package_name = m.group(0)
+            plugin_name = package_name[len(package_prefix) :]
+            yield plugin_name
+
+    def _resolve_requested_plugins(self) -> Sequence[str]:
+        _a, _b, _c, source_package, _d = self._parse_dctrl()
+        bd = source_package.fields.get("Build-Depends", "")
+        plugins = list(self._plugin_from_dependency_field(bd))
+        for field_name in ("Build-Depends-Arch", "Build-Depends-Indep"):
+            f = source_package.fields.get(field_name)
+            if not f:
+                continue
+            for plugin in self._plugin_from_dependency_field(f):
+                raise DebputyRuntimeError(
+                    f"Cannot load plugins via {field_name}:"
+                    f" Please move debputy-plugin-{plugin} dependency to Build-Depends."
+                )
+
+        return plugins
+
+    @property
+    def substitution(self) -> Substitution:
+        if self._substitution is None:
+            self._substitution = self._create_substitution(
+                self.parsed_args,
+                self._debputy_plugin_feature_set,
+                self.debian_dir,
+            )
+        return self._substitution
+
+    def _parse_dctrl(
+        self,
+    ) -> Tuple[
+        DpkgArchitectureBuildProcessValuesTable,
+        DpkgArchTable,
+        DebBuildOptionsAndProfiles,
+        "SourcePackage",
+        Mapping[str, "BinaryPackage"],
+    ]:
+        if self._dctrl_data is None:
+            build_env = DebBuildOptionsAndProfiles.instance()
+            dpkg_architecture_variables = dpkg_architecture_table()
+            dpkg_arch_query_table = DpkgArchTable.load_arch_table()
+
+            packages: Union[Set[str], FrozenSet[str]] = frozenset()
+            if hasattr(self.parsed_args, "packages"):
+                packages = self.parsed_args.packages
+
+            try:
+                debian_control = self.debian_dir.get("control")
+                if debian_control is None:
+                    raise FileNotFoundError(
+                        errno.ENOENT,
+                        os.strerror(errno.ENOENT),
+                        os.path.join(self.debian_dir.fs_path, "control"),
+                    )
+                source_package, binary_packages = parse_source_debian_control(
+                    debian_control,
+                    packages,  # -p/--package
+                    set(),  # -N/--no-package
+                    False,  # -i
+                    False,  # -a
+                    dpkg_architecture_variables=dpkg_architecture_variables,
+                    dpkg_arch_query_table=dpkg_arch_query_table,
+                    build_env=build_env,
+                )
+                assert packages <= binary_packages.keys()
+            except FileNotFoundError:
+                _error(
+                    "This subcommand must be run from a source package root; expecting debian/control to exist."
+                )
+
+            self._dctrl_data = (
+                dpkg_architecture_variables,
+                dpkg_arch_query_table,
+                build_env,
+                source_package,
+                binary_packages,
+            )
+
+        return self._dctrl_data
+
+    @property
+    def has_dctrl_file(self) -> bool:
+        debian_control = self.debian_dir.get("control")
+        return debian_control is not None
+
+    def manifest_parser(
+        self,
+        *,
+        manifest_path: Optional[str] = None,
+    ) -> YAMLManifestParser:
+        substitution = self.substitution
+
+        (
+            dpkg_architecture_variables,
+            dpkg_arch_query_table,
+            build_env,
+            source_package,
+            binary_packages,
+        ) = self._parse_dctrl()
+
+        if self.parsed_args.debputy_manifest is not None:
+            manifest_path = self.parsed_args.debputy_manifest
+        if manifest_path is None:
+            manifest_path = os.path.join(self.debian_dir.fs_path, "debputy.manifest")
+        return YAMLManifestParser(
+            manifest_path,
+            source_package,
+            binary_packages,
+            substitution,
+            dpkg_architecture_variables,
+            dpkg_arch_query_table,
+            build_env,
+            self.load_plugins(),
+            debian_dir=self.debian_dir,
+        )
+
+    def parse_manifest(
+        self,
+        *,
+        manifest_path: Optional[str] = None,
+    ) -> HighLevelManifest:
+        substitution = self.substitution
+        manifest_required = False
+
+        (
+            dpkg_architecture_variables,
+            dpkg_arch_query_table,
+            build_env,
+            _,
+            binary_packages,
+        ) = self._parse_dctrl()
+
+        if self.parsed_args.debputy_manifest is not None:
+            manifest_path = self.parsed_args.debputy_manifest
+            manifest_required = True
+        if manifest_path is None:
+            manifest_path = os.path.join(self.debian_dir.fs_path, "debputy.manifest")
+        parser = self.manifest_parser(manifest_path=manifest_path)
+
+        os.environ["SOURCE_DATE_EPOCH"] = substitution.substitute(
+            "{{SOURCE_DATE_EPOCH}}",
+            "Internal resolution",
+        )
+        if os.path.isfile(manifest_path):
+            return parser.parse_manifest()
+        if manifest_required:
+            _error(f'The path "{manifest_path}" is not a file!')
+        return parser.build_manifest()
+
+
+class CommandBase:
+    __slots__ = ()
+
+    def configure(self, argparser: argparse.ArgumentParser) -> None:
+        # Does nothing by default
+        pass
+
+    def __call__(self, command_arg: CommandArg) -> None:
+        raise NotImplementedError
+
+
+class SubcommandBase(CommandBase):
+    __slots__ = ("name", "aliases", "help_description")
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        aliases: Sequence[str] = tuple(),
+        help_description: Optional[str] = None,
+    ) -> None:
+        self.name = name
+        self.aliases = aliases
+        self.help_description = help_description
+
+    def add_subcommand_to_subparser(
+        self,
+        subparser: "_SubParsersAction",
+    ) -> argparse.ArgumentParser:
+        parser = subparser.add_parser(
+            self.name,
+            aliases=self.aliases,
+            help=self.help_description,
+            allow_abbrev=False,
+        )
+        self.configure(parser)
+        return parser
+
+
+class GenericSubCommand(SubcommandBase):
+    __slots__ = (
+        "_handler",
+        "_configure_handler",
+        "_require_substitution",
+        "_requested_plugins_only",
+        "_log_only_to_stderr",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        handler: Callable[[CommandContext], None],
+        *,
+        aliases: Sequence[str] = tuple(),
+        help_description: Optional[str] = None,
+        configure_handler: Optional[Callable[[argparse.ArgumentParser], None]] = None,
+        require_substitution: bool = True,
+        requested_plugins_only: bool = False,
+        log_only_to_stderr: bool = False,
+    ) -> None:
+        super().__init__(name, aliases=aliases, help_description=help_description)
+        self._handler = handler
+        self._configure_handler = configure_handler
+        self._require_substitution = require_substitution
+        self._requested_plugins_only = requested_plugins_only
+        self._log_only_to_stderr = log_only_to_stderr
+
+    def configure_handler(
+        self,
+        handler: Callable[[argparse.ArgumentParser], None],
+    ) -> None:
+        if self._configure_handler is not None:
+            raise TypeError("Only one argument handler can be provided")
+        self._configure_handler = handler
+
+    def configure(self, argparser: argparse.ArgumentParser) -> None:
+        handler = self._configure_handler
+        if handler is not None:
+            handler(argparser)
+
+    def __call__(self, command_arg: CommandArg) -> None:
+        context = CommandContext(
+            command_arg.parsed_args,
+            command_arg.plugin_search_dirs,
+            self._require_substitution,
+            self._requested_plugins_only,
+        )
+        if self._log_only_to_stderr:
+            setup_logging(reconfigure_logging=True, log_only_to_stderr=True)
+        return self._handler(context)
+
+
+class DispatchingCommandMixin(CommandBase):
+    __slots__ = ()
+
+    def add_subcommand(self, subcommand: SubcommandBase) -> None:
+        raise NotImplementedError
+
+    def add_dispatching_subcommand(
+        self,
+        name: str,
+        dest: str,
+        *,
+        aliases: Sequence[str] = tuple(),
+        help_description: Optional[str] = None,
+        metavar: str = "command",
+        default_subcommand: Optional[str] = None,
+    ) -> "DispatcherCommand":
+        ds = DispatcherCommand(
+            name,
+            dest,
+            aliases=aliases,
+            help_description=help_description,
+            metavar=metavar,
+            default_subcommand=default_subcommand,
+        )
+        self.add_subcommand(ds)
+        return ds
+
+    def register_subcommand(
+        self,
+        name: Union[str, Sequence[str]],
+        *,
+        help_description: Optional[str] = None,
+        argparser: Optional[
+            Union[ArgparserConfigurator, Sequence[ArgparserConfigurator]]
+        ] = None,
+        require_substitution: bool = True,
+        requested_plugins_only: bool = False,
+        log_only_to_stderr: bool = False,
+    ) -> Callable[[CommandHandler], GenericSubCommand]:
+        if isinstance(name, str):
+            cmd_name = name
+            aliases = []
+        else:
+            cmd_name = name[0]
+            aliases = name[1:]
+
+        if argparser is not None and not callable(argparser):
+            args = argparser
+
+            def _wrapper(parser: argparse.ArgumentParser) -> None:
+                for configurator in args:
+                    configurator(parser)
+
+            argparser = _wrapper
+
+        def _annotation_impl(func: CommandHandler) -> GenericSubCommand:
+            subcommand = GenericSubCommand(
+                cmd_name,
+                func,
+                aliases=aliases,
+                help_description=help_description,
+                require_substitution=require_substitution,
+                requested_plugins_only=requested_plugins_only,
+                log_only_to_stderr=log_only_to_stderr,
+            )
+            self.add_subcommand(subcommand)
+            if argparser is not None:
+                subcommand.configure_handler(argparser)
+
+            return subcommand
+
+        return _annotation_impl
+
+
+class DispatcherCommand(SubcommandBase, DispatchingCommandMixin):
+    __slots__ = (
+        "_subcommands",
+        "_aliases",
+        "_dest",
+        "_metavar",
+        "_required",
+        "_default_subcommand",
+        "_argparser",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        dest: str,
+        *,
+        aliases: Sequence[str] = tuple(),
+        help_description: Optional[str] = None,
+        metavar: str = "command",
+        default_subcommand: Optional[str] = None,
+    ) -> None:
+        super().__init__(name, aliases=aliases, help_description=help_description)
+        self._aliases: Dict[str, SubcommandBase] = {}
+        self._subcommands: Dict[str, SubcommandBase] = {}
+        self._dest = dest
+        self._metavar = metavar
+        self._default_subcommand = default_subcommand
+        self._argparser: Optional[argparse.ArgumentParser] = None
+
+    def add_subcommand(self, subcommand: SubcommandBase) -> None:
+        all_names = [subcommand.name]
+        if subcommand.aliases:
+            all_names.extend(subcommand.aliases)
+        aliases = self._aliases
+        for n in all_names:
+            if n in aliases:
+                raise ValueError(
+                    f"Internal error: Multiple handlers for {n} on topic {self.name}"
+                )
+
+            aliases[n] = subcommand
+        self._subcommands[subcommand.name] = subcommand
+
+    def configure(self, argparser: argparse.ArgumentParser) -> None:
+        if self._argparser is not None:
+            raise TypeError("Cannot configure twice!")
+        self._argparser = argparser
+        subcommands = self._subcommands
+        if not subcommands:
+            raise ValueError(
+                f"Internal error: No subcommands for subcommand {self.name} (then why do we have it?)"
+            )
+        default_subcommand = self._default_subcommand
+        required = default_subcommand is None
+        if (
+            default_subcommand is not None
+            and default_subcommand not in ("--help", "-h")
+            and default_subcommand not in subcommands
+        ):
+            raise ValueError(
+                f"Internal error: Subcommand {self.name} should have {default_subcommand} as default,"
+                " but it was not registered?"
+            )
+        subparser = argparser.add_subparsers(
+            dest=self._dest,
+            required=required,
+            metavar=self._metavar,
+        )
+        for subcommand in subcommands.values():
+            subcommand.add_subcommand_to_subparser(subparser)
+
+    def has_command(self, command: str) -> bool:
+        return command in self._aliases
+
+    def __call__(self, command_arg: CommandArg) -> None:
+        argparser = self._argparser
+        assert argparser is not None
+        v = getattr(command_arg.parsed_args, self._dest, None)
+        if v is None:
+            v = self._default_subcommand
+            if v in ("--help", "-h"):
+                argparser.parse_args([v])
+                _error("Missing command", prog=argparser.prog)
+
+        assert (
+            v is not None
+        ), f"Internal error: No default subcommand and argparse did not provide the required subcommand {self._dest}?"
+        assert (
+            v in self._aliases
+        ), f"Internal error: {v} was accepted as a topic, but it was not registered?"
+        self._aliases[v](command_arg)
+
+
+ROOT_COMMAND = DispatcherCommand(
+    "root",
+    dest="command",
+    metavar="COMMAND",
+)
diff --git a/src/debputy/commands/debputy_cmd/dc_util.py b/src/debputy/commands/debputy_cmd/dc_util.py
new file mode 100644
index 0000000..f54a4d1
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/dc_util.py
@@ -0,0 +1,15 @@
+from typing import Dict, Iterable
+
+from debputy.packager_provided_files import (
+    PerPackagePackagerProvidedResult,
+    PackagerProvidedFile,
+)
+
+
+def flatten_ppfs(
+    all_ppfs: Dict[str, PerPackagePackagerProvidedResult]
+) -> Iterable[PackagerProvidedFile]:
+    for matched_ppf in all_ppfs.values():
+        yield from matched_ppf.auto_installable
+        for reserved_ppfs in matched_ppf.reserved_only.values():
+            yield from reserved_ppfs
diff --git a/src/debputy/commands/debputy_cmd/lint_and_lsp_cmds.py b/src/debputy/commands/debputy_cmd/lint_and_lsp_cmds.py
new file mode 100644
index 0000000..0f2ae0f
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/lint_and_lsp_cmds.py
@@ -0,0 +1,210 @@
+import textwrap
+from argparse import BooleanOptionalAction
+
+from debputy.commands.debputy_cmd.context import ROOT_COMMAND, CommandContext, add_arg
+from debputy.util import _error
+
+
+_EDITOR_SNIPPETS = {
+    "emacs": "emacs+eglot",
+    "emacs+eglot": textwrap.dedent(
+        """\
+        ;; `deputy lsp server` glue for emacs eglot (eglot is built-in these days)
+        ;;
+        ;; Add to ~/.emacs or ~/.emacs.d/init.el and then activate via `M-x eglot`.
+        ;;
+        ;; Requires: apt install elpa-dpkg-dev-el
+
+        ;; Make emacs recognize debian/debputy.manifest as a YAML file
+        (add-to-list 'auto-mode-alist '("/debian/debputy.manifest\\'" . yaml-mode))
+        ;; Inform eglot about the debputy LSP
+        (with-eval-after-load 'eglot
+            (add-to-list 'eglot-server-programs
+                    '(debian-control-mode . ("debputy" "lsp" "server")))
+            (add-to-list 'eglot-server-programs
+                    '(debian-changelog-mode . ("debputy" "lsp" "server")))
+            (add-to-list 'eglot-server-programs
+                    '(debian-copyright-mode . ("debputy" "lsp" "server")))
+            ;; The debian/rules file uses the qmake mode.
+            (add-to-list 'eglot-server-programs
+                    '(makefile-gmake-mode . ("debputy" "lsp" "server")))
+        )
+
+        ;; Auto-start eglot for the relevant modes.
+        (add-hook 'debian-control-mode-hook 'eglot-ensure)
+        ;; NOTE: changelog disabled by default because for some reason it
+        ;;       this hook causes perceivable delay (several seconds) when
+        ;;       opening the first changelog. It seems to be related to imenu.
+        ;; (add-hook 'debian-changelog-mode-hook 'eglot-ensure)
+        (add-hook 'debian-copyright-mode-hook 'eglot-ensure)
+        (add-hook 'makefile-gmake-mode-hook 'eglot-ensure)
+    """
+    ),
+    "vim": "vim+youcompleteme",
+    "vim+youcompleteme": textwrap.dedent(
+        """\
+        # debputy lsp server glue for vim with vim-youcompleteme. Add to ~/.vimrc
+        #
+        # Requires: apt install vim-youcompleteme
+
+        # Make vim recognize debputy.manifest as YAML file
+        au BufNewFile,BufRead debputy.manifest          setf yaml
+        # Inform vim/ycm about the debputy LSP
+        let g:ycm_language_server = [
+          \\   { 'name': 'debputy',
+          \\     'filetypes': [ 'debcontrol', 'debcopyright', 'debchangelog', 'make'],
+          \\     'cmdline': [ 'debputy', 'lsp', 'server' ]
+          \\   },
+          \\ ]
+
+        packadd! youcompleteme
+        nmap <leader>d <plug>(YCMHover)
+    """
+    ),
+}
+
+
+lsp_command = ROOT_COMMAND.add_dispatching_subcommand(
+    "lsp",
+    dest="lsp_command",
+    help_description="Language server related subcommands",
+)
+
+
+@lsp_command.register_subcommand(
+    "server",
+    log_only_to_stderr=True,
+    help_description="Start the language server",
+    argparser=[
+        add_arg(
+            "--tcp",
+            action="store_true",
+            help="Use TCP server",
+        ),
+        add_arg(
+            "--ws",
+            action="store_true",
+            help="Use WebSocket server",
+        ),
+        add_arg(
+            "--host",
+            default="127.0.0.1",
+            help="Bind to this address (Use with --tcp / --ws)",
+        ),
+        add_arg(
+            "--port",
+            type=int,
+            default=2087,
+            help="Bind to this port (Use with --tcp / --ws)",
+        ),
+    ],
+)
+def lsp_server_cmd(context: CommandContext) -> None:
+    parsed_args = context.parsed_args
+
+    try:
+        import lsprotocol
+        import pygls
+    except ImportError:
+        _error(
+            "This feature requires lsprotocol and pygls (apt-get install python3-lsprotocol python3-pygls)"
+        )
+
+    from debputy.lsp.lsp_features import ensure_lsp_features_are_loaded
+    from debputy.lsp.lsp_dispatch import DEBPUTY_LANGUAGE_SERVER
+
+    ensure_lsp_features_are_loaded()
+    debputy_language_server = DEBPUTY_LANGUAGE_SERVER
+
+    if parsed_args.tcp:
+        debputy_language_server.start_tcp(parsed_args.host, parsed_args.port)
+    elif parsed_args.ws:
+        debputy_language_server.start_ws(parsed_args.host, parsed_args.port)
+    else:
+        debputy_language_server.start_io()
+
+
+@lsp_command.register_subcommand(
+    "editor-config",
+    help_description="Provide editor configuration snippets",
+    argparser=[
+        add_arg(
+            "editor_name",
+            metavar="editor",
+            choices=_EDITOR_SNIPPETS,
+            help="The editor to provide a snippet for",
+        ),
+    ],
+)
+def lsp_editor_glue(context: CommandContext) -> None:
+    editor_name = context.parsed_args.editor_name
+    result = _EDITOR_SNIPPETS[editor_name]
+    while result in _EDITOR_SNIPPETS:
+        result = _EDITOR_SNIPPETS[result]
+    print(result)
+
+
+@lsp_command.register_subcommand(
+    "features",
+    help_description="Describe language ids and features",
+)
+def lsp_editor_glue(_context: CommandContext) -> None:
+    try:
+        import lsprotocol
+        import pygls
+    except ImportError:
+        _error(
+            "This feature requires lsprotocol and pygls (apt-get install python3-lsprotocol python3-pygls)"
+        )
+
+    from debputy.lsp.lsp_features import describe_lsp_features
+
+    describe_lsp_features()
+
+
+@ROOT_COMMAND.register_subcommand(
+    "lint",
+    log_only_to_stderr=True,
+    argparser=[
+        add_arg(
+            "--spellcheck",
+            dest="spellcheck",
+            action="store_true",
+            shared=True,
+            help="Enable spellchecking",
+        ),
+        add_arg(
+            "--auto-fix",
+            dest="auto_fix",
+            action="store_true",
+            shared=True,
+            help="Automatically fix problems with trivial or obvious corrections.",
+        ),
+        add_arg(
+            "--linter-exit-code",
+            dest="linter_exit_code",
+            default=True,
+            action=BooleanOptionalAction,
+            help='Enable or disable the "linter" convention of exiting with an error if severe issues were found',
+        ),
+    ],
+)
+def lint_cmd(context: CommandContext) -> None:
+    try:
+        import lsprotocol
+    except ImportError:
+        _error("This feature requires lsprotocol (apt-get install python3-lsprotocol)")
+
+    from debputy.linting.lint_impl import perform_linting
+
+    # For the side effect of validating that we are run from a debian directory.
+    context.binary_packages()
+    perform_linting(context)
+
+
+def ensure_lint_and_lsp_commands_are_loaded():
+    # Loading the module does the heavy lifting
+    # However, having this function means that we do not have an "unused" import that some tool
+    # gets tempted to remove
+    assert ROOT_COMMAND.has_command("lsp")
+    assert ROOT_COMMAND.has_command("lint")
diff --git a/src/debputy/commands/debputy_cmd/output.py b/src/debputy/commands/debputy_cmd/output.py
new file mode 100644
index 0000000..131338a
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/output.py
@@ -0,0 +1,335 @@
+import argparse
+import contextlib
+import itertools
+import os
+import re
+import shutil
+import subprocess
+import sys
+from typing import (
+    Union,
+    Sequence,
+    Iterable,
+    Iterator,
+    IO,
+    Mapping,
+    Tuple,
+    Optional,
+    Any,
+)
+
+from debputy.util import assume_not_none
+
+try:
+    import colored
+except ImportError:
+    colored = None
+
+
+def _pager() -> Optional[str]:
+    pager = os.environ.get("DEBPUTY_PAGER")
+    if pager is None:
+        pager = os.environ.get("PAGER")
+    if pager is None and shutil.which("less") is not None:
+        pager = "less"
+    return pager
+
+
+URL_START = "\033]8;;"
+URL_END = "\033]8;;\a"
+MAN_URL_REWRITE = re.compile(r"man:(\S+)[(](\d+)[)]")
+
+_SUPPORTED_COLORS = {
+    "black",
+    "red",
+    "green",
+    "yellow",
+    "blue",
+    "magenta",
+    "cyan",
+    "white",
+}
+_SUPPORTED_STYLES = {"none", "bold"}
+
+
+class OutputStylingBase:
+    def __init__(
+        self,
+        stream: IO[str],
+        output_format: str,
+        *,
+        optimize_for_screen_reader: bool = False,
+    ) -> None:
+        self.stream = stream
+        self.output_format = output_format
+        self.optimize_for_screen_reader = optimize_for_screen_reader
+        self._color_support = None
+
+    def colored(
+        self,
+        text: str,
+        *,
+        fg: Optional[Union[str]] = None,
+        bg: Optional[str] = None,
+        style: Optional[str] = None,
+    ) -> str:
+        self._check_color(fg)
+        self._check_color(bg)
+        self._check_text_style(style)
+        return text
+
+    @property
+    def supports_colors(self) -> bool:
+        return False
+
+    def print_list_table(
+        self,
+        headers: Sequence[Union[str, Tuple[str, str]]],
+        rows: Sequence[Sequence[str]],
+    ) -> None:
+        if rows:
+            if any(len(r) != len(rows[0]) for r in rows):
+                raise ValueError(
+                    "Unbalanced table: All rows must have the same column count"
+                )
+            if len(rows[0]) != len(headers):
+                raise ValueError(
+                    "Unbalanced table: header list does not agree with row list on number of columns"
+                )
+
+        if not headers:
+            raise ValueError("No headers provided!?")
+
+        cadjust = {}
+        header_names = []
+        for c in headers:
+            if isinstance(c, str):
+                header_names.append(c)
+            else:
+                cname, adjust = c
+                header_names.append(cname)
+                cadjust[cname] = adjust
+
+        if self.output_format == "csv":
+            from csv import writer
+
+            w = writer(self.stream)
+            w.writerow(header_names)
+            w.writerows(rows)
+            return
+
+        column_lengths = [
+            max((len(h), max(len(r[i]) for r in rows)))
+            for i, h in enumerate(header_names)
+        ]
+        # divider => "+---+---+-...-+"
+        divider = "+-" + "-+-".join("-" * x for x in column_lengths) + "-+"
+        # row_format => '| {:<10} | {:<8} | ... |' where the numbers are the column lengths
+        row_format_inner = " | ".join(
+            f"{{CELL_COLOR}}{{:{cadjust.get(cn, '<')}{x}}}{{CELL_COLOR_RESET}}"
+            for cn, x in zip(header_names, column_lengths)
+        )
+
+        row_format = f"| {row_format_inner} |"
+
+        if self.supports_colors:
+            c = self._color_support
+            assert c is not None
+            header_color = c.Style.bold
+            header_color_reset = c.Style.reset
+        else:
+            header_color = ""
+            header_color_reset = ""
+
+        self.print_visual_formatting(divider)
+        self.print(
+            row_format.format(
+                *header_names,
+                CELL_COLOR=header_color,
+                CELL_COLOR_RESET=header_color_reset,
+            )
+        )
+        self.print_visual_formatting(divider)
+        for row in rows:
+            self.print(row_format.format(*row, CELL_COLOR="", CELL_COLOR_RESET=""))
+        self.print_visual_formatting(divider)
+
+    def print(self, /, string: str = "", **kwargs) -> None:
+        if "file" in kwargs:
+            raise ValueError("Unsupported kwarg file")
+        print(string, file=self.stream, **kwargs)
+
+    def print_visual_formatting(self, /, format_sequence: str, **kwargs) -> None:
+        if self.optimize_for_screen_reader:
+            return
+        self.print(format_sequence, **kwargs)
+
+    def print_for_screen_reader(self, /, text: str, **kwargs) -> None:
+        if not self.optimize_for_screen_reader:
+            return
+        self.print(text, **kwargs)
+
+    def _check_color(self, color: Optional[str]) -> None:
+        if color is not None and color not in _SUPPORTED_COLORS:
+            raise ValueError(
+                f"Unsupported color: {color}. Only the following are supported {','.join(_SUPPORTED_COLORS)}"
+            )
+
+    def _check_text_style(self, style: Optional[str]) -> None:
+        if style is not None and style not in _SUPPORTED_STYLES:
+            raise ValueError(
+                f"Unsupported style: {style}. Only the following are supported {','.join(_SUPPORTED_STYLES)}"
+            )
+
+    def render_url(self, link_url: str) -> str:
+        return link_url
+
+
+class ANSIOutputStylingBase(OutputStylingBase):
+    def __init__(
+        self,
+        stream: IO[str],
+        output_format: str,
+        *,
+        support_colors: bool = True,
+        support_clickable_urls: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(stream, output_format, **kwargs)
+        self._stream = stream
+        self._color_support = colored
+        self._support_colors = (
+            support_colors if self._color_support is not None else False
+        )
+        self._support_clickable_urls = support_clickable_urls
+
+    @property
+    def supports_colors(self) -> bool:
+        return self._support_colors
+
+    def colored(
+        self,
+        text: str,
+        *,
+        fg: Optional[str] = None,
+        bg: Optional[str] = None,
+        style: Optional[str] = None,
+    ) -> str:
+        self._check_color(fg)
+        self._check_color(bg)
+        self._check_text_style(style)
+        if not self.supports_colors:
+            return text
+        _colored = self._color_support
+        codes = []
+        if style is not None:
+            code = getattr(_colored.Style, style)
+            assert code is not None
+            codes.append(code)
+        if fg is not None:
+            code = getattr(_colored.Fore, fg)
+            assert code is not None
+            codes.append(code)
+        if bg is not None:
+            code = getattr(_colored.Back, bg)
+            assert code is not None
+            codes.append(code)
+        if not codes:
+            return text
+        return "".join(codes) + text + _colored.Style.reset
+
+    def render_url(self, link_url: str) -> str:
+        if not self._support_clickable_urls:
+            return super().render_url(link_url)
+        link_text = link_url
+        if not self.optimize_for_screen_reader and link_url.startswith("man:"):
+            # Rewrite manpage to a clickable link by default. I am not sure how the hyperlink
+            # ANSI code works with screen readers, so lets not rewrite the manpage link by
+            # default. My fear is that both the link url and the link text gets read out.
+            m = MAN_URL_REWRITE.match(link_url)
+            if m:
+                page, section = m.groups()
+                link_url = f"https://manpages.debian.org/{page}.{section}"
+        return URL_START + f"{link_url}\a{link_text}" + URL_END
+
+
+def _output_styling(
+    parsed_args: argparse.Namespace,
+    stream: IO[str],
+) -> OutputStylingBase:
+    output_format = getattr(parsed_args, "output_format", None)
+    if output_format is None:
+        output_format = "text"
+    optimize_for_screen_reader = os.environ.get("OPTIMIZE_FOR_SCREEN_READER", "") != ""
+    if not stream.isatty():
+        return OutputStylingBase(
+            stream, output_format, optimize_for_screen_reader=optimize_for_screen_reader
+        )
+    return ANSIOutputStylingBase(
+        stream, output_format, optimize_for_screen_reader=optimize_for_screen_reader
+    )
+
+
+@contextlib.contextmanager
+def _stream_to_pager(
+    parsed_args: argparse.Namespace,
+) -> Iterator[Tuple[IO[str], OutputStylingBase]]:
+    fancy_output = _output_styling(parsed_args, sys.stdout)
+    if (
+        not parsed_args.pager
+        or not sys.stdout.isatty()
+        or fancy_output.output_format != "text"
+    ):
+        yield sys.stdout, fancy_output
+        return
+
+    pager = _pager()
+    if pager is None:
+        yield sys.stdout, fancy_output
+        return
+
+    env: Mapping[str, str] = os.environ
+    if "LESS" not in env:
+        env_copy = dict(os.environ)
+        env_copy["LESS"] = "-FRSXMQ"
+        env = env_copy
+
+    cmd = subprocess.Popen(
+        pager,
+        stdin=subprocess.PIPE,
+        encoding="utf-8",
+        env=env,
+    )
+    stdin = assume_not_none(cmd.stdin)
+    try:
+        fancy_output.stream = stdin
+        yield stdin, fancy_output
+    except Exception:
+        stdin.close()
+        cmd.kill()
+        cmd.wait()
+        raise
+    finally:
+        fancy_output.stream = sys.stdin
+    stdin.close()
+    cmd.wait()
+
+
+def _normalize_cell(cell: Union[str, Sequence[str]], times: int) -> Iterable[str]:
+    if isinstance(cell, str):
+        return itertools.chain([cell], itertools.repeat("", times=times - 1))
+    if not cell:
+        return itertools.repeat("", times=times)
+    return itertools.chain(cell, itertools.repeat("", times=times - len(cell)))
+
+
+def _expand_rows(
+    rows: Sequence[Sequence[Union[str, Sequence[str]]]]
+) -> Iterator[Sequence[str]]:
+    for row in rows:
+        if all(isinstance(c, str) for c in row):
+            yield row
+        else:
+            longest = max(len(c) if isinstance(c, list) else 1 for c in row)
+            cells = [_normalize_cell(c, times=longest) for c in row]
+            yield from zip(*cells)
diff --git a/src/debputy/commands/debputy_cmd/plugin_cmds.py b/src/debputy/commands/debputy_cmd/plugin_cmds.py
new file mode 100644
index 0000000..3d8bdcb
--- /dev/null
+++ b/src/debputy/commands/debputy_cmd/plugin_cmds.py
@@ -0,0 +1,1364 @@
+import argparse
+import operator
+import os
+import sys
+from itertools import chain
+from typing import (
+    Sequence,
+    Union,
+    Tuple,
+    Iterable,
+    Any,
+    Optional,
+    Type,
+    Mapping,
+    Callable,
+)
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy.commands.debputy_cmd.context import (
+    CommandContext,
+    add_arg,
+    ROOT_COMMAND,
+)
+from debputy.commands.debputy_cmd.dc_util import flatten_ppfs
+from debputy.commands.debputy_cmd.output import (
+    _stream_to_pager,
+    _output_styling,
+    OutputStylingBase,
+)
+from debputy.exceptions import DebputySubstitutionError
+from debputy.filesystem_scan import build_virtual_fs
+from debputy.manifest_parser.base_types import TypeMapping
+from debputy.manifest_parser.declarative_parser import (
+    DeclarativeMappingInputParser,
+    DeclarativeNonMappingInputParser,
+    BASIC_SIMPLE_TYPES,
+)
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import unpack_type, AttributePath
+from debputy.packager_provided_files import detect_all_packager_provided_files
+from debputy.plugin.api.example_processing import (
+    process_discard_rule_example,
+    DiscardVerdict,
+)
+from debputy.plugin.api.impl import plugin_metadata_for_debputys_own_plugin
+from debputy.plugin.api.impl_types import (
+    PackagerProvidedFileClassSpec,
+    PluginProvidedManifestVariable,
+    DispatchingParserBase,
+    DeclarativeInputParser,
+    DebputyPluginMetadata,
+    DispatchingObjectParser,
+    SUPPORTED_DISPATCHABLE_TABLE_PARSERS,
+    OPARSER_MANIFEST_ROOT,
+    PluginProvidedDiscardRule,
+    AutomaticDiscardRuleExample,
+    MetadataOrMaintscriptDetector,
+    PluginProvidedTypeMapping,
+)
+from debputy.plugin.api.spec import (
+    ParserDocumentation,
+    reference_documentation,
+    undocumented_attr,
+    TypeMappingExample,
+)
+from debputy.substitution import Substitution
+from debputy.util import _error, assume_not_none, _warn
+
+plugin_dispatcher = ROOT_COMMAND.add_dispatching_subcommand(
+    "plugin",
+    "plugin_subcommand",
+    default_subcommand="--help",
+    help_description="Interact with debputy plugins",
+    metavar="command",
+)
+
+plugin_list_cmds = plugin_dispatcher.add_dispatching_subcommand(
+    "list",
+    "plugin_subcommand_list",
+    metavar="topic",
+    default_subcommand="plugins",
+    help_description="List plugins or things provided by plugins (unstable format)."
+    " Pass `--help` *after* `list` get a topic listing",
+)
+
+plugin_show_cmds = plugin_dispatcher.add_dispatching_subcommand(
+    "show",
+    "plugin_subcommand_show",
+    metavar="topic",
+    help_description="Show details about a plugin or things provided by plugins (unstable format)."
+    " Pass `--help` *after* `show` get a topic listing",
+)
+
+
+def format_output_arg(
+    default_format: str,
+    allowed_formats: Sequence[str],
+    help_text: str,
+) -> Callable[[argparse.ArgumentParser], None]:
+    if default_format not in allowed_formats:
+        raise ValueError("The default format must be in the allowed_formats...")
+
+    def _configurator(argparser: argparse.ArgumentParser) -> None:
+        argparser.add_argument(
+            "--output-format",
+            dest="output_format",
+            default=default_format,
+            choices=allowed_formats,
+            help=help_text,
+        )
+
+    return _configurator
+
+
+# To let --output-format=... "always" work
+TEXT_ONLY_FORMAT = format_output_arg(
+    "text",
+    ["text"],
+    "Select a given output format (options and output are not stable between releases)",
+)
+
+
+TEXT_CSV_FORMAT_NO_STABILITY_PROMISE = format_output_arg(
+    "text",
+    ["text", "csv"],
+    "Select a given output format (options and output are not stable between releases)",
+)
+
+
+@plugin_list_cmds.register_subcommand(
+    "plugins",
+    help_description="List known plugins with their versions",
+    argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE,
+)
+def _plugin_cmd_list_plugins(context: CommandContext) -> None:
+    plugin_metadata_entries = context.load_plugins().plugin_data.values()
+    # Because the "plugins" part is optional, we are not guaranteed tha TEXT_CSV_FORMAT applies
+    output_format = getattr(context.parsed_args, "output_format", "text")
+    assert output_format in {"text", "csv"}
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Plugin Name", "Plugin Path"],
+            [(p.plugin_name, p.plugin_path) for p in plugin_metadata_entries],
+        )
+
+
+def _path(path: str) -> str:
+    if path.startswith("./"):
+        return path[1:]
+    return path
+
+
+def _ppf_flags(ppf: PackagerProvidedFileClassSpec) -> str:
+    flags = []
+    if ppf.allow_name_segment:
+        flags.append("named")
+    if ppf.allow_architecture_segment:
+        flags.append("arch")
+    if ppf.supports_priority:
+        flags.append(f"priority={ppf.default_priority}")
+    if ppf.packageless_is_fallback_for_all_packages:
+        flags.append("main-all-fallback")
+    if ppf.post_formatting_rewrite:
+        flags.append("post-format-hook")
+    return ",".join(flags)
+
+
+@plugin_list_cmds.register_subcommand(
+    ["used-packager-provided-files", "uppf", "u-p-p-f"],
+    help_description="List packager provided files used by this package (debian/pkg.foo)",
+    argparser=TEXT_ONLY_FORMAT,
+)
+def _plugin_cmd_list_uppf(context: CommandContext) -> None:
+    ppf_table = context.load_plugins().packager_provided_files
+    all_ppfs = detect_all_packager_provided_files(
+        ppf_table,
+        context.debian_dir,
+        context.binary_packages(),
+    )
+    requested_plugins = set(context.requested_plugins())
+    requested_plugins.add("debputy")
+    all_detected_ppfs = list(flatten_ppfs(all_ppfs))
+
+    used_ppfs = [
+        p
+        for p in all_detected_ppfs
+        if p.definition.debputy_plugin_metadata.plugin_name in requested_plugins
+    ]
+    inactive_ppfs = [
+        p
+        for p in all_detected_ppfs
+        if p.definition.debputy_plugin_metadata.plugin_name not in requested_plugins
+    ]
+
+    if not used_ppfs and not inactive_ppfs:
+        print("No packager provided files detected; not even a changelog... ?")
+        return
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        if used_ppfs:
+            headers: Sequence[Union[str, Tuple[str, str]]] = [
+                "File",
+                "Matched Stem",
+                "Installed Into",
+                "Installed As",
+            ]
+            fo.print_list_table(
+                headers,
+                [
+                    (
+                        ppf.path.path,
+                        ppf.definition.stem,
+                        ppf.package_name,
+                        "/".join(ppf.compute_dest()).lstrip("."),
+                    )
+                    for ppf in sorted(
+                        used_ppfs, key=operator.attrgetter("package_name")
+                    )
+                ],
+            )
+
+        if inactive_ppfs:
+            headers: Sequence[Union[str, Tuple[str, str]]] = [
+                "UNUSED FILE",
+                "Matched Stem",
+                "Installed Into",
+                "Could Be Installed As",
+                "If B-D Had",
+            ]
+            fo.print_list_table(
+                headers,
+                [
+                    (
+                        f"~{ppf.path.path}~",
+                        ppf.definition.stem,
+                        f"~{ppf.package_name}~",
+                        "/".join(ppf.compute_dest()).lstrip("."),
+                        f"debputy-plugin-{ppf.definition.debputy_plugin_metadata.plugin_name}",
+                    )
+                    for ppf in sorted(
+                        inactive_ppfs, key=operator.attrgetter("package_name")
+                    )
+                ],
+            )
+
+
+@plugin_list_cmds.register_subcommand(
+    ["packager-provided-files", "ppf", "p-p-f"],
+    help_description="List packager provided file definitions (debian/pkg.foo)",
+    argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE,
+)
+def _plugin_cmd_list_ppf(context: CommandContext) -> None:
+    ppfs: Iterable[PackagerProvidedFileClassSpec]
+    ppfs = context.load_plugins().packager_provided_files.values()
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        headers: Sequence[Union[str, Tuple[str, str]]] = [
+            "Stem",
+            "Installed As",
+            ("Mode", ">"),
+            "Features",
+            "Provided by",
+        ]
+        fo.print_list_table(
+            headers,
+            [
+                (
+                    ppf.stem,
+                    _path(ppf.installed_as_format),
+                    "0" + oct(ppf.default_mode)[2:],
+                    _ppf_flags(ppf),
+                    ppf.debputy_plugin_metadata.plugin_name,
+                )
+                for ppf in sorted(ppfs, key=operator.attrgetter("stem"))
+            ],
+        )
+
+        if os.path.isdir("debian/") and fo.output_format == "text":
+            fo.print()
+            fo.print(
+                "Hint: You can use `debputy plugin list used-packager-provided-files` to have `debputy`",
+            )
+            fo.print("list all the files in debian/ that matches these definitions.")
+
+
+@plugin_list_cmds.register_subcommand(
+    ["metadata-detectors"],
+    help_description="List metadata detectors",
+    argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE,
+)
+def _plugin_cmd_list_metadata_detectors(context: CommandContext) -> None:
+    mds = list(
+        chain.from_iterable(
+            context.load_plugins().metadata_maintscript_detectors.values()
+        )
+    )
+
+    def _sort_key(md: "MetadataOrMaintscriptDetector") -> Any:
+        return md.plugin_metadata.plugin_name, md.detector_id
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Provided by", "Detector Id"],
+            [
+                (md.plugin_metadata.plugin_name, md.detector_id)
+                for md in sorted(mds, key=_sort_key)
+            ],
+        )
+
+
+def _resolve_variable_for_list(
+    substitution: Substitution,
+    variable: PluginProvidedManifestVariable,
+) -> str:
+    var = "{{" + variable.variable_name + "}}"
+    try:
+        value = substitution.substitute(var, "CLI request")
+    except DebputySubstitutionError:
+        value = None
+    return _render_manifest_variable_value(value)
+
+
+def _render_manifest_variable_flag(variable: PluginProvidedManifestVariable) -> str:
+    flags = []
+    if variable.is_for_special_case:
+        flags.append("special-use-case")
+    if variable.is_internal:
+        flags.append("internal")
+    return ",".join(flags)
+
+
+def _render_list_filter(v: Optional[bool]) -> str:
+    if v is None:
+        return "N/A"
+    return "shown" if v else "hidden"
+
+
+@plugin_list_cmds.register_subcommand(
+    ["manifest-variables"],
+    help_description="List plugin provided manifest variables (such as `{{path:FOO}}`)",
+)
+def plugin_cmd_list_manifest_variables(context: CommandContext) -> None:
+    variables = context.load_plugins().manifest_variables
+    substitution = context.substitution.with_extra_substitutions(
+        PACKAGE="<package-name>"
+    )
+    parsed_args = context.parsed_args
+    show_special_case_vars = parsed_args.show_special_use_variables
+    show_token_vars = parsed_args.show_token_variables
+    show_all_vars = parsed_args.show_all_variables
+
+    def _include_var(var: PluginProvidedManifestVariable) -> bool:
+        if show_all_vars:
+            return True
+        if var.is_internal:
+            return False
+        if var.is_for_special_case and not show_special_case_vars:
+            return False
+        if var.is_token and not show_token_vars:
+            return False
+        return True
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Variable (use via: `{{ NAME }}`)", "Value", "Flag", "Provided by"],
+            [
+                (
+                    k,
+                    _resolve_variable_for_list(substitution, var),
+                    _render_manifest_variable_flag(var),
+                    var.plugin_metadata.plugin_name,
+                )
+                for k, var in sorted(variables.items())
+                if _include_var(var)
+            ],
+        )
+
+        fo.print()
+
+        filters = [
+            (
+                "Token variables",
+                show_token_vars if not show_all_vars else None,
+                "--show-token-variables",
+            ),
+            (
+                "Special use variables",
+                show_special_case_vars if not show_all_vars else None,
+                "--show-special-case-variables",
+            ),
+        ]
+
+        fo.print_list_table(
+            ["Variable type", "Value", "Option"],
+            [
+                (
+                    fname,
+                    _render_list_filter(value or show_all_vars),
+                    f"{option} OR --show-all-variables",
+                )
+                for fname, value, option in filters
+            ],
+        )
+
+
+@plugin_cmd_list_manifest_variables.configure_handler
+def list_manifest_variable_arg_parser(
+    plugin_list_manifest_variables_parser: argparse.ArgumentParser,
+) -> None:
+    plugin_list_manifest_variables_parser.add_argument(
+        "--show-special-case-variables",
+        dest="show_special_use_variables",
+        default=False,
+        action="store_true",
+        help="Show variables that are only used in special / niche cases",
+    )
+    plugin_list_manifest_variables_parser.add_argument(
+        "--show-token-variables",
+        dest="show_token_variables",
+        default=False,
+        action="store_true",
+        help="Show token (syntactical) variables like {{token:TAB}}",
+    )
+    plugin_list_manifest_variables_parser.add_argument(
+        "--show-all-variables",
+        dest="show_all_variables",
+        default=False,
+        action="store_true",
+        help="Show all variables regardless of type/kind (overrules other filter settings)",
+    )
+    TEXT_ONLY_FORMAT(plugin_list_manifest_variables_parser)
+
+
+def _parser_type_name(v: Union[str, Type[Any]]) -> str:
+    if isinstance(v, str):
+        return v if v != "<ROOT>" else ""
+    return v.__name__
+
+
+@plugin_list_cmds.register_subcommand(
+    ["plugable-manifest-rules", "p-m-r", "pmr"],
+    help_description="Plugable manifest rules (such as install rules)",
+    argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE,
+)
+def _plugin_cmd_list_manifest_rules(context: CommandContext) -> None:
+    feature_set = context.load_plugins()
+
+    # Type hint to make the chain call easier for the type checker, which does not seem
+    # to derive to this common base type on its own.
+    base_type = Iterable[Tuple[Union[str, Type[Any]], DispatchingParserBase[Any]]]
+
+    table_parsers: base_type = feature_set.dispatchable_table_parsers.items()
+    object_parsers: base_type = feature_set.dispatchable_object_parsers.items()
+
+    parsers = chain(
+        table_parsers,
+        object_parsers,
+    )
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Rule Name", "Rule Type", "Provided By"],
+            [
+                (
+                    rn,
+                    _parser_type_name(rt),
+                    pt.parser_for(rn).plugin_metadata.plugin_name,
+                )
+                for rt, pt in parsers
+                for rn in pt.registered_keywords()
+            ],
+        )
+
+
+@plugin_list_cmds.register_subcommand(
+    ["automatic-discard-rules", "a-d-r"],
+    help_description="List automatic discard rules",
+    argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE,
+)
+def _plugin_cmd_list_automatic_discard_rules(context: CommandContext) -> None:
+    auto_discard_rules = context.load_plugins().auto_discard_rules
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Name", "Provided By"],
+            [
+                (
+                    name,
+                    ppdr.plugin_metadata.plugin_name,
+                )
+                for name, ppdr in auto_discard_rules.items()
+            ],
+        )
+
+
+def _provide_placeholder_parser_doc(
+    parser_doc: Optional[ParserDocumentation],
+    attributes: Iterable[str],
+) -> ParserDocumentation:
+    if parser_doc is None:
+        parser_doc = reference_documentation()
+    changes = {}
+    if parser_doc.attribute_doc is None:
+        changes["attribute_doc"] = [undocumented_attr(attr) for attr in attributes]
+
+    if changes:
+        return parser_doc.replace(**changes)
+    return parser_doc
+
+
+def _doc_args_parser_doc(
+    rule_name: str,
+    declarative_parser: DeclarativeInputParser[Any],
+    plugin_metadata: DebputyPluginMetadata,
+) -> Tuple[Mapping[str, str], ParserDocumentation]:
+    attributes: Iterable[str]
+    if isinstance(declarative_parser, DeclarativeMappingInputParser):
+        attributes = declarative_parser.source_attributes.keys()
+    else:
+        attributes = []
+    doc_args = {
+        "RULE_NAME": rule_name,
+        "MANIFEST_FORMAT_DOC": f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md",
+        "PLUGIN_NAME": plugin_metadata.plugin_name,
+    }
+    parser_doc = _provide_placeholder_parser_doc(
+        declarative_parser.inline_reference_documentation,
+        attributes,
+    )
+    return doc_args, parser_doc
+
+
+def _render_rule(
+    rule_name: str,
+    rule_type: str,
+    declarative_parser: DeclarativeInputParser[Any],
+    plugin_metadata: DebputyPluginMetadata,
+    manifest_attribute_path: str,
+) -> None:
+    is_root_rule = rule_name == "::"
+
+    doc_args, parser_doc = _doc_args_parser_doc(
+        "the manifest root" if is_root_rule else rule_name,
+        declarative_parser,
+        plugin_metadata,
+    )
+    t = assume_not_none(parser_doc.title).format(**doc_args)
+    print(t)
+    print("=" * len(t))
+    print()
+
+    print(assume_not_none(parser_doc.description).format(**doc_args).rstrip())
+
+    print()
+    alt_form_parser = getattr(declarative_parser, "alt_form_parser", None)
+    if isinstance(
+        declarative_parser, (DeclarativeMappingInputParser, DispatchingObjectParser)
+    ):
+        if isinstance(declarative_parser, DeclarativeMappingInputParser):
+            attributes = declarative_parser.source_attributes
+            required = declarative_parser.input_time_required_parameters
+            conditionally_required = declarative_parser.at_least_one_of
+            mutually_exclusive = declarative_parser.mutually_exclusive_attributes
+        else:
+            attributes = {}
+            required = frozenset()
+            conditionally_required = frozenset()
+            mutually_exclusive = frozenset()
+        print("Attributes:")
+        attribute_docs = (
+            parser_doc.attribute_doc if parser_doc.attribute_doc is not None else []
+        )
+        for attr_doc in assume_not_none(attribute_docs):
+            attr_description = attr_doc.description
+            prefix = " - "
+
+            for parameter in sorted(attr_doc.attributes):
+                parameter_details = attributes.get(parameter)
+                if parameter_details is not None:
+                    source_name = parameter_details.source_attribute_name
+                    describe_type = parameter_details.type_validator.describe_type()
+                else:
+                    assert isinstance(declarative_parser, DispatchingObjectParser)
+                    source_name = parameter
+                    subparser = declarative_parser.parser_for(source_name).parser
+                    if isinstance(subparser, DispatchingObjectParser):
+                        rule_prefix = rule_name if rule_name != "::" else ""
+                        describe_type = f"Object (see `{rule_prefix}::{subparser.manifest_attribute_path_template}`)"
+                    elif isinstance(subparser, DeclarativeMappingInputParser):
+                        describe_type = "<Type definition not implemented yet>"  # TODO: Derive from subparser
+                    elif isinstance(subparser, DeclarativeNonMappingInputParser):
+                        describe_type = (
+                            subparser.alt_form_parser.type_validator.describe_type()
+                        )
+                    else:
+                        describe_type = f"<Unknown: Non-introspectable subparser - {subparser.__class__.__name__}>"
+
+                if source_name in required:
+                    req_str = "required"
+                elif any(source_name in s for s in conditionally_required):
+                    req_str = "conditional"
+                else:
+                    req_str = "optional"
+                print(f"{prefix}`{source_name}` ({req_str}): {describe_type}")
+                prefix = "   "
+
+            if attr_description:
+                print()
+                for line in attr_description.format(**doc_args).splitlines(
+                    keepends=False
+                ):
+                    print(f"   {line}")
+                print()
+
+        if (
+            bool(conditionally_required)
+            or bool(mutually_exclusive)
+            or any(pd.conflicting_attributes for pd in attributes.values())
+        ):
+            print()
+            print("This rule enforces the following restrictions:")
+
+            if conditionally_required:
+                for cr in conditionally_required:
+                    anames = "`, `".join(
+                        attributes[a].source_attribute_name for a in cr
+                    )
+                    if cr in mutually_exclusive:
+                        print(f" - The rule must use exactly one of: `{anames}`")
+                    else:
+                        print(f" - The rule must use at least one of: `{anames}`")
+
+            if mutually_exclusive or any(
+                pd.conflicting_attributes for pd in attributes.values()
+            ):
+                for parameter, parameter_details in sorted(attributes.items()):
+                    source_name = parameter_details.source_attribute_name
+                    conflicts = set(parameter_details.conflicting_attributes)
+                    for mx in mutually_exclusive:
+                        if parameter in mx and mx not in conditionally_required:
+                            conflicts |= mx
+                    if conflicts:
+                        conflicts.discard(parameter)
+                        cnames = "`, `".join(
+                            attributes[a].source_attribute_name for a in conflicts
+                        )
+                        print(
+                            f" - The attribute `{source_name}` cannot be used with any of: `{cnames}`"
+                        )
+        print()
+    if alt_form_parser is not None:
+        # FIXME: Mapping[str, Any] ends here, which is ironic given the headline.
+        print(f"Non-mapping format: {alt_form_parser.type_validator.describe_type()}")
+        alt_parser_desc = parser_doc.alt_parser_description
+        if alt_parser_desc:
+            for line in alt_parser_desc.format(**doc_args).splitlines(keepends=False):
+                print(f"   {line}")
+        print()
+
+    if declarative_parser.reference_documentation_url is not None:
+        print(
+            f"Reference documentation: {declarative_parser.reference_documentation_url}"
+        )
+    else:
+        print(
+            "Reference documentation: No reference documentation link provided by the plugin"
+        )
+
+    if not is_root_rule:
+        print(
+            f"Used in: {manifest_attribute_path if manifest_attribute_path != '<ROOT>' else 'The manifest root'}"
+        )
+        print(f"Rule reference: {rule_type}::{rule_name}")
+        print(f"Plugin: {plugin_metadata.plugin_name}")
+    else:
+        print(f"Rule reference: {rule_name}")
+
+    print()
+    print(
+        "PS: If you want to know more about a non-trivial type of an attribute such as `FileSystemMatchRule`,"
+    )
+    print(
+        "you can use `debputy plugin show type-mapping FileSystemMatchRule` to look it up "
+    )
+
+
+def _render_manifest_variable_value(v: Optional[str]) -> str:
+    if v is None:
+        return "(N/A: Cannot resolve the variable)"
+    v = v.replace("\n", "\\n").replace("\t", "\\t")
+    return v
+
+
+def _render_multiline_documentation(
+    documentation: str,
+    *,
+    first_line_prefix: str = "Documentation: ",
+    following_line_prefix: str = " ",
+) -> None:
+    current_prefix = first_line_prefix
+    for line in documentation.splitlines(keepends=False):
+        if line.isspace():
+            if not current_prefix.isspace():
+                print(current_prefix.rstrip())
+                current_prefix = following_line_prefix
+            else:
+                print()
+            continue
+        print(f"{current_prefix}{line}")
+        current_prefix = following_line_prefix
+
+
+@plugin_show_cmds.register_subcommand(
+    ["manifest-variables"],
+    help_description="Plugin provided manifest variables (such as `{{path:FOO}}`)",
+    argparser=add_arg(
+        "manifest_variable",
+        metavar="manifest-variable",
+        help="Name of the variable (such as `path:FOO` or `{{path:FOO}}`) to display details about",
+    ),
+)
+def _plugin_cmd_show_manifest_variables(context: CommandContext) -> None:
+    plugin_feature_set = context.load_plugins()
+    variables = plugin_feature_set.manifest_variables
+    substitution = context.substitution
+    parsed_args = context.parsed_args
+    variable_name = parsed_args.manifest_variable
+    fo = _output_styling(context.parsed_args, sys.stdout)
+    if variable_name.startswith("{{") and variable_name.endswith("}}"):
+        variable_name = variable_name[2:-2]
+    variable: Optional[PluginProvidedManifestVariable]
+    if variable_name.startswith("env:") and len(variable_name) > 4:
+        env_var = variable_name[4:]
+        variable = PluginProvidedManifestVariable(
+            plugin_feature_set.plugin_data["debputy"],
+            variable_name,
+            variable_value=None,
+            is_context_specific_variable=False,
+            is_documentation_placeholder=True,
+            variable_reference_documentation=f'Environment variable "{env_var}"',
+        )
+    else:
+        variable = variables.get(variable_name)
+    if variable is None:
+        _error(
+            f'Cannot resolve "{variable_name}" as a known variable from any of the available'
+            f" plugins. Please use `debputy plugin list manifest-variables` to list all known"
+            f" provided variables."
+        )
+
+    var_with_braces = "{{" + variable_name + "}}"
+    try:
+        source_value = substitution.substitute(var_with_braces, "CLI request")
+    except DebputySubstitutionError:
+        source_value = None
+    binary_value = source_value
+    print(f"Variable: {variable_name}")
+    fo.print_visual_formatting(f"=========={'=' * len(variable_name)}")
+    print()
+
+    if variable.is_context_specific_variable:
+        try:
+            binary_value = substitution.with_extra_substitutions(
+                PACKAGE="<package-name>",
+            ).substitute(var_with_braces, "CLI request")
+        except DebputySubstitutionError:
+            binary_value = None
+
+    doc = variable.variable_reference_documentation or "No documentation provided"
+    _render_multiline_documentation(doc)
+
+    if source_value == binary_value:
+        print(f"Resolved: {_render_manifest_variable_value(source_value)}")
+    else:
+        print("Resolved:")
+        print(f"    [source context]: {_render_manifest_variable_value(source_value)}")
+        print(f"    [binary context]: {_render_manifest_variable_value(binary_value)}")
+
+    if variable.is_for_special_case:
+        print(
+            'Special-case: The variable has been marked as a "special-case"-only variable.'
+        )
+
+    if not variable.is_documentation_placeholder:
+        print(f"Plugin: {variable.plugin_metadata.plugin_name}")
+
+    if variable.is_internal:
+        print()
+        # I knew everything I felt was showing on my face, and I hate that. I grated out,
+        print("That was private.")
+
+
+def _determine_ppf(
+    context: CommandContext,
+) -> Tuple[PackagerProvidedFileClassSpec, bool]:
+    feature_set = context.load_plugins()
+    ppf_name = context.parsed_args.ppf_name
+    try:
+        return feature_set.packager_provided_files[ppf_name], False
+    except KeyError:
+        pass
+
+    orig_ppf_name = ppf_name
+    if (
+        ppf_name.startswith("d/")
+        and not os.path.lexists(ppf_name)
+        and os.path.lexists("debian/" + ppf_name[2:])
+    ):
+        ppf_name = "debian/" + ppf_name[2:]
+
+    if ppf_name in ("debian/control", "debian/debputy.manifest", "debian/rules"):
+        if ppf_name == "debian/debputy.manifest":
+            doc = f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md"
+        else:
+            doc = "Debian Policy Manual or a packaging tutorial"
+        _error(
+            f"Sorry. While {orig_ppf_name} is a well-defined packaging file, it does not match the definition of"
+            f" a packager provided file. Please see {doc} for more information about this file"
+        )
+
+    if context.has_dctrl_file and os.path.lexists(ppf_name):
+        basename = ppf_name[7:]
+        if "/" not in basename:
+            debian_dir = build_virtual_fs([basename])
+            all_ppfs = detect_all_packager_provided_files(
+                feature_set.packager_provided_files,
+                debian_dir,
+                context.binary_packages(),
+            )
+            if all_ppfs:
+                matched = next(iter(all_ppfs.values()))
+                if len(matched.auto_installable) == 1 and not matched.reserved_only:
+                    return matched.auto_installable[0].definition, True
+                if not matched.auto_installable and len(matched.reserved_only) == 1:
+                    reserved = next(iter(matched.reserved_only.values()))
+                    if len(reserved) == 1:
+                        return reserved[0].definition, True
+
+    _error(
+        f'Unknown packager provided file "{orig_ppf_name}". Please use'
+        f" `debputy plugin list packager-provided-files` to see them all."
+    )
+
+
+@plugin_show_cmds.register_subcommand(
+    ["packager-provided-files", "ppf", "p-p-f"],
+    help_description="Show details about a given packager provided file (debian/pkg.foo)",
+    argparser=add_arg(
+        "ppf_name",
+        metavar="name",
+        help="Name of the packager provided file (such as `changelog`) to display details about",
+    ),
+)
+def _plugin_cmd_show_ppf(context: CommandContext) -> None:
+    ppf, matched_file = _determine_ppf(context)
+
+    fo = _output_styling(context.parsed_args, sys.stdout)
+
+    fo.print(f"Packager Provided File: {ppf.stem}")
+    fo.print_visual_formatting(f"========================{'=' * len(ppf.stem)}")
+    fo.print()
+    ref_doc = ppf.reference_documentation
+    description = ref_doc.description if ref_doc else None
+    doc_uris = ref_doc.format_documentation_uris if ref_doc else tuple()
+    if description is None:
+        fo.print(
+            f"Sorry, no description provided by the plugin {ppf.debputy_plugin_metadata.plugin_name}."
+        )
+    else:
+        for line in description.splitlines(keepends=False):
+            fo.print(line)
+
+    fo.print()
+    fo.print("Features:")
+    if ppf.packageless_is_fallback_for_all_packages:
+        fo.print(f" * debian/{ppf.stem} is used for *ALL* packages")
+    else:
+        fo.print(f' * debian/{ppf.stem} is used for only for the "main" package')
+    if ppf.allow_name_segment:
+        fo.print(" * Supports naming segment (multiple files and custom naming).")
+    else:
+        fo.print(
+            " * No naming support; at most one per package and it is named after the package."
+        )
+    if ppf.allow_architecture_segment:
+        fo.print(" * Supports architecture specific variants.")
+    else:
+        fo.print(" * No architecture specific variants.")
+    if ppf.supports_priority:
+        fo.print(
+            f" * Has a priority system (default priority: {ppf.default_priority})."
+        )
+
+    fo.print()
+    fo.print("Examples matches:")
+
+    if context.has_dctrl_file:
+        first_pkg = next(iter(context.binary_packages()))
+    else:
+        first_pkg = "example-package"
+    example_files = [
+        (f"debian/{ppf.stem}", first_pkg),
+        (f"debian/{first_pkg}.{ppf.stem}", first_pkg),
+    ]
+    if ppf.allow_name_segment:
+        example_files.append(
+            (f"debian/{first_pkg}.my.custom.name.{ppf.stem}", "my.custom.name")
+        )
+    if ppf.allow_architecture_segment:
+        example_files.append((f"debian/{first_pkg}.{ppf.stem}.amd64", first_pkg)),
+        if ppf.allow_name_segment:
+            example_files.append(
+                (
+                    f"debian/{first_pkg}.my.custom.name.{ppf.stem}.amd64",
+                    "my.custom.name",
+                )
+            )
+    fs_root = build_virtual_fs([x for x, _ in example_files])
+    priority = ppf.default_priority if ppf.supports_priority else None
+    rendered_examples = []
+    for example_file, assigned_name in example_files:
+        example_path = fs_root.lookup(example_file)
+        assert example_path is not None and example_path.is_file
+        dest = ppf.compute_dest(
+            assigned_name,
+            owning_package=first_pkg,
+            assigned_priority=priority,
+            path=example_path,
+        )
+        dest_path = "/".join(dest).lstrip(".")
+        rendered_examples.append((example_file, dest_path))
+
+    fo.print_list_table(["Source file", "Installed As"], rendered_examples)
+
+    if doc_uris:
+        fo.print()
+        fo.print("Documentation URIs:")
+        for uri in doc_uris:
+            fo.print(f" * {fo.render_url(uri)}")
+
+    plugin_name = ppf.debputy_plugin_metadata.plugin_name
+    fo.print()
+    fo.print(f"Install Mode: 0{oct(ppf.default_mode)[2:]}")
+    fo.print(f"Provided by plugin: {plugin_name}")
+    if (
+        matched_file
+        and plugin_name != "debputy"
+        and plugin_name not in context.requested_plugins()
+    ):
+        fo.print()
+        _warn(
+            f"The file might *NOT* be used due to missing Build-Depends on debputy-plugin-{plugin_name}"
+        )
+
+
+@plugin_show_cmds.register_subcommand(
+    ["plugable-manifest-rules", "p-m-r", "pmr"],
+    help_description="Plugable manifest rules (such as install rules)",
+    argparser=add_arg(
+        "pmr_rule_name",
+        metavar="rule-name",
+        help="Name of the rule (such as `install`) to display details about",
+    ),
+)
+def _plugin_cmd_show_manifest_rule(context: CommandContext) -> None:
+    feature_set = context.load_plugins()
+    parsed_args = context.parsed_args
+    req_rule_type = None
+    rule_name = parsed_args.pmr_rule_name
+    if "::" in rule_name and rule_name != "::":
+        req_rule_type, rule_name = rule_name.split("::", 1)
+
+    matched = []
+
+    base_type = Iterable[Tuple[Union[str, Type[Any]], DispatchingParserBase[Any]]]
+    table_parsers: base_type = feature_set.dispatchable_table_parsers.items()
+    object_parsers: base_type = feature_set.dispatchable_object_parsers.items()
+
+    parsers = chain(
+        table_parsers,
+        object_parsers,
+    )
+
+    for rule_type, dispatching_parser in parsers:
+        if req_rule_type is not None and req_rule_type not in _parser_type_name(
+            rule_type
+        ):
+            continue
+        if dispatching_parser.is_known_keyword(rule_name):
+            matched.append((rule_type, dispatching_parser))
+
+    if len(matched) != 1 and (matched or rule_name != "::"):
+        if not matched:
+            _error(
+                f"Could not find any plugable manifest rule related to {parsed_args.pmr_rule_name}."
+                f" Please use `debputy plugin list plugable-manifest-rules` to see the list of rules."
+            )
+        match_a = matched[0][0]
+        match_b = matched[1][0]
+        _error(
+            f"The name {rule_name} was ambiguous and matched multiple rule types.  Please use"
+            f" <rule-type>::{rule_name} to clarify which rule to use"
+            f" (such as {_parser_type_name(match_a)}::{rule_name} or {_parser_type_name(match_b)}::{rule_name})."
+            f" Please use `debputy plugin list plugable-manifest-rules` to see the list of rules."
+        )
+
+    if matched:
+        rule_type, matched_dispatching_parser = matched[0]
+        plugin_provided_parser = matched_dispatching_parser.parser_for(rule_name)
+        if isinstance(rule_type, str):
+            manifest_attribute_path = rule_type
+        else:
+            manifest_attribute_path = SUPPORTED_DISPATCHABLE_TABLE_PARSERS[rule_type]
+        parser_type_name = _parser_type_name(rule_type)
+        parser = plugin_provided_parser.parser
+        plugin_metadata = plugin_provided_parser.plugin_metadata
+    else:
+        rule_name = "::"
+        parser = feature_set.dispatchable_object_parsers[OPARSER_MANIFEST_ROOT]
+        parser_type_name = ""
+        plugin_metadata = plugin_metadata_for_debputys_own_plugin()
+        manifest_attribute_path = ""
+
+    _render_rule(
+        rule_name,
+        parser_type_name,
+        parser,
+        plugin_metadata,
+        manifest_attribute_path,
+    )
+
+
+def _render_discard_rule_example(
+    fo: OutputStylingBase,
+    discard_rule: PluginProvidedDiscardRule,
+    example: AutomaticDiscardRuleExample,
+) -> None:
+    processed = process_discard_rule_example(discard_rule, example)
+
+    if processed.inconsistent_paths:
+        plugin_name = discard_rule.plugin_metadata.plugin_name
+        _warn(
+            f"This example is inconsistent with what the code actually does."
+            f" Please consider filing a bug against the plugin {plugin_name}"
+        )
+
+    doc = example.description
+    if doc:
+        print(doc)
+
+    print("Consider the following source paths matched by a glob or directory match:")
+    print()
+    if fo.optimize_for_screen_reader:
+        for p, _ in processed.rendered_paths:
+            path_name = p.absolute
+            print(
+                f"The path {path_name} is a {'directory' if p.is_dir else 'file or symlink.'}"
+            )
+
+        print()
+        if any(v.is_consistent and v.is_discarded for _, v in processed.rendered_paths):
+            print("The following paths will be discarded by this rule:")
+            for p, verdict in processed.rendered_paths:
+                path_name = p.absolute
+                if verdict.is_consistent and verdict.is_discarded:
+                    print()
+                    if p.is_dir:
+                        print(f"{path_name} along with anything beneath it")
+                    else:
+                        print(path_name)
+        else:
+            print("No paths will be discarded in this example.")
+
+        print()
+        if any(v.is_consistent and v.is_kept for _, v in processed.rendered_paths):
+            print("The following paths will be not be discarded by this rule:")
+            for p, verdict in processed.rendered_paths:
+                path_name = p.absolute
+                if verdict.is_consistent and verdict.is_kept:
+                    print()
+                    print(path_name)
+
+        if any(not v.is_consistent for _, v in processed.rendered_paths):
+            print()
+            print(
+                "The example was inconsistent with the code. These are the paths where the code disagrees with"
+                " the provided example:"
+            )
+            for p, verdict in processed.rendered_paths:
+                path_name = p.absolute
+                if not verdict.is_consistent:
+                    print()
+                    if verdict == DiscardVerdict.DISCARDED_BY_CODE:
+                        print(
+                            f"The path {path_name} was discarded by the code, but the example said it should"
+                            f" have been installed."
+                        )
+                    else:
+                        print(
+                            f"The path {path_name} was not discarded by the code, but the example said it should"
+                            f" have been discarded."
+                        )
+        return
+
+    # Add +1 for dirs because we want trailing slashes in the output
+    max_len = max(
+        (len(p.absolute) + (1 if p.is_dir else 0)) for p, _ in processed.rendered_paths
+    )
+    for p, verdict in processed.rendered_paths:
+        path_name = p.absolute
+        if p.is_dir:
+            path_name += "/"
+
+        if not verdict.is_consistent:
+            print(f"    {path_name:<{max_len}}  !! {verdict.message}")
+        elif verdict.is_discarded:
+            print(f"    {path_name:<{max_len}}  << {verdict.message}")
+        else:
+            print(f"    {path_name:<{max_len}}")
+
+
+def _render_discard_rule(
+    context: CommandContext,
+    discard_rule: PluginProvidedDiscardRule,
+) -> None:
+    fo = _output_styling(context.parsed_args, sys.stdout)
+    print(fo.colored(f"Automatic Discard Rule: {discard_rule.name}", style="bold"))
+    fo.print_visual_formatting(
+        f"========================{'=' * len(discard_rule.name)}"
+    )
+    print()
+    doc = discard_rule.reference_documentation or "No documentation provided"
+    _render_multiline_documentation(doc, first_line_prefix="", following_line_prefix="")
+
+    if len(discard_rule.examples) > 1:
+        print()
+        fo.print_visual_formatting("Examples")
+        fo.print_visual_formatting("--------")
+        print()
+        for no, example in enumerate(discard_rule.examples, start=1):
+            print(
+                fo.colored(
+                    f"Example {no} of {len(discard_rule.examples)}", style="bold"
+                )
+            )
+            fo.print_visual_formatting(f"........{'.' * len(str(no))}")
+            _render_discard_rule_example(fo, discard_rule, example)
+    elif discard_rule.examples:
+        print()
+        print(fo.colored("Example", style="bold"))
+        fo.print_visual_formatting("-------")
+        print()
+        _render_discard_rule_example(fo, discard_rule, discard_rule.examples[0])
+
+
+@plugin_show_cmds.register_subcommand(
+    ["automatic-discard-rules", "a-d-r"],
+    help_description="Plugable manifest rules (such as install rules)",
+    argparser=add_arg(
+        "discard_rule",
+        metavar="automatic-discard-rule",
+        help="Name of the automatic discard rule (such as `backup-files`)",
+    ),
+)
+def _plugin_cmd_show_automatic_discard_rules(context: CommandContext) -> None:
+    auto_discard_rules = context.load_plugins().auto_discard_rules
+    name = context.parsed_args.discard_rule
+    discard_rule = auto_discard_rules.get(name)
+    if discard_rule is None:
+        _error(
+            f'No automatic discard rule with the name "{name}". Please use'
+            f" `debputy plugin list automatic-discard-rules` to see the list of automatic discard rules"
+        )
+
+    _render_discard_rule(context, discard_rule)
+
+
+def _render_source_type(t: Any) -> str:
+    _, origin_type, args = unpack_type(t, False)
+    if origin_type == Union:
+        at = ", ".join(_render_source_type(st) for st in args)
+        return f"One of: {at}"
+    name = BASIC_SIMPLE_TYPES.get(t)
+    if name is not None:
+        return name
+    try:
+        return t.__name__
+    except AttributeError:
+        return str(t)
+
+
+@plugin_list_cmds.register_subcommand(
+    "type-mappings",
+    help_description="Registered type mappings/descriptions",
+)
+def _plugin_cmd_list_type_mappings(context: CommandContext) -> None:
+    type_mappings = context.load_plugins().mapped_types
+
+    with _stream_to_pager(context.parsed_args) as (fd, fo):
+        fo.print_list_table(
+            ["Type", "Base Type", "Provided By"],
+            [
+                (
+                    target_type.__name__,
+                    _render_source_type(type_mapping.mapped_type.source_type),
+                    type_mapping.plugin_metadata.plugin_name,
+                )
+                for target_type, type_mapping in type_mappings.items()
+            ],
+        )
+
+
+@plugin_show_cmds.register_subcommand(
+    "type-mappings",
+    help_description="Register type mappings/descriptions",
+    argparser=add_arg(
+        "type_mapping",
+        metavar="type-mapping",
+        help="Name of the type",
+    ),
+)
+def _plugin_cmd_show_type_mappings(context: CommandContext) -> None:
+    type_mapping_name = context.parsed_args.type_mapping
+    type_mappings = context.load_plugins().mapped_types
+
+    matches = []
+    for type_ in type_mappings:
+        if type_.__name__ == type_mapping_name:
+            matches.append(type_)
+
+    if not matches:
+        simple_types = set(BASIC_SIMPLE_TYPES.values())
+        simple_types.update(t.__name__ for t in BASIC_SIMPLE_TYPES)
+
+        if type_mapping_name in simple_types:
+            print(f"The type {type_mapping_name} is a YAML scalar.")
+            return
+        if type_mapping_name == "Any":
+            print(
+                "The Any type is a placeholder for when no typing information is provided. Often this implies"
+                " custom parse logic."
+            )
+            return
+
+        if type_mapping_name in ("List", "list"):
+            print(
+                f"The {type_mapping_name} is a YAML Sequence. Please see the YAML documentation for examples."
+            )
+            return
+
+        if type_mapping_name in ("Mapping", "dict"):
+            print(
+                f"The {type_mapping_name} is a YAML mapping. Please see the YAML documentation for examples."
+            )
+            return
+
+        if "[" in type_mapping_name:
+            _error(
+                f"No known matches for {type_mapping_name}. Note: It looks like a composite type. Try searching"
+                " for its component parts. As an example, replace List[FileSystemMatchRule] with FileSystemMatchRule."
+            )
+
+        _error(f"Sorry, no known matches for {type_mapping_name}")
+
+    if len(matches) > 1:
+        _error(
+            f"Too many matches for {type_mapping_name}... Sorry, there is no way to avoid this right now :'("
+        )
+
+    match = matches[0]
+    _render_type(context, type_mappings[match])
+
+
+def _render_type_example(
+    context: CommandContext,
+    fo: OutputStylingBase,
+    parser_context: ParserContextData,
+    type_mapping: TypeMapping[Any, Any],
+    example: TypeMappingExample,
+) -> Tuple[str, bool]:
+    attr_path = AttributePath.builtin_path()["CLI Request"]
+    v = _render_value(example.source_input)
+    try:
+        type_mapping.mapper(
+            example.source_input,
+            attr_path,
+            parser_context,
+        )
+    except RuntimeError:
+        if context.parsed_args.debug_mode:
+            raise
+        fo.print(
+            fo.colored("Broken example: ", fg="red")
+            + f"Provided example input ({v})"
+            + " caused an exception when parsed. Please file a bug against the plugin."
+            + " Use --debug to see the stack trace"
+        )
+        return fo.colored(v, fg="red") + " [Example value could not be parsed]", True
+    return fo.colored(v, fg="green"), False
+
+
+def _render_type(
+    context: CommandContext,
+    pptm: PluginProvidedTypeMapping,
+) -> None:
+    fo = _output_styling(context.parsed_args, sys.stdout)
+    type_mapping = pptm.mapped_type
+    target_type = type_mapping.target_type
+    ref_doc = pptm.reference_documentation
+    desc = ref_doc.description if ref_doc is not None else None
+    examples = ref_doc.examples if ref_doc is not None else tuple()
+
+    fo.print(fo.colored(f"# Type Mapping: {target_type.__name__}", style="bold"))
+    fo.print()
+    if desc is not None:
+        _render_multiline_documentation(
+            desc, first_line_prefix="", following_line_prefix=""
+        )
+    else:
+        fo.print("No documentation provided.")
+
+    context.parse_manifest()
+
+    manifest_parser = context.manifest_parser()
+
+    if examples:
+        had_issues = False
+        fo.print()
+        fo.print(fo.colored("## Example values", style="bold"))
+        fo.print()
+        for no, example in enumerate(examples, start=1):
+            v, i = _render_type_example(
+                context, fo, manifest_parser, type_mapping, example
+            )
+            fo.print(f" * {v}")
+            if i:
+                had_issues = True
+    else:
+        had_issues = False
+
+    fo.print()
+    fo.print(f"Provided by plugin: {pptm.plugin_metadata.plugin_name}")
+
+    if had_issues:
+        fo.print()
+        fo.print(
+            fo.colored(
+                "Examples had issues. Please file a bug against the plugin", fg="red"
+            )
+        )
+        fo.print()
+        fo.print("Use --debug to see the stacktrace")
+
+
+def _render_value(v: Any) -> str:
+    if isinstance(v, str) and '"' not in v:
+        return f'"{v}"'
+    return str(v)
+
+
+def ensure_plugin_commands_are_loaded():
+    # Loading the module does the heavy lifting
+    # However, having this function means that we do not have an "unused" import that some tool
+    # gets tempted to remove
+    assert ROOT_COMMAND.has_command("plugin")
diff --git a/src/debputy/deb_packaging_support.py b/src/debputy/deb_packaging_support.py
new file mode 100644
index 0000000..4cb4e8f
--- /dev/null
+++ b/src/debputy/deb_packaging_support.py
@@ -0,0 +1,1489 @@
+import collections
+import contextlib
+import dataclasses
+import datetime
+import functools
+import hashlib
+import itertools
+import operator
+import os
+import re
+import subprocess
+import tempfile
+import textwrap
+from contextlib import ExitStack
+from tempfile import mkstemp
+from typing import (
+    Iterable,
+    List,
+    Optional,
+    Set,
+    Dict,
+    Sequence,
+    Tuple,
+    Iterator,
+    Literal,
+    TypeVar,
+    FrozenSet,
+    cast,
+)
+
+import debian.deb822
+from debian.changelog import Changelog
+from debian.deb822 import Deb822
+
+from debputy._deb_options_profiles import DebBuildOptionsAndProfiles
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.debhelper_emulation import (
+    dhe_install_pkg_file_as_ctrl_file_if_present,
+    dhe_dbgsym_root_dir,
+)
+from debputy.elf_util import find_all_elf_files, ELF_MAGIC
+from debputy.exceptions import DebputyDpkgGensymbolsError
+from debputy.filesystem_scan import FSPath, FSROOverlay
+from debputy.highlevel_manifest import (
+    HighLevelManifest,
+    PackageTransformationDefinition,
+    BinaryPackageData,
+)
+from debputy.maintscript_snippet import (
+    ALL_CONTROL_SCRIPTS,
+    MaintscriptSnippetContainer,
+    STD_CONTROL_SCRIPTS,
+)
+from debputy.packages import BinaryPackage, SourcePackage
+from debputy.packaging.alternatives import process_alternatives
+from debputy.packaging.debconf_templates import process_debconf_templates
+from debputy.packaging.makeshlibs import (
+    compute_shlibs,
+    ShlibsContent,
+    generate_shlib_dirs,
+)
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.plugin.api.impl import ServiceRegistryImpl
+from debputy.plugin.api.impl_types import (
+    MetadataOrMaintscriptDetector,
+    PackageDataTable,
+)
+from debputy.plugin.api.spec import (
+    FlushableSubstvars,
+    VirtualPath,
+    PackageProcessingContext,
+)
+from debputy.util import (
+    _error,
+    ensure_dir,
+    assume_not_none,
+    perl_module_dirs,
+    perlxs_api_dependency,
+    detect_fakeroot,
+    grouper,
+    _info,
+    xargs,
+    escape_shell,
+    generated_content_dir,
+    print_command,
+    _warn,
+)
+
+VP = TypeVar("VP", bound=VirtualPath, covariant=True)
+
+_T64_REGEX = re.compile("^lib.*t64(?:-nss)?$")
+_T64_PROVIDES = "t64:Provides"
+
+
+def generate_md5sums_file(control_output_dir: str, fs_root: VirtualPath) -> None:
+    conffiles = os.path.join(control_output_dir, "conffiles")
+    md5sums = os.path.join(control_output_dir, "md5sums")
+    exclude = set()
+    if os.path.isfile(conffiles):
+        with open(conffiles, "rt") as fd:
+            for line in fd:
+                if not line.startswith("/"):
+                    continue
+                exclude.add("." + line.rstrip("\n"))
+    had_content = False
+    files = sorted(
+        (
+            path
+            for path in fs_root.all_paths()
+            if path.is_file and path.path not in exclude
+        ),
+        # Sort in the same order as dh_md5sums, which is not quite the same as dpkg/`all_paths()`
+        # Compare `.../doc/...` vs `.../doc-base/...` if you want to see the difference between
+        # the two approaches.
+        key=lambda p: p.path,
+    )
+    with open(md5sums, "wt") as md5fd:
+        for member in files:
+            path = member.path
+            assert path.startswith("./")
+            path = path[2:]
+            with member.open(byte_io=True) as f:
+                file_hash = hashlib.md5()
+                while chunk := f.read(8192):
+                    file_hash.update(chunk)
+            had_content = True
+            md5fd.write(f"{file_hash.hexdigest()}  {path}\n")
+    if not had_content:
+        os.unlink(md5sums)
+
+
+def install_or_generate_conffiles(
+    binary_package: BinaryPackage,
+    root_dir: str,
+    fs_root: VirtualPath,
+    debian_dir: VirtualPath,
+) -> None:
+    conffiles_dest = os.path.join(root_dir, "conffiles")
+    dhe_install_pkg_file_as_ctrl_file_if_present(
+        debian_dir,
+        binary_package,
+        "conffiles",
+        root_dir,
+        0o0644,
+    )
+    etc_dir = fs_root.lookup("etc")
+    if etc_dir:
+        _add_conffiles(conffiles_dest, (p for p in etc_dir.all_paths() if p.is_file))
+    if os.path.isfile(conffiles_dest):
+        os.chmod(conffiles_dest, 0o0644)
+
+
+PERL_DEP_PROGRAM = 1
+PERL_DEP_INDEP_PM_MODULE = 2
+PERL_DEP_XS_MODULE = 4
+PERL_DEP_ARCH_PM_MODULE = 8
+PERL_DEP_MA_ANY_INCOMPATIBLE_TYPES = ~(PERL_DEP_PROGRAM | PERL_DEP_INDEP_PM_MODULE)
+
+
+@functools.lru_cache(2)  # In practice, param will be "perl" or "perl-base"
+def _dpkg_perl_version(package: str) -> str:
+    dpkg_version = None
+    lines = (
+        subprocess.check_output(["dpkg", "-s", package])
+        .decode("utf-8")
+        .splitlines(keepends=False)
+    )
+    for line in lines:
+        if line.startswith("Version: "):
+            dpkg_version = line[8:].strip()
+            break
+    assert dpkg_version is not None
+    return dpkg_version
+
+
+def handle_perl_code(
+    dctrl_bin: BinaryPackage,
+    dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+    fs_root: FSPath,
+    substvars: FlushableSubstvars,
+) -> None:
+    known_perl_inc_dirs = perl_module_dirs(dpkg_architecture_variables, dctrl_bin)
+    detected_dep_requirements = 0
+
+    # MakeMaker always makes lib and share dirs, but typically only one directory is actually used.
+    for perl_inc_dir in known_perl_inc_dirs:
+        p = fs_root.lookup(perl_inc_dir)
+        if p and p.is_dir:
+            p.prune_if_empty_dir()
+
+    # FIXME: 80% of this belongs in a metadata detector, but that requires us to expose .walk() in the public API,
+    #  which will not be today.
+    for d, pm_mode in [
+        (known_perl_inc_dirs.vendorlib, PERL_DEP_INDEP_PM_MODULE),
+        (known_perl_inc_dirs.vendorarch, PERL_DEP_ARCH_PM_MODULE),
+    ]:
+        inc_dir = fs_root.lookup(d)
+        if not inc_dir:
+            continue
+        for path in inc_dir.all_paths():
+            if not path.is_file:
+                continue
+            if path.name.endswith(".so"):
+                detected_dep_requirements |= PERL_DEP_XS_MODULE
+            elif path.name.endswith(".pm"):
+                detected_dep_requirements |= pm_mode
+
+    for path, children in fs_root.walk():
+        if path.path == "./usr/share/doc":
+            children.clear()
+            continue
+        if (
+            not path.is_file
+            or not path.has_fs_path
+            or not (path.is_executable or path.name.endswith(".pl"))
+        ):
+            continue
+
+        interpreter = path.interpreter()
+        if interpreter is not None and interpreter.command_full_basename == "perl":
+            detected_dep_requirements |= PERL_DEP_PROGRAM
+
+    if not detected_dep_requirements:
+        return
+    dpackage = "perl"
+    # FIXME: Currently, dh_perl supports perl-base via manual toggle.
+
+    dependency = dpackage
+    if not (detected_dep_requirements & PERL_DEP_MA_ANY_INCOMPATIBLE_TYPES):
+        dependency += ":any"
+
+    if detected_dep_requirements & PERL_DEP_XS_MODULE:
+        dpkg_version = _dpkg_perl_version(dpackage)
+        dependency += f" (>= {dpkg_version})"
+    substvars.add_dependency("perl:Depends", dependency)
+
+    if detected_dep_requirements & (PERL_DEP_XS_MODULE | PERL_DEP_ARCH_PM_MODULE):
+        substvars.add_dependency("perl:Depends", perlxs_api_dependency())
+
+
+def usr_local_transformation(dctrl: BinaryPackage, fs_root: VirtualPath) -> None:
+    path = fs_root.lookup("./usr/local")
+    if path and any(path.iterdir):
+        # There are two key issues:
+        #  1) Getting the generated maintscript carried on to the final maintscript
+        #  2) Making sure that manifest created directories do not trigger the "unused error".
+        _error(
+            f"Replacement of /usr/local paths is currently not supported in debputy (triggered by: {dctrl.name})."
+        )
+
+
+def _find_and_analyze_systemd_service_files(
+    fs_root: VirtualPath,
+    systemd_service_dir: Literal["system", "user"],
+) -> Iterable[VirtualPath]:
+    service_dirs = [
+        f"./usr/lib/systemd/{systemd_service_dir}",
+        f"./lib/systemd/{systemd_service_dir}",
+    ]
+    aliases: Dict[str, List[str]] = collections.defaultdict(list)
+    seen = set()
+    all_files = []
+
+    for d in service_dirs:
+        system_dir = fs_root.lookup(d)
+        if not system_dir:
+            continue
+        for child in system_dir.iterdir:
+            if child.is_symlink:
+                dest = os.path.basename(child.readlink())
+                aliases[dest].append(child.name)
+            elif child.is_file and child.name not in seen:
+                seen.add(child.name)
+                all_files.append(child)
+
+    return all_files
+
+
+def detect_systemd_user_service_files(
+    dctrl: BinaryPackage,
+    fs_root: VirtualPath,
+) -> None:
+    for service_file in _find_and_analyze_systemd_service_files(fs_root, "user"):
+        _error(
+            f'Sorry, systemd user services files are not supported at the moment (saw "{service_file.path}"'
+            f" in {dctrl.name})"
+        )
+
+
+# Generally, this should match the release date of oldstable or oldoldstable
+_DCH_PRUNE_CUT_OFF_DATE = datetime.date(2019, 7, 6)
+_DCH_MIN_NUM_OF_ENTRIES = 4
+
+
+def _prune_dch_file(
+    package: BinaryPackage,
+    path: VirtualPath,
+    is_changelog: bool,
+    keep_versions: Optional[Set[str]],
+    *,
+    trim: bool = True,
+) -> Tuple[bool, Optional[Set[str]]]:
+    # TODO: Process `d/changelog` once
+    # Note we cannot assume that changelog_file is always `d/changelog` as you can have
+    # per-package changelogs.
+    with path.open() as fd:
+        dch = Changelog(fd)
+    shortened = False
+    important_entries = 0
+    binnmu_entries = []
+    if is_changelog:
+        kept_entries = []
+        for block in dch:
+            if block.other_pairs.get("binary-only", "no") == "yes":
+                # Always keep binNMU entries (they are always in the top) and they do not count
+                # towards our kept_entries limit
+                binnmu_entries.append(block)
+                continue
+            block_date = block.date
+            if block_date is None:
+                _error(f"The Debian changelog was missing date in sign off line")
+            entry_date = datetime.datetime.strptime(
+                block_date, "%a, %d %b %Y %H:%M:%S %z"
+            ).date()
+            if (
+                trim
+                and entry_date < _DCH_PRUNE_CUT_OFF_DATE
+                and important_entries >= _DCH_MIN_NUM_OF_ENTRIES
+            ):
+                shortened = True
+                break
+            # Match debhelper in incrementing after the check.
+            important_entries += 1
+            kept_entries.append(block)
+    else:
+        assert keep_versions is not None
+        # The NEWS files should match the version for the dch to avoid lintian warnings.
+        # If that means we remove all entries in the NEWS file, then we delete the NEWS
+        # file (see #1021607)
+        kept_entries = [b for b in dch if b.version in keep_versions]
+        shortened = len(dch) > len(kept_entries)
+        if shortened and not kept_entries:
+            path.unlink()
+            return True, None
+
+    if not shortened and not binnmu_entries:
+        return False, None
+
+    parent_dir = assume_not_none(path.parent_dir)
+
+    with path.replace_fs_path_content() as fs_path, open(
+        fs_path, "wt", encoding="utf-8"
+    ) as fd:
+        for entry in kept_entries:
+            fd.write(str(entry))
+
+        if is_changelog and shortened:
+            # For changelog (rather than NEWS) files, add a note about how to
+            # get the full version.
+            msg = textwrap.dedent(
+                f"""\
+                # Older entries have been removed from this changelog.
+                # To read the complete changelog use `apt changelog {package.name}`.
+                """
+            )
+            fd.write(msg)
+
+    if binnmu_entries:
+        if package.is_arch_all:
+            _error(
+                f"The package {package.name} is architecture all, but it is built during a binNMU. A binNMU build"
+                " must not include architecture all packages"
+            )
+
+        with parent_dir.add_file(
+            f"{path.name}.{package.resolved_architecture}"
+        ) as binnmu_changelog, open(
+            binnmu_changelog.fs_path,
+            "wt",
+            encoding="utf-8",
+        ) as binnmu_fd:
+            for entry in binnmu_entries:
+                binnmu_fd.write(str(entry))
+
+    if not shortened:
+        return False, None
+    return True, {b.version for b in kept_entries}
+
+
+def fixup_debian_changelog_and_news_file(
+    dctrl: BinaryPackage,
+    fs_root: VirtualPath,
+    is_native: bool,
+    build_env: DebBuildOptionsAndProfiles,
+) -> None:
+    doc_dir = fs_root.lookup(f"./usr/share/doc/{dctrl.name}")
+    if not doc_dir:
+        return
+    changelog = doc_dir.get("changelog.Debian")
+    if changelog and is_native:
+        changelog.name = "changelog"
+    elif is_native:
+        changelog = doc_dir.get("changelog")
+
+    trim = False if "notrimdch" in build_env.deb_build_options else True
+
+    kept_entries = None
+    pruned_changelog = False
+    if changelog and changelog.has_fs_path:
+        pruned_changelog, kept_entries = _prune_dch_file(
+            dctrl, changelog, True, None, trim=trim
+        )
+
+    if not trim:
+        return
+
+    news_file = doc_dir.get("NEWS.Debian")
+    if news_file and news_file.has_fs_path and pruned_changelog:
+        _prune_dch_file(dctrl, news_file, False, kept_entries)
+
+
+_UPSTREAM_CHANGELOG_SOURCE_DIRS = [
+    ".",
+    "doc",
+    "docs",
+]
+_UPSTREAM_CHANGELOG_NAMES = {
+    # The value is a priority to match the debhelper order.
+    #  - The suffix weights heavier than the basename (because that is what debhelper did)
+    #
+    # We list the name/suffix in order of priority in the code. That makes it easier to
+    # see the priority directly, but it gives the "lowest" value to the most important items
+    f"{n}{s}": (sw, nw)
+    for (nw, n), (sw, s) in itertools.product(
+        enumerate(["changelog", "changes", "history"], start=1),
+        enumerate(["", ".txt", ".md", ".rst"], start=1),
+    )
+}
+_NONE_TUPLE = (None, (0, 0))
+
+
+def _detect_upstream_changelog(names: Iterable[str]) -> Optional[str]:
+    matches = []
+    for name in names:
+        match_priority = _UPSTREAM_CHANGELOG_NAMES.get(name.lower())
+        if match_priority is not None:
+            matches.append((name, match_priority))
+    return min(matches, default=_NONE_TUPLE, key=operator.itemgetter(1))[0]
+
+
+def install_upstream_changelog(
+    dctrl_bin: BinaryPackage,
+    fs_root: FSPath,
+    source_fs_root: VirtualPath,
+) -> None:
+    doc_dir = f"./usr/share/doc/{dctrl_bin.name}"
+    bdir = fs_root.lookup(doc_dir)
+    if bdir and not bdir.is_dir:
+        # "/usr/share/doc/foo -> bar" symlink. Avoid croaking on those per:
+        # https://salsa.debian.org/debian/debputy/-/issues/49
+        return
+
+    if bdir:
+        if bdir.get("changelog") or bdir.get("changelog.gz"):
+            # Upstream's build system already provided the changelog with the correct name.
+            # Accept that as the canonical one.
+            return
+        upstream_changelog = _detect_upstream_changelog(
+            p.name for p in bdir.iterdir if p.is_file and p.has_fs_path and p.size > 0
+        )
+        if upstream_changelog:
+            p = bdir.lookup(upstream_changelog)
+            assert p is not None  # Mostly as a typing hint
+            p.name = "changelog"
+            return
+    for dirname in _UPSTREAM_CHANGELOG_SOURCE_DIRS:
+        dir_path = source_fs_root.lookup(dirname)
+        if not dir_path or not dir_path.is_dir:
+            continue
+        changelog_name = _detect_upstream_changelog(
+            p.name
+            for p in dir_path.iterdir
+            if p.is_file and p.has_fs_path and p.size > 0
+        )
+        if changelog_name:
+            if bdir is None:
+                bdir = fs_root.mkdirs(doc_dir)
+            bdir.insert_file_from_fs_path(
+                "changelog",
+                dir_path[changelog_name].fs_path,
+            )
+            break
+
+
+@dataclasses.dataclass(slots=True)
+class _ElfInfo:
+    path: VirtualPath
+    fs_path: str
+    is_stripped: Optional[bool] = None
+    build_id: Optional[str] = None
+    dbgsym: Optional[FSPath] = None
+
+
+def _elf_static_lib_walk_filter(
+    fs_path: VirtualPath,
+    children: List[VP],
+) -> bool:
+    if (
+        fs_path.name == ".build-id"
+        and assume_not_none(fs_path.parent_dir).name == "debug"
+    ):
+        children.clear()
+        return False
+    # Deal with some special cases, where certain files are not supposed to be stripped in a given directory
+    if "debug/" in fs_path.path or fs_path.name.endswith("debug/"):
+        # FIXME: We need a way to opt out of this per #468333/#1016122
+        for so_file in (f for f in list(children) if f.name.endswith(".so")):
+            children.remove(so_file)
+    if "/guile/" in fs_path.path or fs_path.name == "guile":
+        for go_file in (f for f in list(children) if f.name.endswith(".go")):
+            children.remove(go_file)
+    return True
+
+
+@contextlib.contextmanager
+def _all_elf_files(fs_root: VirtualPath) -> Iterator[Dict[str, _ElfInfo]]:
+    all_elf_files = find_all_elf_files(
+        fs_root,
+        walk_filter=_elf_static_lib_walk_filter,
+    )
+    if not all_elf_files:
+        yield {}
+        return
+    with ExitStack() as cm_stack:
+        resolved = (
+            (p, cm_stack.enter_context(p.replace_fs_path_content()))
+            for p in all_elf_files
+        )
+        elf_info = {
+            fs_path: _ElfInfo(
+                path=assume_not_none(fs_root.lookup(detached_path.path)),
+                fs_path=fs_path,
+            )
+            for detached_path, fs_path in resolved
+        }
+        _resolve_build_ids(elf_info)
+        yield elf_info
+
+
+def _find_all_static_libs(
+    fs_root: FSPath,
+) -> Iterator[FSPath]:
+    for path, children in fs_root.walk():
+        # Matching the logic of dh_strip for now.
+        if not _elf_static_lib_walk_filter(path, children):
+            continue
+        if not path.is_file:
+            continue
+        if path.name.startswith("lib") and path.name.endswith("_g.a"):
+            # _g.a are historically ignored. I do not remember why, but guessing the "_g" is
+            # an encoding of gcc's -g parameter into the filename (with -g meaning "I want debug
+            # symbols")
+            continue
+        if not path.has_fs_path:
+            continue
+        with path.open(byte_io=True) as fd:
+            magic = fd.read(8)
+            if magic not in (b"!<arch>\n", b"!<thin>\n"):
+                continue
+            # Maybe we should see if the first file looks like an index file.
+            # Three random .a samples suggests the index file is named "/"
+            # Not sure if we should skip past it and then do the ELF check or just assume
+            # that "index => static lib".
+            data = fd.read(1024 * 1024)
+            if b"\0" not in data and ELF_MAGIC not in data:
+                continue
+        yield path
+
+
+@contextlib.contextmanager
+def _all_static_libs(fs_root: FSPath) -> Iterator[List[str]]:
+    all_static_libs = list(_find_all_static_libs(fs_root))
+    if not all_static_libs:
+        yield []
+        return
+    with ExitStack() as cm_stack:
+        resolved: List[str] = [
+            cm_stack.enter_context(p.replace_fs_path_content()) for p in all_static_libs
+        ]
+        yield resolved
+
+
+_FILE_BUILD_ID_RE = re.compile(rb"BuildID(?:\[\S+\])?=([A-Fa-f0-9]+)")
+
+
+def _resolve_build_ids(elf_info: Dict[str, _ElfInfo]) -> None:
+    static_cmd = ["file", "-00", "-N"]
+    if detect_fakeroot():
+        static_cmd.append("--no-sandbox")
+
+    for cmd in xargs(static_cmd, (i.fs_path for i in elf_info.values())):
+        _info(f"Looking up build-ids via: {escape_shell(*cmd)}")
+        output = subprocess.check_output(cmd)
+
+        # Trailing "\0" gives an empty element in the end when splitting, so strip it out
+        lines = output.rstrip(b"\0").split(b"\0")
+
+        for fs_path_b, verdict in grouper(lines, 2, incomplete="strict"):
+            fs_path = fs_path_b.decode("utf-8")
+            info = elf_info[fs_path]
+            info.is_stripped = b"not stripped" not in verdict
+            m = _FILE_BUILD_ID_RE.search(verdict)
+            if m:
+                info.build_id = m.group(1).decode("utf-8")
+
+
+def _make_debug_file(
+    objcopy: str, fs_path: str, build_id: str, dbgsym_fs_root: FSPath
+) -> FSPath:
+    dbgsym_dirname = f"./usr/lib/debug/.build-id/{build_id[0:2]}/"
+    dbgsym_basename = f"{build_id[2:]}.debug"
+    dbgsym_dir = dbgsym_fs_root.mkdirs(dbgsym_dirname)
+    if dbgsym_basename in dbgsym_dir:
+        return dbgsym_dir[dbgsym_basename]
+    # objcopy is a pain and includes the basename verbatim when you do `--add-gnu-debuglink` without having an option
+    # to overwrite the physical basename.  So we have to ensure that the physical basename matches the installed
+    # basename.
+    with dbgsym_dir.add_file(
+        dbgsym_basename,
+        unlink_if_exists=False,
+        fs_basename_matters=True,
+        subdir_key="dbgsym-build-ids",
+    ) as dbgsym:
+        try:
+            subprocess.check_call(
+                [
+                    objcopy,
+                    "--only-keep-debug",
+                    "--compress-debug-sections",
+                    fs_path,
+                    dbgsym.fs_path,
+                ]
+            )
+        except subprocess.CalledProcessError:
+            full_command = (
+                f"{objcopy} --only-keep-debug --compress-debug-sections"
+                f" {escape_shell(fs_path, dbgsym.fs_path)}"
+            )
+            _error(
+                f"Attempting to create a .debug file failed. Please review the error message from {objcopy} to"
+                f" understand what went wrong.  Full command was: {full_command}"
+            )
+    return dbgsym
+
+
+def _strip_binary(strip: str, options: List[str], paths: Iterable[str]) -> None:
+    # We assume the paths are obtained via `p.replace_fs_path_content()`,
+    # which is the case at the time of written and should remain so forever.
+    it = iter(paths)
+    first = next(it, None)
+    if first is None:
+        return
+    static_cmd = [strip]
+    static_cmd.extend(options)
+
+    for cmd in xargs(static_cmd, itertools.chain((first,), (f for f in it))):
+        _info(f"Removing unnecessary ELF debug info via: {escape_shell(*cmd)}")
+        try:
+            subprocess.check_call(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                restore_signals=True,
+            )
+        except subprocess.CalledProcessError:
+            _error(
+                f"Attempting to remove ELF debug info failed. Please review the error from {strip} above"
+                f" understand what went wrong."
+            )
+
+
+def _attach_debug(objcopy: str, elf_binary: VirtualPath, dbgsym: FSPath) -> None:
+    dbgsym_fs_path: str
+    with dbgsym.replace_fs_path_content() as dbgsym_fs_path:
+        cmd = [objcopy, "--add-gnu-debuglink", dbgsym_fs_path, elf_binary.fs_path]
+        print_command(*cmd)
+        try:
+            subprocess.check_call(cmd)
+        except subprocess.CalledProcessError:
+            _error(
+                f"Attempting to attach ELF debug link to ELF binary failed. Please review the error from {objcopy}"
+                f" above understand what went wrong."
+            )
+
+
+def _run_dwz(
+    dctrl: BinaryPackage,
+    dbgsym_fs_root: FSPath,
+    unstripped_elf_info: List[_ElfInfo],
+) -> None:
+    if not unstripped_elf_info or dctrl.is_udeb:
+        return
+    dwz_cmd = ["dwz"]
+    dwz_ma_dir_name = f"usr/lib/debug/.dwz/{dctrl.deb_multiarch}"
+    dwz_ma_basename = f"{dctrl.name}.debug"
+    multifile = f"{dwz_ma_dir_name}/{dwz_ma_basename}"
+    build_time_multifile = None
+    if len(unstripped_elf_info) > 1:
+        fs_content_dir = generated_content_dir()
+        fd, build_time_multifile = mkstemp(suffix=dwz_ma_basename, dir=fs_content_dir)
+        os.close(fd)
+        dwz_cmd.append(f"-m{build_time_multifile}")
+        dwz_cmd.append(f"-M/{multifile}")
+
+    # TODO: configuration for disabling multi-file and tweaking memory limits
+
+    dwz_cmd.extend(e.fs_path for e in unstripped_elf_info)
+
+    _info(f"Deduplicating ELF debug info via: {escape_shell(*dwz_cmd)}")
+    try:
+        subprocess.check_call(dwz_cmd)
+    except subprocess.CalledProcessError:
+        _error(
+            "Attempting to deduplicate ELF info via dwz failed. Please review the output from dwz above"
+            " to understand what went wrong."
+        )
+    if build_time_multifile is not None and os.stat(build_time_multifile).st_size > 0:
+        dwz_dir = dbgsym_fs_root.mkdirs(dwz_ma_dir_name)
+        dwz_dir.insert_file_from_fs_path(
+            dwz_ma_basename,
+            build_time_multifile,
+            mode=0o644,
+            require_copy_on_write=False,
+            follow_symlinks=False,
+        )
+
+
+def relocate_dwarves_into_dbgsym_packages(
+    dctrl: BinaryPackage,
+    package_fs_root: FSPath,
+    dbgsym_fs_root: VirtualPath,
+) -> List[str]:
+    # FIXME: hardlinks
+    with _all_static_libs(package_fs_root) as all_static_files:
+        if all_static_files:
+            strip = dctrl.cross_command("strip")
+            _strip_binary(
+                strip,
+                [
+                    "--strip-debug",
+                    "--remove-section=.comment",
+                    "--remove-section=.note",
+                    "--enable-deterministic-archives",
+                    "-R",
+                    ".gnu.lto_*",
+                    "-R",
+                    ".gnu.debuglto_*",
+                    "-N",
+                    "__gnu_lto_slim",
+                    "-N",
+                    "__gnu_lto_v1",
+                ],
+                all_static_files,
+            )
+
+    with _all_elf_files(package_fs_root) as all_elf_files:
+        if not all_elf_files:
+            return []
+        objcopy = dctrl.cross_command("objcopy")
+        strip = dctrl.cross_command("strip")
+        unstripped_elf_info = list(
+            e for e in all_elf_files.values() if not e.is_stripped
+        )
+
+        _run_dwz(dctrl, dbgsym_fs_root, unstripped_elf_info)
+
+        for elf_info in unstripped_elf_info:
+            elf_info.dbgsym = _make_debug_file(
+                objcopy,
+                elf_info.fs_path,
+                assume_not_none(elf_info.build_id),
+                dbgsym_fs_root,
+            )
+
+        # Note: When run strip, we do so also on already stripped ELF binaries because that is what debhelper does!
+        # Executables (defined by mode)
+        _strip_binary(
+            strip,
+            ["--remove-section=.comment", "--remove-section=.note"],
+            (i.fs_path for i in all_elf_files.values() if i.path.is_executable),
+        )
+
+        # Libraries (defined by mode)
+        _strip_binary(
+            strip,
+            ["--remove-section=.comment", "--remove-section=.note", "--strip-unneeded"],
+            (i.fs_path for i in all_elf_files.values() if not i.path.is_executable),
+        )
+
+        for elf_info in unstripped_elf_info:
+            _attach_debug(
+                objcopy,
+                assume_not_none(elf_info.path),
+                assume_not_none(elf_info.dbgsym),
+            )
+
+        # Set for uniqueness
+        all_debug_info = sorted(
+            {assume_not_none(i.build_id) for i in unstripped_elf_info}
+        )
+
+    dbgsym_doc_dir = dbgsym_fs_root.mkdirs("./usr/share/doc/")
+    dbgsym_doc_dir.add_symlink(f"{dctrl.name}-dbgsym", dctrl.name)
+    return all_debug_info
+
+
+def run_package_processors(
+    manifest: HighLevelManifest,
+    package_metadata_context: PackageProcessingContext,
+    fs_root: VirtualPath,
+) -> None:
+    pppps = manifest.plugin_provided_feature_set.package_processors_in_order()
+    binary_package = package_metadata_context.binary_package
+    for pppp in pppps:
+        if not pppp.applies_to(binary_package):
+            continue
+        pppp.run_package_processor(fs_root, None, package_metadata_context)
+
+
+def cross_package_control_files(
+    package_data_table: PackageDataTable,
+    manifest: HighLevelManifest,
+) -> None:
+    errors = []
+    combined_shlibs = ShlibsContent()
+    shlibs_dir = None
+    shlib_dirs: List[str] = []
+    shlibs_local = manifest.debian_dir.get("shlibs.local")
+    if shlibs_local and shlibs_local.is_file:
+        with shlibs_local.open() as fd:
+            combined_shlibs.add_entries_from_shlibs_file(fd)
+
+    debputy_plugin_metadata = manifest.plugin_provided_feature_set.plugin_data[
+        "debputy"
+    ]
+
+    for binary_package_data in package_data_table:
+        binary_package = binary_package_data.binary_package
+        if binary_package.is_arch_all or not binary_package.should_be_acted_on:
+            continue
+        control_output_dir = assume_not_none(binary_package_data.control_output_dir)
+        fs_root = binary_package_data.fs_root
+        package_state = manifest.package_state_for(binary_package.name)
+        related_udeb_package = (
+            binary_package_data.package_metadata_context.related_udeb_package
+        )
+
+        udeb_package_name = related_udeb_package.name if related_udeb_package else None
+        ctrl = binary_package_data.ctrl_creator.for_plugin(
+            debputy_plugin_metadata,
+            "compute_shlibs",
+        )
+        try:
+            soname_info_list = compute_shlibs(
+                binary_package,
+                control_output_dir,
+                fs_root,
+                manifest,
+                udeb_package_name,
+                ctrl,
+                package_state.reserved_packager_provided_files,
+                combined_shlibs,
+            )
+        except DebputyDpkgGensymbolsError as e:
+            errors.append(e.message)
+        else:
+            if soname_info_list:
+                if shlibs_dir is None:
+                    shlibs_dir = generated_content_dir(
+                        subdir_key="_shlibs_materialization_dir"
+                    )
+                generate_shlib_dirs(
+                    binary_package,
+                    shlibs_dir,
+                    soname_info_list,
+                    shlib_dirs,
+                )
+    if errors:
+        for error in errors:
+            _warn(error)
+        _error("Stopping due to the errors above")
+
+    generated_shlibs_local = None
+    if combined_shlibs:
+        if shlibs_dir is None:
+            shlibs_dir = generated_content_dir(subdir_key="_shlibs_materialization_dir")
+        generated_shlibs_local = os.path.join(shlibs_dir, "shlibs.local")
+        with open(generated_shlibs_local, "wt", encoding="utf-8") as fd:
+            combined_shlibs.write_to(fd)
+        _info(f"Generated {generated_shlibs_local} for dpkg-shlibdeps")
+
+    for binary_package_data in package_data_table:
+        binary_package = binary_package_data.binary_package
+        if binary_package.is_arch_all or not binary_package.should_be_acted_on:
+            continue
+        binary_package_data.ctrl_creator.shlibs_details = (
+            generated_shlibs_local,
+            shlib_dirs,
+        )
+
+
+def setup_control_files(
+    binary_package_data: BinaryPackageData,
+    manifest: HighLevelManifest,
+    dbgsym_fs_root: VirtualPath,
+    dbgsym_ids: List[str],
+    package_metadata_context: PackageProcessingContext,
+    *,
+    allow_ctrl_file_management: bool = True,
+) -> None:
+    binary_package = package_metadata_context.binary_package
+    control_output_dir = assume_not_none(binary_package_data.control_output_dir)
+    fs_root = binary_package_data.fs_root
+    package_state = manifest.package_state_for(binary_package.name)
+
+    feature_set: PluginProvidedFeatureSet = manifest.plugin_provided_feature_set
+    metadata_maintscript_detectors = feature_set.metadata_maintscript_detectors
+    substvars = binary_package_data.substvars
+
+    snippets = STD_CONTROL_SCRIPTS
+    if binary_package.is_udeb:
+        # FIXME: Add missing udeb scripts
+        snippets = ["postinst"]
+
+    if allow_ctrl_file_management:
+        process_alternatives(
+            binary_package,
+            fs_root,
+            package_state.reserved_packager_provided_files,
+            package_state.maintscript_snippets,
+        )
+        process_debconf_templates(
+            binary_package,
+            package_state.reserved_packager_provided_files,
+            package_state.maintscript_snippets,
+            substvars,
+            control_output_dir,
+        )
+
+        for service_manager_details in feature_set.service_managers.values():
+            service_registry = ServiceRegistryImpl(service_manager_details)
+            service_manager_details.service_detector(
+                fs_root,
+                service_registry,
+                package_metadata_context,
+            )
+
+            ctrl = binary_package_data.ctrl_creator.for_plugin(
+                service_manager_details.plugin_metadata,
+                service_manager_details.service_manager,
+            )
+            service_definitions = service_registry.detected_services
+            if not service_definitions:
+                continue
+            service_manager_details.service_integrator(
+                service_definitions,
+                ctrl,
+                package_metadata_context,
+            )
+
+        plugin_detector_definition: MetadataOrMaintscriptDetector
+        for plugin_detector_definition in itertools.chain.from_iterable(
+            metadata_maintscript_detectors.values()
+        ):
+            if not plugin_detector_definition.applies_to(binary_package):
+                continue
+            ctrl = binary_package_data.ctrl_creator.for_plugin(
+                plugin_detector_definition.plugin_metadata,
+                plugin_detector_definition.detector_id,
+            )
+            plugin_detector_definition.run_detector(
+                fs_root, ctrl, package_metadata_context
+            )
+
+        for script in snippets:
+            _generate_snippet(
+                control_output_dir,
+                script,
+                package_state.maintscript_snippets,
+            )
+
+    else:
+        if package_state.maintscript_snippets:
+            for script, snippet_container in package_state.maintscript_snippets.items():
+                for snippet in snippet_container.all_snippets():
+                    source = snippet.definition_source
+                    _error(
+                        f"This integration mode cannot use maintscript snippets"
+                        f' (since dh_installdeb has already been called). However, "{source}" triggered'
+                        f" a snippet for {script}. Please remove the offending definition if it is from"
+                        f" the manifest or file a bug if it is caused by a built-in rule."
+                    )
+
+        dh_staging_dir = os.path.join("debian", binary_package.name, "DEBIAN")
+        try:
+            with os.scandir(dh_staging_dir) as it:
+                existing_control_files = [
+                    f.path
+                    for f in it
+                    if f.is_file(follow_symlinks=False)
+                    and f.name not in ("control", "md5sums")
+                ]
+        except FileNotFoundError:
+            existing_control_files = []
+
+        if existing_control_files:
+            cmd = ["cp", "-a"]
+            cmd.extend(existing_control_files)
+            cmd.append(control_output_dir)
+            print_command(*cmd)
+            subprocess.check_call(cmd)
+
+    if binary_package.is_udeb:
+        _generate_control_files(
+            binary_package_data.source_package,
+            binary_package,
+            package_state,
+            control_output_dir,
+            fs_root,
+            substvars,
+            # We never built udebs due to #797391, so skip over this information,
+            # when creating the udeb
+            None,
+            None,
+        )
+        return
+
+    generated_triggers = list(binary_package_data.ctrl_creator.generated_triggers())
+    if generated_triggers:
+        if not allow_ctrl_file_management:
+            for trigger in generated_triggers:
+                source = f"{trigger.provider.plugin_name}:{trigger.provider_source_id}"
+                _error(
+                    f"This integration mode must not generate triggers"
+                    f' (since dh_installdeb has already been called). However, "{source}" created'
+                    f" a trigger. Please remove the offending definition if it is from"
+                    f" the manifest or file a bug if it is caused by a built-in rule."
+                )
+
+        if generated_triggers:
+            dest_file = os.path.join(control_output_dir, "triggers")
+            with open(dest_file, "at", encoding="utf-8") as fd:
+                fd.writelines(
+                    textwrap.dedent(
+                        f"""\
+                    # Added by {t.provider_source_id} from {t.provider.plugin_name}
+                    {t.dpkg_trigger_type} {t.dpkg_trigger_target}
+                """
+                    )
+                    for t in generated_triggers
+                )
+                os.chmod(fd.fileno(), 0o644)
+        install_or_generate_conffiles(
+            binary_package,
+            control_output_dir,
+            fs_root,
+            manifest.debian_dir,
+        )
+    _generate_control_files(
+        binary_package_data.source_package,
+        binary_package,
+        package_state,
+        control_output_dir,
+        fs_root,
+        substvars,
+        dbgsym_fs_root,
+        dbgsym_ids,
+    )
+
+
+def _generate_snippet(
+    control_output_dir: str,
+    script: str,
+    maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+) -> None:
+    debputy_snippets = maintscript_snippets.get(script)
+    if debputy_snippets is None:
+        return
+    reverse = script in ("prerm", "postrm")
+    snippets = [
+        debputy_snippets.generate_snippet(reverse=reverse),
+        debputy_snippets.generate_snippet(snippet_order="service", reverse=reverse),
+    ]
+    if reverse:
+        snippets = reversed(snippets)
+    full_content = "".join(f"{s}\n" for s in filter(None, snippets))
+    if not full_content:
+        return
+    filename = os.path.join(control_output_dir, script)
+    with open(filename, "wt") as fd:
+        fd.write("#!/bin/sh\nset -e\n\n")
+        fd.write(full_content)
+        os.chmod(fd.fileno(), 0o755)
+
+
+def _add_conffiles(
+    conffiles_dest: str,
+    conffile_matches: Iterable[VirtualPath],
+) -> None:
+    with open(conffiles_dest, "at") as fd:
+        for conffile_match in conffile_matches:
+            conffile = conffile_match.absolute
+            assert conffile_match.is_file
+            fd.write(f"{conffile}\n")
+    if os.stat(conffiles_dest).st_size == 0:
+        os.unlink(conffiles_dest)
+
+
+def _ensure_base_substvars_defined(substvars: FlushableSubstvars) -> None:
+    for substvar in ("misc:Depends", "misc:Pre-Depends"):
+        if substvar not in substvars:
+            substvars[substvar] = ""
+
+
+def _compute_installed_size(fs_root: VirtualPath) -> int:
+    """Emulate dpkg-gencontrol's code for computing the default Installed-Size"""
+    size_in_kb = 0
+    hard_links = set()
+    for path in fs_root.all_paths():
+        if not path.is_dir and path.has_fs_path:
+            st = path.stat()
+            if st.st_nlink > 1:
+                hl_key = (st.st_dev, st.st_ino)
+                if hl_key in hard_links:
+                    continue
+                hard_links.add(hl_key)
+            path_size = (st.st_size + 1023) // 1024
+        elif path.is_symlink:
+            path_size = (len(path.readlink()) + 1023) // 1024
+        else:
+            path_size = 1
+        size_in_kb += path_size
+    return size_in_kb
+
+
+def _generate_dbgsym_control_file_if_relevant(
+    binary_package: BinaryPackage,
+    dbgsym_fs_root: VirtualPath,
+    dbgsym_root_dir: str,
+    dbgsym_ids: str,
+    multi_arch: Optional[str],
+    extra_common_params: Sequence[str],
+) -> None:
+    section = binary_package.archive_section
+    component = ""
+    extra_params = []
+    if section is not None and "/" in section and not section.startswith("main/"):
+        component = section.split("/", 1)[1] + "/"
+    if multi_arch != "same":
+        extra_params.append("-UMulti-Arch")
+    extra_params.append("-UReplaces")
+    extra_params.append("-UBreaks")
+    dbgsym_control_dir = os.path.join(dbgsym_root_dir, "DEBIAN")
+    ensure_dir(dbgsym_control_dir)
+    # Pass it via cmd-line to make it more visible that we are providing the
+    # value.  It also prevents the dbgsym package from picking up this value.
+    ctrl_fs_root = FSROOverlay.create_root_dir("DEBIAN", dbgsym_control_dir)
+    total_size = _compute_installed_size(dbgsym_fs_root) + _compute_installed_size(
+        ctrl_fs_root
+    )
+    extra_params.append(f"-VInstalled-Size={total_size}")
+    extra_params.extend(extra_common_params)
+
+    package = binary_package.name
+    dpkg_cmd = [
+        "dpkg-gencontrol",
+        f"-p{package}",
+        # FIXME: Support d/<pkg>.changelog at some point.
+        "-ldebian/changelog",
+        "-T/dev/null",
+        f"-P{dbgsym_root_dir}",
+        f"-DPackage={package}-dbgsym",
+        "-DDepends=" + package + " (= ${binary:Version})",
+        f"-DDescription=debug symbols for {package}",
+        f"-DSection={component}debug",
+        f"-DBuild-Ids={dbgsym_ids}",
+        "-UPre-Depends",
+        "-URecommends",
+        "-USuggests",
+        "-UEnhances",
+        "-UProvides",
+        "-UEssential",
+        "-UConflicts",
+        "-DPriority=optional",
+        "-UHomepage",
+        "-UImportant",
+        "-UBuilt-Using",
+        "-UStatic-Built-Using",
+        "-DAuto-Built-Package=debug-symbols",
+        "-UProtected",
+        *extra_params,
+    ]
+    print_command(*dpkg_cmd)
+    try:
+        subprocess.check_call(dpkg_cmd)
+    except subprocess.CalledProcessError:
+        _error(
+            f"Attempting to generate DEBIAN/control file for {package}-dbgsym failed. Please review the output from "
+            " dpkg-gencontrol above to understand what went wrong."
+        )
+    os.chmod(os.path.join(dbgsym_root_dir, "DEBIAN", "control"), 0o644)
+
+
+def _all_parent_directories_of(directories: Iterable[str]) -> Set[str]:
+    result = {"."}
+    for path in directories:
+        current = os.path.dirname(path)
+        while current and current not in result:
+            result.add(current)
+            current = os.path.dirname(current)
+    return result
+
+
+def _auto_compute_multi_arch(
+    binary_package: BinaryPackage,
+    control_output_dir: str,
+    fs_root: FSPath,
+) -> Optional[str]:
+    resolved_arch = binary_package.resolved_architecture
+    if resolved_arch == "all":
+        return None
+    if any(
+        script
+        for script in ALL_CONTROL_SCRIPTS
+        if os.path.isfile(os.path.join(control_output_dir, script))
+    ):
+        return None
+
+    resolved_multiarch = binary_package.deb_multiarch
+    assert resolved_arch != "all"
+    acceptable_no_descend_paths = {
+        f"./usr/lib/{resolved_multiarch}",
+        f"./usr/include/{resolved_multiarch}",
+    }
+    acceptable_files = {
+        f"./usr/share/doc/{binary_package.name}/{basename}"
+        for basename in (
+            "copyright",
+            "changelog.gz",
+            "changelog.Debian.gz",
+            f"changelog.Debian.{resolved_arch}.gz",
+            "NEWS.Debian",
+            "NEWS.Debian.gz",
+            "README.Debian",
+            "README.Debian.gz",
+        )
+    }
+    acceptable_intermediate_dirs = _all_parent_directories_of(
+        itertools.chain(acceptable_no_descend_paths, acceptable_files)
+    )
+
+    for fs_path, children in fs_root.walk():
+        path = fs_path.path
+        if path in acceptable_no_descend_paths:
+            children.clear()
+            continue
+        if path in acceptable_intermediate_dirs or path in acceptable_files:
+            continue
+        return None
+
+    return "same"
+
+
+@functools.lru_cache()
+def _has_t64_enabled() -> bool:
+    try:
+        output = subprocess.check_output(
+            ["dpkg-buildflags", "--query-features", "abi"]
+        ).decode()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+    for stanza in Deb822.iter_paragraphs(output):
+        if stanza.get("Feature") == "time64" and stanza.get("Enabled") == "yes":
+            return True
+    return False
+
+
+def _t64_migration_substvar(
+    binary_package: BinaryPackage,
+    control_output_dir: str,
+    substvars: FlushableSubstvars,
+) -> None:
+    name = binary_package.name
+    compat_name = binary_package.fields.get("X-Time64-Compat")
+    if compat_name is None and not _T64_REGEX.match(name):
+        return
+
+    if not any(
+        os.path.isfile(os.path.join(control_output_dir, n))
+        for n in ["symbols", "shlibs"]
+    ):
+        return
+
+    if compat_name is None:
+        compat_name = name.replace("t64", "", 1)
+        if compat_name == name:
+            raise AssertionError(
+                f"Failed to derive a t64 compat name for {name}. Please file a bug against debputy."
+                " As a work around, you can explicitly provide a X-Time64-Compat header in debian/control"
+                " where you specify the desired compat name."
+            )
+
+    arch_bits = binary_package.package_deb_architecture_variable("ARCH_BITS")
+
+    if arch_bits != "32" or not _has_t64_enabled():
+        substvars.add_dependency(
+            _T64_PROVIDES,
+            f"{compat_name} (= ${{binary:Version}})",
+        )
+    elif _T64_PROVIDES not in substvars:
+        substvars[_T64_PROVIDES] = ""
+
+
+@functools.lru_cache()
+def dpkg_field_list_pkg_dep() -> Sequence[str]:
+    try:
+        output = subprocess.check_output(
+            [
+                "perl",
+                "-MDpkg::Control::Fields",
+                "-e",
+                r'print "$_\n" for field_list_pkg_dep',
+            ]
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        _error("Could not run perl -MDpkg::Control::Fields to get a list of fields")
+    return output.decode("utf-8").splitlines(keepends=False)
+
+
+def _handle_relationship_substvars(
+    source: SourcePackage,
+    dctrl: BinaryPackage,
+    substvars: FlushableSubstvars,
+) -> Optional[str]:
+    relationship_fields = dpkg_field_list_pkg_dep()
+    relationship_fields_lc = frozenset(x.lower() for x in relationship_fields)
+    substvar_fields = collections.defaultdict(list)
+    for substvar_name, substvar in substvars.as_substvar.items():
+        if substvar.assignment_operator == "$=" or ":" not in substvar_name:
+            # Automatically handled; no need for manual merging.
+            continue
+        _, field = substvar_name.rsplit(":", 1)
+        field_lc = field.lower()
+        if field_lc not in relationship_fields_lc:
+            continue
+        substvar_fields[field_lc].append("${" + substvar_name + "}")
+    if not substvar_fields:
+        return None
+
+    replacement_stanza = debian.deb822.Deb822(dctrl.fields)
+
+    for field_name in relationship_fields:
+        field_name_lc = field_name.lower()
+        addendum = substvar_fields.get(field_name_lc)
+        if addendum is None:
+            # No merging required
+            continue
+        substvars_part = ", ".join(addendum)
+        existing_value = replacement_stanza.get(field_name)
+
+        if existing_value is None or existing_value.isspace():
+            final_value = substvars_part
+        else:
+            existing_value = existing_value.rstrip().rstrip(",")
+            final_value = f"{existing_value}, {substvars_part}"
+        replacement_stanza[field_name] = final_value
+
+    tmpdir = generated_content_dir(package=dctrl)
+    with tempfile.NamedTemporaryFile(
+        mode="wb",
+        dir=tmpdir,
+        suffix="__DEBIAN_control",
+        delete=False,
+    ) as fd:
+        try:
+            cast("Any", source.fields).dump(fd)
+        except AttributeError:
+            debian.deb822.Deb822(source.fields).dump(fd)
+        fd.write(b"\n")
+        replacement_stanza.dump(fd)
+    return fd.name
+
+
+def _generate_control_files(
+    source_package: SourcePackage,
+    binary_package: BinaryPackage,
+    package_state: PackageTransformationDefinition,
+    control_output_dir: str,
+    fs_root: FSPath,
+    substvars: FlushableSubstvars,
+    dbgsym_root_fs: Optional[VirtualPath],
+    dbgsym_build_ids: Optional[List[str]],
+) -> None:
+    package = binary_package.name
+    extra_common_params = []
+    extra_params_specific = []
+    _ensure_base_substvars_defined(substvars)
+    if "Installed-Size" not in substvars:
+        # Pass it via cmd-line to make it more visible that we are providing the
+        # value.  It also prevents the dbgsym package from picking up this value.
+        ctrl_fs_root = FSROOverlay.create_root_dir("DEBIAN", control_output_dir)
+        total_size = _compute_installed_size(fs_root) + _compute_installed_size(
+            ctrl_fs_root
+        )
+        extra_params_specific.append(f"-VInstalled-Size={total_size}")
+
+    ma_value = binary_package.fields.get("Multi-Arch")
+    if not binary_package.is_udeb and ma_value is None:
+        ma_value = _auto_compute_multi_arch(binary_package, control_output_dir, fs_root)
+        if ma_value is not None:
+            _info(
+                f'The package "{binary_package.name}" looks like it should be "Multi-Arch: {ma_value}" based'
+                ' on the contents and there is no explicit "Multi-Arch" field. Setting the Multi-Arch field'
+                ' accordingly in the binary.  If this auto-correction is wrong, please  add "Multi-Arch: no" to the'
+                ' relevant part of "debian/control" to disable this feature.'
+            )
+            extra_params_specific.append(f"-DMulti-Arch={ma_value}")
+    elif ma_value == "no":
+        extra_params_specific.append("-UMulti-Arch")
+
+    dbgsym_root_dir = dhe_dbgsym_root_dir(binary_package)
+    dbgsym_ids = " ".join(dbgsym_build_ids) if dbgsym_build_ids else ""
+    if package_state.binary_version is not None:
+        extra_common_params.append(f"-v{package_state.binary_version}")
+
+    _t64_migration_substvar(binary_package, control_output_dir, substvars)
+
+    with substvars.flush() as flushed_substvars:
+        if dbgsym_root_fs is not None and any(
+            f for f in dbgsym_root_fs.all_paths() if f.is_file
+        ):
+            _generate_dbgsym_control_file_if_relevant(
+                binary_package,
+                dbgsym_root_fs,
+                dbgsym_root_dir,
+                dbgsym_ids,
+                ma_value,
+                extra_common_params,
+            )
+            generate_md5sums_file(
+                os.path.join(dbgsym_root_dir, "DEBIAN"),
+                dbgsym_root_fs,
+            )
+        elif dbgsym_ids:
+            extra_common_params.append(f"-DBuild-Ids={dbgsym_ids}")
+
+        dctrl = _handle_relationship_substvars(
+            source_package,
+            binary_package,
+            substvars,
+        )
+        if dctrl is None:
+            dctrl = "debian/control"
+
+        ctrl_file = os.path.join(control_output_dir, "control")
+        dpkg_cmd = [
+            "dpkg-gencontrol",
+            f"-p{package}",
+            # FIXME: Support d/<pkg>.changelog at some point.
+            "-ldebian/changelog",
+            f"-c{dctrl}",
+            f"-T{flushed_substvars}",
+            f"-O{ctrl_file}",
+            f"-P{control_output_dir}",
+            *extra_common_params,
+            *extra_params_specific,
+        ]
+        print_command(*dpkg_cmd)
+        try:
+            subprocess.check_call(dpkg_cmd)
+        except subprocess.CalledProcessError:
+            _error(
+                f"Attempting to generate DEBIAN/control file for {package} failed. Please review the output from "
+                " dpkg-gencontrol above to understand what went wrong."
+            )
+        os.chmod(ctrl_file, 0o644)
+
+    if not binary_package.is_udeb:
+        generate_md5sums_file(control_output_dir, fs_root)
diff --git a/src/debputy/debhelper_emulation.py b/src/debputy/debhelper_emulation.py
new file mode 100644
index 0000000..88352bd
--- /dev/null
+++ b/src/debputy/debhelper_emulation.py
@@ -0,0 +1,270 @@
+import dataclasses
+import os.path
+import re
+import shutil
+from re import Match
+from typing import (
+    Optional,
+    Callable,
+    Union,
+    Iterable,
+    Tuple,
+    Sequence,
+    cast,
+    Mapping,
+    Any,
+    Set,
+    List,
+)
+
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import VirtualPath
+from debputy.substitution import Substitution
+from debputy.util import ensure_dir, print_command, _error
+
+SnippetReplacement = Union[str, Callable[[str], str]]
+MAINTSCRIPT_TOKEN_NAME_PATTERN = r"[A-Za-z0-9_.+]+"
+MAINTSCRIPT_TOKEN_NAME_REGEX = re.compile(MAINTSCRIPT_TOKEN_NAME_PATTERN)
+MAINTSCRIPT_TOKEN_REGEX = re.compile(f"#({MAINTSCRIPT_TOKEN_NAME_PATTERN})#")
+_ARCH_FILTER_START = re.compile(r"^\s*(\[([^]]*)])[ \t]+")
+_ARCH_FILTER_END = re.compile(r"\s+(\[([^]]*)])\s*$")
+_BUILD_PROFILE_FILTER = re.compile(r"(<([^>]*)>(?:\s+<([^>]*)>)*)")
+
+
+class CannotEmulateExecutableDHConfigFile(Exception):
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+    def config_file(self) -> VirtualPath:
+        return cast("VirtualPath", self.args[1])
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DHConfigFileLine:
+    config_file: VirtualPath
+    line_no: int
+    executable_config: bool
+    original_line: str
+    tokens: Sequence[str]
+    arch_filter: Optional[str]
+    build_profile_filter: Optional[str]
+
+    def conditional_key(self) -> Tuple[str, ...]:
+        k = []
+        if self.arch_filter is not None:
+            k.append("arch")
+            k.append(self.arch_filter)
+        if self.build_profile_filter is not None:
+            k.append("build-profiles")
+            k.append(self.build_profile_filter)
+        return tuple(k)
+
+    def conditional(self) -> Optional[Mapping[str, Any]]:
+        filters = []
+        if self.arch_filter is not None:
+            filters.append({"arch-matches": self.arch_filter})
+        if self.build_profile_filter is not None:
+            filters.append({"build-profiles-matches": self.build_profile_filter})
+        if not filters:
+            return None
+        if len(filters) == 1:
+            return filters[0]
+        return {"all-of": filters}
+
+
+def dhe_dbgsym_root_dir(binary_package: BinaryPackage) -> str:
+    return os.path.join("debian", ".debhelper", binary_package.name, "dbgsym-root")
+
+
+def read_dbgsym_file(binary_package: BinaryPackage) -> List[str]:
+    dbgsym_id_file = os.path.join(
+        "debian", ".debhelper", binary_package.name, "dbgsym-build-ids"
+    )
+    try:
+        with open(dbgsym_id_file, "rt", encoding="utf-8") as fd:
+            return fd.read().split()
+    except FileNotFoundError:
+        return []
+
+
+def assert_no_dbgsym_migration(binary_package: BinaryPackage) -> None:
+    dbgsym_migration_file = os.path.join(
+        "debian", ".debhelper", binary_package.name, "dbgsym-migration"
+    )
+    if os.path.lexists(dbgsym_migration_file):
+        _error(
+            "Sorry, debputy does not support dh_strip --dbgsym-migration feature. Please either finish the"
+            " migration first or migrate to debputy later"
+        )
+
+
+def _prune_match(
+    line: str,
+    match: Optional[Match[str]],
+    match_mapper: Optional[Callable[[Match[str]], str]] = None,
+) -> Tuple[str, Optional[str]]:
+    if match is None:
+        return line, None
+    s, e = match.span()
+    if match_mapper:
+        matched_part = match_mapper(match)
+    else:
+        matched_part = line[s:e]
+    # We prune exactly the matched part and assume the regexes leaves behind spaces if they were important.
+    line = line[:s] + line[e:]
+    # One special-case, if the match is at the beginning or end, then we can safely discard left
+    # over whitespace.
+    return line.strip(), matched_part
+
+
+def dhe_filedoublearray(
+    config_file: VirtualPath,
+    substitution: Substitution,
+    *,
+    allow_dh_exec_rename: bool = False,
+) -> Iterable[DHConfigFileLine]:
+    with config_file.open() as fd:
+        is_executable = config_file.is_executable
+        for line_no, orig_line in enumerate(fd, start=1):
+            arch_filter = None
+            build_profile_filter = None
+            if (
+                line_no == 1
+                and is_executable
+                and not orig_line.startswith(
+                    ("#!/usr/bin/dh-exec", "#! /usr/bin/dh-exec")
+                )
+            ):
+                raise CannotEmulateExecutableDHConfigFile(
+                    "Only #!/usr/bin/dh-exec based executables can be emulated",
+                    config_file,
+                )
+            orig_line = orig_line.rstrip("\n")
+            line = orig_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if is_executable:
+                if "=>" in line and not allow_dh_exec_rename:
+                    raise CannotEmulateExecutableDHConfigFile(
+                        'Cannot emulate dh-exec\'s "=>" feature to rename files for the concrete file',
+                        config_file,
+                    )
+                line, build_profile_filter = _prune_match(
+                    line,
+                    _BUILD_PROFILE_FILTER.search(line),
+                )
+                line, arch_filter = _prune_match(
+                    line,
+                    _ARCH_FILTER_START.search(line) or _ARCH_FILTER_END.search(line),
+                    # Remove the enclosing []
+                    lambda m: m.group(1)[1:-1].strip(),
+                )
+
+            parts = tuple(
+                substitution.substitute(
+                    w, f'{config_file.path} line {line_no} token "{w}"'
+                )
+                for w in line.split()
+            )
+            yield DHConfigFileLine(
+                config_file,
+                line_no,
+                is_executable,
+                orig_line,
+                parts,
+                arch_filter,
+                build_profile_filter,
+            )
+
+
+def dhe_pkgfile(
+    debian_dir: VirtualPath,
+    binary_package: BinaryPackage,
+    basename: str,
+    always_fallback_to_packageless_variant: bool = False,
+    bug_950723_prefix_matching: bool = False,
+) -> Optional[VirtualPath]:
+    # TODO: Architecture specific files
+    maybe_at_suffix = "@" if bug_950723_prefix_matching else ""
+    possible_names = [f"{binary_package.name}{maybe_at_suffix}.{basename}"]
+    if binary_package.is_main_package or always_fallback_to_packageless_variant:
+        possible_names.append(
+            f"{basename}@" if bug_950723_prefix_matching else basename
+        )
+
+    for name in possible_names:
+        match = debian_dir.get(name)
+        if match is not None and not match.is_dir:
+            return match
+    return None
+
+
+def dhe_pkgdir(
+    debian_dir: VirtualPath,
+    binary_package: BinaryPackage,
+    basename: str,
+) -> Optional[VirtualPath]:
+    possible_names = [f"{binary_package.name}.{basename}"]
+    if binary_package.is_main_package:
+        possible_names.append(basename)
+
+    for name in possible_names:
+        match = debian_dir.get(name)
+        if match is not None and match.is_dir:
+            return match
+    return None
+
+
+def dhe_install_pkg_file_as_ctrl_file_if_present(
+    debian_dir: VirtualPath,
+    binary_package: BinaryPackage,
+    basename: str,
+    control_output_dir: str,
+    mode: int,
+) -> None:
+    source = dhe_pkgfile(debian_dir, binary_package, basename)
+    if source is None:
+        return
+    ensure_dir(control_output_dir)
+    dhe_install_path(source.fs_path, os.path.join(control_output_dir, basename), mode)
+
+
+def dhe_install_path(source: str, dest: str, mode: int) -> None:
+    # TODO: "install -p -mXXXX foo bar" silently discards broken
+    # symlinks to install the file in place.  (#868204)
+    print_command("install", "-p", f"-m{oct(mode)[2:]}", source, dest)
+    shutil.copyfile(source, dest)
+    os.chmod(dest, mode)
+
+
+_FIND_DH_WITH = re.compile(r"--with(?:\s+|=)(\S+)")
+_DEP_REGEX = re.compile("^([a-z0-9][-+.a-z0-9]+)", re.ASCII)
+
+
+def parse_drules_for_addons(debian_rules: VirtualPath, sequences: Set[str]) -> None:
+    with debian_rules.open() as fd:
+        for line in fd:
+            if not line.startswith("\tdh "):
+                continue
+            for match in _FIND_DH_WITH.finditer(line):
+                sequence_def = match.group(1)
+                sequences.update(sequence_def.split(","))
+
+
+def extract_dh_addons_from_control(
+    source_paragraph: Mapping[str, str],
+    sequences: Set[str],
+) -> None:
+    for f in ("Build-Depends", "Build-Depends-Indep", "Build-Depends-Arch"):
+        field = source_paragraph.get(f)
+        if not field:
+            continue
+
+        for dep_clause in (d.strip() for d in field.split(",")):
+            match = _DEP_REGEX.match(dep_clause.strip())
+            if not match:
+                continue
+            dep = match.group(1)
+            if not dep.startswith("dh-sequence-"):
+                continue
+            sequences.add(dep[12:])
diff --git a/src/debputy/dh_migration/__init__.py b/src/debputy/dh_migration/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/dh_migration/__init__.py
diff --git a/src/debputy/dh_migration/migration.py b/src/debputy/dh_migration/migration.py
new file mode 100644
index 0000000..1366f22
--- /dev/null
+++ b/src/debputy/dh_migration/migration.py
@@ -0,0 +1,344 @@
+import json
+import os
+import re
+import subprocess
+from itertools import chain
+from typing import Optional, List, Callable, Set
+
+from debian.deb822 import Deb822
+
+from debputy.debhelper_emulation import CannotEmulateExecutableDHConfigFile
+from debputy.dh_migration.migrators import MIGRATORS
+from debputy.dh_migration.migrators_impl import (
+    read_dh_addon_sequences,
+    MIGRATION_TARGET_DH_DEBPUTY,
+    MIGRATION_TARGET_DH_DEBPUTY_RRR,
+)
+from debputy.dh_migration.models import (
+    FeatureMigration,
+    AcceptableMigrationIssues,
+    UnsupportedFeature,
+    ConflictingChange,
+)
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.plugin.api import VirtualPath
+from debputy.util import _error, _warn, _info, escape_shell, assume_not_none
+
+
+def _print_migration_summary(
+    migrations: List[FeatureMigration],
+    compat: int,
+    min_compat_level: int,
+    required_plugins: Set[str],
+    requested_plugins: Optional[Set[str]],
+) -> None:
+    warning_count = 0
+
+    for migration in migrations:
+        if not migration.anything_to_do:
+            continue
+        underline = "-" * len(migration.tagline)
+        if migration.warnings:
+            _warn(f"Summary for migration: {migration.tagline}")
+            _warn(f"-----------------------{underline}")
+            _warn(" /!\\ ATTENTION /!\\")
+            warning_count += len(migration.warnings)
+            for warning in migration.warnings:
+                _warn(f"    * {warning}")
+
+    if compat < min_compat_level:
+        if warning_count:
+            _warn("")
+        _warn("Supported debhelper compat check")
+        _warn("--------------------------------")
+        warning_count += 1
+        _warn(
+            f"The migration tool assumes debhelper compat {min_compat_level}+ semantics, but this package"
+            f" is using compat {compat}.  Consider upgrading the package to compat {min_compat_level}"
+            " first."
+        )
+
+    if required_plugins:
+        if requested_plugins is None:
+            warning_count += 1
+            needed_plugins = ", ".join(f"debputy-plugin-{n}" for n in required_plugins)
+            if warning_count:
+                _warn("")
+            _warn("Missing debputy plugin check")
+            _warn("----------------------------")
+            _warn(
+                f"The migration tool could not read d/control and therefore cannot tell if all the required"
+                f" plugins have been requested.  Please ensure that the package Build-Depends on: {needed_plugins}"
+            )
+        else:
+            missing_plugins = required_plugins - requested_plugins
+            if missing_plugins:
+                warning_count += 1
+                needed_plugins = ", ".join(
+                    f"debputy-plugin-{n}" for n in missing_plugins
+                )
+                if warning_count:
+                    _warn("")
+                _warn("Missing debputy plugin check")
+                _warn("----------------------------")
+                _warn(
+                    f"The migration tool asserted that the following `debputy` plugins would be required, which"
+                    f" are not explicitly requested.  Please add the following to Build-Depends: {needed_plugins}"
+                )
+
+    if warning_count:
+        _warn("")
+        _warn(
+            f"/!\\ Total number of warnings or manual migrations required: {warning_count}"
+        )
+
+
+def _dh_compat_level() -> Optional[int]:
+    try:
+        res = subprocess.check_output(
+            ["dh_assistant", "active-compat-level"], stderr=subprocess.DEVNULL
+        )
+    except subprocess.CalledProcessError:
+        compat = None
+    else:
+        try:
+            compat = json.loads(res)["declared-compat-level"]
+        except RuntimeError:
+            compat = None
+        else:
+            if not isinstance(compat, int):
+                compat = None
+    return compat
+
+
+def _requested_debputy_plugins(debian_dir: VirtualPath) -> Optional[Set[str]]:
+    ctrl_file = debian_dir.get("control")
+    if not ctrl_file:
+        return None
+
+    dep_regex = re.compile("^([a-z0-9][-+.a-z0-9]+)", re.ASCII)
+    plugins = set()
+
+    with ctrl_file.open() as fd:
+        ctrl = list(Deb822.iter_paragraphs(fd))
+    source_paragraph = ctrl[0] if ctrl else {}
+
+    for f in ("Build-Depends", "Build-Depends-Indep", "Build-Depends-Arch"):
+        field = source_paragraph.get(f)
+        if not field:
+            continue
+
+        for dep_clause in (d.strip() for d in field.split(",")):
+            match = dep_regex.match(dep_clause.strip())
+            if not match:
+                continue
+            dep = match.group(1)
+            if not dep.startswith("debputy-plugin-"):
+                continue
+            plugins.add(dep[15:])
+    return plugins
+
+
+def _check_migration_target(
+    debian_dir: VirtualPath,
+    migration_target: Optional[str],
+) -> str:
+    r = read_dh_addon_sequences(debian_dir)
+    if r is None and migration_target is None:
+        _error("debian/control is missing and no migration target was provided")
+    bd_sequences, dr_sequences = r
+    all_sequences = bd_sequences | dr_sequences
+
+    has_zz_debputy = "zz-debputy" in all_sequences or "debputy" in all_sequences
+    has_zz_debputy_rrr = "zz-debputy-rrr" in all_sequences
+    has_any_existing = has_zz_debputy or has_zz_debputy_rrr
+
+    if migration_target == "dh-sequence-zz-debputy-rrr" and has_zz_debputy:
+        _error("Cannot migrate from (zz-)debputy to zz-debputy-rrr")
+
+    if has_zz_debputy_rrr and not has_zz_debputy:
+        resolved_migration_target = MIGRATION_TARGET_DH_DEBPUTY_RRR
+    else:
+        resolved_migration_target = MIGRATION_TARGET_DH_DEBPUTY
+
+    if migration_target is not None:
+        resolved_migration_target = migration_target
+
+    if has_any_existing:
+        _info(
+            f'Using "{resolved_migration_target}" as migration target based on the packaging'
+        )
+    else:
+        _info(f'Using "{resolved_migration_target}" as default migration target.')
+
+    return resolved_migration_target
+
+
+def migrate_from_dh(
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    permit_destructive_changes: Optional[bool],
+    migration_target: Optional[str],
+    manifest_parser_factory: Callable[[str], HighLevelManifest],
+) -> None:
+    migrations = []
+    compat = _dh_compat_level()
+    if compat is None:
+        _error(
+            'Cannot detect declared compat level (try running "dh_assistant active-compat-level")'
+        )
+
+    debian_dir = manifest.debian_dir
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+
+    resolved_migration_target = _check_migration_target(debian_dir, migration_target)
+
+    try:
+        for migrator in MIGRATORS[resolved_migration_target]:
+            feature_migration = FeatureMigration(migrator.__name__)
+            migrator(
+                debian_dir,
+                manifest,
+                acceptable_migration_issues,
+                feature_migration,
+                resolved_migration_target,
+            )
+            migrations.append(feature_migration)
+    except CannotEmulateExecutableDHConfigFile as e:
+        _error(
+            f"Unable to process the executable dh config file {e.config_file().fs_path}: {e.message()}"
+        )
+    except UnsupportedFeature as e:
+        msg = (
+            f"Unable to migrate automatically due to missing features in debputy. The feature is:"
+            f"\n\n  * {e.message}"
+        )
+        keys = e.issue_keys
+        if keys:
+            primary_key = keys[0]
+            alt_keys = ""
+            if len(keys) > 1:
+                alt_keys = (
+                    f' Alternatively you can also use one of: {", ".join(keys[1:])}.  Please note that some'
+                    " of these may cover more cases."
+                )
+            msg += (
+                f"\n\nUse --acceptable-migration-issues={primary_key} to convert this into a warning and try again."
+                " However, you should only do that if you believe you can replace the functionality manually"
+                f" or the usage is obsolete / can be removed. {alt_keys}"
+            )
+        _error(msg)
+    except ConflictingChange as e:
+        _error(
+            "The migration tool detected a conflict data being migrated and data already migrated / in the existing"
+            "manifest."
+            f"\n\n   * {e.message}"
+            "\n\nPlease review the situation and resolve the conflict manually."
+        )
+
+    # We start on compat 12 for arch:any due to the new dh_makeshlibs and dh_installinit default
+    min_compat = 12
+    min_compat = max(
+        (m.assumed_compat for m in migrations if m.assumed_compat is not None),
+        default=min_compat,
+    )
+
+    if compat < min_compat and "min-compat-level" not in acceptable_migration_issues:
+        # The migration summary special-cases the compat mismatch and warns for us.
+        _error(
+            f"The migration tool assumes debhelper compat {min_compat} or later but the package is only on"
+            f" compat {compat}.  This may lead to incorrect result."
+            f"\n\nUse --acceptable-migration-issues=min-compat-level to convert this into a warning and"
+            f" try again, if you want to continue regardless."
+        )
+
+    requested_plugins = _requested_debputy_plugins(debian_dir)
+    required_plugins: Set[str] = set()
+    required_plugins.update(
+        chain.from_iterable(
+            m.required_plugins for m in migrations if m.required_plugins
+        )
+    )
+
+    _print_migration_summary(
+        migrations, compat, min_compat, required_plugins, requested_plugins
+    )
+    migration_count = sum((m.performed_changes for m in migrations), 0)
+
+    if not migration_count:
+        _info(
+            "debputy was not able to find any (supported) migrations that it could perform for you."
+        )
+        return
+
+    if any(m.successful_manifest_changes for m in migrations):
+        new_manifest_path = manifest.manifest_path + ".new"
+
+        with open(new_manifest_path, "w") as fd:
+            mutable_manifest.write_to(fd)
+
+        try:
+            _info("Verifying the generating manifest")
+            manifest_parser_factory(new_manifest_path)
+        except ManifestParseException as e:
+            raise AssertionError(
+                "Could not parse the manifest generated from the migrator"
+            ) from e
+
+        if permit_destructive_changes:
+            if os.path.isfile(manifest.manifest_path):
+                os.rename(manifest.manifest_path, manifest.manifest_path + ".orig")
+            os.rename(new_manifest_path, manifest.manifest_path)
+            _info(f"Updated manifest {manifest.manifest_path}")
+        else:
+            _info(
+                f'Created draft manifest "{new_manifest_path}" (rename to "{manifest.manifest_path}"'
+                " to activate it)"
+            )
+    else:
+        _info("No manifest changes detected; skipping update of manifest.")
+
+    removals: int = sum((len(m.remove_paths_on_success) for m in migrations), 0)
+    renames: int = sum((len(m.rename_paths_on_success) for m in migrations), 0)
+
+    if renames:
+        if permit_destructive_changes:
+            _info("Paths being renamed:")
+        else:
+            _info("Migration *would* rename the following paths:")
+        for previous_path, new_path in (
+            p for m in migrations for p in m.rename_paths_on_success
+        ):
+            _info(f"   mv {escape_shell(previous_path, new_path)}")
+
+    if removals:
+        if permit_destructive_changes:
+            _info("Removals:")
+        else:
+            _info("Migration *would* remove the following files:")
+        for path in (p for m in migrations for p in m.remove_paths_on_success):
+            _info(f"  rm -f {escape_shell(path)}")
+
+    if permit_destructive_changes is None:
+        print()
+        _info(
+            "If you would like to perform the migration, please re-run with --apply-changes."
+        )
+    elif permit_destructive_changes:
+        for previous_path, new_path in (
+            p for m in migrations for p in m.rename_paths_on_success
+        ):
+            os.rename(previous_path, new_path)
+        for path in (p for m in migrations for p in m.remove_paths_on_success):
+            os.unlink(path)
+
+        print()
+        _info("Migrations performed successfully")
+        print()
+        _info(
+            "Remember to validate the resulting binary packages after rebuilding with debputy"
+        )
+    else:
+        print()
+        _info("No migrations performed as requested")
diff --git a/src/debputy/dh_migration/migrators.py b/src/debputy/dh_migration/migrators.py
new file mode 100644
index 0000000..7e056ae
--- /dev/null
+++ b/src/debputy/dh_migration/migrators.py
@@ -0,0 +1,67 @@
+from typing import Callable, List, Mapping
+
+from debputy.dh_migration.migrators_impl import (
+    migrate_links_files,
+    migrate_maintscript,
+    migrate_tmpfile,
+    migrate_install_file,
+    migrate_installdocs_file,
+    migrate_installexamples_file,
+    migrate_dh_hook_targets,
+    migrate_misspelled_readme_debian_files,
+    migrate_doc_base_files,
+    migrate_lintian_overrides_files,
+    detect_unsupported_zz_debputy_features,
+    detect_pam_files,
+    detect_dh_addons,
+    migrate_not_installed_file,
+    migrate_installman_file,
+    migrate_bash_completion,
+    migrate_installinfo_file,
+    migrate_dh_installsystemd_files,
+    detect_obsolete_substvars,
+    detect_dh_addons_zz_debputy_rrr,
+    MIGRATION_TARGET_DH_DEBPUTY,
+    MIGRATION_TARGET_DH_DEBPUTY_RRR,
+)
+from debputy.dh_migration.models import AcceptableMigrationIssues, FeatureMigration
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.plugin.api import VirtualPath
+
+Migrator = Callable[
+    [VirtualPath, HighLevelManifest, AcceptableMigrationIssues, FeatureMigration, str],
+    None,
+]
+
+
+MIGRATORS: Mapping[str, List[Migrator]] = {
+    MIGRATION_TARGET_DH_DEBPUTY_RRR: [
+        migrate_dh_hook_targets,
+        migrate_misspelled_readme_debian_files,
+        detect_dh_addons_zz_debputy_rrr,
+        detect_obsolete_substvars,
+    ],
+    MIGRATION_TARGET_DH_DEBPUTY: [
+        detect_unsupported_zz_debputy_features,
+        detect_pam_files,
+        migrate_dh_hook_targets,
+        migrate_dh_installsystemd_files,
+        migrate_install_file,
+        migrate_installdocs_file,
+        migrate_installexamples_file,
+        migrate_installman_file,
+        migrate_installinfo_file,
+        migrate_misspelled_readme_debian_files,
+        migrate_doc_base_files,
+        migrate_links_files,
+        migrate_maintscript,
+        migrate_tmpfile,
+        migrate_lintian_overrides_files,
+        migrate_bash_completion,
+        detect_dh_addons,
+        detect_obsolete_substvars,
+        # not-installed should go last, so its rules appear after other installations
+        # It is not perfect, but it is a start.
+        migrate_not_installed_file,
+    ],
+}
diff --git a/src/debputy/dh_migration/migrators_impl.py b/src/debputy/dh_migration/migrators_impl.py
new file mode 100644
index 0000000..6613c25
--- /dev/null
+++ b/src/debputy/dh_migration/migrators_impl.py
@@ -0,0 +1,1706 @@
+import collections
+import dataclasses
+import json
+import os
+import re
+import subprocess
+from typing import (
+    Iterable,
+    Optional,
+    Tuple,
+    List,
+    Set,
+    Mapping,
+    Any,
+    Union,
+    Callable,
+    TypeVar,
+    Dict,
+)
+
+from debian.deb822 import Deb822
+
+from debputy.architecture_support import dpkg_architecture_table
+from debputy.deb_packaging_support import dpkg_field_list_pkg_dep
+from debputy.debhelper_emulation import (
+    dhe_filedoublearray,
+    DHConfigFileLine,
+    dhe_pkgfile,
+    parse_drules_for_addons,
+    extract_dh_addons_from_control,
+)
+from debputy.dh_migration.models import (
+    ConflictingChange,
+    FeatureMigration,
+    UnsupportedFeature,
+    AcceptableMigrationIssues,
+    DHMigrationSubstitution,
+)
+from debputy.highlevel_manifest import (
+    MutableYAMLSymlink,
+    HighLevelManifest,
+    MutableYAMLConffileManagementItem,
+    AbstractMutableYAMLInstallRule,
+)
+from debputy.installations import MAN_GUESS_FROM_BASENAME, MAN_GUESS_LANG_FROM_PATH
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import VirtualPath
+from debputy.util import (
+    _error,
+    PKGVERSION_REGEX,
+    PKGNAME_REGEX,
+    _normalize_path,
+    assume_not_none,
+    has_glob_magic,
+)
+
+MIGRATION_TARGET_DH_DEBPUTY_RRR = "dh-sequence-zz-debputy-rrr"
+MIGRATION_TARGET_DH_DEBPUTY = "dh-sequence-zz-debputy"
+
+
+# Align with debputy.py
+DH_COMMANDS_REPLACED = {
+    MIGRATION_TARGET_DH_DEBPUTY_RRR: frozenset(
+        {
+            "dh_fixperms",
+            "dh_gencontrol",
+            "dh_md5sums",
+            "dh_builddeb",
+        }
+    ),
+    MIGRATION_TARGET_DH_DEBPUTY: frozenset(
+        {
+            "dh_install",
+            "dh_installdocs",
+            "dh_installchangelogs",
+            "dh_installexamples",
+            "dh_installman",
+            "dh_installcatalogs",
+            "dh_installcron",
+            "dh_installdebconf",
+            "dh_installemacsen",
+            "dh_installifupdown",
+            "dh_installinfo",
+            "dh_installinit",
+            "dh_installsysusers",
+            "dh_installtmpfiles",
+            "dh_installsystemd",
+            "dh_installsystemduser",
+            "dh_installmenu",
+            "dh_installmime",
+            "dh_installmodules",
+            "dh_installlogcheck",
+            "dh_installlogrotate",
+            "dh_installpam",
+            "dh_installppp",
+            "dh_installudev",
+            "dh_installgsettings",
+            "dh_installinitramfs",
+            "dh_installalternatives",
+            "dh_bugfiles",
+            "dh_ucf",
+            "dh_lintian",
+            "dh_icons",
+            "dh_usrlocal",
+            "dh_perl",
+            "dh_link",
+            "dh_installwm",
+            "dh_installxfonts",
+            "dh_strip_nondeterminism",
+            "dh_compress",
+            "dh_fixperms",
+            "dh_dwz",
+            "dh_strip",
+            "dh_makeshlibs",
+            "dh_shlibdeps",
+            "dh_missing",
+            "dh_installdeb",
+            "dh_gencontrol",
+            "dh_md5sums",
+            "dh_builddeb",
+        }
+    ),
+}
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class UnsupportedDHConfig:
+    dh_config_basename: str
+    dh_tool: str
+    bug_950723_prefix_matching: bool = False
+    is_missing_migration: bool = False
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class DHSequenceMigration:
+    debputy_plugin: str
+    remove_dh_sequence: bool = True
+    must_use_zz_debputy: bool = False
+
+
+UNSUPPORTED_DH_CONFIGS_AND_TOOLS_FOR_ZZ_DEBPUTY = [
+    UnsupportedDHConfig("config", "dh_installdebconf"),
+    UnsupportedDHConfig("templates", "dh_installdebconf"),
+    UnsupportedDHConfig("emacsen-compat", "dh_installemacsen"),
+    UnsupportedDHConfig("emacsen-install", "dh_installemacsen"),
+    UnsupportedDHConfig("emacsen-remove", "dh_installemacsen"),
+    UnsupportedDHConfig("emacsen-startup", "dh_installemacsen"),
+    # The `upstart` file should be long dead, but we might as well detect it.
+    UnsupportedDHConfig("upstart", "dh_installinit"),
+    # dh_installsystemduser
+    UnsupportedDHConfig(
+        "user.path", "dh_installsystemduser", bug_950723_prefix_matching=False
+    ),
+    UnsupportedDHConfig(
+        "user.path", "dh_installsystemduser", bug_950723_prefix_matching=True
+    ),
+    UnsupportedDHConfig(
+        "user.service", "dh_installsystemduser", bug_950723_prefix_matching=False
+    ),
+    UnsupportedDHConfig(
+        "user.service", "dh_installsystemduser", bug_950723_prefix_matching=True
+    ),
+    UnsupportedDHConfig(
+        "user.socket", "dh_installsystemduser", bug_950723_prefix_matching=False
+    ),
+    UnsupportedDHConfig(
+        "user.socket", "dh_installsystemduser", bug_950723_prefix_matching=True
+    ),
+    UnsupportedDHConfig(
+        "user.target", "dh_installsystemduser", bug_950723_prefix_matching=False
+    ),
+    UnsupportedDHConfig(
+        "user.target", "dh_installsystemduser", bug_950723_prefix_matching=True
+    ),
+    UnsupportedDHConfig(
+        "user.timer", "dh_installsystemduser", bug_950723_prefix_matching=False
+    ),
+    UnsupportedDHConfig(
+        "user.timer", "dh_installsystemduser", bug_950723_prefix_matching=True
+    ),
+    UnsupportedDHConfig("udev", "dh_installudev"),
+    UnsupportedDHConfig("menu", "dh_installmenu"),
+    UnsupportedDHConfig("menu-method", "dh_installmenu"),
+    UnsupportedDHConfig("ucf", "dh_ucf"),
+    UnsupportedDHConfig("wm", "dh_installwm"),
+    UnsupportedDHConfig("triggers", "dh_installdeb"),
+    UnsupportedDHConfig("postinst", "dh_installdeb"),
+    UnsupportedDHConfig("postrm", "dh_installdeb"),
+    UnsupportedDHConfig("preinst", "dh_installdeb"),
+    UnsupportedDHConfig("prerm", "dh_installdeb"),
+    UnsupportedDHConfig("menutest", "dh_installdeb"),
+    UnsupportedDHConfig("isinstallable", "dh_installdeb"),
+]
+SUPPORTED_DH_ADDONS = frozenset(
+    {
+        # debputy's own
+        "debputy",
+        "zz-debputy",
+        # debhelper provided sequences that should work.
+        "single-binary",
+    }
+)
+DH_ADDONS_TO_REMOVE = frozenset(
+    [
+        # Sequences debputy directly replaces
+        "dwz",
+        "elf-tools",
+        "installinitramfs",
+        "installsysusers",
+        "doxygen",
+        # Sequences that are embedded fully into debputy
+        "bash-completion",
+        "sodeps",
+    ]
+)
+DH_ADDONS_TO_PLUGINS = {
+    "gnome": DHSequenceMigration(
+        "gnome",
+        # The sequence still provides a command for the clean sequence
+        remove_dh_sequence=False,
+        must_use_zz_debputy=True,
+    ),
+    "numpy3": DHSequenceMigration(
+        "numpy3",
+        # The sequence provides (build-time) dependencies that we cannot provide
+        remove_dh_sequence=False,
+        must_use_zz_debputy=True,
+    ),
+    "perl-openssl": DHSequenceMigration(
+        "perl-openssl",
+        # The sequence provides (build-time) dependencies that we cannot provide
+        remove_dh_sequence=False,
+        must_use_zz_debputy=True,
+    ),
+}
+
+
+def _dh_config_file(
+    debian_dir: VirtualPath,
+    dctrl_bin: BinaryPackage,
+    basename: str,
+    helper_name: str,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    manifest: HighLevelManifest,
+    support_executable_files: bool = False,
+    allow_dh_exec_rename: bool = False,
+    pkgfile_lookup: bool = True,
+    remove_on_migration: bool = True,
+) -> Union[Tuple[None, None], Tuple[VirtualPath, Iterable[DHConfigFileLine]]]:
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    dh_config_file = (
+        dhe_pkgfile(debian_dir, dctrl_bin, basename)
+        if pkgfile_lookup
+        else debian_dir.get(basename)
+    )
+    if dh_config_file is None or dh_config_file.is_dir:
+        return None, None
+    if dh_config_file.is_executable and not support_executable_files:
+        primary_key = f"executable-{helper_name}-config"
+        if (
+            primary_key in acceptable_migration_issues
+            or "any-executable-dh-configs" in acceptable_migration_issues
+        ):
+            feature_migration.warn(
+                f'TODO: MANUAL MIGRATION of executable dh config "{dh_config_file}" is required.'
+            )
+            return None, None
+        raise UnsupportedFeature(
+            f"Executable configuration files not supported (found: {dh_config_file}).",
+            [primary_key, "any-executable-dh-configs"],
+        )
+
+    if remove_on_migration:
+        feature_migration.remove_on_success(dh_config_file.fs_path)
+    substitution = DHMigrationSubstitution(
+        dpkg_architecture_table(),
+        acceptable_migration_issues,
+        feature_migration,
+        mutable_manifest,
+    )
+    content = dhe_filedoublearray(
+        dh_config_file,
+        substitution,
+        allow_dh_exec_rename=allow_dh_exec_rename,
+    )
+    return dh_config_file, content
+
+
+def _validate_rm_mv_conffile(
+    package: str,
+    config_line: DHConfigFileLine,
+) -> Tuple[str, str, Optional[str], Optional[str], Optional[str]]:
+    cmd, *args = config_line.tokens
+    if "--" in config_line.tokens:
+        raise ValueError(
+            f'The maintscripts file "{config_line.config_file.path}" for {package} includes a "--" in line'
+            f" {config_line.line_no}. The offending line is: {config_line.original_line}"
+        )
+    if cmd == "rm_conffile":
+        min_args = 1
+        max_args = 3
+    else:
+        min_args = 2
+        max_args = 4
+    if len(args) > max_args or len(args) < min_args:
+        raise ValueError(
+            f'The "{cmd}" command takes at least {min_args} and at most {max_args} arguments.  However,'
+            f' in "{config_line.config_file.path}" line {config_line.line_no} (for {package}), there'
+            f" are {len(args)} arguments. The offending line is: {config_line.original_line}"
+        )
+
+    obsolete_conffile = args[0]
+    new_conffile = args[1] if cmd == "mv_conffile" else None
+    prior_version = args[min_args] if len(args) > min_args else None
+    owning_package = args[min_args + 1] if len(args) > min_args + 1 else None
+    if not obsolete_conffile.startswith("/"):
+        raise ValueError(
+            f'The (old-)conffile parameter for {cmd} must be absolute (i.e., start with "/").  However,'
+            f' in "{config_line.config_file.path}" line {config_line.line_no} (for {package}), it was specified'
+            f' as "{obsolete_conffile}". The offending line is: {config_line.original_line}'
+        )
+    if new_conffile is not None and not new_conffile.startswith("/"):
+        raise ValueError(
+            f'The new-conffile parameter for {cmd} must be absolute (i.e., start with "/").  However,'
+            f' in "{config_line.config_file.path}" line {config_line.line_no} (for {package}), it was specified'
+            f' as "{new_conffile}". The offending line is: {config_line.original_line}'
+        )
+    if prior_version is not None and not PKGVERSION_REGEX.fullmatch(prior_version):
+        raise ValueError(
+            f"The prior-version parameter for {cmd} must be a valid package version (i.e., match"
+            f' {PKGVERSION_REGEX}).  However, in "{config_line.config_file.path}" line {config_line.line_no}'
+            f' (for {package}), it was specified as "{prior_version}". The offending line is:'
+            f" {config_line.original_line}"
+        )
+    if owning_package is not None and not PKGNAME_REGEX.fullmatch(owning_package):
+        raise ValueError(
+            f"The package parameter for {cmd} must be a valid package name (i.e., match {PKGNAME_REGEX})."
+            f'  However, in "{config_line.config_file.path}" line {config_line.line_no} (for {package}), it'
+            f' was specified as "{owning_package}". The offending line is: {config_line.original_line}'
+        )
+    return cmd, obsolete_conffile, new_conffile, prior_version, owning_package
+
+
+_BASH_COMPLETION_RE = re.compile(
+    r"""
+      (^|[|&;])\s*complete.*-[A-Za-z].*
+    | \$\(.*\)
+    | \s*compgen.*-[A-Za-z].*
+    | \s*if.*;.*then/
+""",
+    re.VERBOSE,
+)
+
+
+def migrate_bash_completion(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_bash-completion files"
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+
+    for dctrl_bin in manifest.all_packages:
+        dh_file = dhe_pkgfile(debian_dir, dctrl_bin, "bash-completion")
+        if dh_file is None:
+            continue
+        is_bash_completion_file = False
+        with dh_file.open() as fd:
+            for line in fd:
+                line = line.strip()
+                if not line or line[0] == "#":
+                    continue
+                if _BASH_COMPLETION_RE.search(line):
+                    is_bash_completion_file = True
+                    break
+        if not is_bash_completion_file:
+            _, content = _dh_config_file(
+                debian_dir,
+                dctrl_bin,
+                "bash-completion",
+                "dh_bash-completion",
+                acceptable_migration_issues,
+                feature_migration,
+                manifest,
+                support_executable_files=True,
+            )
+        else:
+            content = None
+
+        if content:
+            install_dest_sources: List[str] = []
+            install_as_rules: List[Tuple[str, str]] = []
+            for dhe_line in content:
+                if len(dhe_line.tokens) > 2:
+                    raise UnsupportedFeature(
+                        f"The dh_bash-completion file {dh_file.path} more than two words on"
+                        f' line {dhe_line.line_no} (line: "{dhe_line.original_line}").'
+                    )
+                source = dhe_line.tokens[0]
+                dest_basename = (
+                    dhe_line.tokens[1]
+                    if len(dhe_line.tokens) > 1
+                    else os.path.basename(source)
+                )
+                if source.startswith("debian/") and not has_glob_magic(source):
+                    if dctrl_bin.name != dest_basename:
+                        dest_path = (
+                            f"debian/{dctrl_bin.name}.{dest_basename}.bash-completion"
+                        )
+                    else:
+                        dest_path = f"debian/{dest_basename}.bash-completion"
+                    feature_migration.rename_on_success(source, dest_path)
+                elif len(dhe_line.tokens) == 1:
+                    install_dest_sources.append(source)
+                else:
+                    install_as_rules.append((source, dest_basename))
+
+            if install_dest_sources:
+                sources = (
+                    install_dest_sources
+                    if len(install_dest_sources) > 1
+                    else install_dest_sources[0]
+                )
+                installations.append(
+                    AbstractMutableYAMLInstallRule.install_dest(
+                        sources=sources,
+                        dest_dir="{{path:BASH_COMPLETION_DIR}}",
+                        into=dctrl_bin.name if not is_single_binary else None,
+                    )
+                )
+
+            for source, dest_basename in install_as_rules:
+                installations.append(
+                    AbstractMutableYAMLInstallRule.install_as(
+                        source=source,
+                        install_as="{{path:BASH_COMPLETION_DIR}}/" + dest_basename,
+                        into=dctrl_bin.name if not is_single_binary else None,
+                    )
+                )
+
+
+def migrate_dh_installsystemd_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    _acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installsystemd files"
+    for dctrl_bin in manifest.all_packages:
+        for stem in [
+            "path",
+            "service",
+            "socket",
+            "target",
+            "timer",
+        ]:
+            pkgfile = dhe_pkgfile(
+                debian_dir, dctrl_bin, stem, bug_950723_prefix_matching=True
+            )
+            if not pkgfile:
+                continue
+            if not pkgfile.name.endswith(f".{stem}") or "@." not in pkgfile.name:
+                raise UnsupportedFeature(
+                    f'Unable to determine the correct name for {pkgfile.fs_path}. It should be a ".@{stem}"'
+                    f" file now (foo@.service => foo.@service)"
+                )
+            newname = pkgfile.name.replace("@.", ".")
+            newname = newname[: -len(stem)] + f"@{stem}"
+            feature_migration.rename_on_success(
+                pkgfile.fs_path, os.path.join(debian_dir.fs_path, newname)
+            )
+
+
+def migrate_maintscript(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installdeb files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    for dctrl_bin in manifest.all_packages:
+        mainscript_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "maintscript",
+            "dh_installdeb",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+        )
+
+        if mainscript_file is None:
+            continue
+        assert content is not None
+
+        package_definition = mutable_manifest.package(dctrl_bin.name)
+        conffiles = {
+            it.obsolete_conffile: it
+            for it in package_definition.conffile_management_items()
+        }
+        seen_conffiles = set()
+
+        for dhe_line in content:
+            cmd = dhe_line.tokens[0]
+            if cmd not in {"rm_conffile", "mv_conffile"}:
+                raise UnsupportedFeature(
+                    f"The dh_installdeb file {mainscript_file.path} contains the (currently)"
+                    f' unsupported command "{cmd}" on line {dhe_line.line_no}'
+                    f' (line: "{dhe_line.original_line}")'
+                )
+
+            try:
+                (
+                    _,
+                    obsolete_conffile,
+                    new_conffile,
+                    prior_to_version,
+                    owning_package,
+                ) = _validate_rm_mv_conffile(dctrl_bin.name, dhe_line)
+            except ValueError as e:
+                _error(
+                    f"Validation error in {mainscript_file} on line {dhe_line.line_no}. The error was: {e.args[0]}."
+                )
+
+            if obsolete_conffile in seen_conffiles:
+                raise ConflictingChange(
+                    f'The {mainscript_file} file defines actions for "{obsolete_conffile}" twice!'
+                    f" Please ensure that it is defined at most once in that file."
+                )
+            seen_conffiles.add(obsolete_conffile)
+
+            if cmd == "rm_conffile":
+                item = MutableYAMLConffileManagementItem.rm_conffile(
+                    obsolete_conffile,
+                    prior_to_version,
+                    owning_package,
+                )
+            else:
+                assert cmd == "mv_conffile"
+                item = MutableYAMLConffileManagementItem.mv_conffile(
+                    obsolete_conffile,
+                    assume_not_none(new_conffile),
+                    prior_to_version,
+                    owning_package,
+                )
+
+            existing_def = conffiles.get(item.obsolete_conffile)
+            if existing_def is not None:
+                if not (
+                    item.command == existing_def.command
+                    and item.new_conffile == existing_def.new_conffile
+                    and item.prior_to_version == existing_def.prior_to_version
+                    and item.owning_package == existing_def.owning_package
+                ):
+                    raise ConflictingChange(
+                        f"The maintscript defines the action {item.command} for"
+                        f' "{obsolete_conffile}" in {mainscript_file}, but there is another'
+                        f" conffile management definition for same path defined already (in the"
+                        f" existing manifest or an migration e.g., inside {mainscript_file})"
+                    )
+                feature_migration.already_present += 1
+                continue
+
+            package_definition.add_conffile_management(item)
+            feature_migration.successful_manifest_changes += 1
+
+
+@dataclasses.dataclass(slots=True)
+class SourcesAndConditional:
+    dest_dir: Optional[str] = None
+    sources: List[str] = dataclasses.field(default_factory=list)
+    conditional: Optional[Union[str, Mapping[str, Any]]] = None
+
+
+def _strip_d_tmp(p: str) -> str:
+    if p.startswith("debian/tmp/") and len(p) > 11:
+        return p[11:]
+    return p
+
+
+def migrate_install_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_install config files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+    priority_lines = []
+    remaining_install_lines = []
+    warn_about_fixmes_in_dest_dir = False
+
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+
+    for dctrl_bin in manifest.all_packages:
+        install_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "install",
+            "dh_install",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+            allow_dh_exec_rename=True,
+        )
+        if not install_file or not content:
+            continue
+        current_sources = []
+        sources_by_destdir: Dict[Tuple[str, Tuple[str, ...]], SourcesAndConditional] = (
+            {}
+        )
+        install_as_rules = []
+        multi_dest = collections.defaultdict(list)
+        seen_sources = set()
+        multi_dest_sources: Set[str] = set()
+
+        for dhe_line in content:
+            special_rule = None
+            if "=>" in dhe_line.tokens:
+                if dhe_line.tokens[0] == "=>" and len(dhe_line.tokens) == 2:
+                    # This rule must be as early as possible to retain the semantics
+                    path = _strip_d_tmp(
+                        _normalize_path(dhe_line.tokens[1], with_prefix=False)
+                    )
+                    special_rule = AbstractMutableYAMLInstallRule.install_dest(
+                        path,
+                        dctrl_bin.name if not is_single_binary else None,
+                        dest_dir=None,
+                        when=dhe_line.conditional(),
+                    )
+                elif len(dhe_line.tokens) != 3:
+                    _error(
+                        f"Validation error in {install_file.path} on line {dhe_line.line_no}. Cannot migrate dh-exec"
+                        ' renames that is not exactly "SOURCE => TARGET" or "=> TARGET".'
+                    )
+                else:
+                    install_rule = AbstractMutableYAMLInstallRule.install_as(
+                        _strip_d_tmp(
+                            _normalize_path(dhe_line.tokens[0], with_prefix=False)
+                        ),
+                        _normalize_path(dhe_line.tokens[2], with_prefix=False),
+                        dctrl_bin.name if not is_single_binary else None,
+                        when=dhe_line.conditional(),
+                    )
+                    install_as_rules.append(install_rule)
+            else:
+                if len(dhe_line.tokens) > 1:
+                    sources = list(
+                        _strip_d_tmp(_normalize_path(w, with_prefix=False))
+                        for w in dhe_line.tokens[:-1]
+                    )
+                    dest_dir = _normalize_path(dhe_line.tokens[-1], with_prefix=False)
+                else:
+                    sources = list(
+                        _strip_d_tmp(_normalize_path(w, with_prefix=False))
+                        for w in dhe_line.tokens
+                    )
+                    dest_dir = None
+
+                multi_dest_sources.update(s for s in sources if s in seen_sources)
+                seen_sources.update(sources)
+
+                if dest_dir is None and dhe_line.conditional() is None:
+                    current_sources.extend(sources)
+                    continue
+                key = (dest_dir, dhe_line.conditional_key())
+                md = _fetch_or_create(
+                    sources_by_destdir,
+                    key,
+                    # Use named parameters to avoid warnings about the values possible changing
+                    # in the next iteration. We always resolve the lambda in this iteration, so
+                    # the bug is non-existent. However, that is harder for a linter to prove.
+                    lambda *, dest=dest_dir, dhe=dhe_line: SourcesAndConditional(
+                        dest_dir=dest,
+                        conditional=dhe.conditional(),
+                    ),
+                )
+                md.sources.extend(sources)
+
+            if special_rule:
+                priority_lines.append(special_rule)
+
+        remaining_install_lines.extend(install_as_rules)
+
+        for md in sources_by_destdir.values():
+            if multi_dest_sources:
+                sources = [s for s in md.sources if s not in multi_dest_sources]
+                already_installed = (s for s in md.sources if s in multi_dest_sources)
+                for s in already_installed:
+                    # The sources are ignored, so we can reuse the object as-is
+                    multi_dest[s].append(md)
+                if not sources:
+                    continue
+            else:
+                sources = md.sources
+            install_rule = AbstractMutableYAMLInstallRule.install_dest(
+                sources[0] if len(sources) == 1 else sources,
+                dctrl_bin.name if not is_single_binary else None,
+                dest_dir=md.dest_dir,
+                when=md.conditional,
+            )
+            remaining_install_lines.append(install_rule)
+
+        if current_sources:
+            if multi_dest_sources:
+                sources = [s for s in current_sources if s not in multi_dest_sources]
+                already_installed = (
+                    s for s in current_sources if s in multi_dest_sources
+                )
+                for s in already_installed:
+                    # The sources are ignored, so we can reuse the object as-is
+                    dest_dir = os.path.dirname(s)
+                    if has_glob_magic(dest_dir):
+                        warn_about_fixmes_in_dest_dir = True
+                        dest_dir = f"FIXME: {dest_dir} (could not reliably compute the dest dir)"
+                    multi_dest[s].append(
+                        SourcesAndConditional(
+                            dest_dir=dest_dir,
+                            conditional=None,
+                        )
+                    )
+            else:
+                sources = current_sources
+
+            if sources:
+                install_rule = AbstractMutableYAMLInstallRule.install_dest(
+                    sources[0] if len(sources) == 1 else sources,
+                    dctrl_bin.name if not is_single_binary else None,
+                    dest_dir=None,
+                )
+                remaining_install_lines.append(install_rule)
+
+        if multi_dest:
+            for source, dest_and_conditionals in multi_dest.items():
+                dest_dirs = [dac.dest_dir for dac in dest_and_conditionals]
+                # We assume the conditional is the same.
+                conditional = next(
+                    iter(
+                        dac.conditional
+                        for dac in dest_and_conditionals
+                        if dac.conditional is not None
+                    ),
+                    None,
+                )
+                remaining_install_lines.append(
+                    AbstractMutableYAMLInstallRule.multi_dest_install(
+                        source,
+                        dest_dirs,
+                        dctrl_bin.name if not is_single_binary else None,
+                        when=conditional,
+                    )
+                )
+
+    if priority_lines:
+        installations.extend(priority_lines)
+
+    if remaining_install_lines:
+        installations.extend(remaining_install_lines)
+
+    feature_migration.successful_manifest_changes += len(priority_lines) + len(
+        remaining_install_lines
+    )
+    if warn_about_fixmes_in_dest_dir:
+        feature_migration.warn(
+            "TODO: FIXME left in dest-dir(s) of some installation rules."
+            " Please review these and remove the FIXME (plus correct as necessary)"
+        )
+
+
+def migrate_installdocs_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installdocs config files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+
+    for dctrl_bin in manifest.all_packages:
+        install_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "docs",
+            "dh_installdocs",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+        )
+        if not install_file:
+            continue
+        assert content is not None
+        docs: List[str] = []
+        for dhe_line in content:
+            if dhe_line.arch_filter or dhe_line.build_profile_filter:
+                _error(
+                    f"Unable to migrate line {dhe_line.line_no} of {install_file.path}."
+                    " Missing support for conditions."
+                )
+            docs.extend(_normalize_path(w, with_prefix=False) for w in dhe_line.tokens)
+
+        if not docs:
+            continue
+        feature_migration.successful_manifest_changes += 1
+        install_rule = AbstractMutableYAMLInstallRule.install_docs(
+            docs if len(docs) > 1 else docs[0],
+            dctrl_bin.name if not is_single_binary else None,
+        )
+        installations.create_definition_if_missing()
+        installations.append(install_rule)
+
+
+def migrate_installexamples_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installexamples config files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+
+    for dctrl_bin in manifest.all_packages:
+        install_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "examples",
+            "dh_installexamples",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+        )
+        if not install_file:
+            continue
+        assert content is not None
+        examples: List[str] = []
+        for dhe_line in content:
+            if dhe_line.arch_filter or dhe_line.build_profile_filter:
+                _error(
+                    f"Unable to migrate line {dhe_line.line_no} of {install_file.path}."
+                    " Missing support for conditions."
+                )
+            examples.extend(
+                _normalize_path(w, with_prefix=False) for w in dhe_line.tokens
+            )
+
+        if not examples:
+            continue
+        feature_migration.successful_manifest_changes += 1
+        install_rule = AbstractMutableYAMLInstallRule.install_examples(
+            examples if len(examples) > 1 else examples[0],
+            dctrl_bin.name if not is_single_binary else None,
+        )
+        installations.create_definition_if_missing()
+        installations.append(install_rule)
+
+
+@dataclasses.dataclass(slots=True)
+class InfoFilesDefinition:
+    sources: List[str] = dataclasses.field(default_factory=list)
+    conditional: Optional[Union[str, Mapping[str, Any]]] = None
+
+
+def migrate_installinfo_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installinfo config files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+
+    for dctrl_bin in manifest.all_packages:
+        info_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "info",
+            "dh_installinfo",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+        )
+        if not info_file:
+            continue
+        assert content is not None
+        info_files_by_condition: Dict[Tuple[str, ...], InfoFilesDefinition] = {}
+        for dhe_line in content:
+            key = dhe_line.conditional_key()
+            info_def = _fetch_or_create(
+                info_files_by_condition,
+                key,
+                lambda: InfoFilesDefinition(conditional=dhe_line.conditional()),
+            )
+            info_def.sources.extend(
+                _normalize_path(w, with_prefix=False) for w in dhe_line.tokens
+            )
+
+        if not info_files_by_condition:
+            continue
+        feature_migration.successful_manifest_changes += 1
+        installations.create_definition_if_missing()
+        for info_def in info_files_by_condition.values():
+            info_files = info_def.sources
+            install_rule = AbstractMutableYAMLInstallRule.install_docs(
+                info_files if len(info_files) > 1 else info_files[0],
+                dctrl_bin.name if not is_single_binary else None,
+                dest_dir="{{path:GNU_INFO_DIR}}",
+                when=info_def.conditional,
+            )
+            installations.append(install_rule)
+
+
+@dataclasses.dataclass(slots=True)
+class ManpageDefinition:
+    sources: List[str] = dataclasses.field(default_factory=list)
+    language: Optional[str] = None
+    conditional: Optional[Union[str, Mapping[str, Any]]] = None
+
+
+DK = TypeVar("DK")
+DV = TypeVar("DV")
+
+
+def _fetch_or_create(d: Dict[DK, DV], key: DK, factory: Callable[[], DV]) -> DV:
+    v = d.get(key)
+    if v is None:
+        v = factory()
+        d[key] = v
+    return v
+
+
+def migrate_installman_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installman config files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+    is_single_binary = sum(1 for _ in manifest.all_packages) == 1
+    warn_about_basename = False
+
+    for dctrl_bin in manifest.all_packages:
+        manpages_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "manpages",
+            "dh_installman",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+            allow_dh_exec_rename=True,
+        )
+        if not manpages_file:
+            continue
+        assert content is not None
+
+        vanilla_definitions = []
+        install_as_rules = []
+        complex_definitions: Dict[
+            Tuple[Optional[str], Tuple[str, ...]], ManpageDefinition
+        ] = {}
+        install_rule: AbstractMutableYAMLInstallRule
+        for dhe_line in content:
+            if "=>" in dhe_line.tokens:
+                # dh-exec allows renaming features.  For `debputy`, we degenerate it into an `install` (w. `as`) feature
+                # without any of the `install-man` features.
+                if dhe_line.tokens[0] == "=>" and len(dhe_line.tokens) == 2:
+                    _error(
+                        f'Unsupported "=> DEST" rule for error in {manpages_file.path} on line {dhe_line.line_no}."'
+                        f' Cannot migrate dh-exec renames that is not exactly "SOURCE => TARGET" for d/manpages files.'
+                    )
+                elif len(dhe_line.tokens) != 3:
+                    _error(
+                        f"Validation error in {manpages_file.path} on line {dhe_line.line_no}. Cannot migrate dh-exec"
+                        ' renames that is not exactly "SOURCE => TARGET" or "=> TARGET".'
+                    )
+                else:
+                    install_rule = AbstractMutableYAMLInstallRule.install_doc_as(
+                        _normalize_path(dhe_line.tokens[0], with_prefix=False),
+                        _normalize_path(dhe_line.tokens[2], with_prefix=False),
+                        dctrl_bin.name if not is_single_binary else None,
+                        when=dhe_line.conditional(),
+                    )
+                    install_as_rules.append(install_rule)
+                continue
+
+            sources = [_normalize_path(w, with_prefix=False) for w in dhe_line.tokens]
+            needs_basename = any(
+                MAN_GUESS_FROM_BASENAME.search(x)
+                and not MAN_GUESS_LANG_FROM_PATH.search(x)
+                for x in sources
+            )
+            if needs_basename or dhe_line.conditional() is not None:
+                if needs_basename:
+                    warn_about_basename = True
+                    language = "derive-from-basename"
+                else:
+                    language = None
+                key = (language, dhe_line.conditional_key())
+                manpage_def = _fetch_or_create(
+                    complex_definitions,
+                    key,
+                    lambda: ManpageDefinition(
+                        language=language, conditional=dhe_line.conditional()
+                    ),
+                )
+                manpage_def.sources.extend(sources)
+            else:
+                vanilla_definitions.extend(sources)
+
+        if not install_as_rules and not vanilla_definitions and not complex_definitions:
+            continue
+        feature_migration.successful_manifest_changes += 1
+        installations.create_definition_if_missing()
+        installations.extend(install_as_rules)
+        if vanilla_definitions:
+            man_source = (
+                vanilla_definitions
+                if len(vanilla_definitions) > 1
+                else vanilla_definitions[0]
+            )
+            install_rule = AbstractMutableYAMLInstallRule.install_man(
+                man_source,
+                dctrl_bin.name if not is_single_binary else None,
+                None,
+            )
+            installations.append(install_rule)
+        for manpage_def in complex_definitions.values():
+            sources = manpage_def.sources
+            install_rule = AbstractMutableYAMLInstallRule.install_man(
+                sources if len(sources) > 1 else sources[0],
+                dctrl_bin.name if not is_single_binary else None,
+                manpage_def.language,
+                when=manpage_def.conditional,
+            )
+            installations.append(install_rule)
+
+    if warn_about_basename:
+        feature_migration.warn(
+            'Detected manpages that might rely on "derive-from-basename" logic.  Please double check'
+            " that the generated `install-man` rules are correct"
+        )
+
+
+def migrate_not_installed_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_missing's not-installed config file"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    installations = mutable_manifest.installations(create_if_absent=False)
+    main_binary = [p for p in manifest.all_packages if p.is_main_package][0]
+
+    missing_file, content = _dh_config_file(
+        debian_dir,
+        main_binary,
+        "not-installed",
+        "dh_missing",
+        acceptable_migration_issues,
+        feature_migration,
+        manifest,
+        support_executable_files=False,
+        pkgfile_lookup=False,
+    )
+    discard_rules: List[str] = []
+    if missing_file:
+        assert content is not None
+        for dhe_line in content:
+            discard_rules.extend(
+                _normalize_path(w, with_prefix=False) for w in dhe_line.tokens
+            )
+
+    if discard_rules:
+        feature_migration.successful_manifest_changes += 1
+        install_rule = AbstractMutableYAMLInstallRule.discard(
+            discard_rules if len(discard_rules) > 1 else discard_rules[0],
+        )
+        installations.create_definition_if_missing()
+        installations.append(install_rule)
+
+
+def detect_pam_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    _acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "detect dh_installpam files (min dh compat)"
+    for dctrl_bin in manifest.all_packages:
+        dh_config_file = dhe_pkgfile(debian_dir, dctrl_bin, "pam")
+        if dh_config_file is not None:
+            feature_migration.assumed_compat = 14
+            break
+
+
+def migrate_tmpfile(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    _acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_installtmpfiles config files"
+    for dctrl_bin in manifest.all_packages:
+        dh_config_file = dhe_pkgfile(debian_dir, dctrl_bin, "tmpfile")
+        if dh_config_file is not None:
+            target = (
+                dh_config_file.name.replace(".tmpfile", ".tmpfiles")
+                if "." in dh_config_file.name
+                else "tmpfiles"
+            )
+            _rename_file_if_exists(
+                debian_dir,
+                dh_config_file.name,
+                target,
+                feature_migration,
+            )
+
+
+def migrate_lintian_overrides_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_lintian config files"
+    for dctrl_bin in manifest.all_packages:
+        # We do not support executable lintian-overrides and `_dh_config_file` handles all of that.
+        # Therefore, the return value is irrelevant to us.
+        _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "lintian-overrides",
+            "dh_lintian",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=False,
+            remove_on_migration=False,
+        )
+
+
+def migrate_links_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh_link files"
+    mutable_manifest = assume_not_none(manifest.mutable_manifest)
+    for dctrl_bin in manifest.all_packages:
+        links_file, content = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "links",
+            "dh_link",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=True,
+        )
+
+        if links_file is None:
+            continue
+        assert content is not None
+
+        package_definition = mutable_manifest.package(dctrl_bin.name)
+        defined_symlink = {
+            symlink.symlink_path: symlink.symlink_target
+            for symlink in package_definition.symlinks()
+        }
+
+        seen_symlinks: Set[str] = set()
+
+        for dhe_line in content:
+            if len(dhe_line.tokens) != 2:
+                raise UnsupportedFeature(
+                    f"The dh_link file {links_file.fs_path} did not have exactly two paths on line"
+                    f' {dhe_line.line_no} (line: "{dhe_line.original_line}"'
+                )
+            target, source = dhe_line.tokens
+            if source in seen_symlinks:
+                # According to #934499, this has happened in the wild already
+                raise ConflictingChange(
+                    f"The {links_file.fs_path} file defines the link path {source} twice! Please ensure"
+                    " that it is defined at most once in that file"
+                )
+            seen_symlinks.add(source)
+            # Symlinks in .links are always considered absolute, but you were not required to have a leading slash.
+            # However, in the debputy manifest, you can have relative links, so we should ensure it is explicitly
+            # absolute.
+            if not target.startswith("/"):
+                target = "/" + target
+            existing_target = defined_symlink.get(source)
+            if existing_target is not None:
+                if existing_target != target:
+                    raise ConflictingChange(
+                        f'The symlink "{source}" points to "{target}" in {links_file}, but there is'
+                        f' another symlink with same path pointing to "{existing_target}" defined'
+                        " already (in the existing manifest or an migration e.g., inside"
+                        f" {links_file.fs_path})"
+                    )
+                feature_migration.already_present += 1
+                continue
+            condition = dhe_line.conditional()
+            package_definition.add_symlink(
+                MutableYAMLSymlink.new_symlink(
+                    source,
+                    target,
+                    condition,
+                )
+            )
+            feature_migration.successful_manifest_changes += 1
+
+
+def migrate_misspelled_readme_debian_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "misspelled README.Debian files"
+    for dctrl_bin in manifest.all_packages:
+        readme, _ = _dh_config_file(
+            debian_dir,
+            dctrl_bin,
+            "README.debian",
+            "dh_installdocs",
+            acceptable_migration_issues,
+            feature_migration,
+            manifest,
+            support_executable_files=False,
+            remove_on_migration=False,
+        )
+        if readme is None:
+            continue
+        new_name = readme.name.replace("README.debian", "README.Debian")
+        assert readme.name != new_name
+        _rename_file_if_exists(
+            debian_dir,
+            readme.name,
+            new_name,
+            feature_migration,
+        )
+
+
+def migrate_doc_base_files(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    _: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "doc-base files"
+    # ignore the dh_make ".EX" file if one should still be present. The dh_installdocs tool ignores it too.
+    possible_effected_doc_base_files = [
+        f
+        for f in debian_dir.iterdir
+        if (
+            (".doc-base." in f.name or f.name.startswith("doc-base."))
+            and not f.name.endswith("doc-base.EX")
+        )
+    ]
+    known_packages = {d.name: d for d in manifest.all_packages}
+    main_package = [d for d in manifest.all_packages if d.is_main_package][0]
+    for doc_base_file in possible_effected_doc_base_files:
+        parts = doc_base_file.name.split(".")
+        owning_package = known_packages.get(parts[0])
+        if owning_package is None:
+            owning_package = main_package
+            package_part = None
+        else:
+            package_part = parts[0]
+            parts = parts[1:]
+
+        if not parts or parts[0] != "doc-base":
+            # Not a doc-base file after all
+            continue
+
+        if len(parts) > 1:
+            name_part = ".".join(parts[1:])
+            if package_part is None:
+                # Named files must have a package prefix
+                package_part = owning_package.name
+        else:
+            # No rename needed
+            continue
+
+        new_basename = ".".join(filter(None, (package_part, name_part, "doc-base")))
+        _rename_file_if_exists(
+            debian_dir,
+            doc_base_file.name,
+            new_basename,
+            feature_migration,
+        )
+
+
+def migrate_dh_hook_targets(
+    debian_dir: VirtualPath,
+    _: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    migration_target: str,
+) -> None:
+    feature_migration.tagline = "dh hook targets"
+    source_root = os.path.dirname(debian_dir.fs_path)
+    if source_root == "":
+        source_root = "."
+    detected_hook_targets = json.loads(
+        subprocess.check_output(
+            ["dh_assistant", "detect-hook-targets"],
+            cwd=source_root,
+        ).decode("utf-8")
+    )
+    sample_hook_target: Optional[str] = None
+    replaced_commands = DH_COMMANDS_REPLACED[migration_target]
+
+    for hook_target_def in detected_hook_targets["hook-targets"]:
+        if hook_target_def["is-empty"]:
+            continue
+        command = hook_target_def["command"]
+        if command not in replaced_commands:
+            continue
+        hook_target = hook_target_def["target-name"]
+        if sample_hook_target is None:
+            sample_hook_target = hook_target
+        feature_migration.warn(
+            f"TODO: MANUAL MIGRATION required for hook target {hook_target}"
+        )
+    if (
+        feature_migration.warnings
+        and "dh-hook-targets" not in acceptable_migration_issues
+    ):
+        assert sample_hook_target
+        raise UnsupportedFeature(
+            f"The debian/rules file contains one or more non empty dh hook targets that will not"
+            f" be run with the requested debputy dh sequence. One of these would be"
+            f" {sample_hook_target}.",
+            ["dh-hook-targets"],
+        )
+
+
+def detect_unsupported_zz_debputy_features(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "Known unsupported features"
+
+    for unsupported_config in UNSUPPORTED_DH_CONFIGS_AND_TOOLS_FOR_ZZ_DEBPUTY:
+        _unsupported_debhelper_config_file(
+            debian_dir,
+            manifest,
+            unsupported_config,
+            acceptable_migration_issues,
+            feature_migration,
+        )
+
+
+def detect_obsolete_substvars(
+    debian_dir: VirtualPath,
+    _manifest: HighLevelManifest,
+    _acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = (
+        "Check for obsolete ${foo:var} variables in debian/control"
+    )
+    ctrl_file = debian_dir.get("control")
+    if not ctrl_file:
+        feature_migration.warn(
+            "Cannot find debian/control. Detection of obsolete substvars could not be performed."
+        )
+        return
+    with ctrl_file.open() as fd:
+        ctrl = list(Deb822.iter_paragraphs(fd))
+
+    relationship_fields = dpkg_field_list_pkg_dep()
+    relationship_fields_lc = frozenset(x.lower() for x in relationship_fields)
+
+    for p in ctrl[1:]:
+        seen_obsolete_relationship_substvars = set()
+        obsolete_fields = set()
+        is_essential = p.get("Essential") == "yes"
+        for df in relationship_fields:
+            field: Optional[str] = p.get(df)
+            if field is None:
+                continue
+            df_lc = df.lower()
+            number_of_relations = 0
+            obsolete_substvars_in_field = set()
+            for d in (d.strip() for d in field.strip().split(",")):
+                if not d:
+                    continue
+                number_of_relations += 1
+                if not d.startswith("${"):
+                    continue
+                try:
+                    end_idx = d.index("}")
+                except ValueError:
+                    continue
+                substvar_name = d[2:end_idx]
+                if ":" not in substvar_name:
+                    continue
+                _, field = substvar_name.rsplit(":", 1)
+                field_lc = field.lower()
+                if field_lc not in relationship_fields_lc:
+                    continue
+                is_obsolete = field_lc == df_lc
+                if (
+                    not is_obsolete
+                    and is_essential
+                    and substvar_name.lower() == "shlibs:depends"
+                    and df_lc == "pre-depends"
+                ):
+                    is_obsolete = True
+
+                if is_obsolete:
+                    obsolete_substvars_in_field.add(d)
+
+            if number_of_relations == len(obsolete_substvars_in_field):
+                obsolete_fields.add(df)
+            else:
+                seen_obsolete_relationship_substvars.update(obsolete_substvars_in_field)
+
+        package = p.get("Package", "(Missing package name!?)")
+        if obsolete_fields:
+            fields = ", ".join(obsolete_fields)
+            feature_migration.warn(
+                f"The following relationship fields can be removed from {package}: {fields}."
+                f"  (The content in them would be applied automatically.)"
+            )
+        if seen_obsolete_relationship_substvars:
+            v = ", ".join(sorted(seen_obsolete_relationship_substvars))
+            feature_migration.warn(
+                f"The following relationship substitution variables can be removed from {package}: {v}"
+            )
+
+
+def read_dh_addon_sequences(
+    debian_dir: VirtualPath,
+) -> Optional[Tuple[Set[str], Set[str]]]:
+    ctrl_file = debian_dir.get("control")
+    if ctrl_file:
+        dr_sequences: Set[str] = set()
+        bd_sequences = set()
+
+        drules = debian_dir.get("rules")
+        if drules and drules.is_file:
+            parse_drules_for_addons(drules, dr_sequences)
+
+        with ctrl_file.open() as fd:
+            ctrl = list(Deb822.iter_paragraphs(fd))
+        source_paragraph = ctrl[0] if ctrl else {}
+
+        extract_dh_addons_from_control(source_paragraph, bd_sequences)
+        return bd_sequences, dr_sequences
+    return None
+
+
+def detect_dh_addons_zz_debputy_rrr(
+    debian_dir: VirtualPath,
+    _manifest: HighLevelManifest,
+    _acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "Check for dh-sequence-addons"
+    r = read_dh_addon_sequences(debian_dir)
+    if r is None:
+        feature_migration.warn(
+            "Cannot find debian/control. Detection of unsupported/missing dh-sequence addon"
+            " could not be performed. Please ensure the package will Build-Depend on dh-sequence-zz-debputy-rrr."
+        )
+        return
+
+    bd_sequences, dr_sequences = r
+
+    remaining_sequences = bd_sequences | dr_sequences
+    saw_dh_debputy = "zz-debputy-rrr" in remaining_sequences
+
+    if not saw_dh_debputy:
+        feature_migration.warn("Missing Build-Depends on dh-sequence-zz-debputy-rrr")
+
+
+def detect_dh_addons(
+    debian_dir: VirtualPath,
+    _manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+    _migration_target: str,
+) -> None:
+    feature_migration.tagline = "Check for dh-sequence-addons"
+    r = read_dh_addon_sequences(debian_dir)
+    if r is None:
+        feature_migration.warn(
+            "Cannot find debian/control. Detection of unsupported/missing dh-sequence addon"
+            " could not be performed. Please ensure the package will Build-Depend on dh-sequence-zz-debputy"
+            " and not rely on any other debhelper sequence addons except those debputy explicitly supports."
+        )
+        return
+
+    bd_sequences, dr_sequences = r
+
+    remaining_sequences = bd_sequences | dr_sequences
+    saw_dh_debputy = (
+        "debputy" in remaining_sequences or "zz-debputy" in remaining_sequences
+    )
+    saw_zz_debputy = "zz-debputy" in remaining_sequences
+    must_use_zz_debputy = False
+    remaining_sequences -= SUPPORTED_DH_ADDONS
+    for sequence in remaining_sequences & DH_ADDONS_TO_PLUGINS.keys():
+        migration = DH_ADDONS_TO_PLUGINS[sequence]
+        feature_migration.require_plugin(migration.debputy_plugin)
+        if migration.remove_dh_sequence:
+            if migration.must_use_zz_debputy:
+                must_use_zz_debputy = True
+            if sequence in bd_sequences:
+                feature_migration.warn(
+                    f"TODO: MANUAL MIGRATION - Remove build-dependency on dh-sequence-{sequence}"
+                    f" (replaced by debputy-plugin-{migration.debputy_plugin})"
+                )
+            else:
+                feature_migration.warn(
+                    f"TODO: MANUAL MIGRATION - Remove --with {sequence} from dh in d/rules"
+                    f" (replaced by debputy-plugin-{migration.debputy_plugin})"
+                )
+
+    remaining_sequences -= DH_ADDONS_TO_PLUGINS.keys()
+
+    alt_key = "unsupported-dh-sequences"
+    for sequence in remaining_sequences & DH_ADDONS_TO_REMOVE:
+        if sequence in bd_sequences:
+            feature_migration.warn(
+                f"TODO: MANUAL MIGRATION - Remove build dependency on dh-sequence-{sequence}"
+            )
+        else:
+            feature_migration.warn(
+                f"TODO: MANUAL MIGRATION - Remove --with {sequence} from dh in d/rules"
+            )
+
+    remaining_sequences -= DH_ADDONS_TO_REMOVE
+
+    for sequence in remaining_sequences:
+        key = f"unsupported-dh-sequence-{sequence}"
+        msg = f'The dh addon "{sequence}" is not known to work with dh-debputy and might malfunction'
+        if (
+            key not in acceptable_migration_issues
+            and alt_key not in acceptable_migration_issues
+        ):
+            raise UnsupportedFeature(msg, [key, alt_key])
+        feature_migration.warn(msg)
+
+    if not saw_dh_debputy:
+        feature_migration.warn("Missing Build-Depends on dh-sequence-zz-debputy")
+    elif must_use_zz_debputy and not saw_zz_debputy:
+        feature_migration.warn(
+            "Please use the zz-debputy sequence rather than the debputy (needed due to dh add-on load order)"
+        )
+
+
+def _rename_file_if_exists(
+    debian_dir: VirtualPath,
+    source: str,
+    dest: str,
+    feature_migration: FeatureMigration,
+) -> None:
+    source_path = debian_dir.get(source)
+    dest_path = debian_dir.get(dest)
+    spath = (
+        source_path.path
+        if source_path is not None
+        else os.path.join(debian_dir.path, source)
+    )
+    dpath = (
+        dest_path.path if dest_path is not None else os.path.join(debian_dir.path, dest)
+    )
+    if source_path is not None and source_path.is_file:
+        if dest_path is not None:
+            if not dest_path.is_file:
+                feature_migration.warnings.append(
+                    f'TODO: MANUAL MIGRATION - there is a "{spath}" (file) and "{dpath}" (not a file).'
+                    f' The migration wanted to replace "{spath}" with "{dpath}", but since "{dpath}" is not'
+                    " a file, this step is left as a manual migration."
+                )
+                return
+            if (
+                subprocess.call(["cmp", "-s", source_path.fs_path, dest_path.fs_path])
+                != 0
+            ):
+                feature_migration.warnings.append(
+                    f'TODO: MANUAL MIGRATION - there is a "{source_path.path}" and "{dest_path.path}"'
+                    f" file. Normally these files are for the same package and there would only be one of"
+                    f" them. In this case, they both exist but their content differs. Be advised that"
+                    f' debputy tool will use the "{dest_path.path}".'
+                )
+            else:
+                feature_migration.remove_on_success(dest_path.fs_path)
+        else:
+            feature_migration.rename_on_success(
+                source_path.fs_path,
+                os.path.join(debian_dir.fs_path, dest),
+            )
+    elif source_path is not None:
+        feature_migration.warnings.append(
+            f'TODO: MANUAL MIGRATION - The migration would normally have renamed "{spath}" to "{dpath}".'
+            f' However, the migration assumed "{spath}" would be a file and it is not. Therefore, this step'
+            " as a manual migration."
+        )
+
+
+def _find_dh_config_file_for_any_pkg(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    unsupported_config: UnsupportedDHConfig,
+) -> Iterable[VirtualPath]:
+    for dctrl_bin in manifest.all_packages:
+        dh_config_file = dhe_pkgfile(
+            debian_dir,
+            dctrl_bin,
+            unsupported_config.dh_config_basename,
+            bug_950723_prefix_matching=unsupported_config.bug_950723_prefix_matching,
+        )
+        if dh_config_file is not None:
+            yield dh_config_file
+
+
+def _unsupported_debhelper_config_file(
+    debian_dir: VirtualPath,
+    manifest: HighLevelManifest,
+    unsupported_config: UnsupportedDHConfig,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    feature_migration: FeatureMigration,
+) -> None:
+    dh_config_files = list(
+        _find_dh_config_file_for_any_pkg(debian_dir, manifest, unsupported_config)
+    )
+    if not dh_config_files:
+        return
+    dh_tool = unsupported_config.dh_tool
+    basename = unsupported_config.dh_config_basename
+    file_stem = (
+        f"@{basename}" if unsupported_config.bug_950723_prefix_matching else basename
+    )
+    dh_config_file = dh_config_files[0]
+    if unsupported_config.is_missing_migration:
+        feature_migration.warn(
+            f'Missing migration support for the "{dh_config_file.path}" debhelper config file'
+            f" (used by {dh_tool}). Manual migration may be feasible depending on the exact features"
+            " required."
+        )
+        return
+    primary_key = f"unsupported-dh-config-file-{file_stem}"
+    secondary_key = "any-unsupported-dh-config-file"
+    if (
+        primary_key not in acceptable_migration_issues
+        and secondary_key not in acceptable_migration_issues
+    ):
+        msg = (
+            f'The "{dh_config_file.path}" debhelper config file (used by {dh_tool} is currently not'
+            " supported by debputy."
+        )
+        raise UnsupportedFeature(
+            msg,
+            [primary_key, secondary_key],
+        )
+    for dh_config_file in dh_config_files:
+        feature_migration.warn(
+            f'TODO: MANUAL MIGRATION - Use of unsupported "{dh_config_file.path}" file (used by {dh_tool})'
+        )
diff --git a/src/debputy/dh_migration/models.py b/src/debputy/dh_migration/models.py
new file mode 100644
index 0000000..ace4185
--- /dev/null
+++ b/src/debputy/dh_migration/models.py
@@ -0,0 +1,173 @@
+import dataclasses
+import re
+from typing import Sequence, Optional, FrozenSet, Tuple, List, cast
+
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.highlevel_manifest import MutableYAMLManifest
+from debputy.substitution import Substitution
+
+_DH_VAR_RE = re.compile(r"([$][{])([A-Za-z0-9][-_:0-9A-Za-z]*)([}])")
+
+
+class AcceptableMigrationIssues:
+    def __init__(self, values: FrozenSet[str]):
+        self._values = values
+
+    def __contains__(self, item: str) -> bool:
+        return item in self._values or "ALL" in self._values
+
+
+class UnsupportedFeature(RuntimeError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+    @property
+    def issue_keys(self) -> Optional[Sequence[str]]:
+        if len(self.args) < 2:
+            return None
+        return cast("Sequence[str]", self.args[1])
+
+
+class ConflictingChange(RuntimeError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+
+@dataclasses.dataclass(slots=True)
+class FeatureMigration:
+    tagline: str
+    successful_manifest_changes: int = 0
+    already_present: int = 0
+    warnings: List[str] = dataclasses.field(default_factory=list)
+    remove_paths_on_success: List[str] = dataclasses.field(default_factory=list)
+    rename_paths_on_success: List[Tuple[str, str]] = dataclasses.field(
+        default_factory=list
+    )
+    assumed_compat: Optional[int] = None
+    required_plugins: List[str] = dataclasses.field(default_factory=list)
+
+    def warn(self, msg: str) -> None:
+        self.warnings.append(msg)
+
+    def rename_on_success(self, source: str, dest: str) -> None:
+        self.rename_paths_on_success.append((source, dest))
+
+    def remove_on_success(self, path: str) -> None:
+        self.remove_paths_on_success.append(path)
+
+    def require_plugin(self, debputy_plugin: str) -> None:
+        self.required_plugins.append(debputy_plugin)
+
+    @property
+    def anything_to_do(self) -> bool:
+        return bool(self.total_changes_involved)
+
+    @property
+    def performed_changes(self) -> int:
+        return (
+            self.successful_manifest_changes
+            + len(self.remove_paths_on_success)
+            + len(self.rename_paths_on_success)
+        )
+
+    @property
+    def total_changes_involved(self) -> int:
+        return (
+            self.successful_manifest_changes
+            + len(self.warnings)
+            + len(self.remove_paths_on_success)
+            + len(self.rename_paths_on_success)
+        )
+
+
+class DHMigrationSubstitution(Substitution):
+    def __init__(
+        self,
+        dpkg_arch_table: DpkgArchitectureBuildProcessValuesTable,
+        acceptable_migration_issues: AcceptableMigrationIssues,
+        feature_migration: FeatureMigration,
+        mutable_manifest: MutableYAMLManifest,
+    ) -> None:
+        self._acceptable_migration_issues = acceptable_migration_issues
+        self._dpkg_arch_table = dpkg_arch_table
+        self._feature_migration = feature_migration
+        self._mutable_manifest = mutable_manifest
+        # TODO: load 1:1 variables from the real subst instance (less stuff to keep in sync)
+        one2one = [
+            "DEB_SOURCE",
+            "DEB_VERSION",
+            "DEB_VERSION_EPOCH_UPSTREAM",
+            "DEB_VERSION_UPSTREAM_REVISION",
+            "DEB_VERSION_UPSTREAM",
+            "SOURCE_DATE_EPOCH",
+        ]
+        self._builtin_substs = {
+            "Tab": "{{token:TAB}}",
+            "Space": " ",
+            "Newline": "{{token:NEWLINE}}",
+            "Dollar": "${}",
+        }
+        self._builtin_substs.update((x, "{{" + x + "}}") for x in one2one)
+
+    def _replacement(self, key: str, definition_source: str) -> str:
+        if key in self._builtin_substs:
+            return self._builtin_substs[key]
+        if key in self._dpkg_arch_table:
+            return "{{" + key + "}}"
+        if key.startswith("env:"):
+            if "dh-subst-env" not in self._acceptable_migration_issues:
+                raise UnsupportedFeature(
+                    "Use of environment based substitution variable {{"
+                    + key
+                    + "}} is not"
+                    f" supported in debputy. The variable was spotted at {definition_source}",
+                    ["dh-subst-env"],
+                )
+        elif "dh-subst-unknown-variable" not in self._acceptable_migration_issues:
+            raise UnsupportedFeature(
+                "Unknown substitution variable {{"
+                + key
+                + "}}, which does not have a known"
+                f" counter part in debputy. The variable was spotted at {definition_source}",
+                ["dh-subst-unknown-variable"],
+            )
+        manifest_definitions = self._mutable_manifest.manifest_definitions(
+            create_if_absent=False
+        )
+        manifest_variables = manifest_definitions.manifest_variables(
+            create_if_absent=False
+        )
+        if key not in manifest_variables.variables:
+            manifest_definitions.create_definition_if_missing()
+            manifest_variables[key] = "TODO: Provide variable value for " + key
+            self._feature_migration.warn(
+                "TODO: MANUAL MIGRATION of unresolved substitution variable {{"
+                + key
+                + "}} from"
+                + f" {definition_source}"
+            )
+            self._feature_migration.successful_manifest_changes += 1
+
+        return "{{" + key + "}}"
+
+    def substitute(
+        self,
+        value: str,
+        definition_source: str,
+        /,
+        escape_glob_characters: bool = False,
+    ) -> str:
+        if "${" not in value:
+            return value
+        replacement = self._apply_substitution(
+            _DH_VAR_RE,
+            value,
+            definition_source,
+            escape_glob_characters=escape_glob_characters,
+        )
+        return replacement.replace("${}", "$")
+
+    def with_extra_substitutions(self, **extra_substitutions: str) -> "Substitution":
+        return self
diff --git a/src/debputy/elf_util.py b/src/debputy/elf_util.py
new file mode 100644
index 0000000..518db37
--- /dev/null
+++ b/src/debputy/elf_util.py
@@ -0,0 +1,208 @@
+import io
+import os
+import struct
+from typing import List, Optional, Callable, Tuple, Iterable
+
+from debputy.filesystem_scan import FSPath
+from debputy.plugin.api import VirtualPath
+
+ELF_HEADER_SIZE32 = 136
+ELF_HEADER_SIZE64 = 232
+ELF_MAGIC = b"\x7fELF"
+ELF_VERSION = 0x00000001
+ELF_ENDIAN_LE = 0x01
+ELF_ENDIAN_BE = 0x02
+ELF_TYPE_EXECUTABLE = 0x0002
+ELF_TYPE_SHARED_OBJECT = 0x0003
+
+ELF_LINKING_TYPE_ANY = None
+ELF_LINKING_TYPE_DYNAMIC = True
+ELF_LINKING_TYPE_STATIC = False
+
+ELF_EI_ELFCLASS32 = 1
+ELF_EI_ELFCLASS64 = 2
+
+ELF_PT_DYNAMIC = 2
+
+ELF_EI_NIDENT = 0x10
+
+# ELF header format:
+# typedef struct {
+#     unsigned char e_ident[EI_NIDENT];  # <-- 16 / 0x10 bytes
+#     uint16_t      e_type;
+#     uint16_t      e_machine;
+#     uint32_t      e_version;
+#     ElfN_Addr     e_entry;
+#     ElfN_Off      e_phoff;
+#     ElfN_Off      e_shoff;
+#     uint32_t      e_flags;
+#     uint16_t      e_ehsize;
+#     uint16_t      e_phentsize;
+#     uint16_t      e_phnum;
+#     uint16_t      e_shentsize;
+#     uint16_t      e_shnum;
+#     uint16_t      e_shstrndx;
+# } ElfN_Ehdr;
+
+
+class IncompleteFileError(RuntimeError):
+    pass
+
+
+def is_so_or_exec_elf_file(
+    path: VirtualPath,
+    *,
+    assert_linking_type: Optional[bool] = ELF_LINKING_TYPE_ANY,
+) -> bool:
+    is_elf, linking_type = _read_elf_file(
+        path,
+        determine_linking_type=assert_linking_type is not None,
+    )
+    return is_elf and (
+        assert_linking_type is ELF_LINKING_TYPE_ANY
+        or assert_linking_type == linking_type
+    )
+
+
+def _read_elf_file(
+    path: VirtualPath,
+    *,
+    determine_linking_type: bool = False,
+) -> Tuple[bool, Optional[bool]]:
+    buffer_size = 4096
+    fd_buffer = bytearray(buffer_size)
+    linking_type = None
+    fd: io.BufferedReader
+    with path.open(byte_io=True, buffering=io.DEFAULT_BUFFER_SIZE) as fd:
+        len_elf_header_raw = fd.readinto(fd_buffer)
+        if (
+            not fd_buffer
+            or len_elf_header_raw < ELF_HEADER_SIZE32
+            or not fd_buffer.startswith(ELF_MAGIC)
+        ):
+            return False, None
+
+        elf_ei_class = fd_buffer[4]
+        endian_raw = fd_buffer[5]
+        if endian_raw == ELF_ENDIAN_LE:
+            endian = "<"
+        elif endian_raw == ELF_ENDIAN_BE:
+            endian = ">"
+        else:
+            return False, None
+
+        if elf_ei_class == ELF_EI_ELFCLASS64:
+            offset_size = "Q"
+            # We know it needs to be a 64bit ELF, then the header must be
+            # large enough for that.
+            if len_elf_header_raw < ELF_HEADER_SIZE64:
+                return False, None
+        elif elf_ei_class == ELF_EI_ELFCLASS32:
+            offset_size = "L"
+        else:
+            return False, None
+
+        elf_type, _elf_machine, elf_version = struct.unpack_from(
+            f"{endian}HHL", fd_buffer, offset=ELF_EI_NIDENT
+        )
+        if elf_version != ELF_VERSION:
+            return False, None
+        if elf_type not in (ELF_TYPE_EXECUTABLE, ELF_TYPE_SHARED_OBJECT):
+            return False, None
+
+        if determine_linking_type:
+            linking_type = _determine_elf_linking_type(
+                fd, fd_buffer, endian, offset_size
+            )
+            if linking_type is None:
+                return False, None
+
+    return True, linking_type
+
+
+def _determine_elf_linking_type(fd, fd_buffer, endian, offset_size) -> Optional[bool]:
+    # To check the linking, we look for a DYNAMICALLY program header
+    # In other words, we assume static linking by default.
+
+    linking_type = ELF_LINKING_TYPE_STATIC
+    # To do that, we need to read a bit more of the ELF header to
+    # locate the Program header table.
+    #
+    # Reading - in order at offset 0x18:
+    #  * e_entry (ignored)
+    #  * e_phoff
+    #  * e_shoff (ignored)
+    #  * e_flags (ignored)
+    #  * e_ehsize (ignored)
+    #  * e_phentsize
+    #  * e_phnum
+    _, e_phoff, _, _, _, e_phentsize, e_phnum = struct.unpack_from(
+        f"{endian}{offset_size}{offset_size}{offset_size}LHHH",
+        fd_buffer,
+        offset=ELF_EI_NIDENT + 8,
+    )
+
+    # man 5 elf suggests that Program headers can be absent.  If so,
+    # e_phnum will be zero - but we assume the same for e_phentsize.
+    if e_phnum == 0:
+        return linking_type
+
+    # Program headers must be at least 4 bytes for this code to do
+    # anything sanely.  In practise, it must be larger than that
+    # as well.  Accordingly, at best this is a corrupted ELF file.
+    if e_phentsize < 4:
+        return None
+
+    fd.seek(e_phoff, os.SEEK_SET)
+    unpack_format = f"{endian}L"
+    try:
+        for program_header_raw in _read_bytes_iteratively(fd, e_phentsize, e_phnum):
+            p_type = struct.unpack_from(unpack_format, program_header_raw)[0]
+            if p_type == ELF_PT_DYNAMIC:
+                linking_type = ELF_LINKING_TYPE_DYNAMIC
+                break
+    except IncompleteFileError:
+        return None
+
+    return linking_type
+
+
+def _read_bytes_iteratively(
+    fd: io.BufferedReader,
+    object_size: int,
+    object_count: int,
+) -> Iterable[bytes]:
+    total_size = object_size * object_count
+    bytes_remaining = total_size
+    # FIXME: improve this to read larger chunks and yield them one-by-one
+    byte_buffer = bytearray(object_size)
+
+    while bytes_remaining > 0:
+        n = fd.readinto(byte_buffer)
+        if n != object_size:
+            break
+        bytes_remaining -= n
+        yield byte_buffer
+
+    if bytes_remaining:
+        raise IncompleteFileError()
+
+
+def find_all_elf_files(
+    fs_root: VirtualPath,
+    *,
+    walk_filter: Optional[Callable[[VirtualPath, List[VirtualPath]], bool]] = None,
+    with_linking_type: Optional[bool] = ELF_LINKING_TYPE_ANY,
+) -> List[VirtualPath]:
+    matches: List[VirtualPath] = []
+    # FIXME: Implementation detail that fs_root is always `FSPath` and has `.walk()`
+    assert isinstance(fs_root, FSPath)
+    for path, children in fs_root.walk():
+        if walk_filter is not None and not walk_filter(path, children):
+            continue
+        if not path.is_file or path.size < ELF_HEADER_SIZE32:
+            continue
+        if not is_so_or_exec_elf_file(path, assert_linking_type=with_linking_type):
+            continue
+        matches.append(path)
+    return matches
diff --git a/src/debputy/exceptions.py b/src/debputy/exceptions.py
new file mode 100644
index 0000000..a445997
--- /dev/null
+++ b/src/debputy/exceptions.py
@@ -0,0 +1,90 @@
+from typing import cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from debputy.plugin.api.impl_types import DebputyPluginMetadata
+
+
+class DebputyRuntimeError(RuntimeError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+
+class DebputySubstitutionError(DebputyRuntimeError):
+    pass
+
+
+class DebputyManifestVariableRequiresDebianDirError(DebputySubstitutionError):
+    pass
+
+
+class DebputyDpkgGensymbolsError(DebputyRuntimeError):
+    pass
+
+
+class SymlinkLoopError(ValueError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+
+class PureVirtualPathError(TypeError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+
+class TestPathWithNonExistentFSPathError(TypeError):
+    @property
+    def message(self) -> str:
+        return cast("str", self.args[0])
+
+
+class DebputyFSError(DebputyRuntimeError):
+    pass
+
+
+class DebputyFSIsROError(DebputyFSError):
+    pass
+
+
+class PluginBaseError(DebputyRuntimeError):
+    pass
+
+
+class DebputyPluginRuntimeError(PluginBaseError):
+    pass
+
+
+class PluginNotFoundError(PluginBaseError):
+    pass
+
+
+class PluginInitializationError(PluginBaseError):
+    pass
+
+
+class PluginMetadataError(PluginBaseError):
+    pass
+
+
+class PluginConflictError(PluginBaseError):
+    @property
+    def plugin_a(self) -> "DebputyPluginMetadata":
+        return cast("DebputyPluginMetadata", self.args[1])
+
+    @property
+    def plugin_b(self) -> "DebputyPluginMetadata":
+        return cast("DebputyPluginMetadata", self.args[2])
+
+
+class PluginAPIViolationError(PluginBaseError):
+    pass
+
+
+class UnhandledOrUnexpectedErrorFromPluginError(PluginBaseError):
+    pass
+
+
+class DebputyMetadataAccessError(DebputyPluginRuntimeError):
+    pass
diff --git a/src/debputy/filesystem_scan.py b/src/debputy/filesystem_scan.py
new file mode 100644
index 0000000..f7f97c2
--- /dev/null
+++ b/src/debputy/filesystem_scan.py
@@ -0,0 +1,1921 @@
+import atexit
+import contextlib
+import dataclasses
+import errno
+import io
+import operator
+import os
+import stat
+import subprocess
+import tempfile
+import time
+from abc import ABC
+from contextlib import suppress
+from typing import (
+    List,
+    Iterable,
+    Dict,
+    Optional,
+    Tuple,
+    Union,
+    Iterator,
+    Mapping,
+    cast,
+    Any,
+    ContextManager,
+    TextIO,
+    BinaryIO,
+    NoReturn,
+    Type,
+    Generic,
+)
+from weakref import ref, ReferenceType
+
+from debputy.exceptions import (
+    PureVirtualPathError,
+    DebputyFSIsROError,
+    DebputyMetadataAccessError,
+    TestPathWithNonExistentFSPathError,
+    SymlinkLoopError,
+)
+from debputy.intermediate_manifest import PathType
+from debputy.manifest_parser.base_types import (
+    ROOT_DEFINITION,
+    StaticFileSystemOwner,
+    StaticFileSystemGroup,
+)
+from debputy.plugin.api.spec import (
+    VirtualPath,
+    PathDef,
+    PathMetadataReference,
+    PMT,
+)
+from debputy.types import VP
+from debputy.util import (
+    generated_content_dir,
+    _error,
+    escape_shell,
+    assume_not_none,
+    _normalize_path,
+)
+
+BY_BASENAME = operator.attrgetter("name")
+
+
+class AlwaysEmptyReadOnlyMetadataReference(PathMetadataReference[PMT]):
+    __slots__ = ("_metadata_type", "_owning_plugin", "_current_plugin")
+
+    def __init__(
+        self,
+        owning_plugin: str,
+        current_plugin: str,
+        metadata_type: Type[PMT],
+    ) -> None:
+        self._owning_plugin = owning_plugin
+        self._current_plugin = current_plugin
+        self._metadata_type = metadata_type
+
+    @property
+    def is_present(self) -> bool:
+        return False
+
+    @property
+    def can_read(self) -> bool:
+        return self._owning_plugin == self._current_plugin
+
+    @property
+    def can_write(self) -> bool:
+        return False
+
+    @property
+    def value(self) -> Optional[PMT]:
+        if self.can_read:
+            return None
+        raise DebputyMetadataAccessError(
+            f"Cannot read the metadata {self._metadata_type.__name__} owned by"
+            f" {self._owning_plugin} as the metadata has not been made"
+            f" readable to the plugin {self._current_plugin}."
+        )
+
+    @value.setter
+    def value(self, new_value: PMT) -> None:
+        if self._is_owner:
+            raise DebputyFSIsROError(
+                f"Cannot set the metadata {self._metadata_type.__name__} as the path is read-only"
+            )
+        raise DebputyMetadataAccessError(
+            f"Cannot set the metadata {self._metadata_type.__name__} owned by"
+            f" {self._owning_plugin} as the metadata has not been made"
+            f" read-write to the plugin {self._current_plugin}."
+        )
+
+    @property
+    def _is_owner(self) -> bool:
+        return self._owning_plugin == self._current_plugin
+
+
+@dataclasses.dataclass(slots=True)
+class PathMetadataValue(Generic[PMT]):
+    owning_plugin: str
+    metadata_type: Type[PMT]
+    value: Optional[PMT] = None
+
+    def can_read_value(self, current_plugin: str) -> bool:
+        return self.owning_plugin == current_plugin
+
+    def can_write_value(self, current_plugin: str) -> bool:
+        return self.owning_plugin == current_plugin
+
+
+class PathMetadataReferenceImplementation(PathMetadataReference[PMT]):
+    __slots__ = ("_owning_path", "_current_plugin", "_path_metadata_value")
+
+    def __init__(
+        self,
+        owning_path: VirtualPath,
+        current_plugin: str,
+        path_metadata_value: PathMetadataValue[PMT],
+    ) -> None:
+        self._owning_path = owning_path
+        self._current_plugin = current_plugin
+        self._path_metadata_value = path_metadata_value
+
+    @property
+    def is_present(self) -> bool:
+        if not self.can_read:
+            return False
+        return self._path_metadata_value.value is not None
+
+    @property
+    def can_read(self) -> bool:
+        return self._path_metadata_value.can_read_value(self._current_plugin)
+
+    @property
+    def can_write(self) -> bool:
+        if not self._path_metadata_value.can_write_value(self._current_plugin):
+            return False
+        owning_path = self._owning_path
+        return owning_path.is_read_write and not owning_path.is_detached
+
+    @property
+    def value(self) -> Optional[PMT]:
+        if self.can_read:
+            return self._path_metadata_value.value
+        raise DebputyMetadataAccessError(
+            f"Cannot read the metadata {self._metadata_type_name} owned by"
+            f" {self._owning_plugin} as the metadata has not been made"
+            f" readable to the plugin {self._current_plugin}."
+        )
+
+    @value.setter
+    def value(self, new_value: PMT) -> None:
+        if not self.can_write:
+            m = "set" if new_value is not None else "delete"
+            raise DebputyMetadataAccessError(
+                f"Cannot {m} the metadata {self._metadata_type_name} owned by"
+                f" {self._owning_plugin} as the metadata has not been made"
+                f" read-write to the plugin {self._current_plugin}."
+            )
+        owning_path = self._owning_path
+        if not owning_path.is_read_write:
+            raise DebputyFSIsROError(
+                f"Cannot set the metadata {self._metadata_type_name} as the path is read-only"
+            )
+        if owning_path.is_detached:
+            raise TypeError(
+                f"Cannot set the metadata {self._metadata_type_name} as the path is detached"
+            )
+        self._path_metadata_value.value = new_value
+
+    @property
+    def _is_owner(self) -> bool:
+        return self._owning_plugin == self._current_plugin
+
+    @property
+    def _owning_plugin(self) -> str:
+        return self._path_metadata_value.owning_plugin
+
+    @property
+    def _metadata_type_name(self) -> str:
+        return self._path_metadata_value.metadata_type.__name__
+
+
+def _cp_a(source: str, dest: str) -> None:
+    cmd = ["cp", "-a", source, dest]
+    try:
+        subprocess.check_call(cmd)
+    except subprocess.CalledProcessError:
+        full_command = escape_shell(*cmd)
+        _error(
+            f"The attempt to make an internal copy of {escape_shell(source)} failed. Please review the output of cp"
+            f" above to understand what went wrong. The full command was: {full_command}"
+        )
+
+
+def _split_path(path: str) -> Tuple[bool, bool, List[str]]:
+    must_be_dir = True if path.endswith("/") else False
+    absolute = False
+    if path.startswith("/"):
+        absolute = True
+        path = "." + path
+    path_parts = path.rstrip("/").split("/")
+    if must_be_dir:
+        path_parts.append(".")
+    return absolute, must_be_dir, path_parts
+
+
+def _root(path: VP) -> VP:
+    current = path
+    while True:
+        parent = current.parent_dir
+        if parent is None:
+            return current
+        current = parent
+
+
+def _check_fs_path_is_file(
+    fs_path: str,
+    unlink_on_error: Optional["FSPath"] = None,
+) -> None:
+    had_issue = False
+    try:
+        # FIXME: Check mode, and use the Virtual Path to cache the result as a side-effect
+        st = os.lstat(fs_path)
+    except FileNotFoundError:
+        had_issue = True
+    else:
+        if not stat.S_ISREG(st.st_mode) or st.st_nlink > 1:
+            had_issue = True
+    if not had_issue:
+        return
+
+    if unlink_on_error:
+        with suppress(FileNotFoundError):
+            os.unlink(fs_path)
+    raise TypeError(
+        "The provided FS backing file was deleted, replaced with a non-file entry or it was hard"
+        " linked to another file. The entry has been disconnected."
+    )
+
+
+class CurrentPluginContextManager:
+    __slots__ = ("_plugin_names",)
+
+    def __init__(self, initial_plugin_name: str) -> None:
+        self._plugin_names = [initial_plugin_name]
+
+    @property
+    def current_plugin_name(self) -> str:
+        return self._plugin_names[-1]
+
+    @contextlib.contextmanager
+    def change_plugin_context(self, new_plugin_name: str) -> Iterator[str]:
+        self._plugin_names.append(new_plugin_name)
+        yield new_plugin_name
+        self._plugin_names.pop()
+
+
+class VirtualPathBase(VirtualPath, ABC):
+    __slots__ = ()
+
+    def _orphan_safe_path(self) -> str:
+        return self.path
+
+    def _rw_check(self) -> None:
+        if not self.is_read_write:
+            raise DebputyFSIsROError(
+                f'Attempt to write to "{self._orphan_safe_path()}" failed:'
+                " Debputy Virtual File system is R/O."
+            )
+
+    def lookup(self, path: str) -> Optional["VirtualPathBase"]:
+        match, missing = self.attempt_lookup(path)
+        if missing:
+            return None
+        return match
+
+    def attempt_lookup(self, path: str) -> Tuple["VirtualPathBase", List[str]]:
+        if self.is_detached:
+            raise ValueError(
+                f'Cannot perform lookup via "{self._orphan_safe_path()}": The path is detached'
+            )
+        absolute, must_be_dir, path_parts = _split_path(path)
+        current = _root(self) if absolute else self
+        path_parts.reverse()
+        link_expansions = set()
+        while path_parts:
+            dir_part = path_parts.pop()
+            if dir_part == ".":
+                continue
+            if dir_part == "..":
+                p = current.parent_dir
+                if p is None:
+                    raise ValueError(f'The path "{path}" escapes the root dir')
+                current = p
+                continue
+            try:
+                current = current[dir_part]
+            except KeyError:
+                path_parts.append(dir_part)
+                path_parts.reverse()
+                if must_be_dir:
+                    path_parts.pop()
+                return current, path_parts
+            if current.is_symlink and path_parts:
+                if current.path in link_expansions:
+                    # This is our loop detection for now. It might have some false positives where you
+                    # could safely resolve the same symlink twice. However, given that this use-case is
+                    # basically none existent in practice for packaging, we just stop here for now.
+                    raise SymlinkLoopError(
+                        f'The path "{path}" traversed the symlink "{current.path}" multiple'
+                        " times. Currently, traversing the same symlink twice is considered"
+                        " a loop by `debputy` even if the path would eventually resolve."
+                        " Consider filing a feature request if you have a benign case that"
+                        " triggers this error."
+                    )
+                link_expansions.add(current.path)
+                link_target = current.readlink()
+                link_absolute, _, link_path_parts = _split_path(link_target)
+                if link_absolute:
+                    current = _root(current)
+                else:
+                    current = assume_not_none(current.parent_dir)
+                link_path_parts.reverse()
+                path_parts.extend(link_path_parts)
+        return current, []
+
+    def mkdirs(self, path: str) -> "VirtualPath":
+        current: VirtualPath
+        current, missing_parts = self.attempt_lookup(
+            f"{path}/" if not path.endswith("/") else path
+        )
+        if not current.is_dir:
+            raise ValueError(
+                f'mkdirs of "{path}" failed: This would require {current.path} to not exist OR be'
+                " a directory. However, that path exist AND is a not directory."
+            )
+        for missing_part in missing_parts:
+            assert missing_part not in (".", "..")
+            current = current.mkdir(missing_part)
+        return current
+
+    def prune_if_empty_dir(self) -> None:
+        """Remove this and all (now) empty parent directories
+
+        Same as: `rmdir --ignore-fail-on-non-empty --parents`
+
+        This operation may cause the path (and any of its parent directories) to become "detached"
+        and therefore unsafe to use in further operations.
+        """
+        self._rw_check()
+
+        if not self.is_dir:
+            raise TypeError(f"{self._orphan_safe_path()} is not a directory")
+        if any(self.iterdir):
+            return
+        parent_dir = assume_not_none(self.parent_dir)
+
+        # Recursive does not matter; we already know the directory is empty.
+        self.unlink()
+
+        # Note: The root dir must never be deleted. This works because when delegating it to the root
+        # directory, its implementation of this method is a no-op. If this is later rewritten to an
+        # inline loop (rather than recursion), be sure to preserve this feature.
+        parent_dir.prune_if_empty_dir()
+
+    def _current_plugin(self) -> str:
+        if self.is_detached:
+            raise TypeError("Cannot resolve the current plugin; path is detached")
+        current = self
+        while True:
+            next_parent = current.parent_dir
+            if next_parent is None:
+                break
+            current = next_parent
+        assert current is not None
+        return cast("FSRootDir", current)._current_plugin()
+
+
+class FSPath(VirtualPathBase, ABC):
+    __slots__ = (
+        "_basename",
+        "_parent_dir",
+        "_children",
+        "_path_cache",
+        "_parent_path_cache",
+        "_last_known_parent_path",
+        "_mode",
+        "_owner",
+        "_group",
+        "_mtime",
+        "_stat_cache",
+        "_metadata",
+        "__weakref__",
+    )
+
+    def __init__(
+        self,
+        basename: str,
+        parent: Optional["FSPath"],
+        children: Optional[Dict[str, "FSPath"]] = None,
+        initial_mode: Optional[int] = None,
+        mtime: Optional[float] = None,
+        stat_cache: Optional[os.stat_result] = None,
+    ) -> None:
+        self._basename = basename
+        self._path_cache: Optional[str] = None
+        self._parent_path_cache: Optional[str] = None
+        self._children = children
+        self._last_known_parent_path: Optional[str] = None
+        self._mode = initial_mode
+        self._mtime = mtime
+        self._stat_cache = stat_cache
+        self._metadata: Dict[Tuple[str, Type[Any]], PathMetadataValue[Any]] = {}
+        self._owner = ROOT_DEFINITION
+        self._group = ROOT_DEFINITION
+
+        # The self._parent_dir = None is to create `_parent_dir` because the parent_dir setter calls
+        # is_orphaned, which assumes self._parent_dir is an attribute.
+        self._parent_dir: Optional[ReferenceType["FSPath"]] = None
+        if parent is not None:
+            self.parent_dir = parent
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}({self._orphan_safe_path()!r},"
+            f" is_file={self.is_file},"
+            f" is_dir={self.is_dir},"
+            f" is_symlink={self.is_symlink},"
+            f" has_fs_path={self.has_fs_path},"
+            f" children_len={len(self._children) if self._children else 0})"
+        )
+
+    @property
+    def name(self) -> str:
+        return self._basename
+
+    @name.setter
+    def name(self, new_name: str) -> None:
+        self._rw_check()
+        if new_name == self._basename:
+            return
+        if self.is_detached:
+            self._basename = new_name
+            return
+        self._rw_check()
+        parent = self.parent_dir
+        # This little parent_dir dance ensures the parent dir detects the rename properly
+        self.parent_dir = None
+        self._basename = new_name
+        self.parent_dir = parent
+
+    @property
+    def iterdir(self) -> Iterable["FSPath"]:
+        if self._children is not None:
+            yield from self._children.values()
+
+    def all_paths(self) -> Iterable["FSPath"]:
+        yield self
+        if not self.is_dir:
+            return
+        by_basename = BY_BASENAME
+        stack = sorted(self.iterdir, key=by_basename, reverse=True)
+        while stack:
+            current = stack.pop()
+            yield current
+            if current.is_dir and not current.is_detached:
+                stack.extend(sorted(current.iterdir, key=by_basename, reverse=True))
+
+    def walk(self) -> Iterable[Tuple["FSPath", List["FSPath"]]]:
+        # FIXME: can this be more "os.walk"-like without making it harder to implement?
+        if not self.is_dir:
+            yield self, []
+            return
+        by_basename = BY_BASENAME
+        stack = [self]
+        while stack:
+            current = stack.pop()
+            children = sorted(current.iterdir, key=by_basename)
+            assert not children or current.is_dir
+            yield current, children
+            # Removing the directory counts as discarding the children.
+            if not current.is_detached:
+                stack.extend(reversed(children))
+
+    def _orphan_safe_path(self) -> str:
+        if not self.is_detached or self._last_known_parent_path is not None:
+            return self.path
+        return f"<orphaned>/{self.name}"
+
+    @property
+    def is_detached(self) -> bool:
+        parent = self._parent_dir
+        if parent is None:
+            return True
+        resolved_parent = parent()
+        if resolved_parent is None:
+            return True
+        return resolved_parent.is_detached
+
+    # The __getitem__ behaves like __getitem__ from Dict but __iter__ would ideally work like a Sequence.
+    # However, that does not feel compatible, so lets force people to use .children instead for the Sequence
+    # behaviour to avoid surprises for now.
+    # (Maybe it is a non-issue, but it is easier to add the API later than to remove it once we have committed
+    # to using it)
+    __iter__ = None
+
+    def __getitem__(self, key) -> "FSPath":
+        if self._children is None:
+            raise KeyError(
+                f"{key} (note: {self._orphan_safe_path()!r} has no children)"
+            )
+        if isinstance(key, FSPath):
+            key = key.name
+        return self._children[key]
+
+    def __delitem__(self, key) -> None:
+        self._rw_check()
+        children = self._children
+        if children is None:
+            raise KeyError(key)
+        del children[key]
+
+    def get(self, key: str) -> "Optional[FSPath]":
+        try:
+            return self[key]
+        except KeyError:
+            return None
+
+    def __contains__(self, item: object) -> bool:
+        if isinstance(item, VirtualPath):
+            return item.parent_dir is self
+        if not isinstance(item, str):
+            return False
+        m = self.get(item)
+        return m is not None
+
+    def _add_child(self, child: "FSPath") -> None:
+        self._rw_check()
+        if not self.is_dir:
+            raise TypeError(f"{self._orphan_safe_path()!r} is not a directory")
+        if self._children is None:
+            self._children = {}
+
+        conflict_child = self.get(child.name)
+        if conflict_child is not None:
+            conflict_child.unlink(recursive=True)
+        self._children[child.name] = child
+
+    @property
+    def tar_path(self) -> str:
+        path = self.path
+        if self.is_dir:
+            return path + "/"
+        return path
+
+    @property
+    def path(self) -> str:
+        parent_path = self.parent_dir_path
+        if (
+            self._parent_path_cache is not None
+            and self._parent_path_cache == parent_path
+        ):
+            return assume_not_none(self._path_cache)
+        if parent_path is None:
+            raise ReferenceError(
+                f"The path {self.name} is detached! {self.__class__.__name__}"
+            )
+        self._parent_path_cache = parent_path
+        ret = os.path.join(parent_path, self.name)
+        self._path_cache = ret
+        return ret
+
+    @property
+    def parent_dir(self) -> Optional["FSPath"]:
+        p_ref = self._parent_dir
+        p = p_ref() if p_ref is not None else None
+        if p is None:
+            raise ReferenceError(
+                f"The path {self.name} is detached! {self.__class__.__name__}"
+            )
+        return p
+
+    @parent_dir.setter
+    def parent_dir(self, new_parent: Optional["FSPath"]) -> None:
+        self._rw_check()
+        if new_parent is not None:
+            if not new_parent.is_dir:
+                raise ValueError(
+                    f"The parent {new_parent._orphan_safe_path()} must be a directory"
+                )
+            new_parent._rw_check()
+        old_parent = None
+        self._last_known_parent_path = None
+        if not self.is_detached:
+            old_parent = self.parent_dir
+            old_parent_children = assume_not_none(assume_not_none(old_parent)._children)
+            del old_parent_children[self.name]
+        if new_parent is not None:
+            self._parent_dir = ref(new_parent)
+            new_parent._add_child(self)
+        else:
+            if old_parent is not None and not old_parent.is_detached:
+                self._last_known_parent_path = old_parent.path
+            self._parent_dir = None
+        self._parent_path_cache = None
+
+    @property
+    def parent_dir_path(self) -> Optional[str]:
+        if self.is_detached:
+            return self._last_known_parent_path
+        return assume_not_none(self.parent_dir).path
+
+    def chown(
+        self,
+        owner: Optional[StaticFileSystemOwner],
+        group: Optional[StaticFileSystemGroup],
+    ) -> None:
+        """Change the owner/group of this path
+
+        :param owner: The desired owner definition for this path. If None, then no change of owner is performed.
+        :param group: The desired  group definition for this path. If None, then no change of group is performed.
+        """
+        self._rw_check()
+
+        if owner is not None:
+            self._owner = owner.ownership_definition
+        if group is not None:
+            self._group = group.ownership_definition
+
+    def stat(self) -> os.stat_result:
+        st = self._stat_cache
+        if st is None:
+            st = self._uncached_stat()
+            self._stat_cache = st
+        return st
+
+    def _uncached_stat(self) -> os.stat_result:
+        return os.lstat(self.fs_path)
+
+    @property
+    def mode(self) -> int:
+        current_mode = self._mode
+        if current_mode is None:
+            current_mode = stat.S_IMODE(self.stat().st_mode)
+            self._mode = current_mode
+        return current_mode
+
+    @mode.setter
+    def mode(self, new_mode: int) -> None:
+        self._rw_check()
+        min_bit = 0o500 if self.is_dir else 0o400
+        if (new_mode & min_bit) != min_bit:
+            omode = oct(new_mode)[2:]
+            omin = oct(min_bit)[2:]
+            raise ValueError(
+                f'Attempt to set mode of path "{self._orphan_safe_path()}" to {omode} rejected;'
+                f" Minimum requirements are {omin} (read-bit and, for dirs, exec bit for user)."
+                " There are no paths that do not need these requirements met and they can cause"
+                " problems during build or on the final system."
+            )
+        self._mode = new_mode
+
+    @property
+    def mtime(self) -> float:
+        mtime = self._mtime
+        if mtime is None:
+            mtime = self.stat().st_mtime
+            self._mtime = mtime
+        return mtime
+
+    @mtime.setter
+    def mtime(self, new_mtime: float) -> None:
+        self._rw_check()
+        self._mtime = new_mtime
+
+    @property
+    def tar_owner_info(self) -> Tuple[str, int, str, int]:
+        owner = self._owner
+        group = self._group
+        return (
+            owner.entity_name,
+            owner.entity_id,
+            group.entity_name,
+            group.entity_id,
+        )
+
+    @property
+    def _can_replace_inline(self) -> bool:
+        return False
+
+    @contextlib.contextmanager
+    def add_file(
+        self,
+        name: str,
+        *,
+        unlink_if_exists: bool = True,
+        use_fs_path_mode: bool = False,
+        mode: int = 0o0644,
+        mtime: Optional[float] = None,
+        # Special-case parameters that are not exposed in the API
+        fs_basename_matters: bool = False,
+        subdir_key: Optional[str] = None,
+    ) -> Iterator["FSPath"]:
+        if "/" in name or name in {".", ".."}:
+            raise ValueError(f'Invalid file name: "{name}"')
+        if not self.is_dir:
+            raise TypeError(
+                f"Cannot create {self._orphan_safe_path()}/{name}:"
+                f" {self._orphan_safe_path()} is not a directory"
+            )
+        self._rw_check()
+        existing = self.get(name)
+        if existing is not None:
+            if not unlink_if_exists:
+                raise ValueError(
+                    f'The path "{self._orphan_safe_path()}" already contains a file called "{name}"'
+                    f" and exist_ok was False"
+                )
+            existing.unlink(recursive=False)
+
+        if fs_basename_matters and subdir_key is None:
+            raise ValueError(
+                "When fs_basename_matters is True, a subdir_key must be provided"
+            )
+
+        directory = generated_content_dir(subdir_key=subdir_key)
+
+        if fs_basename_matters:
+            fs_path = os.path.join(directory, name)
+            with open(fs_path, "xb") as _:
+                # Ensure that the fs_path exists
+                pass
+            child = FSBackedFilePath(
+                name,
+                self,
+                fs_path,
+                replaceable_inline=True,
+                mtime=mtime,
+            )
+            yield child
+        else:
+            with tempfile.NamedTemporaryFile(
+                dir=directory, suffix=f"__{name}", delete=False
+            ) as fd:
+                fs_path = fd.name
+                child = FSBackedFilePath(
+                    name,
+                    self,
+                    fs_path,
+                    replaceable_inline=True,
+                    mtime=mtime,
+                )
+                fd.close()
+                yield child
+
+        if use_fs_path_mode:
+            # Ensure the caller can see the current mode
+            os.chmod(fs_path, mode)
+        _check_fs_path_is_file(fs_path, unlink_on_error=child)
+        child._reset_caches()
+        if not use_fs_path_mode:
+            child.mode = mode
+
+    def insert_file_from_fs_path(
+        self,
+        name: str,
+        fs_path: str,
+        *,
+        exist_ok: bool = True,
+        use_fs_path_mode: bool = False,
+        mode: int = 0o0644,
+        require_copy_on_write: bool = True,
+        follow_symlinks: bool = True,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> "FSPath":
+        if "/" in name or name in {".", ".."}:
+            raise ValueError(f'Invalid file name: "{name}"')
+        if not self.is_dir:
+            raise TypeError(
+                f"Cannot create {self._orphan_safe_path()}/{name}:"
+                f" {self._orphan_safe_path()} is not a directory"
+            )
+        self._rw_check()
+        if name in self and not exist_ok:
+            raise ValueError(
+                f'The path "{self._orphan_safe_path()}" already contains a file called "{name}"'
+                f" and exist_ok was False"
+            )
+        new_fs_path = fs_path
+        if follow_symlinks:
+            if reference_path is not None:
+                raise ValueError(
+                    "The reference_path cannot be used with follow_symlinks"
+                )
+            new_fs_path = os.path.realpath(new_fs_path, strict=True)
+
+        fmode: Optional[int] = mode
+        if use_fs_path_mode:
+            fmode = None
+
+        st = None
+        if reference_path is None:
+            st = os.lstat(new_fs_path)
+            if stat.S_ISDIR(st.st_mode):
+                raise ValueError(
+                    f'The provided path "{fs_path}" is a directory. However, this'
+                    " method does not support directories"
+                )
+
+            if not stat.S_ISREG(st.st_mode):
+                if follow_symlinks:
+                    raise ValueError(
+                        f"The resolved fs_path ({new_fs_path}) was not a file."
+                    )
+                raise ValueError(f"The provided fs_path ({fs_path}) was not a file.")
+        return FSBackedFilePath(
+            name,
+            self,
+            new_fs_path,
+            initial_mode=fmode,
+            stat_cache=st,
+            replaceable_inline=not require_copy_on_write,
+            reference_path=reference_path,
+        )
+
+    def add_symlink(
+        self,
+        link_name: str,
+        link_target: str,
+        *,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> "FSPath":
+        if "/" in link_name or link_name in {".", ".."}:
+            raise ValueError(
+                f'Invalid file name: "{link_name}" (it must be a valid basename)'
+            )
+        if not self.is_dir:
+            raise TypeError(
+                f"Cannot create {self._orphan_safe_path()}/{link_name}:"
+                f" {self._orphan_safe_path()} is not a directory"
+            )
+        self._rw_check()
+
+        existing = self.get(link_name)
+        if existing:
+            # Emulate ln -sf with attempts a non-recursive unlink first.
+            existing.unlink(recursive=False)
+
+        return SymlinkVirtualPath(
+            link_name,
+            self,
+            link_target,
+            reference_path=reference_path,
+        )
+
+    def mkdir(
+        self,
+        name: str,
+        *,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> "FSPath":
+        if "/" in name or name in {".", ".."}:
+            raise ValueError(
+                f'Invalid file name: "{name}" (it must be a valid basename)'
+            )
+        if not self.is_dir:
+            raise TypeError(
+                f"Cannot create {self._orphan_safe_path()}/{name}:"
+                f" {self._orphan_safe_path()} is not a directory"
+            )
+        if reference_path is not None and not reference_path.is_dir:
+            raise ValueError(
+                f'The provided fs_path "{reference_path.fs_path}" exist but it is not a directory!'
+            )
+        self._rw_check()
+
+        existing = self.get(name)
+        if existing:
+            raise ValueError(f"Path {existing.path} already exist")
+        return VirtualDirectoryFSPath(name, self, reference_path=reference_path)
+
+    def mkdirs(self, path: str) -> "FSPath":
+        return cast("FSPath", super().mkdirs(path))
+
+    @property
+    def is_read_write(self) -> bool:
+        """When true, the file system entry may be mutated
+
+        :return: Whether file system mutations are permitted.
+        """
+        if self.is_detached:
+            return True
+        return assume_not_none(self.parent_dir).is_read_write
+
+    def unlink(self, *, recursive: bool = False) -> None:
+        """Unlink a file or a directory
+
+        This operation will detach the path from the file system (causing "is_detached" to return True).
+
+        Note that the root directory cannot be deleted.
+
+        :param recursive: If True, then non-empty directories will be unlinked as well removing everything inside them
+          as well.  When False, an error is raised if the path is a non-empty directory
+        """
+        if self.is_detached:
+            return
+        if not recursive and any(self.iterdir):
+            raise ValueError(
+                f'Refusing to unlink "{self.path}": The directory was not empty and recursive was False'
+            )
+        # The .parent_dir setter does a _rw_check() for us.
+        self.parent_dir = None
+
+    def _reset_caches(self) -> None:
+        self._mtime = None
+        self._stat_cache = None
+
+    def metadata(
+        self,
+        metadata_type: Type[PMT],
+        *,
+        owning_plugin: Optional[str] = None,
+    ) -> PathMetadataReference[PMT]:
+        current_plugin = self._current_plugin()
+        if owning_plugin is None:
+            owning_plugin = current_plugin
+        metadata_key = (owning_plugin, metadata_type)
+        metadata_value = self._metadata.get(metadata_key)
+        if metadata_value is None:
+            if self.is_detached:
+                raise TypeError(
+                    f"Cannot access the metadata {metadata_type.__name__}: The path is detached."
+                )
+            if not self.is_read_write:
+                return AlwaysEmptyReadOnlyMetadataReference(
+                    owning_plugin,
+                    current_plugin,
+                    metadata_type,
+                )
+            metadata_value = PathMetadataValue(owning_plugin, metadata_type)
+            self._metadata[metadata_key] = metadata_value
+        return PathMetadataReferenceImplementation(
+            self,
+            current_plugin,
+            metadata_value,
+        )
+
+    @contextlib.contextmanager
+    def replace_fs_path_content(
+        self,
+        *,
+        use_fs_path_mode: bool = False,
+    ) -> Iterator[str]:
+        if not self.is_file:
+            raise TypeError(
+                f'Cannot replace contents of "{self._orphan_safe_path()}" as it is not a file'
+            )
+        self._rw_check()
+        fs_path = self.fs_path
+        if not self._can_replace_inline:
+            fs_path = self.fs_path
+            directory = generated_content_dir()
+            with tempfile.NamedTemporaryFile(
+                dir=directory, suffix=f"__{self.name}", delete=False
+            ) as new_path_fd:
+                new_path_fd.close()
+                _cp_a(fs_path, new_path_fd.name)
+                fs_path = new_path_fd.name
+                self._replaced_path(fs_path)
+                assert self.fs_path == fs_path
+
+        current_mtime = self._mtime
+        if current_mtime is not None:
+            os.utime(fs_path, (current_mtime, current_mtime))
+
+        current_mode = self.mode
+        yield fs_path
+        _check_fs_path_is_file(fs_path, unlink_on_error=self)
+        if not use_fs_path_mode:
+            os.chmod(fs_path, current_mode)
+        self._reset_caches()
+
+    def _replaced_path(self, new_fs_path: str) -> None:
+        raise NotImplementedError
+
+
+class VirtualFSPathBase(FSPath, ABC):
+    __slots__ = ()
+
+    def __init__(
+        self,
+        basename: str,
+        parent: Optional["FSPath"],
+        children: Optional[Dict[str, "FSPath"]] = None,
+        initial_mode: Optional[int] = None,
+        mtime: Optional[float] = None,
+        stat_cache: Optional[os.stat_result] = None,
+    ) -> None:
+        super().__init__(
+            basename,
+            parent,
+            children,
+            initial_mode=initial_mode,
+            mtime=mtime,
+            stat_cache=stat_cache,
+        )
+
+    @property
+    def mtime(self) -> float:
+        mtime = self._mtime
+        if mtime is None:
+            mtime = time.time()
+            self._mtime = mtime
+        return mtime
+
+    @property
+    def has_fs_path(self) -> bool:
+        return False
+
+    def stat(self) -> os.stat_result:
+        if not self.has_fs_path:
+            raise PureVirtualPathError(
+                "stat() is only applicable to paths backed by the file system. The path"
+                f" {self._orphan_safe_path()!r} is purely virtual"
+            )
+        return super().stat()
+
+    @property
+    def fs_path(self) -> str:
+        if not self.has_fs_path:
+            raise PureVirtualPathError(
+                "fs_path is only applicable to paths backed by the file system. The path"
+                f" {self._orphan_safe_path()!r} is purely virtual"
+            )
+        return self.fs_path
+
+
+class FSRootDir(FSPath):
+    __slots__ = ("_fs_path", "_fs_read_write", "_plugin_context")
+
+    def __init__(self, fs_path: Optional[str] = None) -> None:
+        self._fs_path = fs_path
+        self._fs_read_write = True
+        super().__init__(
+            ".",
+            None,
+            children={},
+            initial_mode=0o755,
+        )
+        self._plugin_context = CurrentPluginContextManager("debputy")
+
+    @property
+    def is_detached(self) -> bool:
+        return False
+
+    def _orphan_safe_path(self) -> str:
+        return self.name
+
+    @property
+    def path(self) -> str:
+        return self.name
+
+    @property
+    def parent_dir(self) -> Optional["FSPath"]:
+        return None
+
+    @parent_dir.setter
+    def parent_dir(self, new_parent: Optional[FSPath]) -> None:
+        if new_parent is not None:
+            raise ValueError("The root directory cannot become a non-root directory")
+
+    @property
+    def parent_dir_path(self) -> Optional[str]:
+        return None
+
+    @property
+    def is_dir(self) -> bool:
+        return True
+
+    @property
+    def is_file(self) -> bool:
+        return False
+
+    @property
+    def is_symlink(self) -> bool:
+        return False
+
+    def readlink(self) -> str:
+        raise TypeError(f'"{self._orphan_safe_path()!r}" is a directory; not a symlink')
+
+    @property
+    def has_fs_path(self) -> bool:
+        return self._fs_path is not None
+
+    def stat(self) -> os.stat_result:
+        if not self.has_fs_path:
+            raise PureVirtualPathError(
+                "stat() is only applicable to paths backed by the file system. The path"
+                f" {self._orphan_safe_path()!r} is purely virtual"
+            )
+        return os.stat(self.fs_path)
+
+    @property
+    def fs_path(self) -> str:
+        if not self.has_fs_path:
+            raise PureVirtualPathError(
+                "fs_path is only applicable to paths backed by the file system. The path"
+                f" {self._orphan_safe_path()!r} is purely virtual"
+            )
+        return assume_not_none(self._fs_path)
+
+    @property
+    def is_read_write(self) -> bool:
+        return self._fs_read_write
+
+    @is_read_write.setter
+    def is_read_write(self, new_value: bool) -> None:
+        self._fs_read_write = new_value
+
+    def prune_if_empty_dir(self) -> None:
+        # No-op for the root directory. There is never a case where you want to delete this directory
+        # (and even if you could, debputy will need it for technical reasons, so the root dir stays)
+        return
+
+    def unlink(self, *, recursive: bool = False) -> None:
+        # There is never a case where you want to delete this directory (and even if you could,
+        # debputy will need it for technical reasons, so the root dir stays)
+        raise TypeError("Cannot delete the root directory")
+
+    def _current_plugin(self) -> str:
+        return self._plugin_context.current_plugin_name
+
+    @contextlib.contextmanager
+    def change_plugin_context(self, new_plugin: str) -> Iterator[str]:
+        with self._plugin_context.change_plugin_context(new_plugin) as r:
+            yield r
+
+
+class VirtualPathWithReference(VirtualFSPathBase, ABC):
+    __slots__ = ("_reference_path",)
+
+    def __init__(
+        self,
+        basename: str,
+        parent: FSPath,
+        *,
+        default_mode: int,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> None:
+        super().__init__(
+            basename,
+            parent=parent,
+            initial_mode=reference_path.mode if reference_path else default_mode,
+        )
+        self._reference_path = reference_path
+
+    @property
+    def has_fs_path(self) -> bool:
+        ref_path = self._reference_path
+        return ref_path is not None and ref_path.has_fs_path
+
+    @property
+    def mtime(self) -> float:
+        mtime = self._mtime
+        if mtime is None:
+            ref_path = self._reference_path
+            if ref_path:
+                mtime = ref_path.mtime
+            else:
+                mtime = super().mtime
+            self._mtime = mtime
+        return mtime
+
+    @mtime.setter
+    def mtime(self, new_mtime: float) -> None:
+        self._rw_check()
+        self._mtime = new_mtime
+
+    @property
+    def fs_path(self) -> str:
+        ref_path = self._reference_path
+        if ref_path is not None and (
+            not super().has_fs_path or super().fs_path == ref_path.fs_path
+        ):
+            return ref_path.fs_path
+        return super().fs_path
+
+    def stat(self) -> os.stat_result:
+        ref_path = self._reference_path
+        if ref_path is not None and (
+            not super().has_fs_path or super().fs_path == ref_path.fs_path
+        ):
+            return ref_path.stat()
+        return super().stat()
+
+    def open(
+        self,
+        *,
+        byte_io: bool = False,
+        buffering: int = -1,
+    ) -> Union[TextIO, BinaryIO]:
+        reference_path = self._reference_path
+        if reference_path is not None and reference_path.fs_path == self.fs_path:
+            return reference_path.open(byte_io=byte_io, buffering=buffering)
+        return super().open(byte_io=byte_io, buffering=buffering)
+
+
+class VirtualDirectoryFSPath(VirtualPathWithReference):
+    __slots__ = ("_reference_path",)
+
+    def __init__(
+        self,
+        basename: str,
+        parent: FSPath,
+        *,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> None:
+        super().__init__(
+            basename,
+            parent,
+            reference_path=reference_path,
+            default_mode=0o755,
+        )
+        self._reference_path = reference_path
+        assert reference_path is None or reference_path.is_dir
+
+    @property
+    def is_dir(self) -> bool:
+        return True
+
+    @property
+    def is_file(self) -> bool:
+        return False
+
+    @property
+    def is_symlink(self) -> bool:
+        return False
+
+    def readlink(self) -> str:
+        raise TypeError(f'"{self._orphan_safe_path()!r}" is a directory; not a symlink')
+
+
+class SymlinkVirtualPath(VirtualPathWithReference):
+    __slots__ = ("_link_target",)
+
+    def __init__(
+        self,
+        basename: str,
+        parent_dir: FSPath,
+        link_target: str,
+        *,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> None:
+        super().__init__(
+            basename,
+            parent=parent_dir,
+            default_mode=_SYMLINK_MODE,
+            reference_path=reference_path,
+        )
+        self._link_target = link_target
+
+    @property
+    def is_dir(self) -> bool:
+        return False
+
+    @property
+    def is_file(self) -> bool:
+        return False
+
+    @property
+    def is_symlink(self) -> bool:
+        return True
+
+    def readlink(self) -> str:
+        return self._link_target
+
+
+class FSBackedFilePath(VirtualPathWithReference):
+    __slots__ = ("_fs_path", "_replaceable_inline")
+
+    def __init__(
+        self,
+        basename: str,
+        parent_dir: FSPath,
+        fs_path: str,
+        *,
+        replaceable_inline: bool = False,
+        initial_mode: Optional[int] = None,
+        mtime: Optional[float] = None,
+        stat_cache: Optional[os.stat_result] = None,
+        reference_path: Optional[VirtualPath] = None,
+    ) -> None:
+        super().__init__(
+            basename,
+            parent_dir,
+            default_mode=0o644,
+            reference_path=reference_path,
+        )
+        self._fs_path = fs_path
+        self._replaceable_inline = replaceable_inline
+        if initial_mode is not None:
+            self.mode = initial_mode
+        if mtime is not None:
+            self._mtime = mtime
+        self._stat_cache = stat_cache
+        assert (
+            not replaceable_inline or "debputy/scratch-dir/" in fs_path
+        ), f"{fs_path} should not be inline-replaceable -- {self.path}"
+
+    @property
+    def is_dir(self) -> bool:
+        return False
+
+    @property
+    def is_file(self) -> bool:
+        return True
+
+    @property
+    def is_symlink(self) -> bool:
+        return False
+
+    def readlink(self) -> str:
+        raise TypeError(f'"{self._orphan_safe_path()!r}" is a file; not a symlink')
+
+    @property
+    def has_fs_path(self) -> bool:
+        return True
+
+    @property
+    def fs_path(self) -> str:
+        return self._fs_path
+
+    @property
+    def _can_replace_inline(self) -> bool:
+        return self._replaceable_inline
+
+    def _replaced_path(self, new_fs_path: str) -> None:
+        self._fs_path = new_fs_path
+        self._reference_path = None
+        self._replaceable_inline = True
+
+
+_SYMLINK_MODE = 0o777
+
+
+class VirtualTestPath(FSPath):
+    __slots__ = (
+        "_path_type",
+        "_has_fs_path",
+        "_fs_path",
+        "_link_target",
+        "_content",
+        "_materialized_content",
+    )
+
+    def __init__(
+        self,
+        basename: str,
+        parent_dir: Optional[FSPath],
+        mode: Optional[int] = None,
+        mtime: Optional[float] = None,
+        is_dir: bool = False,
+        has_fs_path: Optional[bool] = False,
+        fs_path: Optional[str] = None,
+        link_target: Optional[str] = None,
+        content: Optional[str] = None,
+        materialized_content: Optional[str] = None,
+    ) -> None:
+        if is_dir:
+            self._path_type = PathType.DIRECTORY
+        elif link_target is not None:
+            self._path_type = PathType.SYMLINK
+            if mode is not None and mode != _SYMLINK_MODE:
+                raise ValueError(
+                    f'Please do not assign a mode to symlinks. Triggered for "{basename}".'
+                )
+            assert mode is None or mode == _SYMLINK_MODE
+        else:
+            self._path_type = PathType.FILE
+
+        if mode is not None:
+            initial_mode = mode
+        else:
+            initial_mode = 0o755 if is_dir else 0o644
+
+        self._link_target = link_target
+        if has_fs_path is None:
+            has_fs_path = bool(fs_path)
+        self._has_fs_path = has_fs_path
+        self._fs_path = fs_path
+        self._materialized_content = materialized_content
+        super().__init__(
+            basename,
+            parent=parent_dir,
+            initial_mode=initial_mode,
+            mtime=mtime,
+        )
+        self._content = content
+
+    @property
+    def is_dir(self) -> bool:
+        return self._path_type == PathType.DIRECTORY
+
+    @property
+    def is_file(self) -> bool:
+        return self._path_type == PathType.FILE
+
+    @property
+    def is_symlink(self) -> bool:
+        return self._path_type == PathType.SYMLINK
+
+    def readlink(self) -> str:
+        if not self.is_symlink:
+            raise TypeError(f"readlink is only valid for symlinks ({self.path!r})")
+        link_target = self._link_target
+        assert link_target is not None
+        return link_target
+
+    @property
+    def mtime(self) -> float:
+        if self._mtime is None:
+            self._mtime = time.time()
+        return self._mtime
+
+    @mtime.setter
+    def mtime(self, new_mtime: float) -> None:
+        self._rw_check()
+        self._mtime = new_mtime
+
+    @property
+    def has_fs_path(self) -> bool:
+        return self._has_fs_path
+
+    def stat(self) -> os.stat_result:
+        if self.has_fs_path:
+            path = self.fs_path
+            if path is None:
+                raise PureVirtualPathError(
+                    f"The test wants a real stat of {self._orphan_safe_path()!r}, which this mock path"
+                    " cannot provide!"
+                )
+            try:
+                return os.stat(path)
+            except FileNotFoundError as e:
+                raise PureVirtualPathError(
+                    f"The test wants a real stat of {self._orphan_safe_path()!r}, which this mock path"
+                    " cannot provide! (An fs_path was provided, but it did not exist)"
+                ) from e
+
+        raise PureVirtualPathError(
+            "stat() is only applicable to paths backed by the file system. The path"
+            f" {self._orphan_safe_path()!r} is purely virtual"
+        )
+
+    @property
+    def size(self) -> int:
+        if self._content is not None:
+            return len(self._content.encode("utf-8"))
+        if not self.has_fs_path or self.fs_path is None:
+            return 0
+        return self.stat().st_size
+
+    @property
+    def fs_path(self) -> str:
+        if self.has_fs_path:
+            if self._fs_path is None and self._materialized_content is not None:
+                with tempfile.NamedTemporaryFile(
+                    mode="w+t",
+                    encoding="utf-8",
+                    suffix=f"__{self.name}",
+                    delete=False,
+                ) as fd:
+                    filepath = fd.name
+                    fd.write(self._materialized_content)
+                self._fs_path = filepath
+                atexit.register(lambda: os.unlink(filepath))
+
+            path = self._fs_path
+            if path is None:
+                raise PureVirtualPathError(
+                    f"The test wants a real file system entry of {self._orphan_safe_path()!r}, which this "
+                    " mock path cannot provide!"
+                )
+            return path
+        raise PureVirtualPathError(
+            "fs_path is only applicable to paths backed by the file system. The path"
+            f" {self._orphan_safe_path()!r} is purely virtual"
+        )
+
+    def replace_fs_path_content(
+        self,
+        *,
+        use_fs_path_mode: bool = False,
+    ) -> ContextManager[str]:
+        if self._content is not None:
+            raise TypeError(
+                f"The `replace_fs_path_content()` method was called on {self.path}. Said path was"
+                " created with `content` but for this method to work, the path should have been"
+                " created with `materialized_content`"
+            )
+        return super().replace_fs_path_content(use_fs_path_mode=use_fs_path_mode)
+
+    def open(
+        self,
+        *,
+        byte_io: bool = False,
+        buffering: int = -1,
+    ) -> Union[TextIO, BinaryIO]:
+        if self._content is None:
+            try:
+                return super().open(byte_io=byte_io, buffering=buffering)
+            except FileNotFoundError as e:
+                raise TestPathWithNonExistentFSPathError(
+                    "The test path {self.path} had an fs_path {self._fs_path}, which does not"
+                    " exist.  This exception can only occur in the testsuite.  Either have the"
+                    " test provide content for the path (`virtual_path_def(..., content=...) or,"
+                    " if that is too painful in general, have the code accept this error as a "
+                    " test only-case and provide a default."
+                ) from e
+
+        if byte_io:
+            return io.BytesIO(self._content.encode("utf-8"))
+        return io.StringIO(self._content)
+
+    def _replaced_path(self, new_fs_path: str) -> None:
+        self._fs_path = new_fs_path
+
+
+class FSROOverlay(VirtualPathBase):
+    __slots__ = (
+        "_path",
+        "_fs_path",
+        "_parent",
+        "_stat_cache",
+        "_readlink_cache",
+        "_children",
+        "_stat_failed_cache",
+        "__weakref__",
+    )
+
+    def __init__(
+        self,
+        path: str,
+        fs_path: str,
+        parent: Optional["FSROOverlay"],
+    ) -> None:
+        self._path: str = path
+        self._fs_path: str = _normalize_path(fs_path, with_prefix=False)
+        self._parent: Optional[ReferenceType[FSROOverlay]] = (
+            ref(parent) if parent is not None else None
+        )
+        self._stat_cache: Optional[os.stat_result] = None
+        self._readlink_cache: Optional[str] = None
+        self._stat_failed_cache = False
+        self._children: Optional[Mapping[str, FSROOverlay]] = None
+
+    @classmethod
+    def create_root_dir(cls, path: str, fs_path: str) -> "FSROOverlay":
+        return FSROOverlay(path, fs_path, None)
+
+    @property
+    def name(self) -> str:
+        return os.path.basename(self._path)
+
+    @property
+    def iterdir(self) -> Iterable["FSROOverlay"]:
+        if not self.is_dir:
+            return
+        if self._children is None:
+            self._ensure_children_are_resolved()
+        yield from assume_not_none(self._children).values()
+
+    def lookup(self, path: str) -> Optional["FSROOverlay"]:
+        if not self.is_dir:
+            return None
+        if self._children is None:
+            self._ensure_children_are_resolved()
+
+        absolute, _, path_parts = _split_path(path)
+        current = cast("FSROOverlay", _root(self)) if absolute else self
+        for no, dir_part in enumerate(path_parts):
+            if dir_part == ".":
+                continue
+            if dir_part == "..":
+                p = current.parent_dir
+                if current is None:
+                    raise ValueError(f'The path "{path}" escapes the root dir')
+                current = p
+                continue
+            try:
+                current = current[dir_part]
+            except KeyError:
+                return None
+        return current
+
+    def all_paths(self) -> Iterable["FSROOverlay"]:
+        yield self
+        if not self.is_dir:
+            return
+        stack = list(self.iterdir)
+        stack.reverse()
+        while stack:
+            current = stack.pop()
+            yield current
+            if current.is_dir:
+                if current._children is None:
+                    current._ensure_children_are_resolved()
+                stack.extend(reversed(current._children.values()))
+
+    def _ensure_children_are_resolved(self) -> None:
+        if not self.is_dir or self._children:
+            return
+        dir_path = self.path
+        dir_fs_path = self.fs_path
+        children = {}
+        for name in sorted(os.listdir(dir_fs_path), key=os.path.basename):
+            child_path = os.path.join(dir_path, name) if dir_path != "." else name
+            child_fs_path = (
+                os.path.join(dir_fs_path, name) if dir_fs_path != "." else name
+            )
+            children[name] = FSROOverlay(
+                child_path,
+                child_fs_path,
+                self,
+            )
+        self._children = children
+
+    @property
+    def is_detached(self) -> bool:
+        return False
+
+    def __getitem__(self, key) -> "VirtualPath":
+        if not self.is_dir:
+            raise KeyError(key)
+        if self._children is None:
+            self._ensure_children_are_resolved()
+        if isinstance(key, FSPath):
+            key = key.name
+        return self._children[key]
+
+    def __delitem__(self, key) -> None:
+        self._error_ro_fs()
+
+    @property
+    def is_read_write(self) -> bool:
+        return False
+
+    def _rw_check(self) -> None:
+        self._error_ro_fs()
+
+    def _error_ro_fs(self) -> NoReturn:
+        raise DebputyFSIsROError(
+            f'Attempt to write to "{self.path}" failed:'
+            " Debputy Virtual File system is R/O."
+        )
+
+    @property
+    def path(self) -> str:
+        return self._path
+
+    @property
+    def parent_dir(self) -> Optional["FSROOverlay"]:
+        parent = self._parent
+        if parent is None:
+            return None
+        resolved = parent()
+        if resolved is None:
+            raise RuntimeError("Parent was garbage collected!")
+        return resolved
+
+    def stat(self) -> os.stat_result:
+        if self._stat_failed_cache:
+            raise FileNotFoundError(
+                errno.ENOENT, os.strerror(errno.ENOENT), self.fs_path
+            )
+
+        if self._stat_cache is None:
+            try:
+                self._stat_cache = os.lstat(self.fs_path)
+            except FileNotFoundError:
+                self._stat_failed_cache = True
+                raise
+        return self._stat_cache
+
+    @property
+    def mode(self) -> int:
+        return stat.S_IMODE(self.stat().st_mode)
+
+    @mode.setter
+    def mode(self, _unused: int) -> None:
+        self._error_ro_fs()
+
+    @property
+    def mtime(self) -> float:
+        return self.stat().st_mtime
+
+    @mtime.setter
+    def mtime(self, new_mtime: float) -> None:
+        self._error_ro_fs()
+
+    def readlink(self) -> str:
+        if not self.is_symlink:
+            raise TypeError(f"readlink is only valid for symlinks ({self.path!r})")
+        if self._readlink_cache is None:
+            self._readlink_cache = os.readlink(self.fs_path)
+        return self._readlink_cache
+
+    @property
+    def fs_path(self) -> str:
+        return self._fs_path
+
+    @property
+    def is_dir(self) -> bool:
+        # The root path can have a non-existent fs_path (such as d/tmp not always existing)
+        try:
+            return stat.S_ISDIR(self.stat().st_mode)
+        except FileNotFoundError:
+            return False
+
+    @property
+    def is_file(self) -> bool:
+        # The root path can have a non-existent fs_path (such as d/tmp not always existing)
+        try:
+            return stat.S_ISREG(self.stat().st_mode)
+        except FileNotFoundError:
+            return False
+
+    @property
+    def is_symlink(self) -> bool:
+        # The root path can have a non-existent fs_path (such as d/tmp not always existing)
+        try:
+            return stat.S_ISLNK(self.stat().st_mode)
+        except FileNotFoundError:
+            return False
+
+    @property
+    def has_fs_path(self) -> bool:
+        return True
+
+    def open(
+        self,
+        *,
+        byte_io: bool = False,
+        buffering: int = -1,
+    ) -> Union[TextIO, BinaryIO]:
+        # Allow symlinks for open here, because we can let the OS resolve the symlink reliably in this
+        # case.
+        if not self.is_file and not self.is_symlink:
+            raise TypeError(
+                f"Cannot open {self.path} for reading: It is not a file nor a symlink"
+            )
+
+        if byte_io:
+            return open(self.fs_path, "rb", buffering=buffering)
+        return open(self.fs_path, "rt", encoding="utf-8", buffering=buffering)
+
+    def chown(
+        self,
+        owner: Optional[StaticFileSystemOwner],
+        group: Optional[StaticFileSystemGroup],
+    ) -> None:
+        self._error_ro_fs()
+
+    def mkdir(self, name: str) -> "VirtualPath":
+        self._error_ro_fs()
+
+    def add_file(
+        self,
+        name: str,
+        *,
+        unlink_if_exists: bool = True,
+        use_fs_path_mode: bool = False,
+        mode: int = 0o0644,
+        mtime: Optional[float] = None,
+    ) -> ContextManager["VirtualPath"]:
+        self._error_ro_fs()
+
+    def add_symlink(self, link_name: str, link_target: str) -> "VirtualPath":
+        self._error_ro_fs()
+
+    def unlink(self, *, recursive: bool = False) -> None:
+        self._error_ro_fs()
+
+    def metadata(
+        self,
+        metadata_type: Type[PMT],
+        *,
+        owning_plugin: Optional[str] = None,
+    ) -> PathMetadataReference[PMT]:
+        current_plugin = self._current_plugin()
+        if owning_plugin is None:
+            owning_plugin = current_plugin
+        return AlwaysEmptyReadOnlyMetadataReference(
+            owning_plugin,
+            current_plugin,
+            metadata_type,
+        )
+
+
+class FSROOverlayRootDir(FSROOverlay):
+    __slots__ = ("_plugin_context",)
+
+    def __init__(self, path: str, fs_path: str) -> None:
+        super().__init__(path, fs_path, None)
+        self._plugin_context = CurrentPluginContextManager("debputy")
+
+    def _current_plugin(self) -> str:
+        return self._plugin_context.current_plugin_name
+
+    @contextlib.contextmanager
+    def change_plugin_context(self, new_plugin: str) -> Iterator[str]:
+        with self._plugin_context.change_plugin_context(new_plugin) as r:
+            yield r
+
+
+def as_path_def(pd: Union[str, PathDef]) -> PathDef:
+    return PathDef(pd) if isinstance(pd, str) else pd
+
+
+def as_path_defs(paths: Iterable[Union[str, PathDef]]) -> Iterable[PathDef]:
+    yield from (as_path_def(p) for p in paths)
+
+
+def build_virtual_fs(
+    paths: Iterable[Union[str, PathDef]],
+    read_write_fs: bool = False,
+) -> "FSPath":
+    root_dir: Optional[FSRootDir] = None
+    directories: Dict[str, FSPath] = {}
+    non_directories = set()
+
+    def _ensure_parent_dirs(p: str) -> None:
+        current = p.rstrip("/")
+        missing_dirs = []
+        while True:
+            current = os.path.dirname(current)
+            if current in directories:
+                break
+            if current in non_directories:
+                raise ValueError(
+                    f'Conflicting definition for "{current}".  The path "{p}" wants it as a directory,'
+                    ' but it is defined as a non-directory.  (Ensure dirs end with "/")'
+                )
+            missing_dirs.append(current)
+        for dir_path in reversed(missing_dirs):
+            parent_dir = directories[os.path.dirname(dir_path)]
+            d = VirtualTestPath(os.path.basename(dir_path), parent_dir, is_dir=True)
+            directories[dir_path] = d
+
+    for path_def in as_path_defs(paths):
+        path = path_def.path_name
+        if path in directories or path in non_directories:
+            raise ValueError(
+                f'Duplicate definition of "{path}".  Can be false positive if input is not in'
+                ' "correct order" (ensure directories occur before their children)'
+            )
+        if root_dir is None:
+            root_fs_path = None
+            if path in (".", "./", "/"):
+                root_fs_path = path_def.fs_path
+            root_dir = FSRootDir(fs_path=root_fs_path)
+            directories["."] = root_dir
+
+        if path not in (".", "./", "/") and not path.startswith("./"):
+            path = "./" + path
+        if path not in (".", "./", "/"):
+            _ensure_parent_dirs(path)
+        if path in (".", "./"):
+            assert "." in directories
+            continue
+        is_dir = False
+        if path.endswith("/"):
+            path = path[:-1]
+            is_dir = True
+        directory = directories[os.path.dirname(path)]
+        assert not is_dir or not bool(
+            path_def.link_target
+        ), f"is_dir={is_dir} vs. link_target={path_def.link_target}"
+        fs_path = VirtualTestPath(
+            os.path.basename(path),
+            directory,
+            is_dir=is_dir,
+            mode=path_def.mode,
+            mtime=path_def.mtime,
+            has_fs_path=path_def.has_fs_path,
+            fs_path=path_def.fs_path,
+            link_target=path_def.link_target,
+            content=path_def.content,
+            materialized_content=path_def.materialized_content,
+        )
+        assert not fs_path.is_detached
+        if fs_path.is_dir:
+            directories[fs_path.path] = fs_path
+        else:
+            non_directories.add(fs_path.path)
+
+    if root_dir is None:
+        root_dir = FSRootDir()
+
+    root_dir.is_read_write = read_write_fs
+    return root_dir
diff --git a/src/debputy/highlevel_manifest.py b/src/debputy/highlevel_manifest.py
new file mode 100644
index 0000000..bae5cdb
--- /dev/null
+++ b/src/debputy/highlevel_manifest.py
@@ -0,0 +1,1608 @@
+import dataclasses
+import functools
+import os
+import textwrap
+from contextlib import suppress
+from dataclasses import dataclass, field
+from typing import (
+    List,
+    Dict,
+    Iterable,
+    Mapping,
+    Any,
+    Union,
+    Optional,
+    TypeVar,
+    Generic,
+    cast,
+    Set,
+    Tuple,
+    Sequence,
+    FrozenSet,
+)
+
+from debian.debian_support import DpkgArchTable
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+from ._deb_options_profiles import DebBuildOptionsAndProfiles
+from ._manifest_constants import *
+from .architecture_support import DpkgArchitectureBuildProcessValuesTable
+from .builtin_manifest_rules import builtin_mode_normalization_rules
+from .debhelper_emulation import (
+    dhe_dbgsym_root_dir,
+    assert_no_dbgsym_migration,
+    read_dbgsym_file,
+)
+from .exceptions import DebputySubstitutionError
+from .filesystem_scan import FSPath, FSRootDir, FSROOverlay
+from .installations import (
+    InstallRule,
+    SourcePathMatcher,
+    PathAlreadyInstalledOrDiscardedError,
+    NoMatchForInstallPatternError,
+    InstallRuleContext,
+    BinaryPackageInstallRuleContext,
+    InstallSearchDirContext,
+    SearchDir,
+)
+from .intermediate_manifest import TarMember, PathType, IntermediateManifest
+from .maintscript_snippet import (
+    DpkgMaintscriptHelperCommand,
+    MaintscriptSnippetContainer,
+)
+from .manifest_conditions import ConditionContext
+from .manifest_parser.base_types import FileSystemMatchRule, FileSystemExactMatchRule
+from .manifest_parser.util import AttributePath
+from .packager_provided_files import PackagerProvidedFile
+from .packages import BinaryPackage, SourcePackage
+from .plugin.api.impl import BinaryCtrlAccessorProviderCreator
+from .plugin.api.impl_types import (
+    PackageProcessingContextProvider,
+    PackageDataTable,
+)
+from .plugin.api.feature_set import PluginProvidedFeatureSet
+from .plugin.api.spec import FlushableSubstvars, VirtualPath
+from .substitution import Substitution
+from .transformation_rules import (
+    TransformationRule,
+    ModeNormalizationTransformationRule,
+    NormalizeShebangLineTransformation,
+)
+from .util import (
+    _error,
+    _warn,
+    debian_policy_normalize_symlink_target,
+    generated_content_dir,
+    _info,
+)
+
+MANIFEST_YAML = YAML()
+
+
+@dataclass(slots=True)
+class DbgsymInfo:
+    dbgsym_fs_root: FSPath
+    dbgsym_ids: List[str]
+
+
+@dataclass(slots=True, frozen=True)
+class BinaryPackageData:
+    source_package: SourcePackage
+    binary_package: BinaryPackage
+    binary_staging_root_dir: str
+    control_output_dir: Optional[str]
+    fs_root: FSPath
+    substvars: FlushableSubstvars
+    package_metadata_context: PackageProcessingContextProvider
+    ctrl_creator: BinaryCtrlAccessorProviderCreator
+    dbgsym_info: DbgsymInfo
+
+
+@dataclass(slots=True)
+class PackageTransformationDefinition:
+    binary_package: BinaryPackage
+    substitution: Substitution
+    is_auto_generated_package: bool
+    binary_version: Optional[str] = None
+    search_dirs: Optional[List[FileSystemExactMatchRule]] = None
+    dpkg_maintscript_helper_snippets: List[DpkgMaintscriptHelperCommand] = field(
+        default_factory=list
+    )
+    maintscript_snippets: Dict[str, MaintscriptSnippetContainer] = field(
+        default_factory=dict
+    )
+    transformations: List[TransformationRule] = field(default_factory=list)
+    reserved_packager_provided_files: Dict[str, List[PackagerProvidedFile]] = field(
+        default_factory=dict
+    )
+    install_rules: List[InstallRule] = field(default_factory=list)
+
+
+def _path_to_tar_member(
+    path: FSPath,
+    clamp_mtime_to: int,
+) -> TarMember:
+    mtime = float(clamp_mtime_to)
+    owner, uid, group, gid = path.tar_owner_info
+    mode = path.mode
+
+    if path.has_fs_path:
+        mtime = min(mtime, path.mtime)
+
+    if path.is_dir:
+        path_type = PathType.DIRECTORY
+    elif path.is_file:
+        # TODO: someday we will need to deal with hardlinks and it might appear here.
+        path_type = PathType.FILE
+    elif path.is_symlink:
+        # Special-case that we resolve immediately (since we need to normalize the target anyway)
+        link_target = debian_policy_normalize_symlink_target(
+            path.path,
+            path.readlink(),
+        )
+        return TarMember.virtual_path(
+            path.tar_path,
+            PathType.SYMLINK,
+            mtime,
+            link_target=link_target,
+            # Force mode to be 0777 as that is the mode we see in the data.tar.  In theory, tar lets you set
+            # it to whatever. However, for reproducibility, we have to be well-behaved - and that is 0777.
+            mode=0o0777,
+            owner=owner,
+            uid=uid,
+            group=group,
+            gid=gid,
+        )
+    else:
+        assert not path.is_symlink
+        raise AssertionError(
+            f"Unsupported file type: {path.path}  - not a file, dir nor a symlink!"
+        )
+
+    if not path.has_fs_path:
+        assert not path.is_file
+        return TarMember.virtual_path(
+            path.tar_path,
+            path_type,
+            mtime,
+            mode=mode,
+            owner=owner,
+            uid=uid,
+            group=group,
+            gid=gid,
+        )
+    may_steal_fs_path = path._can_replace_inline
+    return TarMember.from_file(
+        path.tar_path,
+        path.fs_path,
+        mode=mode,
+        uid=uid,
+        owner=owner,
+        gid=gid,
+        group=group,
+        path_type=path_type,
+        path_mtime=mtime,
+        clamp_mtime_to=clamp_mtime_to,
+        may_steal_fs_path=may_steal_fs_path,
+    )
+
+
+def _generate_intermediate_manifest(
+    fs_root: FSPath,
+    clamp_mtime_to: int,
+) -> Iterable[TarMember]:
+    symlinks = []
+    for path in fs_root.all_paths():
+        tar_member = _path_to_tar_member(path, clamp_mtime_to)
+        if tar_member.path_type == PathType.SYMLINK:
+            symlinks.append(tar_member)
+            continue
+        yield tar_member
+    yield from symlinks
+
+
+ST = TypeVar("ST")
+T = TypeVar("T")
+
+
+class AbstractYAMLSubStore(Generic[ST]):
+    def __init__(
+        self,
+        parent_store: Any,
+        parent_key: Optional[Union[int, str]],
+        store: Optional[ST] = None,
+    ) -> None:
+        if parent_store is not None and parent_key is not None:
+            try:
+                from_parent_store = parent_store[parent_key]
+            except (KeyError, IndexError):
+                from_parent_store = None
+            if (
+                store is not None
+                and from_parent_store is not None
+                and store is not parent_store
+            ):
+                raise ValueError(
+                    "Store is provided but is not the one already in the parent store"
+                )
+            if store is None:
+                store = from_parent_store
+        self._parent_store = parent_store
+        self._parent_key = parent_key
+        self._is_detached = (
+            parent_key is None or parent_store is None or parent_key not in parent_store
+        )
+        assert self._is_detached or store is not None
+        if store is None:
+            store = self._create_new_instance()
+        self._store: ST = store
+
+    def _create_new_instance(self) -> ST:
+        raise NotImplementedError
+
+    def create_definition_if_missing(self) -> None:
+        if self._is_detached:
+            self.create_definition()
+
+    def create_definition(self) -> None:
+        if not self._is_detached:
+            raise RuntimeError("Definition is already present")
+        parent_store = self._parent_store
+        if parent_store is None:
+            raise RuntimeError(
+                f"Definition is not attached to any parent!? ({self.__class__.__name__})"
+            )
+        if isinstance(parent_store, list):
+            assert self._parent_key is None
+            self._parent_key = len(parent_store)
+            self._parent_store.append(self._store)
+        else:
+            parent_store[self._parent_key] = self._store
+        self._is_detached = False
+
+    def remove_definition(self) -> None:
+        self._ensure_attached()
+        del self._parent_store[self._parent_key]
+        if isinstance(self._parent_store, list):
+            self._parent_key = None
+        self._is_detached = True
+
+    def _ensure_attached(self) -> None:
+        if self._is_detached:
+            raise RuntimeError("The definition has been removed!")
+
+
+class AbstractYAMLListSubStore(Generic[T], AbstractYAMLSubStore[List[T]]):
+    def _create_new_instance(self) -> List[T]:
+        return CommentedSeq()
+
+
+class AbstractYAMLDictSubStore(Generic[T], AbstractYAMLSubStore[Dict[str, T]]):
+    def _create_new_instance(self) -> Dict[str, T]:
+        return CommentedMap()
+
+
+class MutableCondition:
+    @classmethod
+    def arch_matches(cls, arch_filter: str) -> CommentedMap:
+        return CommentedMap({MK_CONDITION_ARCH_MATCHES: arch_filter})
+
+    @classmethod
+    def build_profiles_matches(cls, build_profiles_matches: str) -> CommentedMap:
+        return CommentedMap(
+            {MK_CONDITION_BUILD_PROFILES_MATCHES: build_profiles_matches}
+        )
+
+
+class MutableYAMLSymlink(AbstractYAMLDictSubStore[Any]):
+    @classmethod
+    def new_symlink(
+        cls, link_path: str, link_target: str, condition: Optional[Any]
+    ) -> "MutableYAMLSymlink":
+        inner = {
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_PATH: link_path,
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_TARGET: link_target,
+        }
+        content = {MK_TRANSFORMATIONS_CREATE_SYMLINK: inner}
+        if condition is not None:
+            inner["when"] = condition
+        return cls(None, None, store=CommentedMap(content))
+
+    @property
+    def symlink_path(self) -> str:
+        return self._store[MK_TRANSFORMATIONS_CREATE_SYMLINK][
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_PATH
+        ]
+
+    @symlink_path.setter
+    def symlink_path(self, path: str) -> None:
+        self._store[MK_TRANSFORMATIONS_CREATE_SYMLINK][
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_PATH
+        ] = path
+
+    @property
+    def symlink_target(self) -> Optional[str]:
+        return self._store[MK_TRANSFORMATIONS_CREATE_SYMLINK][
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_TARGET
+        ]
+
+    @symlink_target.setter
+    def symlink_target(self, target: str) -> None:
+        self._store[MK_TRANSFORMATIONS_CREATE_SYMLINK][
+            MK_TRANSFORMATIONS_CREATE_SYMLINK_LINK_TARGET
+        ] = target
+
+
+class MutableYAMLConffileManagementItem(AbstractYAMLDictSubStore[Any]):
+    @classmethod
+    def rm_conffile(
+        cls,
+        conffile: str,
+        prior_to_version: Optional[str],
+        owning_package: Optional[str],
+    ) -> "MutableYAMLConffileManagementItem":
+        r = cls(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_CONFFILE_MANAGEMENT_REMOVE: CommentedMap(
+                        {MK_CONFFILE_MANAGEMENT_REMOVE_PATH: conffile}
+                    )
+                }
+            ),
+        )
+        r.prior_to_version = prior_to_version
+        r.owning_package = owning_package
+        return r
+
+    @classmethod
+    def mv_conffile(
+        cls,
+        old_conffile: str,
+        new_conffile: str,
+        prior_to_version: Optional[str],
+        owning_package: Optional[str],
+    ) -> "MutableYAMLConffileManagementItem":
+        r = cls(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_CONFFILE_MANAGEMENT_RENAME: CommentedMap(
+                        {
+                            MK_CONFFILE_MANAGEMENT_RENAME_SOURCE: old_conffile,
+                            MK_CONFFILE_MANAGEMENT_RENAME_TARGET: new_conffile,
+                        }
+                    )
+                }
+            ),
+        )
+        r.prior_to_version = prior_to_version
+        r.owning_package = owning_package
+        return r
+
+    @property
+    def _container(self) -> Dict[str, Any]:
+        assert len(self._store) == 1
+        return next(iter(self._store.values()))
+
+    @property
+    def command(self) -> str:
+        assert len(self._store) == 1
+        return next(iter(self._store))
+
+    @property
+    def obsolete_conffile(self) -> str:
+        if self.command == MK_CONFFILE_MANAGEMENT_REMOVE:
+            return self._container[MK_CONFFILE_MANAGEMENT_REMOVE_PATH]
+        assert self.command == MK_CONFFILE_MANAGEMENT_RENAME
+        return self._container[MK_CONFFILE_MANAGEMENT_RENAME_SOURCE]
+
+    @obsolete_conffile.setter
+    def obsolete_conffile(self, value: str) -> None:
+        if self.command == MK_CONFFILE_MANAGEMENT_REMOVE:
+            self._container[MK_CONFFILE_MANAGEMENT_REMOVE_PATH] = value
+        else:
+            assert self.command == MK_CONFFILE_MANAGEMENT_RENAME
+            self._container[MK_CONFFILE_MANAGEMENT_RENAME_SOURCE] = value
+
+    @property
+    def new_conffile(self) -> str:
+        if self.command != MK_CONFFILE_MANAGEMENT_RENAME:
+            raise TypeError(
+                f"The new_conffile attribute is only applicable to command {MK_CONFFILE_MANAGEMENT_RENAME}."
+                f" This is a {self.command}"
+            )
+        return self._container[MK_CONFFILE_MANAGEMENT_RENAME_TARGET]
+
+    @new_conffile.setter
+    def new_conffile(self, value: str) -> None:
+        if self.command != MK_CONFFILE_MANAGEMENT_RENAME:
+            raise TypeError(
+                f"The new_conffile attribute is only applicable to command {MK_CONFFILE_MANAGEMENT_RENAME}."
+                f" This is a {self.command}"
+            )
+        self._container[MK_CONFFILE_MANAGEMENT_RENAME_TARGET] = value
+
+    @property
+    def prior_to_version(self) -> Optional[str]:
+        return self._container.get(MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION)
+
+    @prior_to_version.setter
+    def prior_to_version(self, value: Optional[str]) -> None:
+        if value is None:
+            try:
+                del self._container[MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION]
+            except KeyError:
+                pass
+        else:
+            self._container[MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION] = value
+
+    @property
+    def owning_package(self) -> Optional[str]:
+        return self._container[MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION]
+
+    @owning_package.setter
+    def owning_package(self, value: Optional[str]) -> None:
+        if value is None:
+            try:
+                del self._container[MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE]
+            except KeyError:
+                pass
+        else:
+            self._container[MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE] = value
+
+
+class MutableYAMLPackageDefinition(AbstractYAMLDictSubStore):
+    def _list_store(
+        self, key, *, create_if_absent: bool = False
+    ) -> Optional[List[Dict[str, Any]]]:
+        if self._is_detached or key not in self._store:
+            if create_if_absent:
+                return None
+            self.create_definition_if_missing()
+            self._store[key] = []
+        return self._store[key]
+
+    def _insert_item(self, key: str, item: AbstractYAMLDictSubStore) -> None:
+        parent_store = self._list_store(key, create_if_absent=True)
+        assert parent_store is not None
+        if not item._is_detached or (
+            item._parent_store is not None and item._parent_store is not parent_store
+        ):
+            raise RuntimeError(
+                "Item is already attached or associated with a different container"
+            )
+        item._parent_store = parent_store
+        item.create_definition()
+
+    def add_symlink(self, symlink: MutableYAMLSymlink) -> None:
+        self._insert_item(MK_TRANSFORMATIONS, symlink)
+
+    def symlinks(self) -> Iterable[MutableYAMLSymlink]:
+        store = self._list_store(MK_TRANSFORMATIONS)
+        if store is None:
+            return
+        for i in range(len(store)):
+            d = store[i]
+            if d and isinstance(d, dict) and len(d) == 1 and "symlink" in d:
+                yield MutableYAMLSymlink(store, i)
+
+    def conffile_management_items(self) -> Iterable[MutableYAMLConffileManagementItem]:
+        store = self._list_store(MK_CONFFILE_MANAGEMENT)
+        if store is None:
+            return
+        yield from (
+            MutableYAMLConffileManagementItem(store, i) for i in range(len(store))
+        )
+
+    def add_conffile_management(
+        self, conffile_management_item: MutableYAMLConffileManagementItem
+    ) -> None:
+        self._insert_item(MK_CONFFILE_MANAGEMENT, conffile_management_item)
+
+
+class AbstractMutableYAMLInstallRule(AbstractYAMLDictSubStore):
+    @property
+    def _container(self) -> Dict[str, Any]:
+        assert len(self._store) == 1
+        return next(iter(self._store.values()))
+
+    @property
+    def into(self) -> Optional[List[str]]:
+        v = self._container[MK_INSTALLATIONS_INSTALL_INTO]
+        if v is None:
+            return None
+        if isinstance(v, str):
+            return [v]
+        return v
+
+    @into.setter
+    def into(self, new_value: Optional[Union[str, List[str]]]) -> None:
+        if new_value is None:
+            with suppress(KeyError):
+                del self._container[MK_INSTALLATIONS_INSTALL_INTO]
+            return
+        if isinstance(new_value, str):
+            self._container[MK_INSTALLATIONS_INSTALL_INTO] = new_value
+            return
+        new_list = CommentedSeq(new_value)
+        self._container[MK_INSTALLATIONS_INSTALL_INTO] = new_list
+
+    @property
+    def when(self) -> Optional[Union[str, Mapping[str, Any]]]:
+        return self._container[MK_CONDITION_WHEN]
+
+    @when.setter
+    def when(self, new_value: Optional[Union[str, Mapping[str, Any]]]) -> None:
+        if new_value is None:
+            with suppress(KeyError):
+                del self._container[MK_CONDITION_WHEN]
+            return
+        if isinstance(new_value, str):
+            self._container[MK_CONDITION_WHEN] = new_value
+            return
+        new_map = CommentedMap(new_value)
+        self._container[MK_CONDITION_WHEN] = new_map
+
+    @classmethod
+    def install_dest(
+        cls,
+        sources: Union[str, List[str]],
+        into: Optional[Union[str, List[str]]],
+        *,
+        dest_dir: Optional[str] = None,
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstall":
+        k = MK_INSTALLATIONS_INSTALL_SOURCES
+        if isinstance(sources, str):
+            k = MK_INSTALLATIONS_INSTALL_SOURCE
+        r = MutableYAMLInstallRuleInstall(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL: CommentedMap(
+                        {
+                            k: sources,
+                        }
+                    )
+                }
+            ),
+        )
+        r.dest_dir = dest_dir
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def multi_dest_install(
+        cls,
+        sources: Union[str, List[str]],
+        dest_dirs: Sequence[str],
+        into: Optional[Union[str, List[str]]],
+        *,
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstall":
+        k = MK_INSTALLATIONS_INSTALL_SOURCES
+        if isinstance(sources, str):
+            k = MK_INSTALLATIONS_INSTALL_SOURCE
+        r = MutableYAMLInstallRuleInstall(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_MULTI_DEST_INSTALL: CommentedMap(
+                        {
+                            k: sources,
+                            "dest-dirs": dest_dirs,
+                        }
+                    )
+                }
+            ),
+        )
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def install_as(
+        cls,
+        source: str,
+        install_as: str,
+        into: Optional[Union[str, List[str]]],
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstall":
+        r = MutableYAMLInstallRuleInstall(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL: CommentedMap(
+                        {
+                            MK_INSTALLATIONS_INSTALL_SOURCE: source,
+                            MK_INSTALLATIONS_INSTALL_AS: install_as,
+                        }
+                    )
+                }
+            ),
+        )
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def install_doc_as(
+        cls,
+        source: str,
+        install_as: str,
+        into: Optional[Union[str, List[str]]],
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstall":
+        r = MutableYAMLInstallRuleInstall(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL_DOCS: CommentedMap(
+                        {
+                            MK_INSTALLATIONS_INSTALL_SOURCE: source,
+                            MK_INSTALLATIONS_INSTALL_AS: install_as,
+                        }
+                    )
+                }
+            ),
+        )
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def install_docs(
+        cls,
+        sources: Union[str, List[str]],
+        into: Optional[Union[str, List[str]]],
+        *,
+        dest_dir: Optional[str] = None,
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstall":
+        k = MK_INSTALLATIONS_INSTALL_SOURCES
+        if isinstance(sources, str):
+            k = MK_INSTALLATIONS_INSTALL_SOURCE
+        r = MutableYAMLInstallRuleInstall(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL_DOCS: CommentedMap(
+                        {
+                            k: sources,
+                        }
+                    )
+                }
+            ),
+        )
+        r.into = into
+        r.dest_dir = dest_dir
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def install_examples(
+        cls,
+        sources: Union[str, List[str]],
+        into: Optional[Union[str, List[str]]],
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleInstallExamples":
+        k = MK_INSTALLATIONS_INSTALL_SOURCES
+        if isinstance(sources, str):
+            k = MK_INSTALLATIONS_INSTALL_SOURCE
+        r = MutableYAMLInstallRuleInstallExamples(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL_EXAMPLES: CommentedMap(
+                        {
+                            k: sources,
+                        }
+                    )
+                }
+            ),
+        )
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def install_man(
+        cls,
+        sources: Union[str, List[str]],
+        into: Optional[Union[str, List[str]]],
+        language: Optional[str],
+        when: Optional[Union[str, Mapping[str, Any]]] = None,
+    ) -> "MutableYAMLInstallRuleMan":
+        k = MK_INSTALLATIONS_INSTALL_SOURCES
+        if isinstance(sources, str):
+            k = MK_INSTALLATIONS_INSTALL_SOURCE
+        r = MutableYAMLInstallRuleMan(
+            None,
+            None,
+            store=CommentedMap(
+                {
+                    MK_INSTALLATIONS_INSTALL_MAN: CommentedMap(
+                        {
+                            k: sources,
+                        }
+                    )
+                }
+            ),
+        )
+        r.language = language
+        r.into = into
+        if when is not None:
+            r.when = when
+        return r
+
+    @classmethod
+    def discard(
+        cls,
+        sources: Union[str, List[str]],
+    ) -> "MutableYAMLInstallRuleDiscard":
+        return MutableYAMLInstallRuleDiscard(
+            None,
+            None,
+            store=CommentedMap({MK_INSTALLATIONS_DISCARD: sources}),
+        )
+
+
+class MutableYAMLInstallRuleInstallExamples(AbstractMutableYAMLInstallRule):
+    pass
+
+
+class MutableYAMLInstallRuleMan(AbstractMutableYAMLInstallRule):
+    @property
+    def language(self) -> Optional[str]:
+        return self._container[MK_INSTALLATIONS_INSTALL_MAN_LANGUAGE]
+
+    @language.setter
+    def language(self, new_value: Optional[str]) -> None:
+        if new_value is not None:
+            self._container[MK_INSTALLATIONS_INSTALL_MAN_LANGUAGE] = new_value
+            return
+        with suppress(KeyError):
+            del self._container[MK_INSTALLATIONS_INSTALL_MAN_LANGUAGE]
+
+
+class MutableYAMLInstallRuleDiscard(AbstractMutableYAMLInstallRule):
+    pass
+
+
+class MutableYAMLInstallRuleInstall(AbstractMutableYAMLInstallRule):
+    @property
+    def sources(self) -> List[str]:
+        v = self._container[MK_INSTALLATIONS_INSTALL_SOURCES]
+        if isinstance(v, str):
+            return [v]
+        return v
+
+    @sources.setter
+    def sources(self, new_value: Union[str, List[str]]) -> None:
+        if isinstance(new_value, str):
+            self._container[MK_INSTALLATIONS_INSTALL_SOURCES] = new_value
+            return
+        new_list = CommentedSeq(new_value)
+        self._container[MK_INSTALLATIONS_INSTALL_SOURCES] = new_list
+
+    @property
+    def dest_dir(self) -> Optional[str]:
+        return self._container.get(MK_INSTALLATIONS_INSTALL_DEST_DIR)
+
+    @dest_dir.setter
+    def dest_dir(self, new_value: Optional[str]) -> None:
+        if new_value is not None and self.dest_as is not None:
+            raise ValueError(
+                f'Cannot both have a "{MK_INSTALLATIONS_INSTALL_DEST_DIR}" and'
+                f' "{MK_INSTALLATIONS_INSTALL_AS}"'
+            )
+        if new_value is not None:
+            self._container[MK_INSTALLATIONS_INSTALL_DEST_DIR] = new_value
+        else:
+            with suppress(KeyError):
+                del self._container[MK_INSTALLATIONS_INSTALL_DEST_DIR]
+
+    @property
+    def dest_as(self) -> Optional[str]:
+        return self._container.get(MK_INSTALLATIONS_INSTALL_AS)
+
+    @dest_as.setter
+    def dest_as(self, new_value: Optional[str]) -> None:
+        if new_value is not None:
+            if self.dest_dir is not None:
+                raise ValueError(
+                    f'Cannot both have a "{MK_INSTALLATIONS_INSTALL_DEST_DIR}" and'
+                    f' "{MK_INSTALLATIONS_INSTALL_AS}"'
+                )
+
+            sources = self._container[MK_INSTALLATIONS_INSTALL_SOURCES]
+            if isinstance(sources, list):
+                if len(sources) != 1:
+                    raise ValueError(
+                        f'Cannot have "{MK_INSTALLATIONS_INSTALL_AS}" when'
+                        f' "{MK_INSTALLATIONS_INSTALL_SOURCES}" is not exactly one item'
+                    )
+                self.sources = sources[0]
+            self._container[MK_INSTALLATIONS_INSTALL_AS] = new_value
+        else:
+            with suppress(KeyError):
+                del self._container[MK_INSTALLATIONS_INSTALL_AS]
+
+
+class MutableYAMLInstallationsDefinition(AbstractYAMLListSubStore[Any]):
+    def append(self, install_rule: AbstractMutableYAMLInstallRule) -> None:
+        parent_store = self._store
+        if not install_rule._is_detached or (
+            install_rule._parent_store is not None
+            and install_rule._parent_store is not parent_store
+        ):
+            raise RuntimeError(
+                "Item is already attached or associated with a different container"
+            )
+        self.create_definition_if_missing()
+        install_rule._parent_store = parent_store
+        install_rule.create_definition()
+
+    def extend(self, install_rules: Iterable[AbstractMutableYAMLInstallRule]) -> None:
+        parent_store = self._store
+        for install_rule in install_rules:
+            if not install_rule._is_detached or (
+                install_rule._parent_store is not None
+                and install_rule._parent_store is not parent_store
+            ):
+                raise RuntimeError(
+                    "Item is already attached or associated with a different container"
+                )
+            self.create_definition_if_missing()
+            install_rule._parent_store = parent_store
+            install_rule.create_definition()
+
+
+class MutableYAMLManifestVariables(AbstractYAMLDictSubStore):
+    @property
+    def variables(self) -> Dict[str, Any]:
+        return self._store
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._store[key] = value
+        self.create_definition_if_missing()
+
+
+class MutableYAMLManifestDefinitions(AbstractYAMLDictSubStore):
+    def manifest_variables(
+        self, *, create_if_absent: bool = True
+    ) -> MutableYAMLManifestVariables:
+        d = MutableYAMLManifestVariables(self._store, MK_MANIFEST_VARIABLES)
+        if create_if_absent:
+            d.create_definition_if_missing()
+        return d
+
+
+class MutableYAMLManifest:
+    def __init__(self, store: Any) -> None:
+        self._store = store
+
+    @classmethod
+    def empty_manifest(cls) -> "MutableYAMLManifest":
+        return cls(CommentedMap({MK_MANIFEST_VERSION: DEFAULT_MANIFEST_VERSION}))
+
+    @property
+    def manifest_version(self) -> str:
+        return self._store[MK_MANIFEST_VERSION]
+
+    @manifest_version.setter
+    def manifest_version(self, version: str) -> None:
+        if version not in SUPPORTED_MANIFEST_VERSIONS:
+            raise ValueError("Unsupported version")
+        self._store[MK_MANIFEST_VERSION] = version
+
+    def installations(
+        self,
+        *,
+        create_if_absent: bool = True,
+    ) -> MutableYAMLInstallationsDefinition:
+        d = MutableYAMLInstallationsDefinition(self._store, MK_INSTALLATIONS)
+        if create_if_absent:
+            d.create_definition_if_missing()
+        return d
+
+    def manifest_definitions(
+        self,
+        *,
+        create_if_absent: bool = True,
+    ) -> MutableYAMLManifestDefinitions:
+        d = MutableYAMLManifestDefinitions(self._store, MK_MANIFEST_DEFINITIONS)
+        if create_if_absent:
+            d.create_definition_if_missing()
+        return d
+
+    def package(
+        self, name: str, *, create_if_absent: bool = True
+    ) -> MutableYAMLPackageDefinition:
+        if MK_PACKAGES not in self._store:
+            self._store[MK_PACKAGES] = CommentedMap()
+        packages_store = self._store[MK_PACKAGES]
+        package = packages_store.get(name)
+        if package is None:
+            if not create_if_absent:
+                raise KeyError(name)
+            assert packages_store is not None
+            d = MutableYAMLPackageDefinition(packages_store, name)
+            d.create_definition()
+        else:
+            d = MutableYAMLPackageDefinition(packages_store, name)
+        return d
+
+    def write_to(self, fd) -> None:
+        MANIFEST_YAML.dump(self._store, fd)
+
+
+def _describe_missing_path(entry: VirtualPath) -> str:
+    if entry.is_dir:
+        return f"{entry.fs_path}/ (empty directory; possible integration point)"
+    if entry.is_symlink:
+        target = os.readlink(entry.fs_path)
+        return f"{entry.fs_path} (symlink; links to {target})"
+    if entry.is_file:
+        return f"{entry.fs_path} (file)"
+    return f"{entry.fs_path} (other!? Probably not supported by debputy and may need a `remove`)"
+
+
+def _detect_missing_installations(
+    path_matcher: SourcePathMatcher,
+    search_dir: VirtualPath,
+) -> None:
+    if not os.path.isdir(search_dir.fs_path):
+        return
+    missing = list(path_matcher.detect_missing(search_dir))
+    if not missing:
+        return
+
+    _warn(
+        f"The following paths were present in {search_dir.fs_path}, but not installed (nor explicitly discarded)."
+    )
+    _warn("")
+    for entry in missing:
+        desc = _describe_missing_path(entry)
+        _warn(f" * {desc}")
+    _warn("")
+
+    excl = textwrap.dedent(
+        """\
+        - discard: "*"
+    """
+    )
+
+    _error(
+        "Please review the list and add either install rules or exclusions to `installations` in"
+        " debian/debputy.manifest.  If you do not need any of these paths, add the following to the"
+        f" end of your 'installations`:\n\n{excl}\n"
+    )
+
+
+def _list_automatic_discard_rules(path_matcher: SourcePathMatcher) -> None:
+    used_discard_rules = path_matcher.used_auto_discard_rules
+    # Discard rules can match and then be overridden.  In that case, they appear
+    # but have 0 matches.
+    if not sum((len(v) for v in used_discard_rules.values()), 0):
+        return
+    _info("The following automatic discard rules were triggered:")
+    example_path: Optional[str] = None
+    for rule in sorted(used_discard_rules):
+        for fs_path in sorted(used_discard_rules[rule]):
+            if example_path is None:
+                example_path = fs_path
+            _info(f" * {rule} -> {fs_path}")
+    assert example_path is not None
+    _info("")
+    _info(
+        "Note that some of these may have been overruled. The overrule detection logic is not"
+    )
+    _info("100% reliable.")
+    _info("")
+    _info(
+        "You can overrule an automatic discard rule by explicitly listing the path. As an example:"
+    )
+    _info("    installations:")
+    _info("    - install:")
+    _info(f"        source: {example_path}")
+
+
+def _install_everything_from_source_dir_if_present(
+    dctrl_bin: BinaryPackage,
+    substitution: Substitution,
+    path_matcher: SourcePathMatcher,
+    install_rule_context: InstallRuleContext,
+    source_condition_context: ConditionContext,
+    source_dir: VirtualPath,
+    *,
+    into_dir: Optional[VirtualPath] = None,
+) -> None:
+    attribute_path = AttributePath.builtin_path()[f"installing {source_dir.fs_path}"]
+    pkg_set = frozenset([dctrl_bin])
+    install_rule = InstallRule.install_dest(
+        [FileSystemMatchRule.from_path_match("*", attribute_path, substitution)],
+        None,
+        pkg_set,
+        f"Built-in; install everything from {source_dir.fs_path} into {dctrl_bin.name}",
+        None,
+    )
+    pkg_search_dir: Tuple[SearchDir] = (
+        SearchDir(
+            source_dir,
+            pkg_set,
+        ),
+    )
+    replacements = {
+        "search_dirs": pkg_search_dir,
+    }
+    if into_dir is not None:
+        binary_package_contexts = dict(install_rule_context.binary_package_contexts)
+        updated = binary_package_contexts[dctrl_bin.name].replace(fs_root=into_dir)
+        binary_package_contexts[dctrl_bin.name] = updated
+        replacements["binary_package_contexts"] = binary_package_contexts
+
+    fake_install_rule_context = install_rule_context.replace(**replacements)
+    try:
+        install_rule.perform_install(
+            path_matcher,
+            fake_install_rule_context,
+            source_condition_context,
+        )
+    except (
+        NoMatchForInstallPatternError,
+        PathAlreadyInstalledOrDiscardedError,
+    ):
+        # Empty directory or everything excluded by default; ignore the error
+        pass
+
+
+class HighLevelManifest:
+    def __init__(
+        self,
+        manifest_path: str,
+        mutable_manifest: Optional[MutableYAMLManifest],
+        install_rules: Optional[List[InstallRule]],
+        source_package: SourcePackage,
+        binary_packages: Mapping[str, BinaryPackage],
+        substitution: Substitution,
+        package_transformations: Mapping[str, PackageTransformationDefinition],
+        dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+        dpkg_arch_query_table: DpkgArchTable,
+        build_env: DebBuildOptionsAndProfiles,
+        plugin_provided_feature_set: PluginProvidedFeatureSet,
+        debian_dir: VirtualPath,
+    ) -> None:
+        self.manifest_path = manifest_path
+        self.mutable_manifest = mutable_manifest
+        self._install_rules = install_rules
+        self._source_package = source_package
+        self._binary_packages = binary_packages
+        self.substitution = substitution
+        self.package_transformations = package_transformations
+        self._dpkg_architecture_variables = dpkg_architecture_variables
+        self._dpkg_arch_query_table = dpkg_arch_query_table
+        self._build_env = build_env
+        self._used_for: Set[str] = set()
+        self._plugin_provided_feature_set = plugin_provided_feature_set
+        self._debian_dir = debian_dir
+
+    def source_version(self, include_binnmu_version: bool = True) -> str:
+        # TODO: There should an easier way to determine the source version; really.
+        version_var = "{{DEB_VERSION}}"
+        if not include_binnmu_version:
+            version_var = "{{_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE}}"
+        try:
+            return self.substitution.substitute(
+                version_var, "internal (resolve version)"
+            )
+        except DebputySubstitutionError as e:
+            raise AssertionError(f"Could not resolve {version_var}") from e
+
+    @property
+    def debian_dir(self) -> VirtualPath:
+        return self._debian_dir
+
+    @property
+    def dpkg_architecture_variables(self) -> DpkgArchitectureBuildProcessValuesTable:
+        return self._dpkg_architecture_variables
+
+    @property
+    def build_env(self) -> DebBuildOptionsAndProfiles:
+        return self._build_env
+
+    @property
+    def plugin_provided_feature_set(self) -> PluginProvidedFeatureSet:
+        return self._plugin_provided_feature_set
+
+    @property
+    def active_packages(self) -> Iterable[BinaryPackage]:
+        yield from (p for p in self._binary_packages.values() if p.should_be_acted_on)
+
+    @property
+    def all_packages(self) -> Iterable[BinaryPackage]:
+        yield from self._binary_packages.values()
+
+    def package_state_for(self, package: str) -> PackageTransformationDefinition:
+        return self.package_transformations[package]
+
+    def _detect_doc_main_package_for(self, package: BinaryPackage) -> BinaryPackage:
+        name = package.name
+        # If it is not a -doc package, then docs should be installed
+        # under its own package name.
+        if not name.endswith("-doc"):
+            return package
+        name = name[:-4]
+        main_package = self._binary_packages.get(name)
+        if main_package:
+            return main_package
+        if name.startswith("lib"):
+            dev_pkg = self._binary_packages.get(f"{name}-dev")
+            if dev_pkg:
+                return dev_pkg
+
+        # If we found no better match; default to the doc package itself.
+        return package
+
+    def perform_installations(
+        self,
+        *,
+        install_request_context: Optional[InstallSearchDirContext] = None,
+        enable_manifest_installation_feature: bool = True,
+    ) -> PackageDataTable:
+        package_data_dict = {}
+        package_data_table = PackageDataTable(package_data_dict)
+        if install_request_context is None:
+
+            @functools.lru_cache(None)
+            def _as_path(fs_path: str) -> VirtualPath:
+                return FSROOverlay.create_root_dir(".", fs_path)
+
+            dtmp_dir = _as_path("debian/tmp")
+            source_root_dir = _as_path(".")
+            into = frozenset(self._binary_packages.values())
+            default_search_dirs = [dtmp_dir]
+            per_package_search_dirs = {
+                t.binary_package: [_as_path(f.match_rule.path) for f in t.search_dirs]
+                for t in self.package_transformations.values()
+                if t.search_dirs is not None
+            }
+            search_dirs = _determine_search_dir_order(
+                per_package_search_dirs,
+                into,
+                default_search_dirs,
+                source_root_dir,
+            )
+            check_for_uninstalled_dirs = tuple(
+                s.search_dir
+                for s in search_dirs
+                if s.search_dir.fs_path != source_root_dir.fs_path
+            )
+            _present_installation_dirs(search_dirs, check_for_uninstalled_dirs, into)
+        else:
+            dtmp_dir = None
+            search_dirs = install_request_context.search_dirs
+            into = frozenset(self._binary_packages.values())
+            seen = set()
+            for search_dir in search_dirs:
+                seen.update(search_dir.applies_to)
+
+            missing = into - seen
+            if missing:
+                names = ", ".join(p.name for p in missing)
+                raise ValueError(
+                    f"The following package(s) had no search dirs: {names}."
+                    " (Generally, the source root would be applicable to all packages)"
+                )
+            extra_names = seen - into
+            if extra_names:
+                names = ", ".join(p.name for p in extra_names)
+                raise ValueError(
+                    f"The install_request_context referenced the following unknown package(s): {names}"
+                )
+
+            check_for_uninstalled_dirs = (
+                install_request_context.check_for_uninstalled_dirs
+            )
+
+        install_rule_context = InstallRuleContext(search_dirs)
+
+        if (
+            enable_manifest_installation_feature
+            and self._install_rules is None
+            and dtmp_dir is not None
+            and os.path.isdir(dtmp_dir.fs_path)
+        ):
+            msg = (
+                "The build system appears to have provided the output of upstream build system's"
+                " install in debian/tmp.  However, these are no provisions for debputy to install"
+                " any of that into any of the debian packages listed in debian/control."
+                " To avoid accidentally creating empty packages, debputy will insist that you "
+                " explicitly define an empty installation definition if you did not want to "
+                " install any of those files even though they have been provided."
+                ' Example: "installations: []"'
+            )
+            _error(msg)
+        elif (
+            not enable_manifest_installation_feature and self._install_rules is not None
+        ):
+            _error(
+                f"The `installations` feature cannot be used in {self.manifest_path} with this integration mode."
+                f" Please remove or comment out the `installations` keyword."
+            )
+
+        for dctrl_bin in self.all_packages:
+            package = dctrl_bin.name
+            doc_main_package = self._detect_doc_main_package_for(dctrl_bin)
+
+            install_rule_context[package] = BinaryPackageInstallRuleContext(
+                dctrl_bin,
+                FSRootDir(),
+                doc_main_package,
+            )
+
+        if enable_manifest_installation_feature:
+            discard_rules = list(
+                self.plugin_provided_feature_set.auto_discard_rules.values()
+            )
+        else:
+            discard_rules = [
+                self.plugin_provided_feature_set.auto_discard_rules["debian-dir"]
+            ]
+        path_matcher = SourcePathMatcher(discard_rules)
+
+        source_condition_context = ConditionContext(
+            binary_package=None,
+            substitution=self.substitution,
+            build_env=self._build_env,
+            dpkg_architecture_variables=self._dpkg_architecture_variables,
+            dpkg_arch_query_table=self._dpkg_arch_query_table,
+        )
+
+        for dctrl_bin in self.active_packages:
+            package = dctrl_bin.name
+            if install_request_context:
+                build_system_staging_dir = install_request_context.debian_pkg_dirs.get(
+                    package
+                )
+            else:
+                build_system_staging_dir_fs_path = os.path.join("debian", package)
+                if os.path.isdir(build_system_staging_dir_fs_path):
+                    build_system_staging_dir = FSROOverlay.create_root_dir(
+                        ".",
+                        build_system_staging_dir_fs_path,
+                    )
+                else:
+                    build_system_staging_dir = None
+
+            if build_system_staging_dir is not None:
+                _install_everything_from_source_dir_if_present(
+                    dctrl_bin,
+                    self.substitution,
+                    path_matcher,
+                    install_rule_context,
+                    source_condition_context,
+                    build_system_staging_dir,
+                )
+
+        if self._install_rules:
+            # FIXME: Check that every install rule remains used after transformations have run.
+            # What we want to check is transformations do not exclude everything from an install
+            # rule. The hard part here is that renaming (etc.) is fine, so we cannot 1:1 string
+            # match.
+            for install_rule in self._install_rules:
+                install_rule.perform_install(
+                    path_matcher,
+                    install_rule_context,
+                    source_condition_context,
+                )
+
+        if enable_manifest_installation_feature:
+            for search_dir in check_for_uninstalled_dirs:
+                _detect_missing_installations(path_matcher, search_dir)
+
+        for dctrl_bin in self.all_packages:
+            package = dctrl_bin.name
+            binary_install_rule_context = install_rule_context[package]
+            build_system_pkg_staging_dir = os.path.join("debian", package)
+            fs_root = binary_install_rule_context.fs_root
+
+            context = self.package_transformations[package]
+            if dctrl_bin.should_be_acted_on and enable_manifest_installation_feature:
+                for special_install_rule in context.install_rules:
+                    special_install_rule.perform_install(
+                        path_matcher,
+                        install_rule_context,
+                        source_condition_context,
+                    )
+
+            if dctrl_bin.should_be_acted_on:
+                self.apply_fs_transformations(package, fs_root)
+                substvars_file = f"debian/{package}.substvars"
+                substvars = FlushableSubstvars.load_from_path(
+                    substvars_file, missing_ok=True
+                )
+                # We do not want to touch the substvars file (non-clean rebuild contamination)
+                substvars.substvars_path = None
+                control_output_dir = generated_content_dir(
+                    package=dctrl_bin, subdir_key="DEBIAN"
+                )
+            else:
+                substvars = FlushableSubstvars()
+                control_output_dir = None
+
+            udeb_package = self._binary_packages.get(f"{package}-udeb")
+            if udeb_package and not udeb_package.is_udeb:
+                udeb_package = None
+
+            package_metadata_context = PackageProcessingContextProvider(
+                self,
+                dctrl_bin,
+                udeb_package,
+                package_data_table,
+                # FIXME: source_package
+            )
+
+            ctrl_creator = BinaryCtrlAccessorProviderCreator(
+                package_metadata_context,
+                substvars,
+                context.maintscript_snippets,
+                context.substitution,
+            )
+
+            if not enable_manifest_installation_feature:
+                assert_no_dbgsym_migration(dctrl_bin)
+                dh_dbgsym_root_fs = FSROOverlay.create_root_dir(
+                    "", dhe_dbgsym_root_dir(dctrl_bin)
+                )
+                dbgsym_root_fs = FSRootDir()
+                _install_everything_from_source_dir_if_present(
+                    dctrl_bin,
+                    self.substitution,
+                    path_matcher,
+                    install_rule_context,
+                    source_condition_context,
+                    dh_dbgsym_root_fs,
+                    into_dir=dbgsym_root_fs,
+                )
+                dbgsym_build_ids = read_dbgsym_file(dctrl_bin)
+                dbgsym_info = DbgsymInfo(
+                    dbgsym_root_fs,
+                    dbgsym_build_ids,
+                )
+            else:
+                dbgsym_info = DbgsymInfo(
+                    FSRootDir(),
+                    [],
+                )
+
+            package_data_dict[package] = BinaryPackageData(
+                self._source_package,
+                dctrl_bin,
+                build_system_pkg_staging_dir,
+                control_output_dir,
+                fs_root,
+                substvars,
+                package_metadata_context,
+                ctrl_creator,
+                dbgsym_info,
+            )
+
+        _list_automatic_discard_rules(path_matcher)
+
+        return package_data_table
+
+    def condition_context(
+        self, binary_package: Optional[Union[BinaryPackage, str]]
+    ) -> ConditionContext:
+        if binary_package is None:
+            return ConditionContext(
+                binary_package=None,
+                substitution=self.substitution,
+                build_env=self._build_env,
+                dpkg_architecture_variables=self._dpkg_architecture_variables,
+                dpkg_arch_query_table=self._dpkg_arch_query_table,
+            )
+        if not isinstance(binary_package, str):
+            binary_package = binary_package.name
+
+        package_transformation = self.package_transformations[binary_package]
+        return ConditionContext(
+            binary_package=package_transformation.binary_package,
+            substitution=package_transformation.substitution,
+            build_env=self._build_env,
+            dpkg_architecture_variables=self._dpkg_architecture_variables,
+            dpkg_arch_query_table=self._dpkg_arch_query_table,
+        )
+
+    def apply_fs_transformations(
+        self,
+        package: str,
+        fs_root: FSPath,
+    ) -> None:
+        if package in self._used_for:
+            raise ValueError(
+                f"data.tar contents for {package} has already been finalized!?"
+            )
+        if package not in self.package_transformations:
+            raise ValueError(
+                f'The package "{package}" was not relevant for the manifest!?'
+            )
+        package_transformation = self.package_transformations[package]
+        condition_context = ConditionContext(
+            binary_package=package_transformation.binary_package,
+            substitution=package_transformation.substitution,
+            build_env=self._build_env,
+            dpkg_architecture_variables=self._dpkg_architecture_variables,
+            dpkg_arch_query_table=self._dpkg_arch_query_table,
+        )
+        norm_rules = list(
+            builtin_mode_normalization_rules(
+                self._dpkg_architecture_variables,
+                package_transformation.binary_package,
+                package_transformation.substitution,
+            )
+        )
+        norm_mode_transformation_rule = ModeNormalizationTransformationRule(norm_rules)
+        norm_mode_transformation_rule.transform_file_system(fs_root, condition_context)
+        for transformation in package_transformation.transformations:
+            transformation.transform_file_system(fs_root, condition_context)
+        interpreter_normalization = NormalizeShebangLineTransformation()
+        interpreter_normalization.transform_file_system(fs_root, condition_context)
+
+    def finalize_data_tar_contents(
+        self,
+        package: str,
+        fs_root: FSPath,
+        clamp_mtime_to: int,
+    ) -> IntermediateManifest:
+        if package in self._used_for:
+            raise ValueError(
+                f"data.tar contents for {package} has already been finalized!?"
+            )
+        if package not in self.package_transformations:
+            raise ValueError(
+                f'The package "{package}" was not relevant for the manifest!?'
+            )
+        self._used_for.add(package)
+
+        # At this point, there so be no further mutations to the file system (because the will not
+        # be present in the intermediate manifest)
+        cast("FSRootDir", fs_root).is_read_write = False
+
+        intermediate_manifest = list(
+            _generate_intermediate_manifest(
+                fs_root,
+                clamp_mtime_to,
+            )
+        )
+        return intermediate_manifest
+
+    def apply_to_binary_staging_directory(
+        self,
+        package: str,
+        fs_root: FSPath,
+        clamp_mtime_to: int,
+    ) -> IntermediateManifest:
+        self.apply_fs_transformations(package, fs_root)
+        return self.finalize_data_tar_contents(package, fs_root, clamp_mtime_to)
+
+
+@dataclasses.dataclass(slots=True)
+class SearchDirOrderState:
+    search_dir: VirtualPath
+    applies_to: Union[Set[BinaryPackage], FrozenSet[BinaryPackage]] = dataclasses.field(
+        default_factory=set
+    )
+    after: Set[str] = dataclasses.field(default_factory=set)
+
+
+def _present_installation_dirs(
+    search_dirs: Sequence[SearchDir],
+    checked_missing_dirs: Sequence[VirtualPath],
+    all_pkgs: FrozenSet[BinaryPackage],
+) -> None:
+    _info("The following directories are considered search dirs (in order):")
+    max_len = max((len(s.search_dir.fs_path) for s in search_dirs), default=1)
+    for search_dir in search_dirs:
+        applies_to = ""
+        if search_dir.applies_to < all_pkgs:
+            names = ", ".join(p.name for p in search_dir.applies_to)
+            applies_to = f"  [only applicable to: {names}]"
+        remark = ""
+        if not os.path.isdir(search_dir.search_dir.fs_path):
+            remark = "  (skipped; absent)"
+        _info(f" * {search_dir.search_dir.fs_path:{max_len}}{applies_to}{remark}")
+
+    if checked_missing_dirs:
+        _info('The following directories are considered for "not-installed" paths;')
+        for d in checked_missing_dirs:
+            remark = ""
+            if not os.path.isdir(d.fs_path):
+                remark = " (skipped; absent)"
+            _info(f" * {d.fs_path:{max_len}}{remark}")
+
+
+def _determine_search_dir_order(
+    requested: Mapping[BinaryPackage, List[VirtualPath]],
+    all_pkgs: FrozenSet[BinaryPackage],
+    default_search_dirs: List[VirtualPath],
+    source_root: VirtualPath,
+) -> Sequence[SearchDir]:
+    search_dir_table = {}
+    assert requested.keys() <= all_pkgs
+    for pkg in all_pkgs:
+        paths = requested.get(pkg, default_search_dirs)
+        previous_search_dir: Optional[SearchDirOrderState] = None
+        for path in paths:
+            try:
+                search_dir_state = search_dir_table[path.fs_path]
+            except KeyError:
+                search_dir_state = SearchDirOrderState(path)
+                search_dir_table[path.fs_path] = search_dir_state
+            search_dir_state.applies_to.add(pkg)
+            if previous_search_dir is not None:
+                search_dir_state.after.add(previous_search_dir.search_dir.fs_path)
+            previous_search_dir = search_dir_state
+
+    search_dirs_in_order = []
+    released = set()
+    remaining = set()
+    for search_dir_state in search_dir_table.values():
+        if not (search_dir_state.after <= released):
+            remaining.add(search_dir_state.search_dir.fs_path)
+            continue
+        search_dirs_in_order.append(search_dir_state)
+        released.add(search_dir_state.search_dir.fs_path)
+
+    while remaining:
+        current_released = len(released)
+        for fs_path in remaining:
+            search_dir_state = search_dir_table[fs_path]
+            if not search_dir_state.after.issubset(released):
+                remaining.add(search_dir_state.search_dir.fs_path)
+                continue
+            search_dirs_in_order.append(search_dir_state)
+            released.add(search_dir_state.search_dir.fs_path)
+
+        if current_released == len(released):
+            names = ", ".join(remaining)
+            _error(
+                f"There is a circular dependency (somewhere) between the search dirs: {names}."
+                " Note that the search directories across all packages have to be ordered (and the"
+                " source root should generally be last)"
+            )
+        remaining -= released
+
+    search_dirs_in_order.append(
+        SearchDirOrderState(
+            source_root,
+            all_pkgs,
+        )
+    )
+
+    return tuple(
+        # Avoid duplicating all_pkgs
+        SearchDir(
+            s.search_dir,
+            frozenset(s.applies_to) if s.applies_to != all_pkgs else all_pkgs,
+        )
+        for s in search_dirs_in_order
+    )
diff --git a/src/debputy/highlevel_manifest_parser.py b/src/debputy/highlevel_manifest_parser.py
new file mode 100644
index 0000000..6181603
--- /dev/null
+++ b/src/debputy/highlevel_manifest_parser.py
@@ -0,0 +1,546 @@
+import collections
+import contextlib
+from typing import (
+    Optional,
+    Dict,
+    Callable,
+    List,
+    Any,
+    Union,
+    Mapping,
+    IO,
+    Iterator,
+    cast,
+    Tuple,
+)
+
+from debian.debian_support import DpkgArchTable
+from ruamel.yaml import YAMLError
+
+from debputy.highlevel_manifest import (
+    HighLevelManifest,
+    PackageTransformationDefinition,
+    MutableYAMLManifest,
+    MANIFEST_YAML,
+)
+from debputy.maintscript_snippet import (
+    MaintscriptSnippet,
+    STD_CONTROL_SCRIPTS,
+    MaintscriptSnippetContainer,
+)
+from debputy.packages import BinaryPackage, SourcePackage
+from debputy.path_matcher import (
+    MatchRuleType,
+    ExactFileSystemPath,
+    MatchRule,
+)
+from debputy.substitution import Substitution
+from debputy.util import (
+    _normalize_path,
+    escape_shell,
+    assume_not_none,
+)
+from debputy.util import _warn, _info
+from ._deb_options_profiles import DebBuildOptionsAndProfiles
+from .architecture_support import DpkgArchitectureBuildProcessValuesTable
+from .filesystem_scan import FSROOverlay
+from .installations import InstallRule, PPFInstallRule
+from .manifest_parser.exceptions import ManifestParseException
+from .manifest_parser.parser_data import ParserContextData
+from .manifest_parser.util import AttributePath
+from .packager_provided_files import detect_all_packager_provided_files
+from .plugin.api import VirtualPath
+from .plugin.api.impl_types import (
+    TP,
+    TTP,
+    DispatchingTableParser,
+    OPARSER_PACKAGES,
+    OPARSER_MANIFEST_ROOT,
+)
+from .plugin.api.feature_set import PluginProvidedFeatureSet
+
+try:
+    from Levenshtein import distance
+except ImportError:
+
+    def _detect_possible_typo(
+        _d,
+        _key,
+        _attribute_parent_path: AttributePath,
+        required: bool,
+    ) -> None:
+        if required:
+            _info(
+                "Install python3-levenshtein to have debputy try to detect typos in the manifest."
+            )
+
+else:
+
+    def _detect_possible_typo(
+        d,
+        key,
+        _attribute_parent_path: AttributePath,
+        _required: bool,
+    ) -> None:
+        k_len = len(key)
+        for actual_key in d:
+            if abs(k_len - len(actual_key)) > 2:
+                continue
+            d = distance(key, actual_key)
+            if d > 2:
+                continue
+            path = _attribute_parent_path.path
+            ref = f'at "{path}"' if path else "at the manifest root level"
+            _warn(
+                f'Possible typo: The key "{actual_key}" should probably have been "{key}" {ref}'
+            )
+
+
+def _per_package_subst_variables(
+    p: BinaryPackage,
+    *,
+    name: Optional[str] = None,
+) -> Dict[str, str]:
+    return {
+        "PACKAGE": name if name is not None else p.name,
+    }
+
+
+class HighLevelManifestParser(ParserContextData):
+    def __init__(
+        self,
+        manifest_path: str,
+        source_package: SourcePackage,
+        binary_packages: Mapping[str, BinaryPackage],
+        substitution: Substitution,
+        dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+        dpkg_arch_query_table: DpkgArchTable,
+        build_env: DebBuildOptionsAndProfiles,
+        plugin_provided_feature_set: PluginProvidedFeatureSet,
+        *,
+        # Available for testing purposes only
+        debian_dir: Union[str, VirtualPath] = "./debian",
+    ):
+        self.manifest_path = manifest_path
+        self._source_package = source_package
+        self._binary_packages = binary_packages
+        self._mutable_yaml_manifest: Optional[MutableYAMLManifest] = None
+        # In source context, some variables are known to be unresolvable. Record this, so
+        # we can give better error messages.
+        self._substitution = substitution
+        self._dpkg_architecture_variables = dpkg_architecture_variables
+        self._dpkg_arch_query_table = dpkg_arch_query_table
+        self._build_env = build_env
+        self._package_state_stack: List[PackageTransformationDefinition] = []
+        self._plugin_provided_feature_set = plugin_provided_feature_set
+        self._declared_variables = {}
+
+        if isinstance(debian_dir, str):
+            debian_dir = FSROOverlay.create_root_dir("debian", debian_dir)
+
+        self._debian_dir = debian_dir
+
+        # Delayed initialized; we rely on this delay to parse the variables.
+        self._all_package_states = None
+
+        self._install_rules: Optional[List[InstallRule]] = None
+        self._ownership_caches_loaded = False
+        self._used = False
+
+    def _ensure_package_states_is_initialized(self) -> None:
+        if self._all_package_states is not None:
+            return
+        substitution = self._substitution
+        binary_packages = self._binary_packages
+        assert self._all_package_states is None
+
+        self._all_package_states = {
+            n: PackageTransformationDefinition(
+                binary_package=p,
+                substitution=substitution.with_extra_substitutions(
+                    **_per_package_subst_variables(p)
+                ),
+                is_auto_generated_package=False,
+                maintscript_snippets=collections.defaultdict(
+                    MaintscriptSnippetContainer
+                ),
+            )
+            for n, p in binary_packages.items()
+        }
+        for n, p in binary_packages.items():
+            dbgsym_name = f"{n}-dbgsym"
+            if dbgsym_name in self._all_package_states:
+                continue
+            self._all_package_states[dbgsym_name] = PackageTransformationDefinition(
+                binary_package=p,
+                substitution=substitution.with_extra_substitutions(
+                    **_per_package_subst_variables(p, name=dbgsym_name)
+                ),
+                is_auto_generated_package=True,
+                maintscript_snippets=collections.defaultdict(
+                    MaintscriptSnippetContainer
+                ),
+            )
+
+    @property
+    def binary_packages(self) -> Mapping[str, BinaryPackage]:
+        return self._binary_packages
+
+    @property
+    def _package_states(self) -> Mapping[str, PackageTransformationDefinition]:
+        assert self._all_package_states is not None
+        return self._all_package_states
+
+    @property
+    def dpkg_architecture_variables(self) -> DpkgArchitectureBuildProcessValuesTable:
+        return self._dpkg_architecture_variables
+
+    @property
+    def dpkg_arch_query_table(self) -> DpkgArchTable:
+        return self._dpkg_arch_query_table
+
+    @property
+    def build_env(self) -> DebBuildOptionsAndProfiles:
+        return self._build_env
+
+    def build_manifest(self) -> HighLevelManifest:
+        if self._used:
+            raise TypeError("build_manifest can only be called once!")
+        self._used = True
+        self._ensure_package_states_is_initialized()
+        for var, attribute_path in self._declared_variables.items():
+            if not self.substitution.is_used(var):
+                raise ManifestParseException(
+                    f'The variable "{var}" is unused. Either use it or remove it.'
+                    f" The variable was declared at {attribute_path.path}."
+                )
+        if isinstance(self, YAMLManifestParser) and self._mutable_yaml_manifest is None:
+            self._mutable_yaml_manifest = MutableYAMLManifest.empty_manifest()
+        all_packager_provided_files = detect_all_packager_provided_files(
+            self._plugin_provided_feature_set.packager_provided_files,
+            self._debian_dir,
+            self.binary_packages,
+        )
+
+        for package in self._package_states:
+            with self.binary_package_context(package) as context:
+                if not context.is_auto_generated_package:
+                    ppf_result = all_packager_provided_files[package]
+                    if ppf_result.auto_installable:
+                        context.install_rules.append(
+                            PPFInstallRule(
+                                context.binary_package,
+                                context.substitution,
+                                ppf_result.auto_installable,
+                            )
+                        )
+                    context.reserved_packager_provided_files.update(
+                        ppf_result.reserved_only
+                    )
+                self._transform_dpkg_maintscript_helpers_to_snippets()
+
+        return HighLevelManifest(
+            self.manifest_path,
+            self._mutable_yaml_manifest,
+            self._install_rules,
+            self._source_package,
+            self.binary_packages,
+            self.substitution,
+            self._package_states,
+            self._dpkg_architecture_variables,
+            self._dpkg_arch_query_table,
+            self._build_env,
+            self._plugin_provided_feature_set,
+            self._debian_dir,
+        )
+
+    @contextlib.contextmanager
+    def binary_package_context(
+        self, package_name: str
+    ) -> Iterator[PackageTransformationDefinition]:
+        if package_name not in self._package_states:
+            self._error(
+                f'The package "{package_name}" is not present in the debian/control file (could not find'
+                f' "Package: {package_name}" in a binary stanza) nor is it a -dbgsym package for one'
+                " for a package in debian/control."
+            )
+        package_state = self._package_states[package_name]
+        self._package_state_stack.append(package_state)
+        ps_len = len(self._package_state_stack)
+        yield package_state
+        if ps_len != len(self._package_state_stack):
+            raise RuntimeError("Internal error: Unbalanced stack manipulation detected")
+        self._package_state_stack.pop()
+
+    def dispatch_parser_table_for(self, rule_type: TTP) -> DispatchingTableParser[TP]:
+        t = self._plugin_provided_feature_set.dispatchable_table_parsers.get(rule_type)
+        if t is None:
+            raise AssertionError(
+                f"Internal error: No dispatching parser for {rule_type.__name__}"
+            )
+        return t
+
+    @property
+    def substitution(self) -> Substitution:
+        if self._package_state_stack:
+            return self._package_state_stack[-1].substitution
+        return self._substitution
+
+    def add_extra_substitution_variables(
+        self,
+        **extra_substitutions: Tuple[str, AttributePath],
+    ) -> Substitution:
+        if self._package_state_stack or self._all_package_states is not None:
+            # For one, it would not "bubble up" correctly when added to the lowest stack.
+            # And if it is not added to the lowest stack, then you get errors about it being
+            # unknown as soon as you leave the stack (which is weird for the user when
+            # the variable is something known, sometimes not)
+            raise RuntimeError("Cannot use add_extra_substitution from this state")
+        for key, (_, path) in extra_substitutions.items():
+            self._declared_variables[key] = path
+        self._substitution = self._substitution.with_extra_substitutions(
+            **{k: v[0] for k, v in extra_substitutions.items()}
+        )
+        return self._substitution
+
+    @property
+    def current_binary_package_state(self) -> PackageTransformationDefinition:
+        if not self._package_state_stack:
+            raise RuntimeError("Invalid state: Not in a binary package context")
+        return self._package_state_stack[-1]
+
+    @property
+    def is_in_binary_package_state(self) -> bool:
+        return bool(self._package_state_stack)
+
+    def _transform_dpkg_maintscript_helpers_to_snippets(self) -> None:
+        package_state = self.current_binary_package_state
+        for dmh in package_state.dpkg_maintscript_helper_snippets:
+            snippet = MaintscriptSnippet(
+                definition_source=dmh.definition_source,
+                snippet=f'dpkg-maintscript-helper {escape_shell(*dmh.cmdline)} -- "$@"\n',
+            )
+            for script in STD_CONTROL_SCRIPTS:
+                package_state.maintscript_snippets[script].append(snippet)
+
+    def normalize_path(
+        self,
+        path: str,
+        definition_source: AttributePath,
+        *,
+        allow_root_dir_match: bool = False,
+    ) -> ExactFileSystemPath:
+        try:
+            normalized = _normalize_path(path)
+        except ValueError:
+            self._error(
+                f'The path "{path}" provided in {definition_source.path} should be relative to the root of the'
+                ' package and not use any ".." or "." segments.'
+            )
+        if normalized == "." and not allow_root_dir_match:
+            self._error(
+                "Manifests must not change the root directory of the deb file.  Please correct"
+                f' "{definition_source.path}" (path: "{path}) in {self.manifest_path}'
+            )
+        return ExactFileSystemPath(
+            self.substitution.substitute(normalized, definition_source.path)
+        )
+
+    def parse_path_or_glob(
+        self,
+        path_or_glob: str,
+        definition_source: AttributePath,
+    ) -> MatchRule:
+        match_rule = MatchRule.from_path_or_glob(
+            path_or_glob, definition_source.path, substitution=self.substitution
+        )
+        # NB: "." and "/" will be translated to MATCH_ANYTHING by MatchRule.from_path_or_glob,
+        # so there is no need to check for an exact match on "." like in normalize_path.
+        if match_rule.rule_type == MatchRuleType.MATCH_ANYTHING:
+            self._error(
+                f'The chosen match rule "{path_or_glob}" matches everything (including the deb root directory).'
+                f' Please correct "{definition_source.path}" (path: "{path_or_glob}) in {self.manifest_path} to'
+                f' something that matches "less" than everything.'
+            )
+        return match_rule
+
+    def parse_manifest(self) -> HighLevelManifest:
+        raise NotImplementedError
+
+
+class YAMLManifestParser(HighLevelManifestParser):
+    def _optional_key(
+        self,
+        d: Mapping[str, Any],
+        key: str,
+        attribute_parent_path: AttributePath,
+        expected_type=None,
+        default_value=None,
+    ):
+        v = d.get(key)
+        if v is None:
+            _detect_possible_typo(d, key, attribute_parent_path, False)
+            return default_value
+        if expected_type is not None:
+            return self._ensure_value_is_type(
+                v, expected_type, key, attribute_parent_path
+            )
+        return v
+
+    def _required_key(
+        self,
+        d: Mapping[str, Any],
+        key: str,
+        attribute_parent_path: AttributePath,
+        expected_type=None,
+        extra: Optional[Union[str, Callable[[], str]]] = None,
+    ):
+        v = d.get(key)
+        if v is None:
+            _detect_possible_typo(d, key, attribute_parent_path, True)
+            if extra is not None:
+                msg = extra if isinstance(extra, str) else extra()
+                extra_info = " " + msg
+            else:
+                extra_info = ""
+            self._error(
+                f'Missing required key {key} at {attribute_parent_path.path} in manifest "{self.manifest_path}.'
+                f"{extra_info}"
+            )
+
+        if expected_type is not None:
+            return self._ensure_value_is_type(
+                v, expected_type, key, attribute_parent_path
+            )
+        return v
+
+    def _ensure_value_is_type(
+        self,
+        v,
+        t,
+        key: Union[str, int, AttributePath],
+        attribute_parent_path: Optional[AttributePath],
+    ):
+        if v is None:
+            return None
+        if not isinstance(v, t):
+            if isinstance(t, tuple):
+                t_msg = "one of: " + ", ".join(x.__name__ for x in t)
+            else:
+                t_msg = f"a {t.__name__}"
+            key_path = (
+                key.path
+                if isinstance(key, AttributePath)
+                else assume_not_none(attribute_parent_path)[key].path
+            )
+            self._error(
+                f'The key {key_path} must be {t_msg} in manifest "{self.manifest_path}"'
+            )
+        return v
+
+    def from_yaml_dict(self, yaml_data: object) -> "HighLevelManifest":
+        attribute_path = AttributePath.root_path()
+        manifest_root_parser = (
+            self._plugin_provided_feature_set.dispatchable_object_parsers[
+                OPARSER_MANIFEST_ROOT
+            ]
+        )
+        parsed_data = cast(
+            "ManifestRootRule",
+            manifest_root_parser.parse(
+                yaml_data,
+                attribute_path,
+                parser_context=self,
+            ),
+        )
+
+        packages_dict = parsed_data.get("packages", {})
+        install_rules = parsed_data.get("installations")
+        if install_rules:
+            self._install_rules = install_rules
+        packages_parent_path = attribute_path["packages"]
+        for package_name_raw, v in packages_dict.items():
+            definition_source = packages_parent_path[package_name_raw]
+            package_name = package_name_raw
+            if "{{" in package_name:
+                package_name = self.substitution.substitute(
+                    package_name_raw,
+                    definition_source.path,
+                )
+
+            with self.binary_package_context(package_name) as package_state:
+                if package_state.is_auto_generated_package:
+                    # Maybe lift (part) of this restriction.
+                    self._error(
+                        f'Cannot define rules for package "{package_name}" (at {definition_source.path}). It is an'
+                        " auto-generated package."
+                    )
+                package_rule_parser = (
+                    self._plugin_provided_feature_set.dispatchable_object_parsers[
+                        OPARSER_PACKAGES
+                    ]
+                )
+                parsed = cast(
+                    "BinaryPackageRule",
+                    package_rule_parser.parse(
+                        v, definition_source, parser_context=self
+                    ),
+                )
+                binary_version = parsed.get("binary-version")
+                if binary_version is not None:
+                    package_state.binary_version = (
+                        package_state.substitution.substitute(
+                            binary_version,
+                            definition_source["binary-version"].path,
+                        )
+                    )
+                search_dirs = parsed.get("installation_search_dirs")
+                if search_dirs is not None:
+                    package_state.search_dirs = search_dirs
+                transformations = parsed.get("transformations")
+                conffile_management = parsed.get("conffile_management")
+                if transformations:
+                    package_state.transformations.extend(transformations)
+                if conffile_management:
+                    package_state.dpkg_maintscript_helper_snippets.extend(
+                        conffile_management
+                    )
+        return self.build_manifest()
+
+    def _parse_manifest(self, fd: Union[IO[bytes], str]) -> HighLevelManifest:
+        try:
+            data = MANIFEST_YAML.load(fd)
+        except YAMLError as e:
+            msg = str(e)
+            lines = msg.splitlines(keepends=True)
+            i = -1
+            for i, line in enumerate(lines):
+                # Avoid an irrelevant "how do configure the YAML parser" message, which the
+                # user cannot use.
+                if line.startswith("To suppress this check"):
+                    break
+            if i > -1 and len(lines) > i + 1:
+                lines = lines[:i]
+                msg = "".join(lines)
+            msg = msg.rstrip()
+            msg += (
+                f"\n\nYou can use `yamllint -d relaxed {escape_shell(self.manifest_path)}` to validate"
+                " the YAML syntax. The yamllint tool also supports style rules for YAML documents"
+                " (such as indentation rules) in case that is of interest."
+            )
+            raise ManifestParseException(
+                f"Could not parse {self.manifest_path} as a YAML document: {msg}"
+            ) from e
+        self._mutable_yaml_manifest = MutableYAMLManifest(data)
+        return self.from_yaml_dict(data)
+
+    def parse_manifest(
+        self,
+        *,
+        fd: Optional[Union[IO[bytes], str]] = None,
+    ) -> HighLevelManifest:
+        if fd is None:
+            with open(self.manifest_path, "rb") as fd:
+                return self._parse_manifest(fd)
+        else:
+            return self._parse_manifest(fd)
diff --git a/src/debputy/installations.py b/src/debputy/installations.py
new file mode 100644
index 0000000..2310cfa
--- /dev/null
+++ b/src/debputy/installations.py
@@ -0,0 +1,1162 @@
+import collections
+import dataclasses
+import os.path
+import re
+from enum import IntEnum
+from typing import (
+    List,
+    Dict,
+    FrozenSet,
+    Callable,
+    Union,
+    Iterator,
+    Tuple,
+    Set,
+    Sequence,
+    Optional,
+    Iterable,
+    TYPE_CHECKING,
+    cast,
+    Any,
+    Mapping,
+)
+
+from debputy.exceptions import DebputyRuntimeError
+from debputy.filesystem_scan import FSPath
+from debputy.manifest_conditions import (
+    ConditionContext,
+    ManifestCondition,
+    _BUILD_DOCS_BDO,
+)
+from debputy.manifest_parser.base_types import (
+    FileSystemMatchRule,
+    FileSystemExactMatchRule,
+    DebputyDispatchableType,
+)
+from debputy.packages import BinaryPackage
+from debputy.path_matcher import MatchRule, ExactFileSystemPath, MATCH_ANYTHING
+from debputy.substitution import Substitution
+from debputy.util import _error, _warn
+
+if TYPE_CHECKING:
+    from debputy.packager_provided_files import PackagerProvidedFile
+    from debputy.plugin.api import VirtualPath
+    from debputy.plugin.api.impl_types import PluginProvidedDiscardRule
+
+
+_MAN_TH_LINE = re.compile(r'^[.]TH\s+\S+\s+"?(\d+[^"\s]*)"?')
+_MAN_DT_LINE = re.compile(r"^[.]Dt\s+\S+\s+(\d+\S*)")
+_MAN_SECTION_BASENAME = re.compile(r"[.]([1-9]\w*)(?:[.]gz)?$")
+_MAN_REAL_SECTION = re.compile(r"^(\d+)")
+_MAN_INST_BASENAME = re.compile(r"[.][^.]+$")
+MAN_GUESS_LANG_FROM_PATH = re.compile(
+    r"(?:^|/)man/(?:([a-z][a-z](?:_[A-Z][A-Z])?)(?:\.[^/]+)?)?/man[1-9]/"
+)
+MAN_GUESS_FROM_BASENAME = re.compile(r"[.]([a-z][a-z](?:_[A-Z][A-Z])?)[.](?:[1-9]|man)")
+
+
+class InstallRuleError(DebputyRuntimeError):
+    pass
+
+
+class PathAlreadyInstalledOrDiscardedError(InstallRuleError):
+    @property
+    def path(self) -> str:
+        return cast("str", self.args[0])
+
+    @property
+    def into(self) -> FrozenSet[BinaryPackage]:
+        return cast("FrozenSet[BinaryPackage]", self.args[1])
+
+    @property
+    def definition_source(self) -> str:
+        return cast("str", self.args[2])
+
+
+class ExactPathMatchTwiceError(InstallRuleError):
+    @property
+    def path(self) -> str:
+        return cast("str", self.args[1])
+
+    @property
+    def into(self) -> BinaryPackage:
+        return cast("BinaryPackage", self.args[2])
+
+    @property
+    def definition_source(self) -> str:
+        return cast("str", self.args[3])
+
+
+class NoMatchForInstallPatternError(InstallRuleError):
+    @property
+    def pattern(self) -> str:
+        return cast("str", self.args[1])
+
+    @property
+    def search_dirs(self) -> Sequence["SearchDir"]:
+        return cast("Sequence[SearchDir]", self.args[2])
+
+    @property
+    def definition_source(self) -> str:
+        return cast("str", self.args[3])
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class SearchDir:
+    search_dir: "VirtualPath"
+    applies_to: FrozenSet[BinaryPackage]
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class BinaryPackageInstallRuleContext:
+    binary_package: BinaryPackage
+    fs_root: FSPath
+    doc_main_package: BinaryPackage
+
+    def replace(self, **changes: Any) -> "BinaryPackageInstallRuleContext":
+        return dataclasses.replace(self, **changes)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class InstallSearchDirContext:
+    search_dirs: Sequence[SearchDir]
+    check_for_uninstalled_dirs: Sequence["VirtualPath"]
+    # TODO: Support search dirs per-package
+    debian_pkg_dirs: Mapping[str, "VirtualPath"] = dataclasses.field(
+        default_factory=dict
+    )
+
+
+@dataclasses.dataclass(slots=True)
+class InstallRuleContext:
+    # TODO: Search dirs should be per-package
+    search_dirs: Sequence[SearchDir]
+    binary_package_contexts: Dict[str, BinaryPackageInstallRuleContext] = (
+        dataclasses.field(default_factory=dict)
+    )
+
+    def __getitem__(self, item: str) -> BinaryPackageInstallRuleContext:
+        return self.binary_package_contexts[item]
+
+    def __setitem__(self, key: str, value: BinaryPackageInstallRuleContext) -> None:
+        self.binary_package_contexts[key] = value
+
+    def replace(self, **changes: Any) -> "InstallRuleContext":
+        return dataclasses.replace(self, **changes)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PathMatch:
+    path: "VirtualPath"
+    search_dir: "VirtualPath"
+    is_exact_match: bool
+    into: FrozenSet[BinaryPackage]
+
+
+class DiscardState(IntEnum):
+    UNCHECKED = 0
+    NOT_DISCARDED = 1
+    DISCARDED_BY_PLUGIN_PROVIDED_RULE = 2
+    DISCARDED_BY_MANIFEST_RULE = 3
+
+
+def _determine_manpage_section(
+    match_rule: PathMatch,
+    provided_section: Optional[int],
+    definition_source: str,
+) -> Optional[str]:
+    section = str(provided_section) if provided_section is not None else None
+    if section is None:
+        detected_section = None
+        with open(match_rule.path.fs_path, "r") as fd:
+            for line in fd:
+                if not line.startswith((".TH", ".Dt")):
+                    continue
+
+                m = _MAN_DT_LINE.match(line)
+                if not m:
+                    m = _MAN_TH_LINE.match(line)
+                    if not m:
+                        continue
+                detected_section = m.group(1)
+                if "." in detected_section:
+                    _warn(
+                        f"Ignoring detected section {detected_section} in {match_rule.path.fs_path}"
+                        f" (detected via {definition_source}): It looks too much like a version"
+                    )
+                    detected_section = None
+                break
+        if detected_section is None:
+            m = _MAN_SECTION_BASENAME.search(os.path.basename(match_rule.path.path))
+            if m:
+                detected_section = m.group(1)
+        section = detected_section
+
+    return section
+
+
+def _determine_manpage_real_section(
+    match_rule: PathMatch,
+    section: Optional[str],
+    definition_source: str,
+) -> int:
+    real_section = None
+    if section is not None:
+        m = _MAN_REAL_SECTION.match(section)
+        if m:
+            real_section = int(m.group(1))
+    if real_section is None or real_section < 0 or real_section > 9:
+        if real_section is not None:
+            _warn(
+                f"Computed section for {match_rule.path.fs_path} was {real_section} (section: {section}),"
+                f" which is not a valid section (must be between 1 and 9 incl.)"
+            )
+        _error(
+            f"Could not determine the section for {match_rule.path.fs_path} automatically.  The manpage"
+            f" was detected via {definition_source}. Consider using `section: <number>` to"
+            " explicitly declare the section. Keep in mind that it applies to all manpages for that"
+            " rule and you may have to split the rule into two for this reason."
+        )
+    return real_section
+
+
+def _determine_manpage_language(
+    match_rule: PathMatch,
+    provided_language: Optional[str],
+) -> Optional[str]:
+    if provided_language is not None:
+        if provided_language not in ("derive-from-basename", "derive-from-path"):
+            return provided_language if provided_language != "C" else None
+        if provided_language == "derive-from-basename":
+            m = MAN_GUESS_FROM_BASENAME.search(match_rule.path.name)
+            if m is None:
+                return None
+            return m.group(1)
+        # Fall-through for derive-from-path case
+    m = MAN_GUESS_LANG_FROM_PATH.search(match_rule.path.path)
+    if m is None:
+        return None
+    return m.group(1)
+
+
+def _dest_path_for_manpage(
+    provided_section: Optional[int],
+    provided_language: Optional[str],
+    definition_source: str,
+) -> Callable[["PathMatch"], str]:
+    def _manpage_dest_path(match_rule: PathMatch) -> str:
+        inst_basename = _MAN_INST_BASENAME.sub("", match_rule.path.name)
+        section = _determine_manpage_section(
+            match_rule, provided_section, definition_source
+        )
+        real_section = _determine_manpage_real_section(
+            match_rule, section, definition_source
+        )
+        assert section is not None
+        language = _determine_manpage_language(match_rule, provided_language)
+        if language is None:
+            maybe_language = ""
+        else:
+            maybe_language = f"{language}/"
+            lang_suffix = f".{language}"
+            if inst_basename.endswith(lang_suffix):
+                inst_basename = inst_basename[: -len(lang_suffix)]
+
+        return (
+            f"usr/share/man/{maybe_language}man{real_section}/{inst_basename}.{section}"
+        )
+
+    return _manpage_dest_path
+
+
+class SourcePathMatcher:
+    def __init__(self, auto_discard_rules: List["PluginProvidedDiscardRule"]) -> None:
+        self._already_matched: Dict[
+            str,
+            Tuple[FrozenSet[BinaryPackage], str],
+        ] = {}
+        self._exact_match_request: Set[Tuple[str, str]] = set()
+        self._discarded: Dict[str, DiscardState] = {}
+        self._auto_discard_rules = auto_discard_rules
+        self.used_auto_discard_rules: Dict[str, Set[str]] = collections.defaultdict(set)
+
+    def is_reserved(self, path: "VirtualPath") -> bool:
+        fs_path = path.fs_path
+        if fs_path in self._already_matched:
+            return True
+        result = self._discarded.get(fs_path, DiscardState.UNCHECKED)
+        if result == DiscardState.UNCHECKED:
+            result = self._check_plugin_provided_exclude_state_for(path)
+        if result == DiscardState.NOT_DISCARDED:
+            return False
+
+        return True
+
+    def exclude(self, path: str) -> None:
+        self._discarded[path] = DiscardState.DISCARDED_BY_MANIFEST_RULE
+
+    def _run_plugin_provided_discard_rules_on(self, path: "VirtualPath") -> bool:
+        for dr in self._auto_discard_rules:
+            verdict = dr.should_discard(path)
+            if verdict:
+                self.used_auto_discard_rules[dr.name].add(path.fs_path)
+                return True
+        return False
+
+    def _check_plugin_provided_exclude_state_for(
+        self,
+        path: "VirtualPath",
+    ) -> DiscardState:
+        cache_misses = []
+        current_path = path
+        while True:
+            fs_path = current_path.fs_path
+            exclude_state = self._discarded.get(fs_path, DiscardState.UNCHECKED)
+            if exclude_state != DiscardState.UNCHECKED:
+                verdict = exclude_state
+                break
+            cache_misses.append(fs_path)
+            if self._run_plugin_provided_discard_rules_on(current_path):
+                verdict = DiscardState.DISCARDED_BY_PLUGIN_PROVIDED_RULE
+                break
+            # We cannot trust a "NOT_DISCARDED" until we check its parent (the directory could
+            # be excluded without the files in it triggering the rule).
+            parent_dir = current_path.parent_dir
+            if not parent_dir:
+                verdict = DiscardState.NOT_DISCARDED
+                break
+            current_path = parent_dir
+        if cache_misses:
+            for p in cache_misses:
+                self._discarded[p] = verdict
+        return verdict
+
+    def may_match(
+        self,
+        match: PathMatch,
+        *,
+        is_exact_match: bool = False,
+    ) -> Tuple[FrozenSet[BinaryPackage], bool]:
+        m = self._already_matched.get(match.path.fs_path)
+        if m:
+            return m[0], False
+        current_path = match.path.fs_path
+        discard_state = self._discarded.get(current_path, DiscardState.UNCHECKED)
+
+        if discard_state == DiscardState.UNCHECKED:
+            discard_state = self._check_plugin_provided_exclude_state_for(match.path)
+
+        assert discard_state is not None and discard_state != DiscardState.UNCHECKED
+
+        is_discarded = discard_state != DiscardState.NOT_DISCARDED
+        if (
+            is_exact_match
+            and discard_state == DiscardState.DISCARDED_BY_PLUGIN_PROVIDED_RULE
+        ):
+            is_discarded = False
+        return frozenset(), is_discarded
+
+    def reserve(
+        self,
+        path: "VirtualPath",
+        reserved_by: FrozenSet[BinaryPackage],
+        definition_source: str,
+        *,
+        is_exact_match: bool = False,
+    ) -> None:
+        fs_path = path.fs_path
+        self._already_matched[fs_path] = reserved_by, definition_source
+        if not is_exact_match:
+            return
+        for pkg in reserved_by:
+            m_key = (pkg.name, fs_path)
+            self._exact_match_request.add(m_key)
+        try:
+            del self._discarded[fs_path]
+        except KeyError:
+            pass
+        for discarded_paths in self.used_auto_discard_rules.values():
+            discarded_paths.discard(fs_path)
+
+    def detect_missing(self, search_dir: "VirtualPath") -> Iterator["VirtualPath"]:
+        stack = list(search_dir.iterdir)
+        while stack:
+            m = stack.pop()
+            if m.is_dir:
+                s_len = len(stack)
+                stack.extend(m.iterdir)
+
+                if s_len == len(stack) and not self.is_reserved(m):
+                    # "Explicitly" empty dir
+                    yield m
+            elif not self.is_reserved(m):
+                yield m
+
+    def find_and_reserve_all_matches(
+        self,
+        match_rule: MatchRule,
+        search_dirs: Sequence[SearchDir],
+        dir_only_match: bool,
+        match_filter: Optional[Callable[["VirtualPath"], bool]],
+        reserved_by: FrozenSet[BinaryPackage],
+        definition_source: str,
+    ) -> Tuple[List[PathMatch], Tuple[int, ...]]:
+        matched = []
+        already_installed_paths = 0
+        already_excluded_paths = 0
+        glob_expand = False if isinstance(match_rule, ExactFileSystemPath) else True
+
+        for match in _resolve_path(
+            match_rule,
+            search_dirs,
+            dir_only_match,
+            match_filter,
+            reserved_by,
+        ):
+            installed_into, excluded = self.may_match(
+                match, is_exact_match=not glob_expand
+            )
+            if installed_into:
+                if glob_expand:
+                    already_installed_paths += 1
+                    continue
+                packages = ", ".join(p.name for p in installed_into)
+                raise PathAlreadyInstalledOrDiscardedError(
+                    f'The "{match.path.fs_path}" has been reserved by and installed into {packages}.'
+                    f" The definition that triggered this issue is {definition_source}.",
+                    match,
+                    installed_into,
+                    definition_source,
+                )
+            if excluded:
+                if glob_expand:
+                    already_excluded_paths += 1
+                    continue
+                raise PathAlreadyInstalledOrDiscardedError(
+                    f'The "{match.path.fs_path}" has been excluded. If you want this path installed, move it'
+                    f" above the exclusion rule that excluded it. The definition that triggered this"
+                    f" issue is {definition_source}.",
+                    match,
+                    installed_into,
+                    definition_source,
+                )
+            if not glob_expand:
+                for pkg in match.into:
+                    m_key = (pkg.name, match.path.fs_path)
+                    if m_key in self._exact_match_request:
+                        raise ExactPathMatchTwiceError(
+                            f'The path "{match.path.fs_path}" (via exact match) has already been installed'
+                            f" into {pkg.name}. The second installation triggered by {definition_source}",
+                            match.path,
+                            pkg,
+                            definition_source,
+                        )
+                    self._exact_match_request.add(m_key)
+
+            if reserved_by:
+                self._already_matched[match.path.fs_path] = (
+                    match.into,
+                    definition_source,
+                )
+            else:
+                self.exclude(match.path.fs_path)
+            matched.append(match)
+        exclude_counts = already_installed_paths, already_excluded_paths
+        return matched, exclude_counts
+
+
+def _resolve_path(
+    match_rule: MatchRule,
+    search_dirs: Iterable["SearchDir"],
+    dir_only_match: bool,
+    match_filter: Optional[Callable[["VirtualPath"], bool]],
+    into: FrozenSet[BinaryPackage],
+) -> Iterator[PathMatch]:
+    missing_matches = set(into)
+    for sdir in search_dirs:
+        matched = False
+        if into and missing_matches.isdisjoint(sdir.applies_to):
+            # All the packages, where this search dir applies, already got a match
+            continue
+        applicable = sdir.applies_to & missing_matches
+        for matched_path in match_rule.finditer(
+            sdir.search_dir,
+            ignore_paths=match_filter,
+        ):
+            if dir_only_match and not matched_path.is_dir:
+                continue
+            if matched_path.parent_dir is None:
+                if match_rule is MATCH_ANYTHING:
+                    continue
+                _error(
+                    f"The pattern {match_rule.describe_match_short()} matched the root dir."
+                )
+            yield PathMatch(matched_path, sdir.search_dir, False, applicable)
+            matched = True
+            # continue; we want to match everything we can from this search directory.
+
+        if matched:
+            missing_matches -= applicable
+            if into and not missing_matches:
+                # For install rules, we can stop as soon as all packages had a match
+                # For discard rules, all search directories must be visited.  Otherwise,
+                # you would have to repeat the discard rule once per search dir to be
+                # sure something is fully discarded
+                break
+
+
+def _resolve_dest_paths(
+    match: PathMatch,
+    dest_paths: Sequence[Tuple[str, bool]],
+    install_context: "InstallRuleContext",
+) -> Sequence[Tuple[str, "FSPath"]]:
+    dest_and_roots = []
+    for dest_path, dest_path_is_format in dest_paths:
+        if dest_path_is_format:
+            for pkg in match.into:
+                parent_dir = match.path.parent_dir
+                pkg_install_context = install_context[pkg.name]
+                fs_root = pkg_install_context.fs_root
+                dpath = dest_path.format(
+                    basename=match.path.name,
+                    dirname=parent_dir.path if parent_dir is not None else "",
+                    package_name=pkg.name,
+                    doc_main_package_name=pkg_install_context.doc_main_package.name,
+                )
+                if dpath.endswith("/"):
+                    raise ValueError(
+                        f'Provided destination (when resolved for {pkg.name}) for "{match.path.path}" ended'
+                        f' with "/" ("{dest_path}"), which it must not!'
+                    )
+                dest_and_roots.append((dpath, fs_root))
+        else:
+            if dest_path.endswith("/"):
+                raise ValueError(
+                    f'Provided destination for "{match.path.path}" ended with "/" ("{dest_path}"),'
+                    " which it must not!"
+                )
+            dest_and_roots.extend(
+                (dest_path, install_context[pkg.name].fs_root) for pkg in match.into
+            )
+    return dest_and_roots
+
+
+def _resolve_matches(
+    matches: List[PathMatch],
+    dest_paths: Union[Sequence[Tuple[str, bool]], Callable[[PathMatch], str]],
+    install_context: "InstallRuleContext",
+) -> Iterator[Tuple[PathMatch, Sequence[Tuple[str, "FSPath"]]]]:
+    if callable(dest_paths):
+        compute_dest_path = dest_paths
+        for match in matches:
+            dpath = compute_dest_path(match)
+            if dpath.endswith("/"):
+                raise ValueError(
+                    f'Provided destination for "{match.path.path}" ended with "/" ("{dpath}"), which it must not!'
+                )
+            dest_and_roots = [
+                (dpath, install_context[pkg.name].fs_root) for pkg in match.into
+            ]
+            yield match, dest_and_roots
+    else:
+        for match in matches:
+            dest_and_roots = _resolve_dest_paths(
+                match,
+                dest_paths,
+                install_context,
+            )
+            yield match, dest_and_roots
+
+
+class InstallRule(DebputyDispatchableType):
+    __slots__ = (
+        "_already_matched",
+        "_exact_match_request",
+        "_condition",
+        "_match_filter",
+        "_definition_source",
+    )
+
+    def __init__(
+        self,
+        condition: Optional[ManifestCondition],
+        definition_source: str,
+        *,
+        match_filter: Optional[Callable[["VirtualPath"], bool]] = None,
+    ) -> None:
+        self._condition = condition
+        self._definition_source = definition_source
+        self._match_filter = match_filter
+
+    def _check_single_match(
+        self, source: FileSystemMatchRule, matches: List[PathMatch]
+    ) -> None:
+        seen_pkgs = set()
+        problem_pkgs = frozenset()
+        for m in matches:
+            problem_pkgs = seen_pkgs & m.into
+            if problem_pkgs:
+                break
+            seen_pkgs.update(problem_pkgs)
+        if problem_pkgs:
+            pkg_names = ", ".join(sorted(p.name for p in problem_pkgs))
+            _error(
+                f'The pattern "{source.raw_match_rule}" matched multiple entries for the packages: {pkg_names}.'
+                "However, it should matched exactly one item. Please tighten the pattern defined"
+                f" in {self._definition_source}"
+            )
+
+    def _match_pattern(
+        self,
+        path_matcher: SourcePathMatcher,
+        fs_match_rule: FileSystemMatchRule,
+        condition_context: ConditionContext,
+        search_dirs: Sequence[SearchDir],
+        into: FrozenSet[BinaryPackage],
+    ) -> List[PathMatch]:
+        (matched, exclude_counts) = path_matcher.find_and_reserve_all_matches(
+            fs_match_rule.match_rule,
+            search_dirs,
+            fs_match_rule.raw_match_rule.endswith("/"),
+            self._match_filter,
+            into,
+            self._definition_source,
+        )
+
+        already_installed_paths, already_excluded_paths = exclude_counts
+
+        if into:
+            allow_empty_match = all(not p.should_be_acted_on for p in into)
+        else:
+            # discard rules must match provided at least one search dir exist.  If none of them
+            # exist, then we assume the discard rule is for a package that will not be built
+            allow_empty_match = any(s.search_dir.is_dir for s in search_dirs)
+        if self._condition is not None and not self._condition.evaluate(
+            condition_context
+        ):
+            allow_empty_match = True
+
+        if not matched and not allow_empty_match:
+            search_dir_text = ", ".join(x.search_dir.fs_path for x in search_dirs)
+            if already_excluded_paths and already_installed_paths:
+                total_paths = already_excluded_paths + already_installed_paths
+                msg = (
+                    f"There were no matches for {fs_match_rule.raw_match_rule} in {search_dir_text} after ignoring"
+                    f" {total_paths} path(s) already been matched previously either by install or"
+                    f" exclude rules. If you wanted to install some of these paths into multiple"
+                    f" packages, please tweak the definition that installed them to install them"
+                    f' into multiple packages (usually change "into: foo" to "into: [foo, bar]".'
+                    f" If you wanted to install these paths and exclude rules are getting in your"
+                    f" way, then please move this install rule before the exclusion rule that causes"
+                    f" issue or, in case of built-in excludes, list the paths explicitly (without"
+                    f" using patterns). Source for this issue is {self._definition_source}. Match rule:"
+                    f" {fs_match_rule.match_rule.describe_match_exact()}"
+                )
+            elif already_excluded_paths:
+                msg = (
+                    f"There were no matches for {fs_match_rule.raw_match_rule} in {search_dir_text} after ignoring"
+                    f" {already_excluded_paths} path(s) that have been excluded."
+                    " If you wanted to install some of these paths, please move the install rule"
+                    " before the exclusion rule or, in case of built-in excludes, list the paths explicitly"
+                    f" (without using patterns). Source for this issue is {self._definition_source}. Match rule:"
+                    f" {fs_match_rule.match_rule.describe_match_exact()}"
+                )
+            elif already_installed_paths:
+                msg = (
+                    f"There were no matches for {fs_match_rule.raw_match_rule} in {search_dir_text} after ignoring"
+                    f" {already_installed_paths} path(s) already been matched previously."
+                    " If you wanted to install some of these paths into multiple packages,"
+                    f" please tweak the definition that installed them to install them into"
+                    f' multiple packages (usually change "into: foo" to "into: [foo, bar]".'
+                    f" Source for this issue is {self._definition_source}. Match rule:"
+                    f" {fs_match_rule.match_rule.describe_match_exact()}"
+                )
+            else:
+                # TODO: Try harder to find the match and point out possible typos
+                msg = (
+                    f"There were no matches for {fs_match_rule.raw_match_rule} in {search_dir_text} (definition:"
+                    f" {self._definition_source}). Match rule: {fs_match_rule.match_rule.describe_match_exact()}"
+                )
+            raise NoMatchForInstallPatternError(
+                msg,
+                fs_match_rule,
+                search_dirs,
+                self._definition_source,
+            )
+        return matched
+
+    def _install_matches(
+        self,
+        path_matcher: SourcePathMatcher,
+        matches: List[PathMatch],
+        dest_paths: Union[Sequence[Tuple[str, bool]], Callable[[PathMatch], str]],
+        install_context: "InstallRuleContext",
+        into: FrozenSet[BinaryPackage],
+        condition_context: ConditionContext,
+    ) -> None:
+        if (
+            self._condition is not None
+            and not self._condition.evaluate(condition_context)
+        ) or not any(p.should_be_acted_on for p in into):
+            # Rule is disabled; skip all its actions - also allow empty matches
+            # for this particular case.
+            return
+
+        if not matches:
+            raise ValueError("matches must not be empty")
+
+        for match, dest_paths_and_roots in _resolve_matches(
+            matches,
+            dest_paths,
+            install_context,
+        ):
+            install_recursively_into_dirs = []
+            for dest, fs_root in dest_paths_and_roots:
+                dir_part, basename = os.path.split(dest)
+                # We do not associate these with the FS path.  First off,
+                # it is complicated to do in most cases (indeed, debhelper
+                # does not preserve these directories either) and secondly,
+                # it is "only" mtime and mode - mostly irrelevant as the
+                # directory is 99.9% likely to be 0755 (we are talking
+                # directories like "/usr", "/usr/share").
+                dir_path = fs_root.mkdirs(dir_part)
+                existing_path = dir_path.get(basename)
+
+                if match.path.is_dir:
+                    if existing_path is not None and not existing_path.is_dir:
+                        existing_path.unlink()
+                        existing_path = None
+                    current_dir = existing_path
+
+                    if current_dir is None:
+                        current_dir = dir_path.mkdir(
+                            basename, reference_path=match.path
+                        )
+                    install_recursively_into_dirs.append(current_dir)
+                else:
+                    if existing_path is not None and existing_path.is_dir:
+                        _error(
+                            f"Cannot install {match.path} ({match.path.fs_path}) as {dest}. That path already exist"
+                            f" and is a directory.  This error was triggered via {self._definition_source}."
+                        )
+
+                    if match.path.is_symlink:
+                        dir_path.add_symlink(
+                            basename, match.path.readlink(), reference_path=match.path
+                        )
+                    else:
+                        dir_path.insert_file_from_fs_path(
+                            basename,
+                            match.path.fs_path,
+                            follow_symlinks=False,
+                            use_fs_path_mode=True,
+                            reference_path=match.path,
+                        )
+            if install_recursively_into_dirs:
+                self._install_dir_recursively(
+                    path_matcher, install_recursively_into_dirs, match, into
+                )
+
+    def _install_dir_recursively(
+        self,
+        path_matcher: SourcePathMatcher,
+        parent_dirs: Sequence[FSPath],
+        match: PathMatch,
+        into: FrozenSet[BinaryPackage],
+    ) -> None:
+        stack = [
+            (parent_dirs, e)
+            for e in match.path.iterdir
+            if not path_matcher.is_reserved(e)
+        ]
+
+        while stack:
+            current_dirs, dir_entry = stack.pop()
+            path_matcher.reserve(
+                dir_entry,
+                into,
+                self._definition_source,
+                is_exact_match=False,
+            )
+            if dir_entry.is_dir:
+                new_dirs = [
+                    d.mkdir(dir_entry.name, reference_path=dir_entry)
+                    for d in current_dirs
+                ]
+                stack.extend(
+                    (new_dirs, de)
+                    for de in dir_entry.iterdir
+                    if not path_matcher.is_reserved(de)
+                )
+            elif dir_entry.is_symlink:
+                for current_dir in current_dirs:
+                    current_dir.add_symlink(
+                        dir_entry.name,
+                        dir_entry.readlink(),
+                        reference_path=dir_entry,
+                    )
+            elif dir_entry.is_file:
+                for current_dir in current_dirs:
+                    current_dir.insert_file_from_fs_path(
+                        dir_entry.name,
+                        dir_entry.fs_path,
+                        use_fs_path_mode=True,
+                        follow_symlinks=False,
+                        reference_path=dir_entry,
+                    )
+            else:
+                _error(
+                    f"Unsupported file type: {dir_entry.fs_path} - neither a file, directory or symlink"
+                )
+
+    def perform_install(
+        self,
+        path_matcher: SourcePathMatcher,
+        install_context: InstallRuleContext,
+        condition_context: ConditionContext,
+    ) -> None:
+        raise NotImplementedError
+
+    @classmethod
+    def install_as(
+        cls,
+        source: FileSystemMatchRule,
+        dest_path: str,
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        return GenericInstallationRule(
+            [source],
+            [(dest_path, False)],
+            into,
+            condition,
+            definition_source,
+            require_single_match=True,
+        )
+
+    @classmethod
+    def install_dest(
+        cls,
+        sources: Sequence[FileSystemMatchRule],
+        dest_dir: Optional[str],
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        if dest_dir is None:
+            dest_dir = "{dirname}/{basename}"
+        else:
+            dest_dir = os.path.join(dest_dir, "{basename}")
+        return GenericInstallationRule(
+            sources,
+            [(dest_dir, True)],
+            into,
+            condition,
+            definition_source,
+        )
+
+    @classmethod
+    def install_multi_as(
+        cls,
+        source: FileSystemMatchRule,
+        dest_paths: Sequence[str],
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        if len(dest_paths) < 2:
+            raise ValueError(
+                "Please use `install_as` when there is less than 2 dest path"
+            )
+        dps = tuple((dp, False) for dp in dest_paths)
+        return GenericInstallationRule(
+            [source],
+            dps,
+            into,
+            condition,
+            definition_source,
+            require_single_match=True,
+        )
+
+    @classmethod
+    def install_multi_dest(
+        cls,
+        sources: Sequence[FileSystemMatchRule],
+        dest_dirs: Sequence[str],
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        if len(dest_dirs) < 2:
+            raise ValueError(
+                "Please use `install_dest` when there is less than 2 dest dir"
+            )
+        dest_paths = tuple((os.path.join(dp, "{basename}"), True) for dp in dest_dirs)
+        return GenericInstallationRule(
+            sources,
+            dest_paths,
+            into,
+            condition,
+            definition_source,
+        )
+
+    @classmethod
+    def install_doc(
+        cls,
+        sources: Sequence[FileSystemMatchRule],
+        dest_dir: Optional[str],
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        cond: ManifestCondition = _BUILD_DOCS_BDO
+        if condition is not None:
+            cond = ManifestCondition.all_of([cond, condition])
+        dest_path_is_format = False
+        if dest_dir is None:
+            dest_dir = "usr/share/doc/{doc_main_package_name}/{basename}"
+            dest_path_is_format = True
+
+        return GenericInstallationRule(
+            sources,
+            [(dest_dir, dest_path_is_format)],
+            into,
+            cond,
+            definition_source,
+        )
+
+    @classmethod
+    def install_doc_as(
+        cls,
+        source: FileSystemMatchRule,
+        dest_path: str,
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        cond: ManifestCondition = _BUILD_DOCS_BDO
+        if condition is not None:
+            cond = ManifestCondition.all_of([cond, condition])
+
+        return GenericInstallationRule(
+            [source],
+            [(dest_path, False)],
+            into,
+            cond,
+            definition_source,
+            require_single_match=True,
+        )
+
+    @classmethod
+    def install_examples(
+        cls,
+        sources: Sequence[FileSystemMatchRule],
+        into: FrozenSet[BinaryPackage],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        cond: ManifestCondition = _BUILD_DOCS_BDO
+        if condition is not None:
+            cond = ManifestCondition.all_of([cond, condition])
+        return GenericInstallationRule(
+            sources,
+            [("usr/share/doc/{doc_main_package_name}/examples/{basename}", True)],
+            into,
+            cond,
+            definition_source,
+        )
+
+    @classmethod
+    def install_man(
+        cls,
+        sources: Sequence[FileSystemMatchRule],
+        into: FrozenSet[BinaryPackage],
+        section: Optional[int],
+        language: Optional[str],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> "InstallRule":
+        cond: ManifestCondition = _BUILD_DOCS_BDO
+        if condition is not None:
+            cond = ManifestCondition.all_of([cond, condition])
+
+        dest_path_computer = _dest_path_for_manpage(
+            section, language, definition_source
+        )
+
+        return GenericInstallationRule(
+            sources,
+            dest_path_computer,
+            into,
+            cond,
+            definition_source,
+            match_filter=lambda m: not m.is_file,
+        )
+
+    @classmethod
+    def discard_paths(
+        cls,
+        paths: Sequence[FileSystemMatchRule],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+        *,
+        limit_to: Optional[Sequence[FileSystemExactMatchRule]] = None,
+    ) -> "InstallRule":
+        return DiscardRule(
+            paths,
+            condition,
+            tuple(limit_to) if limit_to is not None else tuple(),
+            definition_source,
+        )
+
+
+class PPFInstallRule(InstallRule):
+    __slots__ = (
+        "_ppfs",
+        "_substitution",
+        "_into",
+    )
+
+    def __init__(
+        self,
+        into: BinaryPackage,
+        substitution: Substitution,
+        ppfs: Sequence["PackagerProvidedFile"],
+    ) -> None:
+        super().__init__(
+            None,
+            "<built-in; PPF install rule>",
+        )
+        self._substitution = substitution
+        self._ppfs = ppfs
+        self._into = into
+
+    def perform_install(
+        self,
+        path_matcher: SourcePathMatcher,
+        install_context: InstallRuleContext,
+        condition_context: ConditionContext,
+    ) -> None:
+        binary_install_context = install_context[self._into.name]
+        fs_root = binary_install_context.fs_root
+        for ppf in self._ppfs:
+            source_path = ppf.path.fs_path
+            dest_dir, name = ppf.compute_dest()
+            dir_path = fs_root.mkdirs(dest_dir)
+
+            dir_path.insert_file_from_fs_path(
+                name,
+                source_path,
+                follow_symlinks=True,
+                use_fs_path_mode=False,
+                mode=ppf.definition.default_mode,
+            )
+
+
+class GenericInstallationRule(InstallRule):
+    __slots__ = (
+        "_sources",
+        "_into",
+        "_dest_paths",
+        "_require_single_match",
+    )
+
+    def __init__(
+        self,
+        sources: Sequence[FileSystemMatchRule],
+        dest_paths: Union[Sequence[Tuple[str, bool]], Callable[[PathMatch], str]],
+        into: FrozenSet[BinaryPackage],
+        condition: Optional[ManifestCondition],
+        definition_source: str,
+        *,
+        require_single_match: bool = False,
+        match_filter: Optional[Callable[["VirtualPath"], bool]] = None,
+    ) -> None:
+        super().__init__(
+            condition,
+            definition_source,
+            match_filter=match_filter,
+        )
+        self._sources = sources
+        self._into = into
+        self._dest_paths = dest_paths
+        self._require_single_match = require_single_match
+        if self._require_single_match and len(sources) != 1:
+            raise ValueError("require_single_match implies sources must have len 1")
+
+    def perform_install(
+        self,
+        path_matcher: SourcePathMatcher,
+        install_context: InstallRuleContext,
+        condition_context: ConditionContext,
+    ) -> None:
+        for source in self._sources:
+            matches = self._match_pattern(
+                path_matcher,
+                source,
+                condition_context,
+                install_context.search_dirs,
+                self._into,
+            )
+            if self._require_single_match and len(matches) > 1:
+                self._check_single_match(source, matches)
+            self._install_matches(
+                path_matcher,
+                matches,
+                self._dest_paths,
+                install_context,
+                self._into,
+                condition_context,
+            )
+
+
+class DiscardRule(InstallRule):
+    __slots__ = ("_fs_match_rules", "_limit_to")
+
+    def __init__(
+        self,
+        fs_match_rules: Sequence[FileSystemMatchRule],
+        condition: Optional[ManifestCondition],
+        limit_to: Sequence[FileSystemExactMatchRule],
+        definition_source: str,
+    ) -> None:
+        super().__init__(condition, definition_source)
+        self._fs_match_rules = fs_match_rules
+        self._limit_to = limit_to
+
+    def perform_install(
+        self,
+        path_matcher: SourcePathMatcher,
+        install_context: InstallRuleContext,
+        condition_context: ConditionContext,
+    ) -> None:
+        into = frozenset()
+        limit_to = self._limit_to
+        if limit_to:
+            matches = {x.match_rule.path for x in limit_to}
+            search_dirs = tuple(
+                s
+                for s in install_context.search_dirs
+                if s.search_dir.fs_path in matches
+            )
+            if len(limit_to) != len(search_dirs):
+                matches.difference(s.search_dir.fs_path for s in search_dirs)
+                paths = ":".join(matches)
+                _error(
+                    f"The discard rule defined at {self._definition_source} mentions the following"
+                    f" search directories that were not known to debputy: {paths}."
+                    " Either the search dir is missing somewhere else or it should be removed from"
+                    " the discard rule."
+                )
+        else:
+            search_dirs = install_context.search_dirs
+
+        for fs_match_rule in self._fs_match_rules:
+            self._match_pattern(
+                path_matcher,
+                fs_match_rule,
+                condition_context,
+                search_dirs,
+                into,
+            )
diff --git a/src/debputy/intermediate_manifest.py b/src/debputy/intermediate_manifest.py
new file mode 100644
index 0000000..7d8dd63
--- /dev/null
+++ b/src/debputy/intermediate_manifest.py
@@ -0,0 +1,333 @@
+import dataclasses
+import json
+import os
+import stat
+import sys
+import tarfile
+from enum import Enum
+
+
+from typing import Optional, List, Dict, Any, Iterable, Union, Self, Mapping, IO
+
+IntermediateManifest = List["TarMember"]
+
+
+class PathType(Enum):
+    FILE = ("file", tarfile.REGTYPE)
+    DIRECTORY = ("directory", tarfile.DIRTYPE)
+    SYMLINK = ("symlink", tarfile.SYMTYPE)
+    # TODO: Add hardlink, FIFO, Char device, BLK device, etc.
+
+    @property
+    def manifest_key(self) -> str:
+        return self.value[0]
+
+    @property
+    def tarinfo_type(self) -> bytes:
+        return self.value[1]
+
+    @property
+    def can_be_virtual(self) -> bool:
+        return self in (PathType.DIRECTORY, PathType.SYMLINK)
+
+
+KEY2PATH_TYPE = {pt.manifest_key: pt for pt in PathType}
+
+
+def _dirname(path: str) -> str:
+    path = path.rstrip("/")
+    if path == ".":
+        return path
+    return os.path.dirname(path)
+
+
+def _fs_type_from_st_mode(fs_path: str, st_mode: int) -> PathType:
+    if stat.S_ISREG(st_mode):
+        path_type = PathType.FILE
+    elif stat.S_ISDIR(st_mode):
+        path_type = PathType.DIRECTORY
+    #        elif stat.S_ISFIFO(st_result):
+    #            type = FIFOTYPE
+    elif stat.S_ISLNK(st_mode):
+        raise ValueError(
+            "Symlinks should have been rewritten to use the virtual rule."
+            " Otherwise, the link would not be normalized according to Debian Policy."
+        )
+    #        elif stat.S_ISCHR(st_result):
+    #            type = CHRTYPE
+    #        elif stat.S_ISBLK(st_result):
+    #            type = BLKTYPE
+    else:
+        raise ValueError(
+            f"The path {fs_path} had an unsupported/unknown file type."
+            f" Probably a bug in the tool"
+        )
+    return path_type
+
+
+@dataclasses.dataclass(slots=True)
+class TarMember:
+    member_path: str
+    path_type: PathType
+    fs_path: Optional[str]
+    mode: int
+    owner: str
+    uid: int
+    group: str
+    gid: int
+    mtime: float
+    link_target: str = ""
+    is_virtual_entry: bool = False
+    may_steal_fs_path: bool = False
+
+    def create_tar_info(self, tar_fd: tarfile.TarFile) -> tarfile.TarInfo:
+        tar_info: tarfile.TarInfo
+        if self.is_virtual_entry:
+            assert self.path_type.can_be_virtual
+            tar_info = tar_fd.tarinfo(self.member_path)
+            tar_info.size = 0
+            tar_info.type = self.path_type.tarinfo_type
+            tar_info.linkpath = self.link_target
+        else:
+            try:
+                tar_info = tar_fd.gettarinfo(
+                    name=self.fs_path, arcname=self.member_path
+                )
+            except (TypeError, ValueError) as e:
+                raise ValueError(
+                    f"Unable to prepare tar info for {self.member_path}"
+                ) from e
+            # TODO: Eventually, we should be able to unconditionally rely on link_target.  However,
+            # until we got symlinks and hardlinks correctly done in the JSON generator, it will be
+            # conditional for now.
+            if self.link_target != "":
+                tar_info.linkpath = self.link_target
+        tar_info.mode = self.mode
+        tar_info.uname = self.owner
+        tar_info.uid = self.uid
+        tar_info.gname = self.group
+        tar_info.gid = self.gid
+        tar_info.mode = self.mode
+        tar_info.mtime = int(self.mtime)
+
+        return tar_info
+
+    @classmethod
+    def from_file(
+        cls,
+        member_path: str,
+        fs_path: str,
+        mode: Optional[int] = None,
+        owner: str = "root",
+        uid: int = 0,
+        group: str = "root",
+        gid: int = 0,
+        path_mtime: Optional[Union[float, int]] = None,
+        clamp_mtime_to: Optional[int] = None,
+        path_type: Optional[PathType] = None,
+        may_steal_fs_path: bool = False,
+    ) -> "TarMember":
+        # Avoid lstat'ing if we can as it makes it easier to do tests of the code
+        # (as we do not need an existing physical fs path)
+        if path_type is None or path_mtime is None or mode is None:
+            st_result = os.lstat(fs_path)
+            st_mode = st_result.st_mode
+            if mode is None:
+                mode = st_mode
+            if path_mtime is None:
+                path_mtime = st_result.st_mtime
+            if path_type is None:
+                path_type = _fs_type_from_st_mode(fs_path, st_mode)
+
+        if clamp_mtime_to is not None and path_mtime > clamp_mtime_to:
+            path_mtime = clamp_mtime_to
+
+        if may_steal_fs_path:
+            assert (
+                "debputy/scratch-dir/" in fs_path
+            ), f"{fs_path} should not have been stealable"
+
+        return cls(
+            member_path=member_path,
+            path_type=path_type,
+            fs_path=fs_path,
+            mode=mode,
+            owner=owner,
+            uid=uid,
+            group=group,
+            gid=gid,
+            mtime=float(path_mtime),
+            is_virtual_entry=False,
+            may_steal_fs_path=may_steal_fs_path,
+        )
+
+    @classmethod
+    def virtual_path(
+        cls,
+        member_path: str,
+        path_type: PathType,
+        mtime: float,
+        mode: int,
+        link_target: str = "",
+        owner: str = "root",
+        uid: int = 0,
+        group: str = "root",
+        gid: int = 0,
+    ) -> Self:
+        if not path_type.can_be_virtual:
+            raise ValueError(f"The path type {path_type.name} cannot be virtual")
+        if (path_type == PathType.SYMLINK) ^ bool(link_target):
+            if not link_target:
+                raise ValueError("Symlinks must have a link target")
+            # TODO: Dear future programmer. Hardlinks will appear here some day and you will have to fix this
+            # code then!
+            raise ValueError("Non-symlinks must not have a link target")
+        return cls(
+            member_path=member_path,
+            path_type=path_type,
+            fs_path=None,
+            link_target=link_target,
+            mode=mode,
+            owner=owner,
+            uid=uid,
+            group=group,
+            gid=gid,
+            mtime=mtime,
+            is_virtual_entry=True,
+        )
+
+    def clone_and_replace(self, /, **changes: Any) -> "TarMember":
+        return dataclasses.replace(self, **changes)
+
+    def to_manifest(self) -> Dict[str, Any]:
+        d = dataclasses.asdict(self)
+        try:
+            d["mode"] = oct(self.mode)
+        except (TypeError, ValueError) as e:
+            raise TypeError(f"Bad mode in TarMember {self.member_path}") from e
+        d["path_type"] = self.path_type.manifest_key
+        # "compress" the output by removing redundant fields
+        if self.link_target is None or self.link_target == "":
+            del d["link_target"]
+        if self.is_virtual_entry:
+            assert self.fs_path is None
+            del d["fs_path"]
+        else:
+            del d["is_virtual_entry"]
+        return d
+
+    @classmethod
+    def parse_intermediate_manifest(cls, manifest_path: str) -> IntermediateManifest:
+        directories = {"."}
+        if manifest_path == "-":
+            with sys.stdin as fd:
+                data = json.load(fd)
+                contents = [TarMember.from_dict(m) for m in data]
+        else:
+            with open(manifest_path) as fd:
+                data = json.load(fd)
+                contents = [TarMember.from_dict(m) for m in data]
+        if not contents:
+            raise ValueError(
+                "Empty manifest (note that the root directory should always be present"
+            )
+        if contents[0].member_path != "./":
+            raise ValueError('The first member must always be the root directory "./"')
+        for tar_member in contents:
+            directory = _dirname(tar_member.member_path)
+            if directory not in directories:
+                raise ValueError(
+                    f'The path "{tar_member.member_path}" came before the directory it is in (or the path'
+                    f" is not a directory). Either way leads to a broken deb."
+                )
+            if tar_member.path_type == PathType.DIRECTORY:
+                directories.add(tar_member.member_path.rstrip("/"))
+        return contents
+
+    @classmethod
+    def from_dict(cls, d: Any) -> "TarMember":
+        member_path = d["member_path"]
+        raw_mode = d["mode"]
+        if not raw_mode.startswith("0o"):
+            raise ValueError(f"Bad mode for {member_path}")
+        is_virtual_entry = d.get("is_virtual_entry") or False
+        path_type = KEY2PATH_TYPE[d["path_type"]]
+        fs_path = d.get("fs_path")
+        mode = int(raw_mode[2:], 8)
+        if is_virtual_entry:
+            if not path_type.can_be_virtual:
+                raise ValueError(
+                    f"Bad file type or is_virtual_entry for {d['member_path']}."
+                    " The file type cannot be virtual"
+                )
+            if fs_path is not None:
+                raise ValueError(
+                    f'Invalid declaration for "{member_path}".'
+                    " The path is listed as a virtual entry but has a file system path"
+                )
+        elif fs_path is None:
+            raise ValueError(
+                f'Invalid declaration for "{member_path}".'
+                " The path is neither a virtual path nor does it have a file system path!"
+            )
+        if path_type == PathType.DIRECTORY and not member_path.endswith("/"):
+            raise ValueError(
+                f'Invalid declaration for "{member_path}".'
+                " The path is listed as a directory but does not end with a slash"
+            )
+
+        link_target = d.get("link_target")
+        if path_type == PathType.SYMLINK:
+            if mode != 0o777:
+                raise ValueError(
+                    f'Invalid declaration for "{member_path}".'
+                    f" Symlinks must have mode 0o0777, got {oct(mode)[2:]}."
+                )
+            if not link_target:
+                raise ValueError(
+                    f'Invalid declaration for "{member_path}".'
+                    " Symlinks must have a link_target"
+                )
+        elif link_target is not None and link_target != "":
+            # TODO: Eventually hardlinks should have them too.  But that is a problem for a future programmer
+            raise ValueError(
+                f'Invalid declaration for "{member_path}".'
+                " Only symlinks can have a link_target"
+            )
+        else:
+            link_target = ""
+        may_steal_fs_path = d.get("may_steal_fs_path") or False
+
+        if may_steal_fs_path:
+            assert (
+                "debputy/scratch-dir/" in fs_path
+            ), f"{fs_path} should not have been stealable"
+        return cls(
+            member_path=member_path,
+            path_type=path_type,
+            fs_path=fs_path,
+            mode=mode,
+            owner=d["owner"],
+            uid=d["uid"],
+            group=d["group"],
+            gid=d["gid"],
+            mtime=float(d["mtime"]),
+            link_target=link_target,
+            is_virtual_entry=is_virtual_entry,
+            may_steal_fs_path=may_steal_fs_path,
+        )
+
+
+def output_intermediate_manifest(
+    manifest_output_file: str,
+    members: Iterable[TarMember],
+) -> None:
+    with open(manifest_output_file, "w") as fd:
+        output_intermediate_manifest_to_fd(fd, members)
+
+
+def output_intermediate_manifest_to_fd(
+    fd: IO[str], members: Iterable[TarMember]
+) -> None:
+    serial_format = [m.to_manifest() for m in members]
+    json.dump(serial_format, fd)
diff --git a/src/debputy/interpreter.py b/src/debputy/interpreter.py
new file mode 100644
index 0000000..0d986e1
--- /dev/null
+++ b/src/debputy/interpreter.py
@@ -0,0 +1,220 @@
+import dataclasses
+import os.path
+import re
+import shutil
+from typing import Optional, IO, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from debputy.plugin.api import VirtualPath
+
+_SHEBANG_RE = re.compile(
+    rb"""
+    ^[#][!]\s*
+    (/\S+/([a-zA-Z][^/\s]*))
+""",
+    re.VERBOSE | re.ASCII,
+)
+_WORD = re.compile(rb"\s+(\S+)")
+_STRIP_VERSION = re.compile(r"(-?\d+(?:[.]\d.+)?)$")
+
+_KNOWN_INTERPRETERS = {
+    os.path.basename(c): c
+    for c in ["/bin/sh", "/bin/bash", "/bin/dash", "/usr/bin/perl", "/usr/bin/python"]
+}
+
+
+class Interpreter:
+    @property
+    def original_command(self) -> str:
+        """The original command (without arguments) from the #! line
+
+        This returns the command as it was written (without flags/arguments) in the file.
+
+        Note as a special-case, if the original command is `env` then the first argument is included
+        as well, because it is assumed to be the real command.
+
+
+        >>> # Note: Normally, you would use `VirtualPath.interpreter()` instead for extracting the interpreter
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3 -b")
+        >>> python3.original_command
+        '/usr/bin/python3'
+        >>> env_sh = extract_shebang_interpreter(b"#! /usr/bin/env sh")
+        >>> env_sh.original_command
+        '/usr/bin/env sh'
+
+        :return: The original command in the #!-line
+        """
+        raise NotImplementedError
+
+    @property
+    def command_full_basename(self) -> str:
+        """The full basename of the command (with version)
+
+        Note that for #!-lines that uses `env`, this will return the argument for `env` rather than
+        `env`.
+
+        >>> # Note: Normally, you would use `VirtualPath.interpreter()` instead for extracting the interpreter
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3 -b")
+        >>> python3.command_full_basename
+        'python3'
+        >>> env_sh = extract_shebang_interpreter(b"#! /usr/bin/env sh")
+        >>> env_sh.command_full_basename
+        'sh'
+
+        :return: The full basename of the command.
+        """
+        raise NotImplementedError
+
+    @property
+    def command_stem(self) -> str:
+        """The basename of the command **without** version
+
+        Note that for #!-lines that uses `env`, this will return the argument for `env` rather than
+        `env`.
+
+        >>> # Note: Normally, you would use `VirtualPath.interpreter()` instead for extracting the interpreter
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3 -b")
+        >>> python3.command_stem
+        'python'
+        >>> env_sh = extract_shebang_interpreter(b"#! /usr/bin/env sh")
+        >>> env_sh.command_stem
+        'sh'
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3.12-dbg -b")
+        >>> python3.command_stem
+        'python'
+
+        :return: The basename of the command **without** version.
+        """
+        raise NotImplementedError
+
+    @property
+    def interpreter_version(self) -> str:
+        """The version part of the basename
+
+        Note that for #!-lines that uses `env`, this will return the argument for `env` rather than
+        `env`.
+
+        >>> # Note: Normally, you would use `VirtualPath.interpreter()` instead for extracting the interpreter
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3 -b")
+        >>> python3.interpreter_version
+        '3'
+        >>> env_sh = extract_shebang_interpreter(b"#! /usr/bin/env sh")
+        >>> env_sh.interpreter_version
+        ''
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3.12-dbg -b")
+        >>> python3.interpreter_version
+        '3.12-dbg'
+
+        :return: The version part of the command or the empty string if the command is versionless.
+        """
+        raise NotImplementedError
+
+    @property
+    def fixup_needed(self) -> bool:
+        """Whether the interpreter uses a non-canonical location
+
+        >>> # Note: Normally, you would use `VirtualPath.interpreter()` instead for extracting the interpreter
+        >>> python3 = extract_shebang_interpreter(b"#! /usr/bin/python3 -b")
+        >>> python3.fixup_needed
+        False
+        >>> env_sh = extract_shebang_interpreter(b"#! /usr/bin/env sh")
+        >>> env_sh.fixup_needed
+        True
+        >>> ub_sh = extract_shebang_interpreter(b"#! /usr/bin/sh")
+        >>> ub_sh.fixup_needed
+        True
+        >>> sh = extract_shebang_interpreter(b"#! /bin/sh")
+        >>> sh.fixup_needed
+        False
+
+        :return: True if this interpreter is uses a non-canonical version.
+        """
+        return False
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DetectedInterpreter(Interpreter):
+    original_command: str
+    command_full_basename: str
+    command_stem: str
+    interpreter_version: str
+    correct_command: Optional[str] = None
+    corrected_shebang_line: Optional[str] = None
+
+    @property
+    def fixup_needed(self) -> bool:
+        return self.corrected_shebang_line is not None
+
+    def replace_shebang_line(self, path: "VirtualPath") -> None:
+        new_shebang_line = self.corrected_shebang_line
+        assert new_shebang_line.startswith("#!")
+        if not new_shebang_line.endswith("\n"):
+            new_shebang_line += "\n"
+        parent_dir = path.parent_dir
+        assert parent_dir is not None
+        with path.open(byte_io=True) as rfd:
+            original_first_line = rfd.readline()
+            if not original_first_line.startswith(b"#!"):
+                raise ValueError(
+                    f'The provided path "{path.path}" does not start with a shebang line!?'
+                )
+            mtime = path.mtime
+            with path.replace_fs_path_content() as new_fs_path, open(
+                new_fs_path, "wb"
+            ) as wfd:
+                wfd.write(new_shebang_line.encode("utf-8"))
+                shutil.copyfileobj(rfd, wfd)
+            # Ensure the mtime is not updated (we do not count interpreter correction as a "change")
+            path.mtime = mtime
+
+
+def extract_shebang_interpreter_from_file(
+    fd: IO[bytes],
+) -> Optional[DetectedInterpreter]:
+    first_line = fd.readline(4096)
+    if b"\n" not in first_line:
+        # If there is no newline, then it is probably not a shebang line
+        return None
+    return extract_shebang_interpreter(first_line)
+
+
+def extract_shebang_interpreter(first_line: bytes) -> Optional[DetectedInterpreter]:
+    m = _SHEBANG_RE.search(first_line)
+    if not m:
+        return None
+    raw_command = m.group(1).strip().decode("utf-8")
+    command_full_basename = m.group(2).strip().decode("utf-8")
+    endpos = m.end()
+    if command_full_basename == "env":
+        wm = _WORD.search(first_line, pos=m.end())
+        if wm is not None:
+            command_full_basename = wm.group(1).decode("utf-8")
+            raw_command += " " + command_full_basename
+            endpos = wm.end()
+    command_stem = command_full_basename
+    vm = _STRIP_VERSION.search(command_full_basename)
+    if vm:
+        version = vm.group(1)
+        command_stem = command_full_basename[: -len(version)]
+    else:
+        version = ""
+    correct_command = _KNOWN_INTERPRETERS.get(command_stem)
+    if correct_command is not None and version != "":
+        correct_command += version
+
+    if correct_command is not None and correct_command != raw_command:
+        trailing = first_line[endpos + 1 :].strip().decode("utf-8")
+        corrected_shebang_line = "#! " + correct_command
+        if trailing:
+            corrected_shebang_line += " " + trailing
+    else:
+        corrected_shebang_line = None
+
+    return DetectedInterpreter(
+        raw_command,
+        command_full_basename,
+        command_stem,
+        version,
+        correct_command,
+        corrected_shebang_line,
+    )
diff --git a/src/debputy/linting/__init__.py b/src/debputy/linting/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/linting/__init__.py
diff --git a/src/debputy/linting/lint_impl.py b/src/debputy/linting/lint_impl.py
new file mode 100644
index 0000000..68be9d9
--- /dev/null
+++ b/src/debputy/linting/lint_impl.py
@@ -0,0 +1,322 @@
+import os
+import stat
+import sys
+from typing import Optional, List, Union, NoReturn
+
+from lsprotocol.types import (
+    CodeAction,
+    Command,
+    CodeActionParams,
+    CodeActionContext,
+    TextDocumentIdentifier,
+    TextEdit,
+    Position,
+    DiagnosticSeverity,
+)
+
+from debputy.commands.debputy_cmd.context import CommandContext
+from debputy.commands.debputy_cmd.output import _output_styling, OutputStylingBase
+from debputy.linting.lint_util import (
+    LINTER_POSITION_CODEC,
+    report_diagnostic,
+    LinterImpl,
+    LintReport,
+)
+from debputy.lsp.lsp_debian_changelog import _lint_debian_changelog
+from debputy.lsp.lsp_debian_control import _lint_debian_control
+from debputy.lsp.lsp_debian_copyright import _lint_debian_copyright
+from debputy.lsp.lsp_debian_debputy_manifest import _lint_debian_debputy_manifest
+from debputy.lsp.lsp_debian_rules import _lint_debian_rules
+from debputy.lsp.quickfixes import provide_standard_quickfixes_from_diagnostics
+from debputy.lsp.spellchecking import disable_spellchecking
+from debputy.lsp.text_edit import (
+    get_well_formatted_edit,
+    merge_sort_text_edits,
+    apply_text_edits,
+)
+from debputy.util import _warn, _error, _info
+
+LINTER_FORMATS = {
+    "debian/control": _lint_debian_control,
+    "debian/copyright": _lint_debian_copyright,
+    "debian/changelog": _lint_debian_changelog,
+    "debian/rules": _lint_debian_rules,
+    "debian/debputy.manifest": _lint_debian_debputy_manifest,
+}
+
+
+def perform_linting(context: CommandContext) -> None:
+    parsed_args = context.parsed_args
+    if not parsed_args.spellcheck:
+        disable_spellchecking()
+    linter_exit_code = parsed_args.linter_exit_code
+    lint_report = LintReport()
+    fo = _output_styling(context.parsed_args, sys.stdout)
+    for name_stem in LINTER_FORMATS:
+        filename = f"./{name_stem}"
+        if not os.path.isfile(filename):
+            continue
+        perform_linting_of_file(
+            fo,
+            filename,
+            name_stem,
+            context.parsed_args.auto_fix,
+            lint_report,
+        )
+    if lint_report.diagnostics_without_severity:
+        _warn(
+            "Some diagnostics did not explicitly set severity. Please report the bug and include the output"
+        )
+    if lint_report.diagnostic_errors:
+        _error(
+            "Some sub-linters reported issues. Please report the bug and include the output"
+        )
+
+    if os.path.isfile("debian/debputy.manifest"):
+        _info("Note: Due to a limitation in the linter, debian/debputy.manifest is")
+        _info("only **partially** checked by this command at the time of writing.")
+        _info("Please use `debputy check-manifest` for checking the manifest.")
+
+    if linter_exit_code:
+        _exit_with_lint_code(lint_report)
+
+
+def _exit_with_lint_code(lint_report: LintReport) -> NoReturn:
+    diagnostics_count = lint_report.diagnostics_count
+    if (
+        diagnostics_count[DiagnosticSeverity.Error]
+        or diagnostics_count[DiagnosticSeverity.Warning]
+    ):
+        sys.exit(2)
+    sys.exit(0)
+
+
+def perform_linting_of_file(
+    fo: OutputStylingBase,
+    filename: str,
+    file_format: str,
+    auto_fixing_enabled: bool,
+    lint_report: LintReport,
+) -> None:
+    handler = LINTER_FORMATS.get(file_format)
+    if handler is None:
+        return
+    with open(filename, "rt", encoding="utf-8") as fd:
+        text = fd.read()
+
+    if auto_fixing_enabled:
+        _auto_fix_run(fo, filename, text, handler, lint_report)
+    else:
+        _diagnostics_run(fo, filename, text, handler, lint_report)
+
+
+def _auto_fix_run(
+    fo: OutputStylingBase,
+    filename: str,
+    text: str,
+    linter: LinterImpl,
+    lint_report: LintReport,
+) -> None:
+    another_round = True
+    unfixed_diagnostics = []
+    remaining_rounds = 10
+    fixed_count = False
+    too_many_rounds = False
+    lines = text.splitlines(keepends=True)
+    current_issues = linter(filename, filename, lines, LINTER_POSITION_CODEC)
+    issue_count_start = len(current_issues) if current_issues else 0
+    while another_round and current_issues:
+        another_round = False
+        last_fix_position = Position(0, 0)
+        unfixed_diagnostics.clear()
+        edits = []
+        fixed_diagnostics = []
+        for diagnostic in current_issues:
+            actions = provide_standard_quickfixes_from_diagnostics(
+                CodeActionParams(
+                    TextDocumentIdentifier(filename),
+                    diagnostic.range,
+                    CodeActionContext(
+                        [diagnostic],
+                    ),
+                )
+            )
+            auto_fixing_edits = resolve_auto_fixer(filename, actions)
+
+            if not auto_fixing_edits:
+                unfixed_diagnostics.append(diagnostic)
+                continue
+
+            sorted_edits = merge_sort_text_edits(
+                [get_well_formatted_edit(e) for e in auto_fixing_edits],
+            )
+            last_edit = sorted_edits[-1]
+            last_edit_pos = last_edit.range.start
+            if (
+                last_edit_pos.line <= last_fix_position.line
+                or last_edit_pos.character < last_fix_position.character
+            ):
+                if not another_round:
+
+                    if remaining_rounds > 0:
+                        remaining_rounds -= 1
+                        print(
+                            "Detected overlapping edit; scheduling another edit round."
+                        )
+                        another_round = True
+                    else:
+                        _warn(
+                            "Too many overlapping edits; stopping after this round (circuit breaker)."
+                        )
+                        too_many_rounds = True
+                continue
+            edits.extend(sorted_edits)
+            fixed_diagnostics.append(diagnostic)
+
+        if another_round and not edits:
+            _error(
+                "Internal error: Detected an overlapping edit and yet had edits to perform..."
+            )
+
+        fixed_count += len(fixed_diagnostics)
+
+        text = apply_text_edits(
+            text,
+            lines,
+            edits,
+        )
+        lines = text.splitlines(keepends=True)
+
+        for diagnostic in fixed_diagnostics:
+            report_diagnostic(
+                fo,
+                filename,
+                diagnostic,
+                lines,
+                True,
+                True,
+                lint_report,
+            )
+        current_issues = linter(filename, filename, lines, LINTER_POSITION_CODEC)
+
+    if fixed_count:
+        output_filename = f"{filename}.tmp"
+        with open(output_filename, "wt", encoding="utf-8") as fd:
+            fd.write(text)
+        orig_mode = stat.S_IMODE(os.stat(filename).st_mode)
+        os.chmod(output_filename, orig_mode)
+        os.rename(output_filename, filename)
+        lines = text.splitlines(keepends=True)
+        remaining_issues = (
+            linter(filename, filename, lines, LINTER_POSITION_CODEC) or []
+        )
+    else:
+        remaining_issues = current_issues or []
+
+    for diagnostic in remaining_issues:
+        report_diagnostic(
+            fo,
+            filename,
+            diagnostic,
+            lines,
+            False,
+            False,
+            lint_report,
+        )
+
+    print()
+    if fixed_count:
+        remaining_issues_count = len(remaining_issues)
+        print(
+            fo.colored(
+                f"Fixes applied to {filename}: {fixed_count}."
+                f" Number of issues went from {issue_count_start} to {remaining_issues_count}",
+                fg="green",
+                style="bold",
+            )
+        )
+    elif remaining_issues:
+        print(
+            fo.colored(
+                f"None of the issues in {filename} could be fixed automatically. Sorry!",
+                fg="yellow",
+                bg="black",
+                style="bold",
+            )
+        )
+    else:
+        assert not current_issues
+        print(
+            fo.colored(
+                f"No issues detected in {filename}",
+                fg="green",
+                style="bold",
+            )
+        )
+    if too_many_rounds:
+        print(
+            fo.colored(
+                f"Not all fixes for issues in {filename} could be applied due to overlapping edits.",
+                fg="yellow",
+                bg="black",
+                style="bold",
+            )
+        )
+        print(
+            "Running once more may cause more fixes to be applied. However, you may be facing"
+            " pathological performance."
+        )
+
+
+def _diagnostics_run(
+    fo: OutputStylingBase,
+    filename: str,
+    text: str,
+    linter: LinterImpl,
+    lint_report: LintReport,
+) -> None:
+    lines = text.splitlines(keepends=True)
+    issues = linter(filename, filename, lines, LINTER_POSITION_CODEC) or []
+    for diagnostic in issues:
+        actions = provide_standard_quickfixes_from_diagnostics(
+            CodeActionParams(
+                TextDocumentIdentifier(filename),
+                diagnostic.range,
+                CodeActionContext(
+                    [diagnostic],
+                ),
+            )
+        )
+        auto_fixer = resolve_auto_fixer(filename, actions)
+        has_auto_fixer = bool(auto_fixer)
+
+        report_diagnostic(
+            fo,
+            filename,
+            diagnostic,
+            lines,
+            has_auto_fixer,
+            False,
+            lint_report,
+        )
+
+
+def resolve_auto_fixer(
+    document_ref: str,
+    actions: Optional[List[Union[Command, CodeAction]]],
+) -> Optional[List[TextEdit]]:
+    if actions is None or len(actions) != 1:
+        return None
+    action = actions[0]
+    if not isinstance(action, CodeAction):
+        return None
+    workspace_edit = action.edit
+    if workspace_edit is None or action.command is not None:
+        return None
+    if (
+        not workspace_edit.changes
+        or len(workspace_edit.changes) != 1
+        or document_ref not in workspace_edit.changes
+    ):
+        return None
+    return workspace_edit.changes[document_ref]
diff --git a/src/debputy/linting/lint_util.py b/src/debputy/linting/lint_util.py
new file mode 100644
index 0000000..7cdb8b6
--- /dev/null
+++ b/src/debputy/linting/lint_util.py
@@ -0,0 +1,175 @@
+import dataclasses
+from typing import List, Optional, Callable, Counter
+
+from lsprotocol.types import Position, Range, Diagnostic, DiagnosticSeverity
+
+from debputy.commands.debputy_cmd.output import OutputStylingBase
+from debputy.util import _DEFAULT_LOGGER, _warn
+
+LinterImpl = Callable[
+    [str, str, List[str], "LintCapablePositionCodec"], Optional[List[Diagnostic]]
+]
+
+
+@dataclasses.dataclass(slots=True)
+class LintReport:
+    diagnostics_count: Counter[DiagnosticSeverity] = dataclasses.field(
+        default_factory=Counter
+    )
+    diagnostics_without_severity: int = 0
+    diagnostic_errors: int = 0
+    fixed: int = 0
+    fixable: int = 0
+
+
+class LinterPositionCodec:
+
+    def client_num_units(self, chars: str):
+        return len(chars)
+
+    def position_from_client_units(
+        self, lines: List[str], position: Position
+    ) -> Position:
+
+        if len(lines) == 0:
+            return Position(0, 0)
+        if position.line >= len(lines):
+            return Position(len(lines) - 1, self.client_num_units(lines[-1]))
+        return position
+
+    def position_to_client_units(
+        self, _lines: List[str], position: Position
+    ) -> Position:
+        return position
+
+    def range_from_client_units(self, _lines: List[str], range: Range) -> Range:
+        return range
+
+    def range_to_client_units(self, _lines: List[str], range: Range) -> Range:
+        return range
+
+
+LINTER_POSITION_CODEC = LinterPositionCodec()
+
+
+_SEVERITY2TAG = {
+    DiagnosticSeverity.Error: lambda fo: fo.colored(
+        "error",
+        fg="red",
+        bg="black",
+        style="bold",
+    ),
+    DiagnosticSeverity.Warning: lambda fo: fo.colored(
+        "warning",
+        fg="yellow",
+        bg="black",
+        style="bold",
+    ),
+    DiagnosticSeverity.Information: lambda fo: fo.colored(
+        "informational",
+        fg="blue",
+        bg="black",
+        style="bold",
+    ),
+    DiagnosticSeverity.Hint: lambda fo: fo.colored(
+        "pedantic",
+        fg="green",
+        bg="black",
+        style="bold",
+    ),
+}
+
+
+def _lines_to_print(range_: Range) -> int:
+    count = range_.end.line - range_.start.line
+    if range_.end.character > 0:
+        count += 1
+    return count
+
+
+def _highlight_range(
+    fo: OutputStylingBase, line: str, line_no: int, range_: Range
+) -> str:
+    line_wo_nl = line.rstrip("\r\n")
+    start_pos = 0
+    prefix = ""
+    suffix = ""
+    if line_no == range_.start.line:
+        start_pos = range_.start.character
+        prefix = line_wo_nl[0:start_pos]
+    if line_no == range_.end.line:
+        end_pos = range_.end.character
+        suffix = line_wo_nl[end_pos:]
+    else:
+        end_pos = len(line_wo_nl)
+
+    marked_part = fo.colored(line_wo_nl[start_pos:end_pos], fg="red", style="bold")
+
+    return prefix + marked_part + suffix
+
+
+def report_diagnostic(
+    fo: OutputStylingBase,
+    filename: str,
+    diagnostic: Diagnostic,
+    lines: List[str],
+    auto_fixable: bool,
+    auto_fixed: bool,
+    lint_report: LintReport,
+) -> None:
+    logger = _DEFAULT_LOGGER
+    assert logger is not None
+    severity = diagnostic.severity
+    missing_severity = False
+    if severity is None:
+        severity = DiagnosticSeverity.Warning
+        missing_severity = True
+    if not auto_fixed:
+        tag_unresolved = _SEVERITY2TAG.get(severity)
+        if tag_unresolved is None:
+            tag_unresolved = _SEVERITY2TAG[DiagnosticSeverity.Warning]
+            lint_report.diagnostics_without_severity += 1
+        else:
+            lint_report.diagnostics_count[severity] += 1
+        tag = tag_unresolved(fo)
+    else:
+        tag = fo.colored(
+            "auto-fixing",
+            fg="magenta",
+            bg="black",
+            style="bold",
+        )
+    start_line = diagnostic.range.start.line
+    start_position = diagnostic.range.start.character
+    end_line = diagnostic.range.end.line
+    end_position = diagnostic.range.end.character
+    has_fixit = ""
+    line_no_width = len(str(len(lines)))
+    if not auto_fixed and auto_fixable:
+        has_fixit = " [Correctable via --auto-fix]"
+        lint_report.fixable += 1
+    print(
+        f"{tag}: File: {filename}:{start_line+1}:{start_position}:{end_line+1}:{end_position}: {diagnostic.message}{has_fixit}",
+    )
+    if missing_severity:
+        _warn(
+            "  This warning did not have an explicit severity; Used Warning as a fallback!"
+        )
+    if auto_fixed:
+        # If it is fixed, there is no reason to show additional context.
+        lint_report.fixed += 1
+        return
+    lines_to_print = _lines_to_print(diagnostic.range)
+    if diagnostic.range.end.line >= len(lines) or diagnostic.range.start.line < 1:
+        lint_report.diagnostic_errors += 1
+        _warn(
+            "Bug in the underlying linter: The line numbers of the warning does not fit in the file..."
+        )
+        return
+    if lines_to_print == 1:
+        line = _highlight_range(fo, lines[start_line], start_line, diagnostic.range)
+        print(f"    {start_line+1:{line_no_width}}: {line}")
+    else:
+        for line_no in range(start_line, end_line):
+            line = _highlight_range(fo, lines[line_no], line_no, diagnostic.range)
+            print(f"    {line_no+1:{line_no_width}}: {line}")
diff --git a/src/debputy/lsp/__init__.py b/src/debputy/lsp/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/lsp/__init__.py
diff --git a/src/debputy/lsp/debian-wordlist.dic b/src/debputy/lsp/debian-wordlist.dic
new file mode 100644
index 0000000..11e0438
--- /dev/null
+++ b/src/debputy/lsp/debian-wordlist.dic
@@ -0,0 +1,333 @@
+_darcs
+abi
+abs2rel
+addon
+add-on
+addons
+add-ons
+alioth
+api
+archs
+args
+awk
+autoconf
+automake
+autopkgtest
+autopkgtests
+autoreconf
+backport
+backportable
+backporter
+backporters
+backporting
+backports
+bashism
+bashisms
+basename
+bhlc
+binNMU
+binNMUs
+binutils
+build-dep
+build-deps
+buildd
+buildds
+buildflags
+buildsystem
+buildsystems
+bz2
+bzip2
+ccache
+CDBS
+cdbs
+cdebconf
+CFLAGS
+changelog
+changelogs
+chdir
+chfn
+chmod
+chown
+chroot
+chsh
+cli
+cvs
+cmake
+compat
+conffile
+conffiles
+config
+cowbuilder
+CPPFLAGS
+cpu
+cron
+crond
+CSV
+cwd
+CXXFLAGS
+dbg
+dbgsym
+dbgsyms
+db_purge
+dch
+deb
+deb822
+debcrossgen
+debs
+debstd
+debconf
+dest
+destdir
+dest_dir
+debhelper
+debhelper's
+debian
+Debian
+debputy
+Dh_Lib
+dfsg
+dh
+dirs
+dirname
+distclean
+doxygen
+dpkg
+dpkg's
+du
+dwz
+egrep
+elif
+elsif
+emacs
+emacsen
+enum
+env
+envvar
+eval
+fakeroot
+fanotify
+fd
+fds
+fgrep
+FHS
+filehandle
+filehandles
+filesystem
+filesystems
+freebsd
+frontend
+frontends
+FTBFS
+FTCBFS
+gconf2
+gdb
+getopt
+GitLab
+GitHub
+glob
+globs
+globbing
+grep
+gunzip
+gzip
+hardlink
+hardlinked
+hardlinks
+htm
+html
+HTML
+html2text
+Indep
+indep
+idempotent
+idempotency
+initramfs
+inotify
+isinstallable
+ispell
+jpeg
+jpg
+json
+JSON
+journalctl
+journald
+kfreebsd
+ksh
+ld
+ldconfig
+LDFLAGS
+levenshtein
+libexec
+libtool
+libtoolize
+linter
+linters
+linting
+lintian
+linux
+lua
+https
+maintscript
+maintscripts
+makefile
+makefiles
+manpage
+manpages
+md5sum
+md5sums
+menutest
+mkdir
+mkdirs
+mkfontdir
+movetousr
+mtime
+multi-arch
+Multi-Arch
+multiarch-support
+noautodbgsym
+noawait
+nocheck
+nodoc
+nohup
+noop
+noudeb
+numpy
+numpy3
+objcopy
+objdump
+OCaml
+ok
+oldoldstable
+oldstable
+openssl
+param
+params
+parentdir
+parent_dir
+passwd
+pbuilder
+perl
+perl5
+pkgfile
+pkgfiles
+png
+preinst
+prerm
+po4a
+po-debconf
+pod2man
+POSIX
+postinst
+postrm
+Pre-Depends
+pwd
+py
+pyc
+pyo
+python3
+Python3
+qmake
+qmake5
+qmake6
+qt5-qmake
+qt6-qmake
+rc
+rcbug
+rcbugs
+readlink
+realpath
+readme
+reportbug
+rm
+rmdir
+rpath
+R³
+sbuild
+sed
+setgid
+setuid
+sha1sum
+sha256sum
+sha512sum
+shlibs
+SONAME
+SONAMEs
+sbin
+scrollkeeper
+sourcedir
+sourcedirs
+ssl
+stacktrace
+stderr
+stdin
+stdout
+subcommand
+subcommands
+subdir
+subdirs
+subprocess
+subprocesses
+subst
+substring
+substvar
+substvars
+suid
+suidmanager
+suidregister
+svg
+svgz
+svn
+symlink
+symlinked
+symlinks
+systemctl
+systemd
+sysusers
+sysvinit
+t64
+temp
+tempdir
+tempdirs
+tempfile
+tempfiles
+tls
+tmp
+tmpfiles
+TODO
+toml
+tomli
+TOML
+ucf
+ucfr
+udeb
+udebs
+udev
+uid
+umask
+undef
+uploaders
+upstreams
+url
+urls
+URI
+URIs
+uri
+uris
+utf-7
+utf-8
+utf-16
+utf-32
+util
+utils
+usr
+vcs
+Vcs
+wishlist
+wm
+YAML
+yaml
+yml
+xargs
+xml
+xz
+zsh
diff --git a/src/debputy/lsp/logins-and-people.dic b/src/debputy/lsp/logins-and-people.dic
new file mode 100644
index 0000000..a7c468b
--- /dev/null
+++ b/src/debputy/lsp/logins-and-people.dic
@@ -0,0 +1,278 @@
+
+Aboubakr
+Aj
+Alessandro
+Allbery
+Allombert
+Alteholz
+Américo
+Andreas
+Andrej
+Andrius
+Ansgar
+Aoki
+aph
+Appaiah
+Aurelien
+Axel
+Bacher
+Badreddin
+Banck
+Basak
+Bastian
+Bastien
+Basto
+Bdale
+Beckert
+Bengen
+Bernd
+Bicha
+Biebl
+Biedl
+Bigonville
+Bobbio
+Bogatov
+Bothamy
+Boulenguez
+Bourg
+Boyuan
+Braakman
+Braud-Santoni
+Brederlow
+Briscoe-Smith
+Brulebois
+Burchardt
+Byrum
+Campagne
+Carraway
+Cascadian
+Changwoo
+Christianson
+Christoph
+cjwatson
+Costamagna
+Cowgill
+Damián
+Damir
+Didier
+Dirson
+d'Itri
+Dmitry
+Dorey
+Dorland
+Drieu
+Durigan
+Düsterhus
+D'Vine
+Dzeko
+Eduard
+Eisentraut
+elbrus
+Emel
+Engel
+Engelhard
+Escalante
+Evgeni
+Fabio
+Falavigna
+Ferenc
+Florian
+Frédéric
+Fumitoshi
+Garbee
+Garside
+Geissert
+Gergely
+Gevers
+Geyer
+Ghe
+Ghedini
+gilbey
+Gillmor
+Glondu
+Godoy
+Golov
+Goswin
+Göttsche
+Grassi
+Greffrath
+gregor
+Grobman
+Groenen
+Grohne
+Guerreiro
+Guilhem
+guillem
+Harald
+Hasdal
+Hasenack
+helmutg
+Henriksson
+Hernández-Novich
+herrmann
+Hideki
+Hikory
+Hilko
+Hiroyuki
+Hofstaedtler
+Holbach
+Hommey
+Hutchings
+Iain
+Jakub
+Jammet
+Jarno
+Jelmer
+Jens
+Jeroen
+Jochen
+Jordi
+Jorgen
+Josip
+Josselin
+Jover
+Kastner
+Kel
+Kis
+Kitover
+Kitt
+Klode
+Klose
+Knauß
+Koeppe
+Koschany
+Krall
+Kumar
+Laboissiere
+Langasek
+Leick
+Leidert
+Lisandro
+Loïc
+Luberda
+Luca
+Lyubimkin
+Mallach
+Marcin
+Marillat
+Markus
+Martin-Éric
+Masanori
+Masato
+Matej
+Mattia
+Maximiliano
+Mennucc
+Merkys
+Metzler
+Mihai
+Miklautz
+Minier
+Modderman
+Modestas
+Monfort
+Monteiro
+Moritz
+Mouette
+Moulder
+Muehlenhoff
+Nadav
+Nicanor
+Niels
+Niko
+O'Dea
+Ondřej
+Osamu
+Overfiend
+Owsiany
+Ożarowski
+Pahula
+Paillard
+Pappacoda
+Pentchev
+Pérez
+Pfannenstein
+Philipp
+Pikulski
+Piotr
+Plessy
+Porras
+Possas
+Pozuelo
+Praveen
+Prévot
+Raboud
+Ragwitz
+Raphaël
+Reiner
+Reyer
+Rivero
+Rizzolo
+Robie
+Roeckx
+Röhling
+rra
+Rubén
+Ruderich
+Ryu
+Sandro
+Sanou
+Sascha
+Sateler
+Schaefer
+Schauer
+Schepler
+Schertler
+Schmelcher
+Schot
+Schrieffer
+Sebastien
+Sébastien
+Sérgio
+Seyeong
+Shachnev
+Shadura
+smcv McVittie
+Smedegaard
+Sprickerhof
+Stapelberg
+Steigies
+Steinbiss
+Stephane
+Stéphane
+Stribblehill
+Suffield
+Surý
+Tagliamonte
+Tambre
+Tandy
+Taruishi
+Theppitak
+Thom
+Thorsten
+Thykier
+Tille
+Timo
+Tranchitella
+Triplett
+Troup
+Ts'o
+Tyni
+Vainius
+Valéry
+Verhelst
+Vernooij
+Villemot
+von
+Wágner
+Wakko
+Welte
+wferi
+Whitton
+Wilk
+Wouter
+Yamane
+Yann
+zeha
+Zeimetz
+Zinoviev
diff --git a/src/debputy/lsp/lsp_debian_changelog.py b/src/debputy/lsp/lsp_debian_changelog.py
new file mode 100644
index 0000000..3ec0b4d
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_changelog.py
@@ -0,0 +1,186 @@
+import sys
+from typing import (
+    Union,
+    List,
+    Dict,
+    Iterator,
+    Optional,
+    Iterable,
+)
+
+from lsprotocol.types import (
+    Diagnostic,
+    DidOpenTextDocumentParams,
+    DidChangeTextDocumentParams,
+    TEXT_DOCUMENT_DID_OPEN,
+    TEXT_DOCUMENT_DID_CHANGE,
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    TEXT_DOCUMENT_CODE_ACTION,
+    TEXT_DOCUMENT_DID_CLOSE,
+    DidCloseTextDocumentParams,
+    Range,
+    Position,
+    DiagnosticSeverity,
+)
+
+from debputy.lsp.lsp_features import lsp_diagnostics, lsp_standard_handler
+from debputy.lsp.quickfixes import (
+    provide_standard_quickfixes_from_diagnostics,
+)
+from debputy.lsp.spellchecking import spellcheck_line
+from debputy.lsp.text_util import (
+    on_save_trim_end_of_line_whitespace,
+    LintCapablePositionCodec,
+)
+
+try:
+    from debian._deb822_repro.locatable import Position as TEPosition, Ranage as TERange
+
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+# Same as Lintian
+_MAXIMUM_WIDTH: int = 82
+_LANGUAGE_IDS = [
+    "debian/changelog",
+    # emacs's name
+    "debian-changelog",
+    # vim's name
+    "debchangelog",
+]
+
+DOCUMENT_VERSION_TABLE: Dict[str, int] = {}
+
+
+def register_dch_lsp(ls: "LanguageServer") -> None:
+    ls.feature(TEXT_DOCUMENT_DID_OPEN)(_diagnostics_debian_changelog)
+    ls.feature(TEXT_DOCUMENT_DID_CHANGE)(_diagnostics_debian_changelog)
+    ls.feature(TEXT_DOCUMENT_DID_CLOSE)(_handle_close)
+    ls.feature(TEXT_DOCUMENT_CODE_ACTION)(
+        ls.thread()(provide_standard_quickfixes_from_diagnostics)
+    )
+    ls.feature(TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)(on_save_trim_end_of_line_whitespace)
+
+
+def _handle_close(
+    ls: "LanguageServer",
+    params: DidCloseTextDocumentParams,
+) -> None:
+    try:
+        del DOCUMENT_VERSION_TABLE[params.text_document.uri]
+    except KeyError:
+        pass
+
+
+def is_doc_at_version(uri: str, version: int) -> bool:
+    dv = DOCUMENT_VERSION_TABLE.get(uri)
+    return dv == version
+
+
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_CODE_ACTION)
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)
+
+
+@lsp_diagnostics(_LANGUAGE_IDS)
+def _diagnostics_debian_changelog(
+    ls: "LanguageServer",
+    params: Union[DidOpenTextDocumentParams, DidChangeTextDocumentParams],
+) -> Iterable[List[Diagnostic]]:
+    doc_uri = params.text_document.uri
+    doc = ls.workspace.get_text_document(doc_uri)
+    lines = doc.lines
+    max_words = 1_000
+    delta_update_size = 10
+    max_lines_between_update = 10
+    scanner = _scan_debian_changelog_for_diagnostics(
+        lines,
+        doc.position_codec,
+        delta_update_size,
+        max_words,
+        max_lines_between_update,
+    )
+
+    yield from scanner
+
+
+def _scan_debian_changelog_for_diagnostics(
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+    delta_update_size: int,
+    max_words: int,
+    max_lines_between_update: int,
+    *,
+    max_line_length: int = _MAXIMUM_WIDTH,
+) -> Iterator[List[Diagnostic]]:
+    diagnostics = []
+    diagnostics_at_last_update = 0
+    lines_since_last_update = 0
+    for line_no, line in enumerate(lines):
+        orig_line = line
+        line = line.rstrip()
+        if not line:
+            continue
+        if not line.startswith("  "):
+            continue
+        # minus 1 for newline
+        orig_line_len = len(orig_line) - 1
+        if orig_line_len > max_line_length:
+            range_server_units = Range(
+                Position(
+                    line_no,
+                    max_line_length,
+                ),
+                Position(
+                    line_no,
+                    orig_line_len,
+                ),
+            )
+            diagnostics.append(
+                Diagnostic(
+                    position_codec.range_to_client_units(lines, range_server_units),
+                    f"Line exceeds {max_line_length} characters",
+                    severity=DiagnosticSeverity.Hint,
+                    source="debputy",
+                )
+            )
+        if len(line) > 3 and line[2] == "[" and line[-1] == "]":
+            # Do not spell check [ X ] as X is usually a name
+            continue
+        lines_since_last_update += 1
+        if max_words > 0:
+            typos = list(spellcheck_line(lines, position_codec, line_no, line))
+            new_diagnostics = len(typos)
+            max_words -= new_diagnostics
+            diagnostics.extend(typos)
+
+        current_diagnostics_len = len(diagnostics)
+        if (
+            lines_since_last_update >= max_lines_between_update
+            or current_diagnostics_len - diagnostics_at_last_update > delta_update_size
+        ):
+            diagnostics_at_last_update = current_diagnostics_len
+            lines_since_last_update = 0
+
+            yield diagnostics
+    if not diagnostics or diagnostics_at_last_update != len(diagnostics):
+        yield diagnostics
+
+
+def _lint_debian_changelog(
+    _doc_reference: str,
+    _path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    limits = sys.maxsize
+    scanner = _scan_debian_changelog_for_diagnostics(
+        lines,
+        position_codec,
+        limits,
+        limits,
+        limits,
+    )
+    return next(iter(scanner), None)
diff --git a/src/debputy/lsp/lsp_debian_control.py b/src/debputy/lsp/lsp_debian_control.py
new file mode 100644
index 0000000..d00f1c2
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_control.py
@@ -0,0 +1,797 @@
+from typing import (
+    Union,
+    Sequence,
+    Tuple,
+    Iterator,
+    Optional,
+    Iterable,
+    Mapping,
+    List,
+)
+
+from debputy.lsp.vendoring._deb822_repro import (
+    parse_deb822_file,
+    Deb822FileElement,
+    Deb822ParagraphElement,
+)
+from debputy.lsp.vendoring._deb822_repro.parsing import (
+    Deb822KeyValuePairElement,
+    LIST_SPACE_SEPARATED_INTERPRETATION,
+)
+from debputy.lsp.vendoring._deb822_repro.tokens import (
+    Deb822Token,
+    tokenize_deb822_file,
+    Deb822FieldNameToken,
+)
+from lsprotocol.types import (
+    DiagnosticSeverity,
+    Range,
+    Diagnostic,
+    Position,
+    DidOpenTextDocumentParams,
+    DidChangeTextDocumentParams,
+    FoldingRangeKind,
+    FoldingRange,
+    FoldingRangeParams,
+    CompletionItem,
+    CompletionList,
+    CompletionParams,
+    TEXT_DOCUMENT_DID_OPEN,
+    TEXT_DOCUMENT_DID_CHANGE,
+    TEXT_DOCUMENT_FOLDING_RANGE,
+    TEXT_DOCUMENT_COMPLETION,
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    DiagnosticRelatedInformation,
+    Location,
+    TEXT_DOCUMENT_HOVER,
+    HoverParams,
+    Hover,
+    TEXT_DOCUMENT_CODE_ACTION,
+    DiagnosticTag,
+    SemanticTokensLegend,
+    TEXT_DOCUMENT_SEMANTIC_TOKENS_FULL,
+    SemanticTokens,
+    SemanticTokensParams,
+)
+
+from debputy.lsp.lsp_debian_control_reference_data import (
+    DctrlKnownField,
+    BINARY_FIELDS,
+    SOURCE_FIELDS,
+    FieldValueClass,
+    DctrlFileMetadata,
+)
+from debputy.lsp.lsp_features import (
+    lint_diagnostics,
+    lsp_completer,
+    lsp_hover,
+    lsp_standard_handler,
+)
+from debputy.lsp.lsp_generic_deb822 import deb822_completer, deb822_hover
+from debputy.lsp.quickfixes import (
+    propose_remove_line_quick_fix,
+    range_compatible_with_remove_line_fix,
+    propose_correct_text_quick_fix,
+    provide_standard_quickfixes_from_diagnostics,
+)
+from debputy.lsp.spellchecking import default_spellchecker
+from debputy.lsp.text_util import (
+    on_save_trim_end_of_line_whitespace,
+    normalize_dctrl_field_name,
+    LintCapablePositionCodec,
+    detect_possible_typo,
+    te_range_to_lsp,
+)
+from debputy.util import _info, _error
+
+try:
+    from debputy.lsp.vendoring._deb822_repro.locatable import (
+        Position as TEPosition,
+        Range as TERange,
+        START_POSITION,
+    )
+
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+_LANGUAGE_IDS = [
+    "debian/control",
+    # emacs's name
+    "debian-control",
+    # vim's name
+    "debcontrol",
+]
+
+
+SEMANTIC_TOKENS_LEGEND = SemanticTokensLegend(
+    token_types=["keyword"],
+    token_modifiers=[],
+)
+_DCTRL_FILE_METADATA = DctrlFileMetadata()
+
+
+def register_dctrl_lsp(ls: "LanguageServer") -> None:
+    try:
+        from debputy.lsp.vendoring._deb822_repro.locatable import Locatable
+    except ImportError:
+        _error(
+            'Sorry; this feature requires a newer version of python-debian (with "Locatable").'
+        )
+
+    ls.feature(TEXT_DOCUMENT_DID_OPEN)(_diagnostics_debian_control)
+    ls.feature(TEXT_DOCUMENT_DID_CHANGE)(_diagnostics_debian_control)
+    ls.feature(TEXT_DOCUMENT_FOLDING_RANGE)(_detect_folding_ranges_debian_control)
+    ls.feature(TEXT_DOCUMENT_COMPLETION)(_debian_control_completions)
+    ls.feature(TEXT_DOCUMENT_CODE_ACTION)(provide_standard_quickfixes_from_diagnostics)
+    ls.feature(TEXT_DOCUMENT_HOVER)(_debian_control_hover)
+    ls.feature(TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)(on_save_trim_end_of_line_whitespace)
+    ls.feature(TEXT_DOCUMENT_SEMANTIC_TOKENS_FULL, SEMANTIC_TOKENS_LEGEND)(
+        _handle_semantic_tokens_full
+    )
+
+
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_CODE_ACTION)
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)
+
+
+@lsp_hover(_LANGUAGE_IDS)
+def _debian_control_hover(
+    ls: "LanguageServer",
+    params: HoverParams,
+) -> Optional[Hover]:
+    return deb822_hover(ls, params, _DCTRL_FILE_METADATA)
+
+
+@lsp_completer(_LANGUAGE_IDS)
+def _debian_control_completions(
+    ls: "LanguageServer",
+    params: CompletionParams,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    return deb822_completer(ls, params, _DCTRL_FILE_METADATA)
+
+
+def _detect_folding_ranges_debian_control(
+    ls: "LanguageServer",
+    params: FoldingRangeParams,
+) -> Optional[Sequence[FoldingRange]]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    comment_start = -1
+    folding_ranges = []
+    for (
+        token,
+        start_line,
+        start_offset,
+        end_line,
+        end_offset,
+    ) in _deb822_token_iter(tokenize_deb822_file(doc.lines)):
+        if token.is_comment:
+            if comment_start < 0:
+                comment_start = start_line
+                _info(f"Detected new comment: {start_line}")
+        elif comment_start > -1:
+            comment_start = -1
+            folding_range = FoldingRange(
+                comment_start,
+                end_line,
+                kind=FoldingRangeKind.Comment,
+            )
+
+            folding_ranges.append(folding_range)
+            _info(f"Detected folding range: {folding_range}")
+
+    return folding_ranges
+
+
+def _deb822_token_iter(
+    tokens: Iterable[Deb822Token],
+) -> Iterator[Tuple[Deb822Token, int, int, int, int, int]]:
+    line_no = 0
+    line_offset = 0
+
+    for token in tokens:
+        start_line = line_no
+        start_line_offset = line_offset
+
+        newlines = token.text.count("\n")
+        line_no += newlines
+        text_len = len(token.text)
+        if newlines:
+            if token.text.endswith("\n"):
+                line_offset = 0
+            else:
+                # -2, one to remove the "\n" and one to get 0-offset
+                line_offset = text_len - token.text.rindex("\n") - 2
+        else:
+            line_offset += text_len
+
+        yield token, start_line, start_line_offset, line_no, line_offset
+
+
+def _paragraph_representation_field(
+    paragraph: Deb822ParagraphElement,
+) -> Deb822KeyValuePairElement:
+    return next(iter(paragraph.iter_parts_of_type(Deb822KeyValuePairElement)))
+
+
+def _extract_first_value_and_position(
+    kvpair: Deb822KeyValuePairElement,
+    stanza_pos: "TEPosition",
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+) -> Tuple[Optional[str], Optional[Range]]:
+    kvpair_pos = kvpair.position_in_parent().relative_to(stanza_pos)
+    value_element_pos = kvpair.value_element.position_in_parent().relative_to(
+        kvpair_pos
+    )
+    for value_ref in kvpair.interpret_as(
+        LIST_SPACE_SEPARATED_INTERPRETATION
+    ).iter_value_references():
+        v = value_ref.value
+        section_value_loc = value_ref.locatable
+        value_range_te = section_value_loc.range_in_parent().relative_to(
+            value_element_pos
+        )
+        section_range_server_units = te_range_to_lsp(value_range_te)
+        section_range = position_codec.range_to_client_units(
+            lines, section_range_server_units
+        )
+        return v, section_range
+    return None, None
+
+
+def _binary_package_checks(
+    stanza: Deb822ParagraphElement,
+    stanza_position: "TEPosition",
+    source_stanza: Deb822ParagraphElement,
+    representation_field_range: Range,
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> None:
+    ma_kvpair = stanza.get_kvpair_element("Multi-Arch", use_get=True)
+    arch = stanza.get("Architecture", "any")
+    if arch == "all" and ma_kvpair is not None:
+        ma_value, ma_value_range = _extract_first_value_and_position(
+            ma_kvpair,
+            stanza_position,
+            position_codec,
+            lines,
+        )
+        if ma_value == "same":
+            diagnostics.append(
+                Diagnostic(
+                    ma_value_range,
+                    "Multi-Arch: same is not valid for Architecture: all packages. Maybe you want foreign?",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                )
+            )
+
+    package_name = stanza.get("Package", "")
+    source_section = source_stanza.get("Section")
+    section_kvpair = stanza.get_kvpair_element("Section", use_get=True)
+    section: Optional[str] = None
+    if section_kvpair is not None:
+        section, section_range = _extract_first_value_and_position(
+            section_kvpair,
+            stanza_position,
+            position_codec,
+            lines,
+        )
+    else:
+        section_range = representation_field_range
+    effective_section = section or source_section or "unknown"
+    package_type = stanza.get("Package-Type", "")
+    component_prefix = ""
+    if "/" in effective_section:
+        component_prefix, effective_section = effective_section.split("/", maxsplit=1)
+        component_prefix += "/"
+
+    if package_name.endswith("-udeb") or package_type == "udeb":
+        if package_type != "udeb":
+            package_type_kvpair = stanza.get_kvpair_element(
+                "Package-Type", use_get=True
+            )
+            package_type_range = None
+            if package_type_kvpair is not None:
+                _, package_type_range = _extract_first_value_and_position(
+                    package_type_kvpair,
+                    stanza_position,
+                    position_codec,
+                    lines,
+                )
+            if package_type_range is None:
+                package_type_range = representation_field_range
+            diagnostics.append(
+                Diagnostic(
+                    package_type_range,
+                    'The Package-Type should be "udeb" given the package name',
+                    severity=DiagnosticSeverity.Warning,
+                    source="debputy",
+                )
+            )
+        if effective_section != "debian-installer":
+            quickfix_data = None
+            if section is not None:
+                quickfix_data = [
+                    propose_correct_text_quick_fix(
+                        f"{component_prefix}debian-installer"
+                    )
+                ]
+            diagnostics.append(
+                Diagnostic(
+                    section_range,
+                    f'The Section should be "{component_prefix}debian-installer" for udebs',
+                    severity=DiagnosticSeverity.Warning,
+                    source="debputy",
+                    data=quickfix_data,
+                )
+            )
+
+
+def _diagnostics_for_paragraph(
+    stanza: Deb822ParagraphElement,
+    stanza_position: "TEPosition",
+    source_stanza: Deb822ParagraphElement,
+    known_fields: Mapping[str, DctrlKnownField],
+    other_known_fields: Mapping[str, DctrlKnownField],
+    is_binary_paragraph: bool,
+    doc_reference: str,
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> None:
+    representation_field = _paragraph_representation_field(stanza)
+    representation_field_pos = representation_field.position_in_parent().relative_to(
+        stanza_position
+    )
+    representation_field_range_server_units = te_range_to_lsp(
+        TERange.from_position_and_size(
+            representation_field_pos, representation_field.size()
+        )
+    )
+    representation_field_range = position_codec.range_to_client_units(
+        lines,
+        representation_field_range_server_units,
+    )
+    for known_field in known_fields.values():
+        missing_field_severity = known_field.missing_field_severity
+        if missing_field_severity is None or known_field.name in stanza:
+            continue
+
+        if known_field.inherits_from_source and known_field.name in source_stanza:
+            continue
+
+        diagnostics.append(
+            Diagnostic(
+                representation_field_range,
+                f"Stanza is missing field {known_field.name}",
+                severity=missing_field_severity,
+                source="debputy",
+            )
+        )
+
+    if is_binary_paragraph:
+        _binary_package_checks(
+            stanza,
+            stanza_position,
+            source_stanza,
+            representation_field_range,
+            position_codec,
+            lines,
+            diagnostics,
+        )
+
+    seen_fields = {}
+
+    for kvpair in stanza.iter_parts_of_type(Deb822KeyValuePairElement):
+        field_name_token = kvpair.field_token
+        field_name = field_name_token.text
+        field_name_lc = field_name.lower()
+        normalized_field_name_lc = normalize_dctrl_field_name(field_name_lc)
+        known_field = known_fields.get(normalized_field_name_lc)
+        field_value = stanza[field_name]
+        field_range_te = kvpair.range_in_parent().relative_to(stanza_position)
+        field_position_te = field_range_te.start_pos
+        field_range_server_units = te_range_to_lsp(field_range_te)
+        field_range = position_codec.range_to_client_units(
+            lines,
+            field_range_server_units,
+        )
+        field_name_typo_detected = False
+        existing_field_range = seen_fields.get(normalized_field_name_lc)
+        if existing_field_range is not None:
+            existing_field_range[3].append(field_range)
+        else:
+            normalized_field_name = normalize_dctrl_field_name(field_name)
+            seen_fields[field_name_lc] = (
+                field_name,
+                normalized_field_name,
+                field_range,
+                [],
+            )
+
+        if known_field is None:
+            candidates = detect_possible_typo(normalized_field_name_lc, known_fields)
+            if candidates:
+                known_field = known_fields[candidates[0]]
+                token_range_server_units = te_range_to_lsp(
+                    TERange.from_position_and_size(
+                        field_position_te, kvpair.field_token.size()
+                    )
+                )
+                field_range = position_codec.range_to_client_units(
+                    lines,
+                    token_range_server_units,
+                )
+                field_name_typo_detected = True
+                diagnostics.append(
+                    Diagnostic(
+                        field_range,
+                        f'The "{field_name}" looks like a typo of "{known_field.name}".',
+                        severity=DiagnosticSeverity.Warning,
+                        source="debputy",
+                        data=[
+                            propose_correct_text_quick_fix(known_fields[m].name)
+                            for m in candidates
+                        ],
+                    )
+                )
+        if known_field is None:
+            known_else_where = other_known_fields.get(normalized_field_name_lc)
+            if known_else_where is not None:
+                intended_usage = "Source" if is_binary_paragraph else "Package"
+                diagnostics.append(
+                    Diagnostic(
+                        field_range,
+                        f'The {field_name} is defined for use in the "{intended_usage}" stanza.'
+                        f" Please move it to the right place or remove it",
+                        severity=DiagnosticSeverity.Error,
+                        source="debputy",
+                    )
+                )
+            continue
+
+        if field_value.strip() == "":
+            diagnostics.append(
+                Diagnostic(
+                    field_range,
+                    f"The {field_name} has no value. Either provide a value or remove it.",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                )
+            )
+            continue
+        diagnostics.extend(
+            known_field.field_diagnostics(
+                kvpair,
+                stanza_position,
+                position_codec,
+                lines,
+                field_name_typo_reported=field_name_typo_detected,
+            )
+        )
+        if known_field.spellcheck_value:
+            words = kvpair.interpret_as(LIST_SPACE_SEPARATED_INTERPRETATION)
+            spell_checker = default_spellchecker()
+            value_position = kvpair.value_element.position_in_parent().relative_to(
+                field_position_te
+            )
+            for word_ref in words.iter_value_references():
+                token = word_ref.value
+                for word, pos, endpos in spell_checker.iter_words(token):
+                    corrections = spell_checker.provide_corrections_for(word)
+                    if not corrections:
+                        continue
+                    word_loc = word_ref.locatable
+                    word_pos_te = word_loc.position_in_parent().relative_to(
+                        value_position
+                    )
+                    if pos:
+                        word_pos_te = TEPosition(0, pos).relative_to(word_pos_te)
+                    word_range = TERange(
+                        START_POSITION,
+                        TEPosition(0, endpos - pos),
+                    )
+                    word_range_server_units = te_range_to_lsp(
+                        TERange.from_position_and_size(word_pos_te, word_range)
+                    )
+                    word_range = position_codec.range_to_client_units(
+                        lines,
+                        word_range_server_units,
+                    )
+                    diagnostics.append(
+                        Diagnostic(
+                            word_range,
+                            f'Spelling "{word}"',
+                            severity=DiagnosticSeverity.Hint,
+                            source="debputy",
+                            data=[
+                                propose_correct_text_quick_fix(c) for c in corrections
+                            ],
+                        )
+                    )
+        source_value = source_stanza.get(field_name)
+        if known_field.warn_if_default and field_value == known_field.default_value:
+            diagnostics.append(
+                Diagnostic(
+                    field_range,
+                    f"The {field_name} is redundant as it is set to the default value and the field should only be"
+                    " used in exceptional cases.",
+                    severity=DiagnosticSeverity.Warning,
+                    source="debputy",
+                )
+            )
+
+        if known_field.inherits_from_source and field_value == source_value:
+            if range_compatible_with_remove_line_fix(field_range):
+                fix_data = propose_remove_line_quick_fix()
+            else:
+                fix_data = None
+            diagnostics.append(
+                Diagnostic(
+                    field_range,
+                    f"The field {field_name} duplicates the value from the Source stanza.",
+                    severity=DiagnosticSeverity.Information,
+                    source="debputy",
+                    data=fix_data,
+                )
+            )
+    for (
+        field_name,
+        normalized_field_name,
+        field_range,
+        duplicates,
+    ) in seen_fields.values():
+        if not duplicates:
+            continue
+        related_information = [
+            DiagnosticRelatedInformation(
+                location=Location(doc_reference, field_range),
+                message=f"First definition of {field_name}",
+            )
+        ]
+        related_information.extend(
+            DiagnosticRelatedInformation(
+                location=Location(doc_reference, r),
+                message=f"Duplicate of {field_name}",
+            )
+            for r in duplicates
+        )
+        for dup_range in duplicates:
+            diagnostics.append(
+                Diagnostic(
+                    dup_range,
+                    f"The {normalized_field_name} field name was used multiple times in this stanza."
+                    f" Please ensure the field is only used once per stanza. Note that {normalized_field_name} and"
+                    f" X[BCS]-{normalized_field_name} are considered the same field.",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                    related_information=related_information,
+                )
+            )
+
+
+def _diagnostics_for_field_name(
+    token: Deb822FieldNameToken,
+    token_position: "TEPosition",
+    known_field: DctrlKnownField,
+    typo_detected: bool,
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> None:
+    field_name = token.text
+    # Defeat the case-insensitivity from python-debian
+    field_name_cased = str(field_name)
+    token_range_server_units = te_range_to_lsp(
+        TERange.from_position_and_size(token_position, token.size())
+    )
+    token_range = position_codec.range_to_client_units(
+        lines,
+        token_range_server_units,
+    )
+    if known_field.deprecated_with_no_replacement:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"{field_name_cased} is deprecated and no longer used",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_remove_line_quick_fix(),
+            )
+        )
+    elif known_field.replaced_by is not None:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"{field_name_cased} is a deprecated name for {known_field.replaced_by}",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_correct_text_quick_fix(known_field.replaced_by),
+            )
+        )
+
+    if not typo_detected and field_name_cased != known_field.name:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"Non-canonical spelling of {known_field.name}",
+                severity=DiagnosticSeverity.Information,
+                source="debputy",
+                data=propose_correct_text_quick_fix(known_field.name),
+            )
+        )
+
+
+def _scan_for_syntax_errors_and_token_level_diagnostics(
+    deb822_file: Deb822FileElement,
+    position_codec: LintCapablePositionCodec,
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> int:
+    first_error = len(lines) + 1
+    spell_checker = default_spellchecker()
+    for (
+        token,
+        start_line,
+        start_offset,
+        end_line,
+        end_offset,
+    ) in _deb822_token_iter(deb822_file.iter_tokens()):
+        if token.is_error:
+            first_error = min(first_error, start_line)
+            start_pos = Position(
+                start_line,
+                start_offset,
+            )
+            end_pos = Position(
+                end_line,
+                end_offset,
+            )
+            token_range = position_codec.range_to_client_units(
+                lines, Range(start_pos, end_pos)
+            )
+            diagnostics.append(
+                Diagnostic(
+                    token_range,
+                    "Syntax error",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy (python-debian parser)",
+                )
+            )
+        elif token.is_comment:
+            for word, pos, end_pos in spell_checker.iter_words(token.text):
+                corrections = spell_checker.provide_corrections_for(word)
+                if not corrections:
+                    continue
+                start_pos = Position(
+                    start_line,
+                    pos,
+                )
+                end_pos = Position(
+                    start_line,
+                    end_pos,
+                )
+                word_range = position_codec.range_to_client_units(
+                    lines, Range(start_pos, end_pos)
+                )
+                diagnostics.append(
+                    Diagnostic(
+                        word_range,
+                        f'Spelling "{word}"',
+                        severity=DiagnosticSeverity.Hint,
+                        source="debputy",
+                        data=[propose_correct_text_quick_fix(c) for c in corrections],
+                    )
+                )
+    return first_error
+
+
+def _diagnostics_debian_control(
+    ls: "LanguageServer",
+    params: Union[DidOpenTextDocumentParams, DidChangeTextDocumentParams],
+) -> None:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    _info(f"Opened document: {doc.path} ({doc.language_id})")
+    lines = doc.lines
+    position_codec: LintCapablePositionCodec = doc.position_codec
+
+    diagnostics = _lint_debian_control(doc.uri, doc.path, lines, position_codec)
+    ls.publish_diagnostics(
+        doc.uri,
+        diagnostics,
+    )
+
+
+@lint_diagnostics(_LANGUAGE_IDS)
+def _lint_debian_control(
+    doc_reference: str,
+    _path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    diagnostics = []
+    deb822_file = parse_deb822_file(
+        lines,
+        accept_files_with_duplicated_fields=True,
+        accept_files_with_error_tokens=True,
+    )
+
+    first_error = _scan_for_syntax_errors_and_token_level_diagnostics(
+        deb822_file,
+        position_codec,
+        lines,
+        diagnostics,
+    )
+
+    paragraphs = list(deb822_file)
+    source_paragraph = paragraphs[0] if paragraphs else None
+
+    for paragraph_no, paragraph in enumerate(paragraphs, start=1):
+        paragraph_pos = paragraph.position_in_file()
+        if paragraph_pos.line_position >= first_error:
+            break
+        is_binary_paragraph = paragraph_no != 1
+        if is_binary_paragraph:
+            known_fields = BINARY_FIELDS
+            other_known_fields = SOURCE_FIELDS
+        else:
+            known_fields = SOURCE_FIELDS
+            other_known_fields = BINARY_FIELDS
+        _diagnostics_for_paragraph(
+            paragraph,
+            paragraph_pos,
+            source_paragraph,
+            known_fields,
+            other_known_fields,
+            is_binary_paragraph,
+            doc_reference,
+            position_codec,
+            lines,
+            diagnostics,
+        )
+
+    return diagnostics
+
+
+def _handle_semantic_tokens_full(
+    ls: "LanguageServer",
+    request: SemanticTokensParams,
+) -> Optional[SemanticTokens]:
+    doc = ls.workspace.get_text_document(request.text_document.uri)
+    lines = doc.lines
+    deb822_file = parse_deb822_file(
+        lines,
+        accept_files_with_duplicated_fields=True,
+        accept_files_with_error_tokens=True,
+    )
+    tokens = []
+    previous_line = 0
+    keyword_token = 0
+    no_modifiers = 0
+
+    for paragraph_no, paragraph in enumerate(deb822_file, start=1):
+        paragraph_position = paragraph.position_in_file()
+        for kvpair in paragraph.iter_parts_of_type(Deb822KeyValuePairElement):
+            field_position_without_comments = kvpair.position_in_parent().relative_to(
+                paragraph_position
+            )
+            field_size = doc.position_codec.client_num_units(kvpair.field_name)
+            current_line = field_position_without_comments.line_position
+            line_delta = current_line - previous_line
+            previous_line = current_line
+            tokens.append(line_delta)  # Line delta
+            tokens.append(0)  # Token delta
+            tokens.append(field_size)  # Token length
+            tokens.append(keyword_token)
+            tokens.append(no_modifiers)
+
+    if not tokens:
+        return None
+    return SemanticTokens(tokens)
diff --git a/src/debputy/lsp/lsp_debian_control_reference_data.py b/src/debputy/lsp/lsp_debian_control_reference_data.py
new file mode 100644
index 0000000..f4791cb
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_control_reference_data.py
@@ -0,0 +1,2067 @@
+import dataclasses
+import functools
+import itertools
+import textwrap
+from abc import ABC
+from enum import Enum, auto
+from typing import (
+    FrozenSet,
+    Optional,
+    cast,
+    Mapping,
+    Iterable,
+    List,
+    Generic,
+    TypeVar,
+    Union,
+)
+
+from debian.debian_support import DpkgArchTable
+from lsprotocol.types import DiagnosticSeverity, Diagnostic, DiagnosticTag
+
+from debputy.lsp.quickfixes import (
+    propose_correct_text_quick_fix,
+    propose_remove_line_quick_fix,
+)
+from debputy.lsp.text_util import (
+    normalize_dctrl_field_name,
+    LintCapablePositionCodec,
+    detect_possible_typo,
+    te_range_to_lsp,
+)
+from debputy.lsp.vendoring._deb822_repro.parsing import (
+    Deb822KeyValuePairElement,
+    LIST_SPACE_SEPARATED_INTERPRETATION,
+    Deb822ParagraphElement,
+    Deb822FileElement,
+)
+from debputy.lsp.vendoring._deb822_repro.tokens import Deb822FieldNameToken
+
+try:
+    from debputy.lsp.vendoring._deb822_repro.locatable import (
+        Position as TEPosition,
+        Range as TERange,
+        START_POSITION,
+    )
+except ImportError:
+    pass
+
+
+F = TypeVar("F", bound="Deb822KnownField")
+S = TypeVar("S", bound="StanzaMetadata")
+
+
+ALL_SECTIONS_WITHOUT_COMPONENT = frozenset(
+    [
+        "admin",
+        "cli-mono",
+        "comm",
+        "database",
+        "debian-installer",
+        "debug",
+        "devel",
+        "doc",
+        "editors",
+        "education",
+        "electronics",
+        "embedded",
+        "fonts",
+        "games",
+        "gnome",
+        "gnu-r",
+        "gnustep",
+        "graphics",
+        "hamradio",
+        "haskell",
+        "interpreters",
+        "introspection",
+        "java",
+        "javascript",
+        "kde",
+        "kernel",
+        "libdevel",
+        "libs",
+        "lisp",
+        "localization",
+        "mail",
+        "math",
+        "metapackages",
+        "misc",
+        "net",
+        "news",
+        "ocaml",
+        "oldlibs",
+        "otherosfs",
+        "perl",
+        "php",
+        "python",
+        "ruby",
+        "rust",
+        "science",
+        "shells",
+        "sound",
+        "tasks",
+        "tex",
+        "text",
+        "utils",
+        "vcs",
+        "video",
+        "virtual",
+        "web",
+        "x11",
+        "xfce",
+        "zope",
+    ]
+)
+
+ALL_COMPONENTS = frozenset(
+    [
+        "main",
+        "restricted",  # Ubuntu
+        "non-free",
+        "non-free-firmware",
+        "contrib",
+    ]
+)
+
+
+def _fields(*fields: F) -> Mapping[str, F]:
+    return {normalize_dctrl_field_name(f.name.lower()): f for f in fields}
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class Keyword:
+    value: str
+    hover_text: Optional[str] = None
+    is_obsolete: bool = False
+    replaced_by: Optional[str] = None
+
+
+def _allowed_values(*values: Union[str, Keyword]) -> Mapping[str, Keyword]:
+    as_keywords = (k if isinstance(k, Keyword) else Keyword(k) for k in values)
+    return {k.value: k for k in as_keywords}
+
+
+ALL_SECTIONS = _allowed_values(
+    *[
+        s if c is None else f"{c}/{s}"
+        for c, s in itertools.product(
+            itertools.chain(cast("Iterable[Optional[str]]", [None]), ALL_COMPONENTS),
+            ALL_SECTIONS_WITHOUT_COMPONENT,
+        )
+    ]
+)
+
+
+def all_architectures_and_wildcards(arch2table) -> Iterable[Union[str, Keyword]]:
+    wildcards = set()
+    yield Keyword(
+        "any",
+        hover_text=textwrap.dedent(
+            """\
+            The package is an architecture dependent package and need to be compiled for each and every
+            architecture it.
+
+            The name `any` refers to the fact that this is an architecture *wildcard* matching 
+            *any machine architecture* supported by dpkg.
+        """
+        ),
+    )
+    yield Keyword(
+        "all",
+        hover_text=textwrap.dedent(
+            """\
+            The package is an architecture independent package.  This is typically fitting for packages containing
+            only scripts, data or documentation.
+
+            This name `all` refers to the fact that the package can be used for *all* architectures at the same.
+            Though note that it is still subject to the rules of the `Multi-Arch` field.
+        """
+        ),
+    )
+    for arch_name, quad_tuple in arch2table.items():
+        yield arch_name
+        cpu_wc = "any-" + quad_tuple.cpu_name
+        os_wc = quad_tuple.os_name + "-any"
+        if cpu_wc not in wildcards:
+            yield cpu_wc
+            wildcards.add(cpu_wc)
+        if os_wc not in wildcards:
+            yield os_wc
+            wildcards.add(os_wc)
+        # Add the remaining wildcards
+
+
+@functools.lru_cache
+def dpkg_arch_and_wildcards() -> FrozenSet[str]:
+    dpkg_arch_table = DpkgArchTable.load_arch_table()
+    return frozenset(all_architectures_and_wildcards(dpkg_arch_table._arch2table))
+
+
+class FieldValueClass(Enum):
+    SINGLE_VALUE = auto()
+    SPACE_SEPARATED_LIST = auto()
+    BUILD_PROFILES_LIST = auto()
+    COMMA_SEPARATED_LIST = auto()
+    COMMA_SEPARATED_EMAIL_LIST = auto()
+    FREE_TEXT_FIELD = auto()
+    DEP5_FILE_LIST = auto()
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class Deb822KnownField:
+    name: str
+    field_value_class: FieldValueClass
+    warn_if_default: bool = True
+    replaced_by: Optional[str] = None
+    deprecated_with_no_replacement: bool = False
+    missing_field_severity: Optional[DiagnosticSeverity] = None
+    default_value: Optional[str] = None
+    known_values: Optional[Mapping[str, Keyword]] = None
+    unknown_value_diagnostic_severity: Optional[DiagnosticSeverity] = (
+        DiagnosticSeverity.Error
+    )
+    hover_text: Optional[str] = None
+    spellcheck_value: bool = False
+    is_stanza_name: bool = False
+    is_single_value_field: bool = True
+
+    def field_diagnostics(
+        self,
+        kvpair: Deb822KeyValuePairElement,
+        stanza_position: "TEPosition",
+        position_codec: "LintCapablePositionCodec",
+        lines: List[str],
+        *,
+        field_name_typo_reported: bool = False,
+    ) -> Iterable[Diagnostic]:
+        field_name_token = kvpair.field_token
+        field_range_te = kvpair.range_in_parent().relative_to(stanza_position)
+        field_position_te = field_range_te.start_pos
+        yield from self._diagnostics_for_field_name(
+            field_name_token,
+            field_position_te,
+            field_name_typo_reported,
+            position_codec,
+            lines,
+        )
+        if not self.spellcheck_value:
+            yield from self._known_value_diagnostics(
+                kvpair, field_position_te, position_codec, lines
+            )
+
+    def _diagnostics_for_field_name(
+        self,
+        token: Deb822FieldNameToken,
+        token_position: "TEPosition",
+        typo_detected: bool,
+        position_codec: "LintCapablePositionCodec",
+        lines: List[str],
+    ) -> Iterable[Diagnostic]:
+        field_name = token.text
+        # Defeat the case-insensitivity from python-debian
+        field_name_cased = str(field_name)
+        token_range_server_units = te_range_to_lsp(
+            TERange.from_position_and_size(token_position, token.size())
+        )
+        token_range = position_codec.range_to_client_units(
+            lines,
+            token_range_server_units,
+        )
+        if self.deprecated_with_no_replacement:
+            yield Diagnostic(
+                token_range,
+                f"{field_name_cased} is deprecated and no longer used",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_remove_line_quick_fix(),
+            )
+        elif self.replaced_by is not None:
+            yield Diagnostic(
+                token_range,
+                f"{field_name_cased} is a deprecated name for {self.replaced_by}",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_correct_text_quick_fix(self.replaced_by),
+            )
+
+        if not typo_detected and field_name_cased != self.name:
+            yield Diagnostic(
+                token_range,
+                f"Non-canonical spelling of {self.name}",
+                severity=DiagnosticSeverity.Information,
+                source="debputy",
+                data=propose_correct_text_quick_fix(self.name),
+            )
+
+    def _known_value_diagnostics(
+        self,
+        kvpair: Deb822KeyValuePairElement,
+        field_position_te: "TEPosition",
+        position_codec: "LintCapablePositionCodec",
+        lines: List[str],
+    ) -> Iterable[Diagnostic]:
+        unknown_value_severity = self.unknown_value_diagnostic_severity
+        allowed_values = self.known_values
+        if not allowed_values:
+            return
+        hint_text = None
+        values = kvpair.interpret_as(LIST_SPACE_SEPARATED_INTERPRETATION)
+        value_off = kvpair.value_element.position_in_parent().relative_to(
+            field_position_te
+        )
+        first_value = True
+        for value_ref in values.iter_value_references():
+            value = value_ref.value
+            if (
+                not first_value
+                and self.field_value_class == FieldValueClass.SINGLE_VALUE
+            ):
+                value_loc = value_ref.locatable
+                value_position_te = value_loc.position_in_parent().relative_to(
+                    value_off
+                )
+                value_range_in_server_units = te_range_to_lsp(
+                    TERange.from_position_and_size(value_position_te, value_loc.size())
+                )
+                value_range = position_codec.range_to_client_units(
+                    lines,
+                    value_range_in_server_units,
+                )
+                yield Diagnostic(
+                    value_range,
+                    f"The field {self.name} can only have exactly one value.",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                )
+                # TODO: Add quickfix if the value is also invalid
+                continue
+            first_value = False
+
+            known_value = self.known_values.get(value)
+            if known_value is None:
+                candidates = detect_possible_typo(
+                    value,
+                    self.known_values,
+                )
+                if hint_text is None:
+                    if len(self.known_values) < 5:
+                        values = ", ".join(sorted(self.known_values))
+                        hint_text = f" Known values for this field: {values}"
+                    else:
+                        hint_text = ""
+                fix_data = None
+                severity = unknown_value_severity
+                fix_text = hint_text
+                if candidates:
+                    match = candidates[0]
+                    fix_text = f' It is possible that the value is a typo of "{match}".{fix_text}'
+                    fix_data = [propose_correct_text_quick_fix(m) for m in candidates]
+                elif severity is None:
+                    continue
+                if severity is None:
+                    severity = DiagnosticSeverity.Warning
+                    message = fix_text
+                else:
+                    message = f'The value "{value}" is not supported in {self.name}.{fix_text}'
+            elif known_value.is_obsolete:
+                replacement = known_value.replaced_by
+                if replacement is not None:
+                    message = f'The value "{value}" has been replaced by {replacement}'
+                    severity = DiagnosticSeverity.Warning
+                    fix_data = [propose_correct_text_quick_fix(replacement)]
+                else:
+                    message = (
+                        f'The value "{value}" is obsolete without a single replacement'
+                    )
+                    severity = DiagnosticSeverity.Warning
+                    fix_data = None
+            else:
+                # All good
+                continue
+
+            value_loc = value_ref.locatable
+            value_position_te = value_loc.position_in_parent().relative_to(value_off)
+            value_range_in_server_units = te_range_to_lsp(
+                TERange.from_position_and_size(value_position_te, value_loc.size())
+            )
+            value_range = position_codec.range_to_client_units(
+                lines,
+                value_range_in_server_units,
+            )
+            yield Diagnostic(
+                value_range,
+                message,
+                severity=severity,
+                source="debputy",
+                data=fix_data,
+            )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DctrlKnownField(Deb822KnownField):
+    inherits_from_source: bool = False
+
+
+SOURCE_FIELDS = _fields(
+    DctrlKnownField(
+        "Source",
+        FieldValueClass.SINGLE_VALUE,
+        missing_field_severity=DiagnosticSeverity.Error,
+        is_stanza_name=True,
+        hover_text=textwrap.dedent(
+            """\
+            Declares the name of the source package.
+
+            Note this must match the name in the first entry of debian/changelog file.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Standards-Version",
+        FieldValueClass.SINGLE_VALUE,
+        missing_field_severity=DiagnosticSeverity.Error,
+        hover_text=textwrap.dedent(
+            """\
+                  Declares the last semantic version of the Debian Policy this package as last checked against.
+
+                  **Example*:
+                  ```
+                  Standards-Version: 4.5.2
+                  ```
+
+                  Note that the last version part of the full Policy version (the **.X** in 4.5.2**.X**) is
+                  typically omitted as it is used solely for editorial changes to the policy (e.g. typo fixes).
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Section",
+        FieldValueClass.SINGLE_VALUE,
+        known_values=ALL_SECTIONS,
+        unknown_value_diagnostic_severity=DiagnosticSeverity.Warning,
+        hover_text=textwrap.dedent(
+            """\
+                Define the default section for packages in this source package.
+
+                Example:
+                ```
+                Section: devel
+                ```
+
+                Please see https://packages.debian.org/unstable for more details about the sections.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Priority",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="optional",
+        warn_if_default=False,
+        known_values=_allowed_values(
+            Keyword(
+                "required",
+                hover_text=textwrap.dedent(
+                    """\
+                    The package is necessary for the proper functioning of the system (read: dpkg needs it).
+
+                    Applicable if dpkg *needs* this package to function and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "important",
+                hover_text=textwrap.dedent(
+                    """\
+                    The *important* packages are a bare minimum of commonly-expected and necessary tools.
+
+                    Applicable if 99% of all users in the distribution needs this package and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "standard",
+                hover_text=textwrap.dedent(
+                    """\
+                    These packages provide a reasonable small but not too limited character-mode system.  This is
+                    what will be installed by default (by the debian-installer) if the user does not select anything
+                    else.  This does not include many large applications.
+
+                    Applicable if your distribution installer will install this package by default on a new system
+                    and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "optional",
+                hover_text="This is the default priority and used by the majority of all packages"
+                " in the Debian archive",
+            ),
+            Keyword(
+                "extra",
+                is_obsolete=True,
+                replaced_by="optional",
+                hover_text="Obsolete alias of `optional`.",
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                    Define the default priority for packages in this source package.
+
+                    The priority field describes how important the package is for the functionality of the system.
+
+                    Example:
+                    ```
+                    Priority: optional
+                    ```
+
+                    Unless you know you need a different value, you should choose <b>optional</b> for your packages.
+                """
+        ),
+    ),
+    DctrlKnownField(
+        "Maintainer",
+        FieldValueClass.SINGLE_VALUE,
+        missing_field_severity=DiagnosticSeverity.Error,
+        hover_text=textwrap.dedent(
+            """\
+                  The maintainer of the package.
+
+                  **Example**:
+                  ```
+                  Maintainer: Jane Contributor <jane@janes.email-provider.org>
+                  ```
+
+                  Note: If a person is listed in the Maintainer field, they should *not* be listed in Uploaders field.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Uploaders",
+        FieldValueClass.COMMA_SEPARATED_EMAIL_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                  Comma separated list of uploaders associated with the package.
+
+                  **Example**:
+                  ```
+                  Uploaders:
+                   John Doe &lt;john@doe.org&gt;,
+                   Lisbeth Worker &lt;lis@worker.org&gt;,
+                  ```
+
+                  Formally uploaders are considered co-maintainers for the package with the party listed in the
+                  **Maintainer** field being the primary maintainer. In practice, each maintainer or maintenance
+                  team can have their own ruleset about the difference between the **Maintainer** and the
+                  **Uploaders**. As an example, the Python packaging team has a different rule set for how to
+                  react to a package depending on whether the packaging team is the **Maintainer** or in the
+                  **Uploaders** field.
+
+                  Note: If a person is listed in the Maintainer field, they should *not* be listed in Uploaders field.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Browser",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+                URL to the Version control system repo used for the packaging. The URL should be usable with a
+                browser *without* requiring any login.
+
+                This should be used together with one of the other **Vcs-** fields.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Git",
+        FieldValueClass.SPACE_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable with `git clone`
+                *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+
+                Note it is possible to specify a branch via the `-b` option.
+
+                ```
+                Vcs-Git: https://salsa.debian.org/some/packaging-repo -b debian/unstable
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Svn",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable with `svn checkout`
+                *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Arch",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable for getting a copy of the
+                sources *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Cvs",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable for getting a copy of the
+                sources *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Darcs",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable for getting a copy of the
+                sources *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Hg",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable for getting a copy of the
+                sources *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Vcs-Mtn",
+        FieldValueClass.SPACE_SEPARATED_LIST,  # TODO: Might be a single value
+        hover_text=textwrap.dedent(
+            """\
+                URL to the git repo used for the packaging. The URL should be usable for getting a copy of the
+                sources *without* requiring any login.
+
+                This should be used together with the **Vcs-Browser** field provided there is a web UI for the repo.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "DM-Upload-Allowed",
+        FieldValueClass.SINGLE_VALUE,
+        deprecated_with_no_replacement=True,
+        default_value="no",
+        known_values=_allowed_values("yes", "no"),
+        hover_text=textwrap.dedent(
+            """\
+                Obsolete field
+
+                It was used to enabling Debian Maintainers to upload the package without requiring a Debian Developer
+                to sign the package. This mechanism has been replaced by a new authorization mechanism.
+
+                Please see https://lists.debian.org/debian-devel-announce/2012/09/msg00008.html for details about the
+                replacement.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Depends",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                   All minimum build-dependencies for this source package. Needed for any target including **clean**.
+                   """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Depends-Arch",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Build-dependencies required for building the architecture dependent binary packages of this source
+                package.
+
+                These build-dependencies must be satisfied when executing the **build-arch** and **binary-arch**
+                targets either directly or indirectly in addition to those listed in **Build-Depends**.
+
+                Note that these dependencies are <em>not</em> available during **clean**.
+       """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Depends-Indep",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Build-dependencies required for building the architecture independent binary packages of this source
+                package.
+
+                These build-dependencies must be satisfied when executing the **build-indep** and **binary-indep**
+                targets either directly or indirectly in addition to those listed in **Build-Depends**.
+
+                Note that these dependencies are <em>not</em> available during **clean**.
+       """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Conflicts",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Packages that must **not** be installed during **any** part of the build, including the **clean**
+                target **clean**.
+
+                Where possible, it is often better to configure the build so that it does not react to the package
+                being present in the first place. Usually this is a question of using a `--without-foo` or
+                `--disable-foo` or such to the build configuration.
+       """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Conflicts-Arch",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Packages that must **not** be installed during the **build-arch** or **binary-arch** targets.
+                This also applies when these targets are run implicitly such as via the **binary** target.
+
+                Where possible, it is often better to configure the build so that it does not react to the package
+                being present in the first place. Usually this is a question of using a `--without-foo` or
+                `--disable-foo` or such to the build configuration.
+       """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Conflicts-Indep",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Packages that must **not** be installed during the **build-indep** or **binary-indep** targets.
+                This also applies when these targets are run implicitly such as via the **binary** target.
+
+                Where possible, it is often better to configure the build so that it does not react to the package
+                being present in the first place. Usually this is a question of using a `--without-foo` or
+                `--disable-foo` or such to the build configuration.
+       """
+        ),
+    ),
+    DctrlKnownField(
+        "Testsuite",
+        FieldValueClass.SPACE_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Declares that this package provides or should run install time tests via `autopkgtest`.
+
+                This field can be used to request an automatically generated autopkgtests via the **autodep8** package.
+                Please refer to the documentation of the **autodep8** package for which values you can put into
+                this field and what kind of testsuite the keywords will provide.
+
+                Declaring this field in *debian/control* is only necessary when you want additional tests beyond
+                those in *debian/tests/control* as **dpkg** automatically records the package provided ones from
+                *debian/tests/control*.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Homepage",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+                Link to the upstream homepage for this source package.
+
+                **Example**:
+                ```
+                Homepage: https://www.janes-tools.org/frob-cleaner
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Rules-Requires-Root",
+        FieldValueClass.SPACE_SEPARATED_LIST,
+        unknown_value_diagnostic_severity=None,
+        known_values=_allowed_values(
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                The build process will not require root or fakeroot during any step.  This enables
+                dpkg-buildpackage and debhelper to perform several optimizations during the build.
+
+                This is the default with dpkg-build-api at version 1 or later.
+        """
+                ),
+            ),
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                    The build process assumes that dpkg-buildpackage will run the relevant binary
+                    target with root or fakeroot. This was the historical default behaviour.
+
+                    This is the default with dpkg-build-api at version 0.
+        """
+                ),
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                Declare if and when the package build assumes it is run as root or fakeroot.
+
+                Most packages do not need to run as root or fakeroot and the legacy behaviour comes with a
+                performance cost. This field can be used to explicitly declare that the legacy behaviour is
+                unnecessary.
+
+                **Example:**
+                ```
+                Rules-Requires-Root: no
+                ```
+
+                Setting this field to `no` *can* cause the package to stop building if it requires root.
+                Depending on the situation, it might require some trivial or some complicated changes to fix that.
+                If it breaks and you cannot figure out how to fix it, then reset the field to `binary-targets`
+                and move on until you have time to fix it.
+
+                The default value for this field depends on the ``dpkg-build-api`` version. If the package
+                `` Build-Depends`` on ``dpkg-build-api (>= 1)`` or later, the default is ``no``. Otherwise,
+                the default is ``binary-target``
+
+                Note it is **not** possible to require running the package as "true root".
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Bugs",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+            Provide a custom bug tracker URL
+
+            This field is *not* used by packages uploaded to Debian or most derivatives as the distro tooling
+            has a default bugtracker built-in. It is primarily useful for third-party provided packages such
+            that bug reporting tooling can redirect the user to their bug tracker.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Origin",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+            Declare the origin of the package.
+
+            This field is *not* used by packages uploaded to Debian or most derivatives as the origin would
+            be the distribution. It is primarily useful for third-party provided packages as some tools will
+            detect this field.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "X-Python-Version",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        replaced_by="X-Python3-Version",
+        hover_text=textwrap.dedent(
+            """\
+            Obsolete field for declaring the supported Python2 versions
+
+            Since Python2 is no longer supported, this field is now redundant. For Python3, the field is
+            called **X-Python3-Version**.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "X-Python3-Version",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            # Too lazy to provide a better description
+            """\
+            For declaring the supported Python3 versions
+
+            This is used by the tools from `dh-python` package. Please see the documentation of that package
+            for when and how to use it.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "XS-Autobuild",
+        FieldValueClass.SINGLE_VALUE,
+        known_values=_allowed_values("yes"),
+        hover_text=textwrap.dedent(
+            """\
+            Used for non-free packages to denote that they may be auto-build on the Debian build infrastructure
+
+            Note that adding this field **must** be combined with following the instructions at
+            https://www.debian.org/doc/manuals/developers-reference/pkgs.html#non-free-buildd
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Description",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+        hover_text=textwrap.dedent(
+            """\
+            This field contains a human-readable description of the package. However, it is not used directly.
+
+            Binary packages can reference parts of it via the `${source:Synopsis}` and the
+            `${source:Extended-Description}` substvars. Without any of these substvars, the `Description` field
+            of the `Source` stanza remains unused.
+
+            The first line immediately after the field is called the *Synopsis* and is a short "noun-phrase"
+            intended to provide a one-line summary of a package. The lines after the **Synopsis** is known
+            as the **Extended Description** and is intended as a longer summary of a package.
+
+            **Example:**
+            ```
+            Description: documentation generator for Python projects
+              Sphinx is a tool for producing documentation for Python projects, using
+              reStructuredText as markup language.
+              .
+              Sphinx features:
+               * HTML, CHM, LaTeX output,
+               * Cross-referencing source code,
+               * Automatic indices,
+               * Code highlighting, using Pygments,
+               * Extensibility. Existing extensions:
+                 - automatic testing of code snippets,
+                 - including docstrings from Python modules.
+              .
+              Build-depend on sphinx if your package uses /usr/bin/sphinx-*
+              executables. Build-depend on python3-sphinx if your package uses
+              the Python API (for instance by calling python3 -m sphinx).
+            ```
+
+            The **Synopsis** is usually displayed in cases where there is limited space such as when reviewing
+            the search results from `apt search foo`.  It is often a good idea to imagine that the **Synopsis**
+            part is inserted into a sentence like "The package provides {{Synopsis-goes-here}}". The
+            **Extended Description** is a standalone description that should describe what the package does and
+            how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).
+            Please see https://www.debian.org/doc/debian-policy/ch-controlfields.html#description for more details
+            about the description field and suggestions for how to write it.
+            """
+        ),
+    ),
+)
+
+BINARY_FIELDS = _fields(
+    DctrlKnownField(
+        "Package",
+        FieldValueClass.SINGLE_VALUE,
+        is_stanza_name=True,
+        missing_field_severity=DiagnosticSeverity.Error,
+        hover_text="Declares the name of a binary package",
+    ),
+    DctrlKnownField(
+        "Package-Type",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="deb",
+        known_values=_allowed_values(
+            Keyword("deb", hover_text="The package will be built as a regular deb."),
+            Keyword(
+                "udeb",
+                hover_text="The package will be built as a micro-deb (also known as a udeb).  These are solely used by the debian-installer.",
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                **Special-purpose only**. *This field is a special purpose field and is rarely needed.*
+                *You are recommended to omit unless you know you need it or someone told you to use it.*
+
+                Determines the type of package.  This field can be used to declare that a given package is a different
+                type of package than usual.  The primary case where this is known to be useful is for building
+                micro-debs ("udeb") to be consumed by the debian-installer.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Architecture",
+        FieldValueClass.SPACE_SEPARATED_LIST,
+        missing_field_severity=DiagnosticSeverity.Error,
+        unknown_value_diagnostic_severity=None,
+        known_values=_allowed_values(*dpkg_arch_and_wildcards()),
+        hover_text=textwrap.dedent(
+            """\
+                Determines which architectures this package can be compiled for or if it is an architecture-independent
+                package.  The value is a space-separated list of dpkg architecture names or wildcards.
+
+                **Example**:
+                ```
+                Package: architecture-specific-package
+                Architecture: any
+                # ...
+
+
+                Package: data-only-package
+                Architecture: all
+                Multi-Arch: foreign
+                # ...
+
+
+                Package: linux-only-package
+                Architecture: linux-any
+                # ...
+                ```
+
+                When in doubt, stick to the values **all** (for scripts, data or documentation, etc.) or **any**
+                (for anything that can be compiled).  For official Debian packages, it is often easier to attempt the
+                compilation for unsupported architectures than to maintain the list of machine architectures that work.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Essential",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="no",
+        known_values=_allowed_values(
+            Keyword(
+                "yes",
+                hover_text="The package is essential and uninstalling it will completely and utterly break the"
+                " system beyond repair.",
+            ),
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                The package is a regular package.  This is the default and recommended.</p>
+
+                Note that declaring a package to be "Essential: no" is the same as not having the field except omitting
+                the field wastes fewer bytes on everyone's hard disk.
+            """
+                ),
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                **Special-purpose only**. *This field is a special purpose field and is rarely needed.*
+                *You are recommended to omit unless you know you need it or someone told you to use it.*
+
+                Whether the package should be considered Essential as defined by Debian Policy.
+
+                Essential packages are subject to several distinct but very important rules:
+
+                 * Essential packages are considered essential for the system to work.  The packaging system
+                   (APT and dpkg) will refuse to uninstall it without some very insisting force options and warnings.
+
+                 * Other packages are not required to declare explicit dependencies on essential packages as a
+                   side-effect of the above except as to ensure a that the given essential package is upgraded
+                   to a given minimum version.
+
+                 * Once installed, essential packages function must at all time no matter where dpkg is in its
+                   installation or upgrade process. During bootstrapping or installation, this requirement is
+                   relaxed.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "XB-Important",
+        FieldValueClass.SINGLE_VALUE,
+        replaced_by="Protected",
+        default_value="no",
+        known_values=_allowed_values(
+            Keyword(
+                "yes",
+                hover_text="The package is protected and attempts to uninstall it will cause strong warnings to the"
+                " user that they might be breaking the system.",
+            ),
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                    The package is a regular package.  This is the default and recommended.</p>
+
+                    Note that declaring a package to be `XB-Important: no` is the same as not having the field
+                    except omitting the field wastes fewer bytes on everyone's hard-disk.
+            """
+                ),
+            ),
+        ),
+    ),
+    DctrlKnownField(
+        "Protected",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="no",
+        known_values=_allowed_values(
+            Keyword(
+                "yes",
+                hover_text="The package is protected and attempts to uninstall it will cause strong warnings to the"
+                " user that they might be breaking the system.",
+            ),
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                    The package is a regular package.  This is the default and recommended.</p>
+
+                    Note that declaring a package to be `Protected: no` is the same as not having the field
+                    except omitting the field wastes fewer bytes on everyone's hard-disk.
+            """
+                ),
+            ),
+        ),
+    ),
+    DctrlKnownField(
+        "Pre-Depends",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+              **Advanced field**. *This field covers an advanced topic.  If you are new to packaging, you are*
+              *probably not looking for this field (except to set a **${misc:Pre-Depends}** relation.  Incorrect use*
+              *of this field can cause issues - among other causing issues during upgrades that users cannot work*
+              *around without passing `--force-*` options to dpkg.*
+
+              This field is like *Depends*, except that is also forces dpkg to complete installation of the packages
+              named before even starting the installation of the package which declares the pre-dependency.
+
+              **Example**:
+              ```
+              Pre-Depends: ${misc:Pre-Depends}
+              ```
+
+              Note this is a very strong dependency and not all packages support being a pre-dependency because it
+              puts additional requirements on the package being depended on. Use of **${misc:Pre-Depends}** is
+              pre-approved and recommended. Essential packages are known to support being in **Pre-Depends**.
+              However, careless use of **Pre-Depends** for essential packages can still cause dependency resolvers
+              problems.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Depends",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+              Lists the packages that must be installed, before this package is installed.
+
+              **Example**:
+              ```
+              Package: foo
+              Architecture: any
+              Depends: ${misc:Depends},
+                       ${shlibs:Depends},
+                       libfoo1 (= ${binary:Version}),
+                       foo-data (= ${source:Version}),
+              ```
+
+              This field declares an absolute dependency. Before installing the package, **dpkg** will require
+              all dependencies to be in state `configured` first. Though, if there is a circular dependency between
+              two or more packages, **dpkg** will break that circle at an arbitrary point where necessary based on
+              built-in heuristics.
+
+              This field should be used if the depended-on package is required for the depending package to provide a
+              *significant amount of functionality* or when it is used in the **postinst** or **prerm** maintainer
+              scripts.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Recommends",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Lists the packages that *should* be installed when this package is installed in all but
+                *unusual installations*.</p>
+
+                **Example**:
+                ```
+                Recommends: foo-optional
+                ```
+
+                By default, APT will attempt to install recommends unless they cannot be installed or the user
+                has configured APT skip recommends. Notably, during automated package builds for the Debian
+                archive, **Recommends** are **not** installed.
+
+                As implied, the package must have some core functionality that works **without** the
+                **Recommends** being satisfied as they are not guaranteed to be there.  If the package cannot
+                provide any functionality without a given package, that package should be in **Depends**.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Suggests",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                Lists the packages that may make this package more useful but not installing them is perfectly
+                reasonable as well. Suggests can also be useful for add-ons that only make sense in particular
+                corner cases like supporting a non-standard file format.
+
+                **Example**:
+                ```
+                Suggests: bar
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Enhances",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                This field is similar to Suggests but works in the opposite direction.  It is used to declare that
+                this package can enhance the functionality of another package.
+
+                **Example**:
+                ```
+                Package: foo
+                Provide: debputy-plugin-foo
+                Enhances: debputy
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Provides",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                  Declare this package also provide one or more other packages.  This means that this package can
+                  substitute for the provided package in some relations.
+
+                  *Example*:
+                  ```
+                  Package: foo
+                  ...
+
+                  Package: foo-plus
+                  Provides: foo (= ${source:Upstream-Version})
+                  ```
+
+                  If the provides relation is versioned, it must use a "strictly equals" version.  If it does not
+                  declare a version, then it *cannot* be used to satisfy a dependency with a version restriction.
+                  Consider the following example:
+
+                  **Archive scenario*:  (This is *not* a debian/control file, despite the resemblance)
+                  ```
+                  Package foo
+                  Depends: bar (>= 1.0)
+
+                  Package: bar
+                  Version: 0.9
+
+                  Package: bar-plus
+                  Provides: bar (= 1.0)
+
+                  Package: bar-clone
+                  Provides: bar
+                  ```
+
+                  In this archive scenario, the `bar-plus` package will satisfy the dependency of `foo` as the
+                  only one. The `bar` package fails because the version is only *0.9* and `bar-clone` because
+                  the provides is unversioned, but the dependency clause is versioned.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Conflicts",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                  **Warning**: *You may be looking for Breaks instead of Conflicts*.
+
+                  This package cannot be installed together with the packages listed in the Conflicts field.  This
+                  is a *bigger hammer* than **Breaks** and is used sparingly.  Notably, if you want to do a versioned
+                  **Conflicts** then you *almost certainly* want **Breaks** instead.
+
+                  **Example**:
+                  ```
+                  Conflicts: bar
+                  ```
+
+                  Please check the description of the **Breaks** field for when you would use **Breaks** vs.
+                  **Conflicts**.
+
+                  Note if a package conflicts with itself (indirectly or via **Provides**), then it is using a
+                  special rule for **Conflicts**.  See section
+                  7.6.2 "[Replacing whole packages, forcing their removal]" in the Debian Policy Manual.
+
+                  [Replacing whole packages, forcing their removal]: https://www.debian.org/doc/debian-policy/ch-relationships.html#replacing-whole-packages-forcing-their-removal
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Breaks",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+      This package cannot be installed together with the packages listed in the `Breaks` field.
+
+      This is often use to declare versioned issues such as "This package does not work with foo if
+      it is version 1.0 or less". In comparison, `Conflicts` is generally used to declare that
+      "This package does not work at all as long as foo is installed".
+
+      **Example**:
+      ```
+      Breaks: bar (<= 1.0~)
+      ````
+
+      **Breaks vs. Conflicts**:
+
+       * I moved files from **foo** to **bar** in version X, what should I do?
+
+         Add `Breaks: foo (<< X~)` + `Replaces: foo (<< X~)` to **bar**
+
+       * Upgrading **bar** while **foo** is version X or less causes problems **foo** or **bar** to break.
+         How do I solve this?
+
+         Add `Breaks: foo (<< X~)` to **bar**
+
+       * The **foo** and **bar** packages provide the same functionality (interface) but different
+         implementations and there can be at most one of them. What should I do?
+
+         See section 7.6.2 [Replacing whole packages, forcing their removal] in the Debian Policy Manual.
+
+       * How to handle when **foo** and **bar** packages are unrelated but happen to provide the same binary?
+
+         Attempt to resolve the name conflict by renaming the clashing files in question on either (or both) sides.
+
+      Note the use of *~* in version numbers in the answers are generally used to ensure this works correctly in
+      case of a backports (in the Debian archive), where the package is rebuilt with the "~bpo" suffix in its
+      version.
+
+      [Replacing whole packages, forcing their removal]: https://www.debian.org/doc/debian-policy/ch-relationships.html#replacing-whole-packages-forcing-their-removal
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Replaces",
+        FieldValueClass.COMMA_SEPARATED_LIST,
+        hover_text=textwrap.dedent(
+            """\
+                  This package either replaces another package or overwrites files that used to be provided by
+                  another package.
+
+                  **Attention**: The `Replaces` field is **always** used with either `Breaks` or `Conflicts` field.
+
+                  **Example**:
+                  ```
+                  Package: foo
+                  ...
+
+                  # The foo package was split to move data files into foo-data in version 1.2-3
+                  Package: foo-data
+                  Replaces: foo (<< 1.2-3~)
+                  Breaks: foo (<< 1.2-3~)
+                  ```
+
+                  Please check the description of the `Breaks` field for when you would use `Breaks` vs. `Conflicts`.
+                  It also covers common uses of `Replaces`.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Build-Profiles",
+        FieldValueClass.BUILD_PROFILES_LIST,
+        hover_text=textwrap.dedent(
+            """\
+      **Advanced field**. *This field covers an advanced topic. If you are new to packaging, you are*
+      *advised to leave it at its default until you have a working basic package or lots of time to understand*
+      *this topic.*
+
+      Declare that the package will only built when the given build-profiles are satisfied.
+
+      This field is primarily used in combination with build profiles inside the build dependency related fields
+      to reduce the number of build dependencies required during bootstrapping of a new architecture.
+
+      **Example*:
+      ```
+      Package: foo
+      ...
+
+      Package: foo-udeb
+      Package-Type: udeb
+      # Skip building foo-udeb when the build profile "noudeb" is set (e.g., via dpkg-buildpackage -Pnoudeb)
+      Build-Profiles: <!noudeb>
+      ```
+
+      Note that there is an official list of "common" build profiles with predefined purposes along with rules
+      for how and when the can be used. This list can be found at
+      https://wiki.debian.org/BuildProfileSpec#Registered_profile_names.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Section",
+        FieldValueClass.SINGLE_VALUE,
+        missing_field_severity=DiagnosticSeverity.Error,
+        inherits_from_source=True,
+        known_values=ALL_SECTIONS,
+        unknown_value_diagnostic_severity=DiagnosticSeverity.Warning,
+        hover_text=textwrap.dedent(
+            """\
+                Define the section for this package.
+
+                Example:
+                ```
+                Section: devel
+                ```
+
+                Please see https://packages.debian.org/unstable for more details about the sections.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Priority",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="optional",
+        warn_if_default=False,
+        missing_field_severity=DiagnosticSeverity.Error,
+        inherits_from_source=True,
+        known_values=_allowed_values(
+            Keyword(
+                "required",
+                hover_text=textwrap.dedent(
+                    """\
+                    The package is necessary for the proper functioning of the system (read: dpkg needs it).
+
+                    Applicable if dpkg *needs* this package to function and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "important",
+                hover_text=textwrap.dedent(
+                    """\
+                    The *important* packages are a bare minimum of commonly-expected and necessary tools.
+
+                    Applicable if 99% of all users in the distribution needs this package and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "standard",
+                hover_text=textwrap.dedent(
+                    """\
+                    These packages provide a reasonable small but not too limited character-mode system.  This is
+                    what will be installed by default (by the debian-installer) if the user does not select anything
+                    else.  This does not include many large applications.
+
+                    Applicable if your distribution installer will install this package by default on a new system
+                    and it is not a library.
+
+                    No two packages that both have a priority of *standard* or higher may conflict with
+                    each other.
+                """
+                ),
+            ),
+            Keyword(
+                "optional",
+                hover_text="This is the default priority and used by the majority of all packages"
+                " in the Debian archive",
+            ),
+            Keyword(
+                "extra",
+                is_obsolete=True,
+                replaced_by="optional",
+                hover_text="Obsolete alias of `optional`.",
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                    Define the priority this package.
+
+                    The priority field describes how important the package is for the functionality of the system.
+
+                    Example:
+                    ```
+                    Priority: optional
+                    ```
+
+                    Unless you know you need a different value, you should choose <b>optional</b> for your packages.
+                """
+        ),
+    ),
+    DctrlKnownField(
+        "Multi-Arch",
+        FieldValueClass.SINGLE_VALUE,
+        # Explicit "no" tends to be used as "someone reviewed this and concluded no", so we do
+        # not warn about it being explicitly "no".
+        warn_if_default=False,
+        default_value="no",
+        known_values=_allowed_values(
+            Keyword(
+                "no",
+                hover_text=textwrap.dedent(
+                    """\
+                    The default. The package can be installed for at most one architecture at the time.  It can
+                    *only* satisfy relations for the same architecture as itself. Note that `Architecture: all`
+                    packages are considered as a part of the system's "primary" architecture (see output of
+                    `dpkg --print-architecture`).
+
+                    Note: Despite the "no", the package *can* be installed for a foreign architecture (as an example,
+                    you can install a 32-bit version of a package on a 64-bit system).  However, packages depending
+                    on it must also be installed for the foreign architecture.
+                """
+                ),
+            ),
+            Keyword(
+                "foreign",
+                hover_text=textwrap.dedent(
+                    """\
+                    The package can be installed for at most one architecture at the time.  However, it can
+                    satisfy relations for packages regardless of their architecture.  This is often useful for packages
+                    solely providing data or binaries that have "Multi-Arch neutral interfaces".
+
+                    Sadly, describing a "Multi-Arch neutral interface" is hard and often only done by Multi-Arch
+                    experts on a case-by-case basis.  Some programs and scripts have "Multi-Arch dependent interfaces"
+                    and are not safe to declare as `Multi-Arch: foreign`.
+
+                    The name "foreign" refers to the fact that the package can satisfy relations for native
+                    *and foreign* architectures at the same time.
+                """
+                ),
+            ),
+            Keyword(
+                "same",
+                hover_text=textwrap.dedent(
+                    """\
+                    The same version of the package can be co-installed for multiple architecture. However,
+                    for this to work, the package *must* ship all files in architecture unique paths (usually
+                    beneath `/usr/lib/<DEB_HOST_MULTIARCH>`) or have bit-for-bit identical content
+                    in files that are in non-architecture unique paths (such as files beneath `/usr/share/doc`).
+
+                    The name `same` refers to the fact that the package can satisfy relations only for the `same`
+                    architecture as itself.  However, in this case, it is co-installable with itself as noted above.
+                    Note: This value **cannot** be used with `Architecture: all`.
+                """
+                ),
+            ),
+            Keyword(
+                "allowed",
+                hover_text=textwrap.dedent(
+                    """\
+                  **Advanced value**.  The package is *not* co-installable with itself but can satisfy Multi-Arch
+                  foreign and Multi-Arch same relations at the same.  This is useful for implementations of
+                  scripting languages (such as Perl or Python).  Here the interpreter contextually need to
+                  satisfy some relations as `Multi-Arch: foreign` and others as `Multi-Arch: same`.
+
+                  Typically, native extensions or plugins will need a `Multi-Arch: same`-relation as they only
+                  work with the interpreter compiled for the same machine architecture as themselves whereas
+                  scripts are usually less picky and can rely on the `Multi-Arch: foreign` relation.  Packages
+                  wanting to rely on the "Multi-Arch: foreign" interface must explicitly declare this adding a
+                  `:any` suffix to the package name in the dependency relation (e.g. `Depends: python3:any`).
+                  However, the `:any"`suffix cannot be used unconditionally and should not be used unless you
+                  know you need it.
+            """
+                ),
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+      **Advanced field**. *This field covers an advanced topic. If you are new to packaging, you are*
+      *advised to leave it at its default until you have a working basic package or lots of time to understand*
+      *this topic.*
+
+      This field is used to declare the Multi-Arch interface of the package.
+
+      The `Multi-Arch` field is used to inform the installation system (APT and dpkg) about how it should handle
+      dependency relations involving this package and foreign architectures. This is useful for multiple purposes
+      such as cross-building without emulation and installing 32-bit packages on a 64-bit system. The latter is
+      often done to use legacy apps or old games that was never ported to 64-bit machines.
+
+      **Example**:
+      ```
+      Multi-Arch: foreign
+      ```
+
+      The rules for `Multi-Arch` can be quite complicated, but in many cases the following simple rules of thumb
+      gets you a long way:
+
+       * If the [Multi-Arch hinter] comes with a hint, then it almost certainly correct. You are recommended
+         to check the hint for further details (some changes can be complicated to do).  Note that the
+         Multi-Arch hinter is only run for official Debian packages and may not be applicable to your case.
+
+       * If you have an `Architecture: all` data-only package, then it often want to be `Multi-Arch: foreign`
+
+       * If you have an architecture dependent package, where everything is installed in
+         `/usr/lib/${DEB_HOST_MULTIARCH}` (plus a bit of standard documentation in `/usr/share/doc`), then
+         you *probably* want `Multi-Arch: same`
+
+       * If none of the above applies, then omit the field unless you know what you are doing or you are
+         receiving advice from a Multi-Arch expert.
+
+
+      There are 4 possible values for the Multi-Arch field, though not all values are applicable to all packages:
+
+
+        * `no` - The default. The package can be installed for at most one architecture at the time.  It can
+          *only* satisfy relations for the same architecture as itself. Note that `Architecture: all` packages
+          are considered as a part of the system's "primary" architecture (see output of `dpkg --print-architecture`).
+
+          Use of an explicit `no` over omitting the field is commonly done to signal that someone took the
+          effort to understand the situation and concluded `no` was the right answer.
+
+          Note: Despite the `no`, the package *can* be installed for a foreign architecture (e.g. you can
+          install a 32-bit version of a package on a 64-bit system).  However, packages depending on it must also
+          be installed for the foreign architecture.
+
+
+        * `foreign` - The package can be installed for at most one architecture at the time.  However, it can
+          satisfy relations for packages regardless of their architecture.  This is often useful for packages
+          solely providing data or binaries that have "Multi-Arch neutral interfaces". Sadly, describing
+          a "Multi-Arch neutral interface" is hard and often only done by Multi-Arch experts on a case-by-case
+          basis. Among other, scripts despite being the same on all architectures can still have a "non-neutral"
+          "Multi-Arch" interface if their output is architecture dependent or if they dependencies force them
+          out of the `foreign` role. The dependency issue usually happens when depending indirectly on an
+          `Multi-Arch: allowed` package.
+
+          Some programs are have "Multi-Arch dependent interfaces" and are not safe to declare as
+          `Multi-Arch: foreign`. The name `foreign` refers to the fact that the package can satisfy relations
+          for native *and foreign* architectures at the same time.
+
+
+        * `same` - The same version of the package can be co-installed for multiple architecture. However,
+          for this to work, the package **must** ship all files in architecture unique paths (usually
+          beneath `/usr/lib/${DEB_HOST_MULTIARCH}`) **or** have bit-for-bit identical content in files
+          that are in non-architecture unique paths (e.g. `/usr/share/doc`). Note that these packages
+          typically do not contain configuration files or **dpkg** `conffile`s.
+
+          The name `same` refers to the fact that the package can satisfy relations only for the "same"
+          architecture as itself.  However, in this case, it is co-installable with itself as noted above.
+
+          Note: This value **cannot** be used with `Architecture: all`.
+
+
+        * `allowed` - **Advanced value**. This value is for a complex use-case that most people does not
+          need. Consider it only if none of the other values seem to do the trick.
+
+          The package is **NOT** co-installable with itself but can satisfy Multi-Arch foreign and Multi-Arch same
+          relations at the same. This is useful for implementations of scripting languages (e.g. Perl or Python).
+          Here the interpreter contextually need to satisfy some relations as `Multi-Arch: foreign` and others as
+          `Multi-Arch: same` (or `Multi-Arch: no`).
+
+          Typically, native extensions or plugins will need a `Multi-Arch: same`-relation as they only work with
+          the interpreter compiled for the same machine architecture as themselves whereas scripts are usually
+          less picky and can rely on the `Multi-Arch: foreign` relation.  Packages wanting to rely on the
+          `Multi-Arch: foreign` interface must explicitly declare this adding a `:any` suffix to the package name
+          in the dependency relation (such as `Depends: python3:any`).  However, the `:any` suffix cannot be used
+          unconditionally and should not be used unless you know you need it.
+
+          Note that depending indirectly on a `Multi-Arch: allowed` package can require a `Architecture: all` +
+          `Multi-Arch: foreign` package to be converted to a `Architecture: any` package. This case is named
+          the "Multi-Arch interpreter problem", since it is commonly seen with script interpreters. However,
+          despite the name, it can happen to any kind of package. The bug [Debian#984701] is an example of
+          this happen in practice.
+
+      [Multi-Arch hinter]: https://wiki.debian.org/MultiArch/Hints
+      [Debian#984701]: https://bugs.debian.org/984701
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "X-DH-Build-For-Type",
+        FieldValueClass.SINGLE_VALUE,
+        default_value="host",
+        known_values=_allowed_values(
+            Keyword(
+                "host",
+                hover_text="The package should be compiled for `DEB_HOST_TARGET` (the default).",
+            ),
+            Keyword(
+                "target",
+                hover_text="The package should be compiled for `DEB_TARGET_ARCH`.",
+            ),
+        ),
+        hover_text=textwrap.dedent(
+            """\
+                  **Special-purpose only**. *This field is a special purpose field and is rarely needed.*
+                  *You are recommended to omit unless you know you need it or someone told you to use it.*
+
+                  This field is used when building a cross-compiling C-compiler (or similar cases), some packages need
+                  to be build for target (DEB_**TARGET**_ARCH) rather than the host (DEB_**HOST**_ARCH) architecture.
+
+                  **Example**:
+                  ```
+                  Package: gcc
+                  Architecture: any
+                  # ...
+
+                  Package: libgcc-s1
+                  Architecture: any
+                  # When building a cross-compiling gcc, then this library needs to be built for the target architecture
+                  # as binaries compiled by gcc will link with this library.
+                  X-DH-Build-For-Type: target
+                  # ...
+                  ```
+
+                  If you are in doubt, then you probably do **not** need this field.
+                """
+        ),
+    ),
+    DctrlKnownField(
+        "X-Time64-Compat",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+                Special purpose field renamed to the 64-bit time transition.
+
+                It is used to inform packaging helpers what the original (non-transitioned) package name
+                was when the auto-detection is inadequate. The non-transitioned package name is then
+                conditionally provided in the `${t64:Provides}` substitution variable.
+                """
+        ),
+    ),
+    DctrlKnownField(
+        "Homepage",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+                Link to the upstream homepage for this binary package.
+
+                This field is rarely used in Package stanzas as most binary packages should have the
+                same homepage as the source package. Though, in the exceptional case where a particular
+                binary package should have a more specific homepage than the source package, you can
+                use this field to override the source package field.
+                ```
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "Description",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+        # It will build just fine. But no one will know what it is for, so it probably won't be installed
+        missing_field_severity=DiagnosticSeverity.Warning,
+        hover_text=textwrap.dedent(
+            """\
+            A human-readable description of the package. This field consists of two related but distinct parts.
+
+
+            The first line immediately after the field is called the *Synopsis* and is a short "noun-phrase"
+            intended to provide a one-line summary of the package. The lines after the **Synopsis** is known
+            as the **Extended Description** and is intended as a longer summary of the package.
+
+            **Example:**
+            ```
+            Description: documentation generator for Python projects
+              Sphinx is a tool for producing documentation for Python projects, using
+              reStructuredText as markup language.
+              .
+              Sphinx features:
+               * HTML, CHM, LaTeX output,
+               * Cross-referencing source code,
+               * Automatic indices,
+               * Code highlighting, using Pygments,
+               * Extensibility. Existing extensions:
+                 - automatic testing of code snippets,
+                 - including docstrings from Python modules.
+              .
+              Build-depend on sphinx if your package uses /usr/bin/sphinx-*
+              executables. Build-depend on python3-sphinx if your package uses
+              the Python API (for instance by calling python3 -m sphinx).
+            ```
+
+            The **Synopsis** is usually displayed in cases where there is limited space such as when reviewing
+            the search results from `apt search foo`.  It is often a good idea to imagine that the **Synopsis**
+            part is inserted into a sentence like "The package provides {{Synopsis-goes-here}}". The
+            **Extended Description** is a standalone description that should describe what the package does and
+            how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).
+            Please see https://www.debian.org/doc/debian-policy/ch-controlfields.html#description for more details
+            about the description field and suggestions for how to write it.
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "XB-Cnf-Visible-Pkgname",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+            **Special-case field**: *This field is only useful in very special circumstances.*
+            *Consider whether you truly need it before adding this field.*
+
+            This field is used by `command-not-found` and can be used to override which package
+            `command-not-found` should propose the user to install.
+
+            Normally, when `command-not-found` detects a missing command, it will suggest the
+            user to install the package name listed in the `Package` field. In most cases, this
+            is what you want. However, in certain special-cases, the binary is provided by a
+            minimal package for technical reasons (like `python3-minimal`) and the user should
+            really install a package that provides more features (such as `python3` to follow
+            the example).
+
+            **Example**:
+            ```
+            Package: python3-minimal
+            XB-Cnf-Visible-Pkgname: python3
+            ```
+
+            Related bug: https://bugs.launchpad.net/ubuntu/+source/python-defaults/+bug/1867157
+            """
+        ),
+    ),
+    DctrlKnownField(
+        "X-DhRuby-Root",
+        FieldValueClass.SINGLE_VALUE,
+        hover_text=textwrap.dedent(
+            """\
+            Used by `dh_ruby` to request "multi-binary" layout and where the root for the given
+            package is.
+
+            Please refer to the documentation of `dh_ruby` for more details.
+
+            https://manpages.debian.org/dh_ruby
+            """
+        ),
+    ),
+)
+_DEP5_HEADER_FIELDS = _fields(
+    Deb822KnownField(
+        "Format",
+        FieldValueClass.SINGLE_VALUE,
+        is_stanza_name=True,
+        missing_field_severity=DiagnosticSeverity.Error,
+    ),
+    Deb822KnownField(
+        "Upstream-Name",
+        FieldValueClass.FREE_TEXT_FIELD,
+    ),
+    Deb822KnownField(
+        "Upstream-Contract",
+        FieldValueClass.FREE_TEXT_FIELD,
+    ),
+    Deb822KnownField(
+        "Source",
+        FieldValueClass.FREE_TEXT_FIELD,
+    ),
+    Deb822KnownField(
+        "Disclaimer",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+    ),
+    Deb822KnownField(
+        "Comment",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+    ),
+    Deb822KnownField(
+        "License",
+        FieldValueClass.FREE_TEXT_FIELD,
+        # Do not tempt people to change legal text because the spellchecker wants to do a typo fix.
+        spellcheck_value=False,
+    ),
+)
+_DEP5_FILES_FIELDS = _fields(
+    Deb822KnownField(
+        "Files",
+        FieldValueClass.DEP5_FILE_LIST,
+        is_stanza_name=True,
+        missing_field_severity=DiagnosticSeverity.Error,
+    ),
+    Deb822KnownField(
+        "Copyright",
+        FieldValueClass.FREE_TEXT_FIELD,
+        # Mostly going to be names with very little free-text; high risk of false positives with low value
+        spellcheck_value=False,
+        missing_field_severity=DiagnosticSeverity.Error,
+    ),
+    Deb822KnownField(
+        "License",
+        FieldValueClass.FREE_TEXT_FIELD,
+        missing_field_severity=DiagnosticSeverity.Error,
+        # Do not tempt people to change legal text because the spellchecker wants to do a typo fix.
+        spellcheck_value=False,
+    ),
+    Deb822KnownField(
+        "Comment",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+    ),
+)
+_DEP5_LICENSE_FIELDS = _fields(
+    Deb822KnownField(
+        "License",
+        FieldValueClass.FREE_TEXT_FIELD,
+        is_stanza_name=True,
+        # Do not tempt people to change legal text because the spellchecker wants to do a typo fix.
+        spellcheck_value=False,
+        missing_field_severity=DiagnosticSeverity.Error,
+    ),
+    Deb822KnownField(
+        "Comment",
+        FieldValueClass.FREE_TEXT_FIELD,
+        spellcheck_value=True,
+    ),
+)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class StanzaMetadata(Mapping[str, F], Generic[F], ABC):
+    stanza_type_name: str
+    stanza_fields: Mapping[str, F]
+
+    def stanza_diagnostics(
+        self,
+        stanza: Deb822ParagraphElement,
+        stanza_position_in_file: "TEPosition",
+    ) -> Iterable[Diagnostic]:
+        raise NotImplementedError
+
+    def __getitem__(self, key: str) -> F:
+        key_lc = key.lower()
+        key_norm = normalize_dctrl_field_name(key_lc)
+        return self.stanza_fields[key_norm]
+
+    def __len__(self) -> int:
+        return len(self.stanza_fields)
+
+    def __iter__(self):
+        return iter(self.stanza_fields.keys())
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class Dep5StanzaMetadata(StanzaMetadata[Deb822KnownField]):
+    def stanza_diagnostics(
+        self,
+        stanza: Deb822ParagraphElement,
+        stanza_position_in_file: "TEPosition",
+    ) -> Iterable[Diagnostic]:
+        pass
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DctrlStanzaMetadata(StanzaMetadata[DctrlKnownField]):
+
+    def stanza_diagnostics(
+        self,
+        stanza: Deb822ParagraphElement,
+        stanza_position_in_file: "TEPosition",
+    ) -> Iterable[Diagnostic]:
+        pass
+
+
+class Deb822FileMetadata(Generic[S]):
+    def classify_stanza(self, stanza: Deb822ParagraphElement, stanza_idx: int) -> S:
+        return self.guess_stanza_classification_by_idx(stanza_idx)
+
+    def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S:
+        raise NotImplementedError
+
+    def stanza_types(self) -> Iterable[S]:
+        raise NotImplementedError
+
+    def __getitem__(self, item: str) -> S:
+        raise NotImplementedError
+
+    def file_diagnostics(
+        self,
+        file: Deb822FileElement,
+    ) -> Iterable[Diagnostic]:
+        raise NotImplementedError
+
+    def get(self, item: str) -> Optional[S]:
+        try:
+            return self[item]
+        except KeyError:
+            return None
+
+
+_DCTRL_SOURCE_STANZA = DctrlStanzaMetadata(
+    "Source",
+    SOURCE_FIELDS,
+)
+_DCTRL_PACKAGE_STANZA = DctrlStanzaMetadata("Package", BINARY_FIELDS)
+
+_DEP5_HEADER_STANZA = Dep5StanzaMetadata(
+    "Header",
+    _DEP5_HEADER_FIELDS,
+)
+_DEP5_FILES_STANZA = Dep5StanzaMetadata(
+    "Files",
+    _DEP5_FILES_FIELDS,
+)
+_DEP5_LICENSE_STANZA = Dep5StanzaMetadata(
+    "License",
+    _DEP5_LICENSE_FIELDS,
+)
+
+
+class Dep5FileMetadata(Deb822FileMetadata[Dep5StanzaMetadata]):
+    def classify_stanza(self, stanza: Deb822ParagraphElement, stanza_idx: int) -> S:
+        if stanza_idx == 0:
+            return _DEP5_HEADER_STANZA
+        if stanza_idx > 0:
+            if "Files" in stanza:
+                return _DEP5_FILES_STANZA
+            return _DEP5_LICENSE_STANZA
+        raise ValueError("The stanza_idx must be 0 or greater")
+
+    def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S:
+        if stanza_idx == 0:
+            return _DEP5_HEADER_STANZA
+        if stanza_idx > 0:
+            return _DEP5_FILES_STANZA
+        raise ValueError("The stanza_idx must be 0 or greater")
+
+    def stanza_types(self) -> Iterable[S]:
+        yield _DEP5_HEADER_STANZA
+        yield _DEP5_FILES_STANZA
+        yield _DEP5_LICENSE_STANZA
+
+    def __getitem__(self, item: str) -> S:
+        if item == "Header":
+            return _DEP5_FILES_STANZA
+        if item == "Files":
+            return _DEP5_FILES_STANZA
+        if item == "License":
+            return _DEP5_LICENSE_STANZA
+        raise KeyError(item)
+
+
+class DctrlFileMetadata(Deb822FileMetadata[DctrlStanzaMetadata]):
+    def guess_stanza_classification_by_idx(self, stanza_idx: int) -> S:
+        if stanza_idx == 0:
+            return _DCTRL_SOURCE_STANZA
+        if stanza_idx > 0:
+            return _DCTRL_PACKAGE_STANZA
+        raise ValueError("The stanza_idx must be 0 or greater")
+
+    def stanza_types(self) -> Iterable[S]:
+        yield _DCTRL_SOURCE_STANZA
+        yield _DCTRL_PACKAGE_STANZA
+
+    def __getitem__(self, item: str) -> S:
+        if item == "Source":
+            return _DCTRL_SOURCE_STANZA
+        if item == "Package":
+            return _DCTRL_PACKAGE_STANZA
+        raise KeyError(item)
diff --git a/src/debputy/lsp/lsp_debian_copyright.py b/src/debputy/lsp/lsp_debian_copyright.py
new file mode 100644
index 0000000..052654a
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_copyright.py
@@ -0,0 +1,685 @@
+import re
+from typing import (
+    Union,
+    Sequence,
+    Tuple,
+    Iterator,
+    Optional,
+    Iterable,
+    Mapping,
+    List,
+)
+
+from debputy.lsp.vendoring._deb822_repro import (
+    parse_deb822_file,
+    Deb822FileElement,
+    Deb822ParagraphElement,
+)
+from debputy.lsp.vendoring._deb822_repro.parsing import (
+    Deb822KeyValuePairElement,
+    LIST_SPACE_SEPARATED_INTERPRETATION,
+)
+from debputy.lsp.vendoring._deb822_repro.tokens import (
+    Deb822Token,
+    tokenize_deb822_file,
+    Deb822FieldNameToken,
+)
+from lsprotocol.types import (
+    DiagnosticSeverity,
+    Range,
+    Diagnostic,
+    Position,
+    DidOpenTextDocumentParams,
+    DidChangeTextDocumentParams,
+    FoldingRangeKind,
+    FoldingRange,
+    FoldingRangeParams,
+    CompletionItem,
+    CompletionList,
+    CompletionParams,
+    TEXT_DOCUMENT_DID_OPEN,
+    TEXT_DOCUMENT_DID_CHANGE,
+    TEXT_DOCUMENT_FOLDING_RANGE,
+    TEXT_DOCUMENT_COMPLETION,
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    DiagnosticRelatedInformation,
+    Location,
+    TEXT_DOCUMENT_HOVER,
+    HoverParams,
+    Hover,
+    TEXT_DOCUMENT_CODE_ACTION,
+    DiagnosticTag,
+    SemanticTokensLegend,
+    TEXT_DOCUMENT_SEMANTIC_TOKENS_FULL,
+    SemanticTokens,
+    SemanticTokensParams,
+)
+
+from debputy.lsp.lsp_debian_control_reference_data import (
+    FieldValueClass,
+    _DEP5_HEADER_FIELDS,
+    _DEP5_FILES_FIELDS,
+    Deb822KnownField,
+    _DEP5_LICENSE_FIELDS,
+    Dep5FileMetadata,
+)
+from debputy.lsp.lsp_features import (
+    lint_diagnostics,
+    lsp_completer,
+    lsp_hover,
+    lsp_standard_handler,
+)
+from debputy.lsp.lsp_generic_deb822 import deb822_completer, deb822_hover
+from debputy.lsp.quickfixes import (
+    propose_remove_line_quick_fix,
+    propose_correct_text_quick_fix,
+    provide_standard_quickfixes_from_diagnostics,
+)
+from debputy.lsp.spellchecking import default_spellchecker
+from debputy.lsp.text_util import (
+    on_save_trim_end_of_line_whitespace,
+    normalize_dctrl_field_name,
+    LintCapablePositionCodec,
+    detect_possible_typo,
+    te_range_to_lsp,
+)
+from debputy.util import _info, _error
+
+try:
+    from debputy.lsp.vendoring._deb822_repro.locatable import (
+        Position as TEPosition,
+        Range as TERange,
+        START_POSITION,
+    )
+
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+_CONTAINS_SPACE_OR_COLON = re.compile(r"[\s:]")
+_LANGUAGE_IDS = [
+    "debian/copyright",
+    # emacs's name
+    "debian-copyright",
+    # vim's name
+    "debcopyright",
+]
+
+_DEP5_FILE_METADATA = Dep5FileMetadata()
+
+SEMANTIC_TOKENS_LEGEND = SemanticTokensLegend(
+    token_types=["keyword"],
+    token_modifiers=[],
+)
+
+
+def register_dcpy_lsp(ls: "LanguageServer") -> None:
+    try:
+        from debian._deb822_repro.locatable import Locatable
+    except ImportError:
+        _error(
+            'Sorry; this feature requires a newer version of python-debian (with "Locatable").'
+        )
+
+    ls.feature(TEXT_DOCUMENT_DID_OPEN)(_diagnostics_debian_copyright)
+    ls.feature(TEXT_DOCUMENT_DID_CHANGE)(_diagnostics_debian_copyright)
+    ls.feature(TEXT_DOCUMENT_FOLDING_RANGE)(_detect_folding_ranges_debian_copyright)
+    ls.feature(TEXT_DOCUMENT_COMPLETION)(_debian_copyright_completions)
+    ls.feature(TEXT_DOCUMENT_CODE_ACTION)(provide_standard_quickfixes_from_diagnostics)
+    ls.feature(TEXT_DOCUMENT_HOVER)(_debian_copyright_hover)
+    ls.feature(TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)(on_save_trim_end_of_line_whitespace)
+    ls.feature(TEXT_DOCUMENT_SEMANTIC_TOKENS_FULL, SEMANTIC_TOKENS_LEGEND)(
+        _handle_semantic_tokens_full
+    )
+
+
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_CODE_ACTION)
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)
+
+
+@lsp_hover(_LANGUAGE_IDS)
+def _debian_copyright_hover(
+    ls: "LanguageServer",
+    params: HoverParams,
+) -> Optional[Hover]:
+    return deb822_hover(ls, params, _DEP5_FILE_METADATA)
+
+
+@lsp_completer(_LANGUAGE_IDS)
+def _debian_copyright_completions(
+    ls: "LanguageServer",
+    params: CompletionParams,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    return deb822_completer(ls, params, _DEP5_FILE_METADATA)
+
+
+def _detect_folding_ranges_debian_copyright(
+    ls: "LanguageServer",
+    params: FoldingRangeParams,
+) -> Optional[Sequence[FoldingRange]]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    comment_start = -1
+    folding_ranges = []
+    for (
+        token,
+        start_line,
+        start_offset,
+        end_line,
+        end_offset,
+    ) in _deb822_token_iter(tokenize_deb822_file(doc.lines)):
+        if token.is_comment:
+            if comment_start < 0:
+                comment_start = start_line
+                _info(f"Detected new comment: {start_line}")
+        elif comment_start > -1:
+            comment_start = -1
+            folding_range = FoldingRange(
+                comment_start,
+                end_line,
+                kind=FoldingRangeKind.Comment,
+            )
+
+            folding_ranges.append(folding_range)
+            _info(f"Detected folding range: {folding_range}")
+
+    return folding_ranges
+
+
+def _deb822_token_iter(
+    tokens: Iterable[Deb822Token],
+) -> Iterator[Tuple[Deb822Token, int, int, int, int, int]]:
+    line_no = 0
+    line_offset = 0
+
+    for token in tokens:
+        start_line = line_no
+        start_line_offset = line_offset
+
+        newlines = token.text.count("\n")
+        line_no += newlines
+        text_len = len(token.text)
+        if newlines:
+            if token.text.endswith("\n"):
+                line_offset = 0
+            else:
+                # -2, one to remove the "\n" and one to get 0-offset
+                line_offset = text_len - token.text.rindex("\n") - 2
+        else:
+            line_offset += text_len
+
+        yield token, start_line, start_line_offset, line_no, line_offset
+
+
+def _paragraph_representation_field(
+    paragraph: Deb822ParagraphElement,
+) -> Deb822KeyValuePairElement:
+    return next(iter(paragraph.iter_parts_of_type(Deb822KeyValuePairElement)))
+
+
+def _extract_first_value_and_position(
+    kvpair: Deb822KeyValuePairElement,
+    stanza_pos: "TEPosition",
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+) -> Tuple[Optional[str], Optional[Range]]:
+    kvpair_pos = kvpair.position_in_parent().relative_to(stanza_pos)
+    value_element_pos = kvpair.value_element.position_in_parent().relative_to(
+        kvpair_pos
+    )
+    for value_ref in kvpair.interpret_as(
+        LIST_SPACE_SEPARATED_INTERPRETATION
+    ).iter_value_references():
+        v = value_ref.value
+        section_value_loc = value_ref.locatable
+        value_range_te = section_value_loc.range_in_parent().relative_to(
+            value_element_pos
+        )
+        section_range_server_units = te_range_to_lsp(value_range_te)
+        section_range = position_codec.range_to_client_units(
+            lines, section_range_server_units
+        )
+        return v, section_range
+    return None, None
+
+
+def _diagnostics_for_paragraph(
+    stanza: Deb822ParagraphElement,
+    stanza_position: "TEPosition",
+    known_fields: Mapping[str, Deb822KnownField],
+    other_known_fields: Mapping[str, Deb822KnownField],
+    is_files_or_license_paragraph: bool,
+    doc_reference: str,
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> None:
+    representation_field = _paragraph_representation_field(stanza)
+    representation_field_pos = representation_field.position_in_parent().relative_to(
+        stanza_position
+    )
+    representation_field_range_server_units = te_range_to_lsp(
+        TERange.from_position_and_size(
+            representation_field_pos, representation_field.size()
+        )
+    )
+    representation_field_range = position_codec.range_to_client_units(
+        lines,
+        representation_field_range_server_units,
+    )
+    for known_field in known_fields.values():
+        missing_field_severity = known_field.missing_field_severity
+        if missing_field_severity is None or known_field.name in stanza:
+            continue
+
+        diagnostics.append(
+            Diagnostic(
+                representation_field_range,
+                f"Stanza is missing field {known_field.name}",
+                severity=missing_field_severity,
+                source="debputy",
+            )
+        )
+
+    seen_fields = {}
+
+    for kvpair in stanza.iter_parts_of_type(Deb822KeyValuePairElement):
+        field_name_token = kvpair.field_token
+        field_name = field_name_token.text
+        field_name_lc = field_name.lower()
+        normalized_field_name_lc = normalize_dctrl_field_name(field_name_lc)
+        known_field = known_fields.get(normalized_field_name_lc)
+        field_value = stanza[field_name]
+        field_range_te = kvpair.range_in_parent().relative_to(stanza_position)
+        field_position_te = field_range_te.start_pos
+        field_range_server_units = te_range_to_lsp(field_range_te)
+        field_range = position_codec.range_to_client_units(
+            lines,
+            field_range_server_units,
+        )
+        field_name_typo_detected = False
+        existing_field_range = seen_fields.get(normalized_field_name_lc)
+        if existing_field_range is not None:
+            existing_field_range[3].append(field_range)
+        else:
+            normalized_field_name = normalize_dctrl_field_name(field_name)
+            seen_fields[field_name_lc] = (
+                field_name,
+                normalized_field_name,
+                field_range,
+                [],
+            )
+
+        if known_field is None:
+            candidates = detect_possible_typo(normalized_field_name_lc, known_fields)
+            if candidates:
+                known_field = known_fields[candidates[0]]
+                token_range_server_units = te_range_to_lsp(
+                    TERange.from_position_and_size(
+                        field_position_te, kvpair.field_token.size()
+                    )
+                )
+                field_range = position_codec.range_to_client_units(
+                    lines,
+                    token_range_server_units,
+                )
+                field_name_typo_detected = True
+                diagnostics.append(
+                    Diagnostic(
+                        field_range,
+                        f'The "{field_name}" looks like a typo of "{known_field.name}".',
+                        severity=DiagnosticSeverity.Warning,
+                        source="debputy",
+                        data=[
+                            propose_correct_text_quick_fix(known_fields[m].name)
+                            for m in candidates
+                        ],
+                    )
+                )
+        if known_field is None:
+            known_else_where = other_known_fields.get(normalized_field_name_lc)
+            if known_else_where is not None:
+                intended_usage = (
+                    "Header" if is_files_or_license_paragraph else "Files/License"
+                )
+                diagnostics.append(
+                    Diagnostic(
+                        field_range,
+                        f'The {field_name} is defined for use in the "{intended_usage}" stanza.'
+                        f" Please move it to the right place or remove it",
+                        severity=DiagnosticSeverity.Error,
+                        source="debputy",
+                    )
+                )
+            continue
+
+        if field_value.strip() == "":
+            diagnostics.append(
+                Diagnostic(
+                    field_range,
+                    f"The {field_name} has no value. Either provide a value or remove it.",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                )
+            )
+            continue
+        diagnostics.extend(
+            known_field.field_diagnostics(
+                kvpair,
+                stanza_position,
+                position_codec,
+                lines,
+                field_name_typo_reported=field_name_typo_detected,
+            )
+        )
+        if known_field.spellcheck_value:
+            words = kvpair.interpret_as(LIST_SPACE_SEPARATED_INTERPRETATION)
+            spell_checker = default_spellchecker()
+            value_position = kvpair.value_element.position_in_parent().relative_to(
+                field_position_te
+            )
+            for word_ref in words.iter_value_references():
+                token = word_ref.value
+                for word, pos, endpos in spell_checker.iter_words(token):
+                    corrections = spell_checker.provide_corrections_for(word)
+                    if not corrections:
+                        continue
+                    word_loc = word_ref.locatable
+                    word_pos_te = word_loc.position_in_parent().relative_to(
+                        value_position
+                    )
+                    if pos:
+                        word_pos_te = TEPosition(0, pos).relative_to(word_pos_te)
+                    word_range = TERange(
+                        START_POSITION,
+                        TEPosition(0, endpos - pos),
+                    )
+                    word_range_server_units = te_range_to_lsp(
+                        TERange.from_position_and_size(word_pos_te, word_range)
+                    )
+                    word_range = position_codec.range_to_client_units(
+                        lines,
+                        word_range_server_units,
+                    )
+                    diagnostics.append(
+                        Diagnostic(
+                            word_range,
+                            f'Spelling "{word}"',
+                            severity=DiagnosticSeverity.Hint,
+                            source="debputy",
+                            data=[
+                                propose_correct_text_quick_fix(c) for c in corrections
+                            ],
+                        )
+                    )
+        if known_field.warn_if_default and field_value == known_field.default_value:
+            diagnostics.append(
+                Diagnostic(
+                    field_range,
+                    f"The {field_name} is redundant as it is set to the default value and the field should only be"
+                    " used in exceptional cases.",
+                    severity=DiagnosticSeverity.Warning,
+                    source="debputy",
+                )
+            )
+    for (
+        field_name,
+        normalized_field_name,
+        field_range,
+        duplicates,
+    ) in seen_fields.values():
+        if not duplicates:
+            continue
+        related_information = [
+            DiagnosticRelatedInformation(
+                location=Location(doc_reference, field_range),
+                message=f"First definition of {field_name}",
+            )
+        ]
+        related_information.extend(
+            DiagnosticRelatedInformation(
+                location=Location(doc_reference, r),
+                message=f"Duplicate of {field_name}",
+            )
+            for r in duplicates
+        )
+        for dup_range in duplicates:
+            diagnostics.append(
+                Diagnostic(
+                    dup_range,
+                    f"The {normalized_field_name} field name was used multiple times in this stanza."
+                    f" Please ensure the field is only used once per stanza. Note that {normalized_field_name} and"
+                    f" X[BCS]-{normalized_field_name} are considered the same field.",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy",
+                    related_information=related_information,
+                )
+            )
+
+
+def _diagnostics_for_field_name(
+    token: Deb822FieldNameToken,
+    token_position: "TEPosition",
+    known_field: Deb822KnownField,
+    typo_detected: bool,
+    position_codec: "LintCapablePositionCodec",
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> None:
+    field_name = token.text
+    # Defeat the case-insensitivity from python-debian
+    field_name_cased = str(field_name)
+    token_range_server_units = te_range_to_lsp(
+        TERange.from_position_and_size(token_position, token.size())
+    )
+    token_range = position_codec.range_to_client_units(
+        lines,
+        token_range_server_units,
+    )
+    if known_field.deprecated_with_no_replacement:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"{field_name_cased} is deprecated and no longer used",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_remove_line_quick_fix(),
+            )
+        )
+    elif known_field.replaced_by is not None:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"{field_name_cased} is a deprecated name for {known_field.replaced_by}",
+                severity=DiagnosticSeverity.Warning,
+                source="debputy",
+                tags=[DiagnosticTag.Deprecated],
+                data=propose_correct_text_quick_fix(known_field.replaced_by),
+            )
+        )
+
+    if not typo_detected and field_name_cased != known_field.name:
+        diagnostics.append(
+            Diagnostic(
+                token_range,
+                f"Non-canonical spelling of {known_field.name}",
+                severity=DiagnosticSeverity.Information,
+                source="debputy",
+                data=propose_correct_text_quick_fix(known_field.name),
+            )
+        )
+
+
+def _scan_for_syntax_errors_and_token_level_diagnostics(
+    deb822_file: Deb822FileElement,
+    position_codec: LintCapablePositionCodec,
+    lines: List[str],
+    diagnostics: List[Diagnostic],
+) -> int:
+    first_error = len(lines) + 1
+    spell_checker = default_spellchecker()
+    for (
+        token,
+        start_line,
+        start_offset,
+        end_line,
+        end_offset,
+    ) in _deb822_token_iter(deb822_file.iter_tokens()):
+        if token.is_error:
+            first_error = min(first_error, start_line)
+            start_pos = Position(
+                start_line,
+                start_offset,
+            )
+            end_pos = Position(
+                end_line,
+                end_offset,
+            )
+            token_range = position_codec.range_to_client_units(
+                lines, Range(start_pos, end_pos)
+            )
+            diagnostics.append(
+                Diagnostic(
+                    token_range,
+                    "Syntax error",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy (python-debian parser)",
+                )
+            )
+        elif token.is_comment:
+            for word, pos, end_pos in spell_checker.iter_words(token.text):
+                corrections = spell_checker.provide_corrections_for(word)
+                if not corrections:
+                    continue
+                start_pos = Position(
+                    start_line,
+                    pos,
+                )
+                end_pos = Position(
+                    start_line,
+                    end_pos,
+                )
+                word_range = position_codec.range_to_client_units(
+                    lines, Range(start_pos, end_pos)
+                )
+                diagnostics.append(
+                    Diagnostic(
+                        word_range,
+                        f'Spelling "{word}"',
+                        severity=DiagnosticSeverity.Hint,
+                        source="debputy",
+                        data=[propose_correct_text_quick_fix(c) for c in corrections],
+                    )
+                )
+    return first_error
+
+
+def _diagnostics_debian_copyright(
+    ls: "LanguageServer",
+    params: Union[DidOpenTextDocumentParams, DidChangeTextDocumentParams],
+) -> None:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    _info(f"Opened document: {doc.path} ({doc.language_id})")
+    lines = doc.lines
+    position_codec: LintCapablePositionCodec = doc.position_codec
+
+    diagnostics = _lint_debian_copyright(doc.uri, doc.path, lines, position_codec)
+    ls.publish_diagnostics(
+        doc.uri,
+        diagnostics,
+    )
+
+
+@lint_diagnostics(_LANGUAGE_IDS)
+def _lint_debian_copyright(
+    doc_reference: str,
+    _path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    diagnostics = []
+    deb822_file = parse_deb822_file(
+        lines,
+        accept_files_with_duplicated_fields=True,
+        accept_files_with_error_tokens=True,
+    )
+
+    first_error = _scan_for_syntax_errors_and_token_level_diagnostics(
+        deb822_file,
+        position_codec,
+        lines,
+        diagnostics,
+    )
+
+    paragraphs = list(deb822_file)
+    is_dep5 = False
+
+    for paragraph_no, paragraph in enumerate(paragraphs, start=1):
+        paragraph_pos = paragraph.position_in_file()
+        if paragraph_pos.line_position >= first_error:
+            break
+        is_files_or_license_paragraph = paragraph_no != 1
+        if is_files_or_license_paragraph:
+            known_fields = (
+                _DEP5_FILES_FIELDS if "Files" in paragraph else _DEP5_LICENSE_FIELDS
+            )
+            other_known_fields = _DEP5_HEADER_FIELDS
+        elif "Format" in paragraph:
+            is_dep5 = True
+            known_fields = _DEP5_HEADER_FIELDS
+            other_known_fields = _DEP5_FILES_FIELDS
+        else:
+            break
+        _diagnostics_for_paragraph(
+            paragraph,
+            paragraph_pos,
+            known_fields,
+            other_known_fields,
+            is_files_or_license_paragraph,
+            doc_reference,
+            position_codec,
+            lines,
+            diagnostics,
+        )
+    if not is_dep5:
+        return None
+    return diagnostics
+
+
+def _handle_semantic_tokens_full(
+    ls: "LanguageServer",
+    request: SemanticTokensParams,
+) -> Optional[SemanticTokens]:
+    doc = ls.workspace.get_text_document(request.text_document.uri)
+    lines = doc.lines
+    deb822_file = parse_deb822_file(
+        lines,
+        accept_files_with_duplicated_fields=True,
+        accept_files_with_error_tokens=True,
+    )
+    tokens = []
+    previous_line = 0
+    keyword_token = 0
+    no_modifiers = 0
+
+    for paragraph_no, paragraph in enumerate(deb822_file, start=1):
+        paragraph_position = paragraph.position_in_file()
+        for kvpair in paragraph.iter_parts_of_type(Deb822KeyValuePairElement):
+            field_position_without_comments = kvpair.position_in_parent().relative_to(
+                paragraph_position
+            )
+            field_size = doc.position_codec.client_num_units(kvpair.field_name)
+            current_line = field_position_without_comments.line_position
+            line_delta = current_line - previous_line
+            previous_line = current_line
+            tokens.append(line_delta)  # Line delta
+            tokens.append(0)  # Token delta
+            tokens.append(field_size)  # Token length
+            tokens.append(keyword_token)
+            tokens.append(no_modifiers)
+
+    if not tokens:
+        return None
+    return SemanticTokens(tokens)
diff --git a/src/debputy/lsp/lsp_debian_debputy_manifest.py b/src/debputy/lsp/lsp_debian_debputy_manifest.py
new file mode 100644
index 0000000..2f9920e
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_debputy_manifest.py
@@ -0,0 +1,111 @@
+import re
+from typing import (
+    Optional,
+    List,
+)
+
+from lsprotocol.types import (
+    Diagnostic,
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    Position,
+    Range,
+    DiagnosticSeverity,
+)
+from ruamel.yaml.error import MarkedYAMLError, YAMLError
+
+from debputy.highlevel_manifest import MANIFEST_YAML
+from debputy.lsp.lsp_features import (
+    lint_diagnostics,
+    lsp_standard_handler,
+)
+from debputy.lsp.text_util import (
+    LintCapablePositionCodec,
+)
+
+try:
+    from pygls.server import LanguageServer
+except ImportError:
+    pass
+
+
+_CONTAINS_TAB_OR_COLON = re.compile(r"[\t:]")
+_WORDS_RE = re.compile("([a-zA-Z0-9_-]+)")
+_MAKE_ERROR_RE = re.compile(r"^[^:]+:(\d+):\s*(\S.+)")
+
+
+_LANGUAGE_IDS = [
+    "debian/debputy.manifest",
+    "debputy.manifest",
+    # LSP's official language ID for YAML files
+    "yaml",
+]
+
+
+# lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_CODE_ACTION)
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)
+
+
+def _word_range_at_position(
+    lines: List[str],
+    line_no: int,
+    char_offset: int,
+) -> Range:
+    line = lines[line_no]
+    line_len = len(line)
+    start_idx = char_offset
+    end_idx = char_offset
+    while end_idx + 1 < line_len and not line[end_idx + 1].isspace():
+        end_idx += 1
+
+    while start_idx - 1 >= 0 and not line[start_idx - 1].isspace():
+        start_idx -= 1
+
+    return Range(
+        Position(line_no, start_idx),
+        Position(line_no, end_idx),
+    )
+
+
+@lint_diagnostics(_LANGUAGE_IDS)
+def _lint_debian_debputy_manifest(
+    _doc_reference: str,
+    _path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    diagnostics = []
+    try:
+        MANIFEST_YAML.load("".join(lines))
+    except MarkedYAMLError as e:
+        error_range = position_codec.range_to_client_units(
+            lines,
+            _word_range_at_position(
+                lines,
+                e.problem_mark.line,
+                e.problem_mark.column,
+            ),
+        )
+        diagnostics.append(
+            Diagnostic(
+                error_range,
+                f"YAML parse error: {e}",
+                DiagnosticSeverity.Error,
+            ),
+        )
+    except YAMLError as e:
+        error_range = position_codec.range_to_client_units(
+            lines,
+            Range(
+                Position(0, 0),
+                Position(0, len(lines[0])),
+            ),
+        )
+        diagnostics.append(
+            Diagnostic(
+                error_range,
+                f"Unknown YAML parse error: {e} [{e!r}]",
+                DiagnosticSeverity.Error,
+            ),
+        )
+
+    return diagnostics
diff --git a/src/debputy/lsp/lsp_debian_rules.py b/src/debputy/lsp/lsp_debian_rules.py
new file mode 100644
index 0000000..7f0e5fb
--- /dev/null
+++ b/src/debputy/lsp/lsp_debian_rules.py
@@ -0,0 +1,384 @@
+import itertools
+import json
+import os
+import re
+import subprocess
+from typing import (
+    Union,
+    Sequence,
+    Optional,
+    Iterable,
+    List,
+    Iterator,
+    Tuple,
+)
+
+from lsprotocol.types import (
+    CompletionItem,
+    DidOpenTextDocumentParams,
+    DidChangeTextDocumentParams,
+    Diagnostic,
+    Range,
+    Position,
+    DiagnosticSeverity,
+    CompletionList,
+    CompletionParams,
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    TEXT_DOCUMENT_CODE_ACTION,
+)
+
+from debputy.lsp.lsp_features import (
+    lint_diagnostics,
+    lsp_standard_handler,
+    lsp_completer,
+)
+from debputy.lsp.quickfixes import propose_correct_text_quick_fix
+from debputy.lsp.spellchecking import spellcheck_line
+from debputy.lsp.text_util import (
+    LintCapablePositionCodec,
+)
+from debputy.util import _warn
+
+try:
+    from debian._deb822_repro.locatable import (
+        Position as TEPosition,
+        Range as TERange,
+        START_POSITION,
+    )
+
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+try:
+    from Levenshtein import distance
+except ImportError:
+
+    def _detect_possible_typo(
+        provided_value: str,
+        known_values: Iterable[str],
+    ) -> Sequence[str]:
+        return tuple()
+
+else:
+
+    def _detect_possible_typo(
+        provided_value: str,
+        known_values: Iterable[str],
+    ) -> Sequence[str]:
+        k_len = len(provided_value)
+        candidates = []
+        for known_value in known_values:
+            if abs(k_len - len(known_value)) > 2:
+                continue
+            d = distance(provided_value, known_value)
+            if d > 2:
+                continue
+            candidates.append(known_value)
+        return candidates
+
+
+_CONTAINS_TAB_OR_COLON = re.compile(r"[\t:]")
+_WORDS_RE = re.compile("([a-zA-Z0-9_-]+)")
+_MAKE_ERROR_RE = re.compile(r"^[^:]+:(\d+):\s*(\S.+)")
+
+
+_KNOWN_TARGETS = {
+    "binary",
+    "binary-arch",
+    "binary-indep",
+    "build",
+    "build-arch",
+    "build-indep",
+    "clean",
+}
+
+_COMMAND_WORDS = frozenset(
+    {
+        "export",
+        "ifeq",
+        "ifneq",
+        "ifdef",
+        "ifndef",
+        "endif",
+        "else",
+    }
+)
+
+_LANGUAGE_IDS = [
+    "debian/rules",
+    # LSP's official language ID for Makefile
+    "makefile",
+    # emacs's name (there is no debian-rules mode)
+    "makefile-gmake",
+    # vim's name (there is no debrules)
+    "make",
+]
+
+
+def _as_hook_targets(command_name: str) -> Iterable[str]:
+    for prefix, suffix in itertools.product(
+        ["override_", "execute_before_", "execute_after_"],
+        ["", "-arch", "-indep"],
+    ):
+        yield f"{prefix}{command_name}{suffix}"
+
+
+def _diagnostics_debian_rules(
+    ls: "LanguageServer",
+    params: Union[DidOpenTextDocumentParams, DidChangeTextDocumentParams],
+) -> None:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    if not doc.path.endswith("debian/rules"):
+        return
+    lines = doc.lines
+    diagnostics = _lint_debian_rules(
+        doc.uri,
+        doc.path,
+        lines,
+        doc.position_codec,
+    )
+    ls.publish_diagnostics(
+        doc.uri,
+        diagnostics,
+    )
+
+
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_CODE_ACTION)
+lsp_standard_handler(_LANGUAGE_IDS, TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL)
+
+
+@lint_diagnostics(_LANGUAGE_IDS)
+def _lint_debian_rules_via_debputy_lsp(
+    doc_reference: str,
+    path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    if not path.endswith("debian/rules"):
+        return None
+    return _lint_debian_rules(
+        doc_reference,
+        path,
+        lines,
+        position_codec,
+    )
+
+
+def _run_make_dryrun(
+    source_root: str,
+    lines: List[str],
+) -> Optional[Diagnostic]:
+    try:
+        make_res = subprocess.run(
+            ["make", "--dry-run", "-f", "-", "debhelper-fail-me"],
+            input="".join(lines).encode("utf-8"),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            cwd=source_root,
+            timeout=1,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    else:
+        if make_res.returncode != 0:
+            make_output = make_res.stderr.decode("utf-8")
+            m = _MAKE_ERROR_RE.match(make_output)
+            if m:
+                # We want it zero-based and make reports it one-based
+                line_of_error = int(m.group(1)) - 1
+                msg = m.group(2).strip()
+                error_range = Range(
+                    Position(
+                        line_of_error,
+                        0,
+                    ),
+                    Position(
+                        line_of_error + 1,
+                        0,
+                    ),
+                )
+                # No conversion needed; it is pure line numbers
+                return Diagnostic(
+                    error_range,
+                    f"make error: {msg}",
+                    severity=DiagnosticSeverity.Error,
+                    source="debputy (make)",
+                )
+    return None
+
+
+def iter_make_lines(
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+    diagnostics: List[Diagnostic],
+) -> Iterator[Tuple[int, str]]:
+    skip_next_line = False
+    is_extended_comment = False
+    for line_no, line in enumerate(lines):
+        skip_this = skip_next_line
+        skip_next_line = False
+        if line.rstrip().endswith("\\"):
+            skip_next_line = True
+
+        if skip_this:
+            if is_extended_comment:
+                diagnostics.extend(
+                    spellcheck_line(lines, position_codec, line_no, line)
+                )
+            continue
+
+        if line.startswith("#"):
+            diagnostics.extend(spellcheck_line(lines, position_codec, line_no, line))
+            is_extended_comment = skip_next_line
+            continue
+        is_extended_comment = False
+
+        if line.startswith("\t") or line.isspace():
+            continue
+
+        is_extended_comment = False
+        # We are not really dealing with extension lines at the moment (other than for spellchecking),
+        # since nothing needs it
+        yield line_no, line
+
+
+def _lint_debian_rules(
+    _doc_reference: str,
+    path: str,
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+) -> Optional[List[Diagnostic]]:
+    source_root = os.path.dirname(os.path.dirname(path))
+    if source_root == "":
+        source_root = "."
+    diagnostics = []
+
+    make_error = _run_make_dryrun(source_root, lines)
+    if make_error is not None:
+        diagnostics.append(make_error)
+    all_dh_commands = _all_dh_commands(source_root)
+    if all_dh_commands:
+        all_hook_targets = {ht for c in all_dh_commands for ht in _as_hook_targets(c)}
+        all_hook_targets.update(_KNOWN_TARGETS)
+        source = "debputy (dh_assistant)"
+    else:
+        all_hook_targets = _KNOWN_TARGETS
+        source = "debputy"
+
+    missing_targets = {}
+
+    for line_no, line in iter_make_lines(lines, position_codec, diagnostics):
+        try:
+            colon_idx = line.index(":")
+            if len(line) > colon_idx + 1 and line[colon_idx + 1] == "=":
+                continue
+        except ValueError:
+            continue
+        target_substring = line[0:colon_idx]
+        if "=" in target_substring or "$(for" in target_substring:
+            continue
+        for i, m in enumerate(_WORDS_RE.finditer(target_substring)):
+            target = m.group(1)
+            if i == 0 and (target in _COMMAND_WORDS or target.startswith("(")):
+                break
+            if "%" in target or "$" in target:
+                continue
+            if target in all_hook_targets or target in missing_targets:
+                continue
+            pos, endpos = m.span(1)
+            hook_location = line_no, pos, endpos
+            missing_targets[target] = hook_location
+
+    for target, (line_no, pos, endpos) in missing_targets.items():
+        candidates = _detect_possible_typo(target, all_hook_targets)
+        if not candidates and not target.startswith(
+            ("override_", "execute_before_", "execute_after_")
+        ):
+            continue
+
+        r_server_units = Range(
+            Position(
+                line_no,
+                pos,
+            ),
+            Position(
+                line_no,
+                endpos,
+            ),
+        )
+        r = position_codec.range_to_client_units(lines, r_server_units)
+        if candidates:
+            msg = f"Target {target} looks like a typo of a known target"
+        else:
+            msg = f"Unknown rules dh hook target {target}"
+        if candidates:
+            fixes = [propose_correct_text_quick_fix(c) for c in candidates]
+        else:
+            fixes = []
+        diagnostics.append(
+            Diagnostic(
+                r,
+                msg,
+                severity=DiagnosticSeverity.Warning,
+                data=fixes,
+                source=source,
+            )
+        )
+    return diagnostics
+
+
+def _all_dh_commands(source_root: str) -> Optional[Sequence[str]]:
+    try:
+        output = subprocess.check_output(
+            ["dh_assistant", "list-commands", "--output-format=json"],
+            stderr=subprocess.DEVNULL,
+            cwd=source_root,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError) as e:
+        _warn(f"dh_assistant failed (dir: {source_root}): {str(e)}")
+        return None
+    data = json.loads(output)
+    commands_raw = data.get("commands") if isinstance(data, dict) else None
+    if not isinstance(commands_raw, list):
+        return None
+
+    commands = []
+
+    for command in commands_raw:
+        if not isinstance(command, dict):
+            return None
+        command_name = command.get("command")
+        if not command_name:
+            return None
+        commands.append(command_name)
+
+    return commands
+
+
+@lsp_completer(_LANGUAGE_IDS)
+def _debian_rules_completions(
+    ls: "LanguageServer",
+    params: CompletionParams,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    if not doc.path.endswith("debian/rules"):
+        return None
+    lines = doc.lines
+    server_position = doc.position_codec.position_from_client_units(
+        lines, params.position
+    )
+
+    line = lines[server_position.line]
+    line_start = line[0 : server_position.character]
+
+    if _CONTAINS_TAB_OR_COLON.search(line_start):
+        return None
+
+    source_root = os.path.dirname(os.path.dirname(doc.path))
+    all_commands = _all_dh_commands(source_root)
+    items = [CompletionItem(ht) for c in all_commands for ht in _as_hook_targets(c)]
+
+    return items
diff --git a/src/debputy/lsp/lsp_dispatch.py b/src/debputy/lsp/lsp_dispatch.py
new file mode 100644
index 0000000..41e9111
--- /dev/null
+++ b/src/debputy/lsp/lsp_dispatch.py
@@ -0,0 +1,131 @@
+import asyncio
+from typing import Dict, Sequence, Union, Optional
+
+from lsprotocol.types import (
+    DidOpenTextDocumentParams,
+    DidChangeTextDocumentParams,
+    TEXT_DOCUMENT_DID_CHANGE,
+    TEXT_DOCUMENT_DID_OPEN,
+    TEXT_DOCUMENT_COMPLETION,
+    CompletionList,
+    CompletionItem,
+    CompletionParams,
+    TEXT_DOCUMENT_HOVER,
+)
+
+from debputy import __version__
+from debputy.lsp.lsp_features import (
+    DIAGNOSTIC_HANDLERS,
+    COMPLETER_HANDLERS,
+    HOVER_HANDLERS,
+)
+from debputy.util import _info
+
+_DOCUMENT_VERSION_TABLE: Dict[str, int] = {}
+
+try:
+    from pygls.server import LanguageServer
+
+    DEBPUTY_LANGUAGE_SERVER = LanguageServer("debputy", f"v{__version__}")
+except ImportError:
+
+    class Mock:
+
+        def feature(self, *args, **kwargs):
+            return lambda x: x
+
+    DEBPUTY_LANGUAGE_SERVER = Mock()
+
+
+def is_doc_at_version(uri: str, version: int) -> bool:
+    dv = _DOCUMENT_VERSION_TABLE.get(uri)
+    return dv == version
+
+
+@DEBPUTY_LANGUAGE_SERVER.feature(TEXT_DOCUMENT_DID_OPEN)
+@DEBPUTY_LANGUAGE_SERVER.feature(TEXT_DOCUMENT_DID_CHANGE)
+async def _open_or_changed_document(
+    ls: "LanguageServer",
+    params: Union[DidOpenTextDocumentParams, DidChangeTextDocumentParams],
+) -> None:
+    version = params.text_document.version
+    doc_uri = params.text_document.uri
+    doc = ls.workspace.get_text_document(doc_uri)
+
+    _DOCUMENT_VERSION_TABLE[doc_uri] = version
+
+    handler = DIAGNOSTIC_HANDLERS.get(doc.language_id)
+    if handler is None:
+        _info(
+            f"Opened/Changed document: {doc.path} ({doc.language_id}) - no diagnostics handler"
+        )
+        return
+    _info(
+        f"Opened/Changed document: {doc.path} ({doc.language_id}) - running diagnostics for doc version {version}"
+    )
+    last_publish_count = -1
+
+    diagnostics_scanner = handler(ls, params)
+    async for diagnostics in diagnostics_scanner:
+        await asyncio.sleep(0)
+        if not is_doc_at_version(doc_uri, version):
+            # This basically happens with very edit, so lets not notify the client
+            # for that.
+            _info(
+                f"Cancel (obsolete) diagnostics for doc version {version}: document version changed"
+            )
+            break
+        if diagnostics is None or last_publish_count != len(diagnostics):
+            last_publish_count = len(diagnostics) if diagnostics is not None else 0
+            ls.publish_diagnostics(
+                doc.uri,
+                diagnostics,
+            )
+
+
+@DEBPUTY_LANGUAGE_SERVER.feature(TEXT_DOCUMENT_COMPLETION)
+def _completions(
+    ls: "LanguageServer",
+    params: CompletionParams,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    doc_uri = params.text_document.uri
+    doc = ls.workspace.get_text_document(doc_uri)
+
+    handler = COMPLETER_HANDLERS.get(doc.language_id)
+    if handler is None:
+        _info(
+            f"Complete request for document: {doc.path} ({doc.language_id}) - no handler"
+        )
+        return
+    _info(
+        f"Complete request for document: {doc.path} ({doc.language_id}) - delegating to handler"
+    )
+
+    return handler(
+        ls,
+        params,
+    )
+
+
+@DEBPUTY_LANGUAGE_SERVER.feature(TEXT_DOCUMENT_HOVER)
+def _hover(
+    ls: "LanguageServer",
+    params: CompletionParams,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    doc_uri = params.text_document.uri
+    doc = ls.workspace.get_text_document(doc_uri)
+
+    handler = HOVER_HANDLERS.get(doc.language_id)
+    if handler is None:
+        _info(
+            f"Hover request for document: {doc.path} ({doc.language_id}) - no handler"
+        )
+        return
+    _info(
+        f"Hover request for document: {doc.path} ({doc.language_id}) - delegating to handler"
+    )
+
+    return handler(
+        ls,
+        params,
+    )
diff --git a/src/debputy/lsp/lsp_features.py b/src/debputy/lsp/lsp_features.py
new file mode 100644
index 0000000..b417dd3
--- /dev/null
+++ b/src/debputy/lsp/lsp_features.py
@@ -0,0 +1,196 @@
+import collections
+import inspect
+from typing import Callable, TypeVar, Sequence, Union, Dict, List, Optional
+
+from lsprotocol.types import (
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL,
+    TEXT_DOCUMENT_CODE_ACTION,
+    DidChangeTextDocumentParams,
+    Diagnostic,
+    DidOpenTextDocumentParams,
+)
+
+try:
+    from pygls.server import LanguageServer
+except ImportError:
+    pass
+
+from debputy.linting.lint_util import LinterImpl
+from debputy.lsp.quickfixes import provide_standard_quickfixes_from_diagnostics
+from debputy.lsp.text_util import on_save_trim_end_of_line_whitespace
+
+C = TypeVar("C", bound=Callable)
+
+
+DIAGNOSTIC_HANDLERS = {}
+COMPLETER_HANDLERS = {}
+HOVER_HANDLERS = {}
+CODE_ACTION_HANDLERS = {}
+WILL_SAVE_WAIT_UNTIL_HANDLERS = {}
+_ALIAS_OF = {}
+
+_STANDARD_HANDLERS = {
+    TEXT_DOCUMENT_CODE_ACTION: (
+        CODE_ACTION_HANDLERS,
+        provide_standard_quickfixes_from_diagnostics,
+    ),
+    TEXT_DOCUMENT_WILL_SAVE_WAIT_UNTIL: (
+        WILL_SAVE_WAIT_UNTIL_HANDLERS,
+        on_save_trim_end_of_line_whitespace,
+    ),
+}
+
+
+def lint_diagnostics(
+    file_formats: Union[str, Sequence[str]]
+) -> Callable[[LinterImpl], LinterImpl]:
+
+    def _wrapper(func: C) -> C:
+        if not inspect.iscoroutinefunction(func):
+
+            async def _lint_wrapper(
+                ls: "LanguageServer",
+                params: Union[
+                    DidOpenTextDocumentParams,
+                    DidChangeTextDocumentParams,
+                ],
+            ) -> Optional[List[Diagnostic]]:
+                doc = ls.workspace.get_text_document(params.text_document.uri)
+                yield func(
+                    doc.uri,
+                    doc.path,
+                    doc.lines,
+                    doc.position_codec,
+                )
+
+        else:
+            raise ValueError("Linters are all non-async at the moment")
+
+        for file_format in file_formats:
+            if file_format in DIAGNOSTIC_HANDLERS:
+                raise AssertionError(
+                    "There is already a diagnostics handler for " + file_format
+                )
+            DIAGNOSTIC_HANDLERS[file_format] = _lint_wrapper
+
+        return func
+
+    return _wrapper
+
+
+def lsp_diagnostics(file_formats: Union[str, Sequence[str]]) -> Callable[[C], C]:
+
+    def _wrapper(func: C) -> C:
+
+        if not inspect.iscoroutinefunction(func):
+
+            async def _linter(*args, **kwargs) -> None:
+                res = func(*args, **kwargs)
+                if inspect.isgenerator(res):
+                    for r in res:
+                        yield r
+                else:
+                    yield res
+
+        else:
+
+            _linter = func
+
+        _register_handler(file_formats, DIAGNOSTIC_HANDLERS, _linter)
+
+        return func
+
+    return _wrapper
+
+
+def lsp_completer(file_formats: Union[str, Sequence[str]]) -> Callable[[C], C]:
+    return _registering_wrapper(file_formats, COMPLETER_HANDLERS)
+
+
+def lsp_hover(file_formats: Union[str, Sequence[str]]) -> Callable[[C], C]:
+    return _registering_wrapper(file_formats, HOVER_HANDLERS)
+
+
+def lsp_standard_handler(file_formats: Union[str, Sequence[str]], topic: str) -> None:
+    res = _STANDARD_HANDLERS.get(topic)
+    if res is None:
+        raise ValueError(f"No standard handler for {topic}")
+
+    table, handler = res
+
+    _register_handler(file_formats, table, handler)
+
+
+def _registering_wrapper(
+    file_formats: Union[str, Sequence[str]], handler_dict: Dict[str, C]
+) -> Callable[[C], C]:
+    def _wrapper(func: C) -> C:
+        _register_handler(file_formats, handler_dict, func)
+        return func
+
+    return _wrapper
+
+
+def _register_handler(
+    file_formats: Union[str, Sequence[str]],
+    handler_dict: Dict[str, C],
+    handler: C,
+) -> None:
+    if isinstance(file_formats, str):
+        file_formats = [file_formats]
+    else:
+        if not file_formats:
+            raise ValueError("At least one language ID (file format) must be provided")
+        main = file_formats[0]
+        for alias in file_formats[1:]:
+            if alias not in _ALIAS_OF:
+                _ALIAS_OF[alias] = main
+
+    for file_format in file_formats:
+        if file_format in handler_dict:
+            raise AssertionError(f"There is already a handler for {file_format}")
+
+        handler_dict[file_format] = handler
+
+
+def ensure_lsp_features_are_loaded() -> None:
+    # FIXME: This import is needed to force loading of the LSP files. But it only works
+    #  for files with a linter (which currently happens to be all of them, but this is
+    #  a bit fragile).
+    from debputy.linting.lint_impl import LINTER_FORMATS
+
+    assert LINTER_FORMATS
+
+
+def describe_lsp_features() -> None:
+
+    ensure_lsp_features_are_loaded()
+
+    feature_list = [
+        ("diagnostics (lint)", DIAGNOSTIC_HANDLERS),
+        ("code actions/quickfixes", CODE_ACTION_HANDLERS),
+        ("completion suggestions", COMPLETER_HANDLERS),
+        ("hover docs", HOVER_HANDLERS),
+        ("on-save handler", WILL_SAVE_WAIT_UNTIL_HANDLERS),
+    ]
+    print("LSP language IDs and their features:")
+    all_ids = sorted(set(lid for _, t in feature_list for lid in t))
+    for lang_id in all_ids:
+        if lang_id in _ALIAS_OF:
+            continue
+        features = [n for n, t in feature_list if lang_id in t]
+        print(f" * {lang_id}:")
+        for feature in features:
+            print(f"   - {feature}")
+
+    aliases = collections.defaultdict(list)
+    for lang_id in all_ids:
+        main_lang = _ALIAS_OF.get(lang_id)
+        if main_lang is None:
+            continue
+        aliases[main_lang].append(lang_id)
+
+    print()
+    print("Aliases:")
+    for main_id, aliases in aliases.items():
+        print(f" * {main_id}: {', '.join(aliases)}")
diff --git a/src/debputy/lsp/lsp_generic_deb822.py b/src/debputy/lsp/lsp_generic_deb822.py
new file mode 100644
index 0000000..245f3de
--- /dev/null
+++ b/src/debputy/lsp/lsp_generic_deb822.py
@@ -0,0 +1,221 @@
+import re
+from typing import (
+    Optional,
+    Union,
+    Sequence,
+    Tuple,
+    Set,
+    Any,
+    Container,
+    List,
+)
+
+from lsprotocol.types import (
+    CompletionParams,
+    CompletionList,
+    CompletionItem,
+    Position,
+    CompletionItemTag,
+    MarkupContent,
+    Hover,
+    MarkupKind,
+    HoverParams,
+)
+
+from debputy.lsp.lsp_debian_control_reference_data import (
+    Deb822FileMetadata,
+    Deb822KnownField,
+    StanzaMetadata,
+)
+from debputy.lsp.text_util import normalize_dctrl_field_name
+from debputy.util import _info
+
+try:
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+_CONTAINS_SPACE_OR_COLON = re.compile(r"[\s:]")
+
+
+def _at_cursor(
+    doc: "TextDocument",
+    lines: List[str],
+    client_position: Position,
+) -> Tuple[Optional[str], str, bool, int, Set[str]]:
+    paragraph_no = -1
+    paragraph_started = False
+    seen_fields = set()
+    last_field_seen: Optional[str] = None
+    current_field: Optional[str] = None
+    server_position = doc.position_codec.position_from_client_units(
+        lines,
+        client_position,
+    )
+    position_line_no = server_position.line
+
+    line_at_position = lines[position_line_no]
+    line_start = ""
+    if server_position.character:
+        line_start = line_at_position[0 : server_position.character]
+
+    for line_no, line in enumerate(lines):
+        if not line or line.isspace():
+            if line_no == position_line_no:
+                current_field = last_field_seen
+                continue
+            last_field_seen = None
+            if line_no > position_line_no:
+                break
+            paragraph_started = False
+        elif line and line[0] == "#":
+            continue
+        elif line and not line[0].isspace() and ":" in line:
+            if not paragraph_started:
+                paragraph_started = True
+                seen_fields = set()
+                paragraph_no += 1
+            key, _ = line.split(":", 1)
+            key_lc = key.lower()
+            last_field_seen = key_lc
+            if line_no == position_line_no:
+                current_field = key_lc
+            seen_fields.add(key_lc)
+
+    in_value = bool(_CONTAINS_SPACE_OR_COLON.search(line_start))
+    current_word = doc.word_at_position(client_position)
+    if current_field is not None:
+        current_field = normalize_dctrl_field_name(current_field)
+    return current_field, current_word, in_value, paragraph_no, seen_fields
+
+
+def deb822_completer(
+    ls: "LanguageServer",
+    params: CompletionParams,
+    file_metadata: Deb822FileMetadata[Any],
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    lines = doc.lines
+
+    current_field, _, in_value, paragraph_no, seen_fields = _at_cursor(
+        doc,
+        lines,
+        params.position,
+    )
+
+    stanza_metadata = file_metadata.guess_stanza_classification_by_idx(paragraph_no)
+
+    if in_value:
+        _info(f"Completion for field value {current_field}")
+        if current_field is None:
+            return None
+        known_field = stanza_metadata.get(current_field)
+        if known_field is None:
+            return None
+        items = _complete_field_value(known_field)
+    else:
+        _info("Completing field name")
+        items = _complete_field_name(
+            stanza_metadata,
+            seen_fields,
+        )
+
+    _info(f"Completion candidates: {items}")
+
+    return items
+
+
+def deb822_hover(
+    ls: "LanguageServer",
+    params: HoverParams,
+    file_metadata: Deb822FileMetadata[Any],
+) -> Optional[Hover]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    lines = doc.lines
+    current_field, word_at_position, in_value, paragraph_no, _ = _at_cursor(
+        doc, lines, params.position
+    )
+    stanza_metadata = file_metadata.guess_stanza_classification_by_idx(paragraph_no)
+
+    if current_field is None:
+        _info("No hover information as we cannot determine which field it is for")
+        return None
+    known_field = stanza_metadata.get(current_field)
+
+    if known_field is None:
+        return None
+    if in_value:
+        if not known_field.known_values:
+            return
+        keyword = known_field.known_values.get(word_at_position)
+        if keyword is None:
+            return
+        hover_text = keyword.hover_text
+    else:
+        hover_text = known_field.hover_text
+        if hover_text is None:
+            hover_text = f"The field {current_field} had no documentation."
+
+    try:
+        supported_formats = ls.client_capabilities.text_document.hover.content_format
+    except AttributeError:
+        supported_formats = []
+
+    _info(f"Supported formats {supported_formats}")
+    markup_kind = MarkupKind.Markdown
+    if markup_kind not in supported_formats:
+        markup_kind = MarkupKind.PlainText
+    return Hover(
+        contents=MarkupContent(
+            kind=markup_kind,
+            value=hover_text,
+        )
+    )
+
+
+def _should_complete_field_with_value(cand: Deb822KnownField) -> bool:
+    return cand.known_values is not None and (
+        len(cand.known_values) == 1
+        or (
+            len(cand.known_values) == 2
+            and cand.warn_if_default
+            and cand.default_value is not None
+        )
+    )
+
+
+def _complete_field_name(
+    fields: StanzaMetadata[Any],
+    seen_fields: Container[str],
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    items = []
+    for cand_key, cand in fields.items():
+        if cand_key.lower() in seen_fields:
+            continue
+        name = cand.name
+        complete_as = name + ": "
+        if _should_complete_field_with_value(cand):
+            value = next(iter(v for v in cand.known_values if v != cand.default_value))
+            complete_as += value
+        tags = []
+        if cand.replaced_by or cand.deprecated_with_no_replacement:
+            tags.append(CompletionItemTag.Deprecated)
+
+        items.append(
+            CompletionItem(
+                name,
+                insert_text=complete_as,
+                tags=tags,
+            )
+        )
+    return items
+
+
+def _complete_field_value(
+    field: Deb822KnownField,
+) -> Optional[Union[CompletionList, Sequence[CompletionItem]]]:
+    if field.known_values is None:
+        return None
+    return [CompletionItem(v) for v in field.known_values]
diff --git a/src/debputy/lsp/quickfixes.py b/src/debputy/lsp/quickfixes.py
new file mode 100644
index 0000000..d911961
--- /dev/null
+++ b/src/debputy/lsp/quickfixes.py
@@ -0,0 +1,202 @@
+from typing import (
+    Literal,
+    TypedDict,
+    Callable,
+    Iterable,
+    Union,
+    TypeVar,
+    Mapping,
+    Dict,
+    Optional,
+    List,
+    cast,
+)
+
+from lsprotocol.types import (
+    CodeAction,
+    Command,
+    CodeActionParams,
+    Diagnostic,
+    CodeActionDisabledType,
+    TextEdit,
+    WorkspaceEdit,
+    TextDocumentEdit,
+    OptionalVersionedTextDocumentIdentifier,
+    Range,
+    Position,
+    CodeActionKind,
+)
+
+from debputy.util import _warn
+
+try:
+    from debian._deb822_repro.locatable import Position as TEPosition, Range as TERange
+
+    from pygls.server import LanguageServer
+    from pygls.workspace import TextDocument
+except ImportError:
+    pass
+
+
+CodeActionName = Literal["correct-text", "remove-line"]
+
+
+class CorrectTextCodeAction(TypedDict):
+    code_action: Literal["correct-text"]
+    correct_value: str
+
+
+class RemoveLineCodeAction(TypedDict):
+    code_action: Literal["remove-line"]
+
+
+def propose_correct_text_quick_fix(correct_value: str) -> CorrectTextCodeAction:
+    return {
+        "code_action": "correct-text",
+        "correct_value": correct_value,
+    }
+
+
+def propose_remove_line_quick_fix() -> RemoveLineCodeAction:
+    return {
+        "code_action": "remove-line",
+    }
+
+
+CODE_ACTION_HANDLERS: Dict[
+    CodeActionName,
+    Callable[
+        [Mapping[str, str], CodeActionParams, Diagnostic],
+        Iterable[Union[CodeAction, Command]],
+    ],
+] = {}
+M = TypeVar("M", bound=Mapping[str, str])
+Handler = Callable[
+    [M, CodeActionParams, Diagnostic],
+    Iterable[Union[CodeAction, Command]],
+]
+
+
+def _code_handler_for(action_name: CodeActionName) -> Callable[[Handler], Handler]:
+    def _wrapper(func: Handler) -> Handler:
+        assert action_name not in CODE_ACTION_HANDLERS
+        CODE_ACTION_HANDLERS[action_name] = func
+        return func
+
+    return _wrapper
+
+
+@_code_handler_for("correct-text")
+def _correct_value_code_action(
+    code_action_data: CorrectTextCodeAction,
+    code_action_params: CodeActionParams,
+    diagnostic: Diagnostic,
+) -> Iterable[Union[CodeAction, Command]]:
+    corrected_value = code_action_data["correct_value"]
+    edits = [
+        TextEdit(
+            diagnostic.range,
+            corrected_value,
+        ),
+    ]
+    yield CodeAction(
+        title=f'Replace with "{corrected_value}"',
+        kind=CodeActionKind.QuickFix,
+        diagnostics=[diagnostic],
+        edit=WorkspaceEdit(
+            changes={code_action_params.text_document.uri: edits},
+            document_changes=[
+                TextDocumentEdit(
+                    text_document=OptionalVersionedTextDocumentIdentifier(
+                        uri=code_action_params.text_document.uri,
+                    ),
+                    edits=edits,
+                )
+            ],
+        ),
+    )
+
+
+def range_compatible_with_remove_line_fix(range_: Range) -> bool:
+    start = range_.start
+    end = range_.end
+    if start.line != end.line and (start.line + 1 != end.line or end.character > 0):
+        return False
+    return True
+
+
+@_code_handler_for("remove-line")
+def _correct_value_code_action(
+    _code_action_data: RemoveLineCodeAction,
+    code_action_params: CodeActionParams,
+    diagnostic: Diagnostic,
+) -> Iterable[Union[CodeAction, Command]]:
+    start = code_action_params.range.start
+    if range_compatible_with_remove_line_fix(code_action_params.range):
+        _warn(
+            "Bug: the quick was used for a diagnostic that spanned multiple lines and would corrupt the file."
+        )
+        return
+
+    edits = [
+        TextEdit(
+            Range(
+                start=Position(
+                    line=start.line,
+                    character=0,
+                ),
+                end=Position(
+                    line=start.line + 1,
+                    character=0,
+                ),
+            ),
+            "",
+        ),
+    ]
+    yield CodeAction(
+        title="Remove the line",
+        kind=CodeActionKind.QuickFix,
+        diagnostics=[diagnostic],
+        edit=WorkspaceEdit(
+            changes={code_action_params.text_document.uri: edits},
+            document_changes=[
+                TextDocumentEdit(
+                    text_document=OptionalVersionedTextDocumentIdentifier(
+                        uri=code_action_params.text_document.uri,
+                    ),
+                    edits=edits,
+                )
+            ],
+        ),
+    )
+
+
+def provide_standard_quickfixes_from_diagnostics(
+    code_action_params: CodeActionParams,
+) -> Optional[List[Union[Command, CodeAction]]]:
+    actions = []
+    for diagnostic in code_action_params.context.diagnostics:
+        data = diagnostic.data
+        if not isinstance(data, list):
+            data = [data]
+        for action_suggestion in data:
+            if (
+                action_suggestion
+                and isinstance(action_suggestion, Mapping)
+                and "code_action" in action_suggestion
+            ):
+                action_name: CodeActionName = action_suggestion["code_action"]
+                handler = CODE_ACTION_HANDLERS.get(action_name)
+                if handler is not None:
+                    actions.extend(
+                        handler(
+                            cast("Mapping[str, str]", action_suggestion),
+                            code_action_params,
+                            diagnostic,
+                        )
+                    )
+                else:
+                    _warn(f"No codeAction handler for {action_name} !?")
+    if not actions:
+        return None
+    return actions
diff --git a/src/debputy/lsp/spellchecking.py b/src/debputy/lsp/spellchecking.py
new file mode 100644
index 0000000..69dd119
--- /dev/null
+++ b/src/debputy/lsp/spellchecking.py
@@ -0,0 +1,304 @@
+import functools
+import itertools
+import os
+import re
+import subprocess
+from typing import Iterable, FrozenSet, Tuple, Optional, List
+
+from debian.debian_support import Release
+from lsprotocol.types import Diagnostic, Range, Position, DiagnosticSeverity
+
+from debputy.lsp.quickfixes import propose_correct_text_quick_fix
+from debputy.lsp.text_util import LintCapablePositionCodec
+from debputy.util import _info, _warn
+
+_SPELL_CHECKER_DICT = "/usr/share/hunspell/en_US.dic"
+_SPELL_CHECKER_AFF = "/usr/share/hunspell/en_US.aff"
+_WORD_PARTS = re.compile(r"(\S+)")
+_PRUNE_SYMBOLS_RE = re.compile(r"(\w+(?:-\w+|'\w+)?)")
+_FIND_QUOTE_CHAR = re.compile(r'["`]')
+_LOOKS_LIKE_FILENAME = re.compile(
+    r"""
+      [.]{0,3}/[a-z0-9]+(/[a-z0-9]+)+/*
+    | [a-z0-9-_]+(/[a-z0-9]+)+/*
+    | [a-z0-9_]+(/[a-z0-9_]+){2,}/*
+    | (?:\S+)?[.][a-z]{1,3}
+
+""",
+    re.VERBOSE,
+)
+_LOOKS_LIKE_PROGRAMMING_TERM = re.compile(
+    r"""
+    (
+        # Java identifier Camel Case
+          [a-z][a-z0-9]*(?:[A-Z]{1,3}[a-z0-9]+)+
+        # Type name Camel Case
+        | [A-Z]{1,3}[a-z0-9]+(?:[A-Z]{1,3}[a-z0-9]+)+
+        # Type name Camel Case with underscore (seen in Dh_Lib.pm among other
+        | [A-Z]{1,3}[a-z0-9]+(?:_[A-Z]{1,3}[a-z0-9]+)+
+        # Perl module
+        | [A-Z]{1,3}[a-z0-9]+(?:_[A-Z]{1,3}[a-z0-9]+)*(::[A-Z]{1,3}[a-z0-9]+(?:_[A-Z]{1,3}[a-z0-9]+)*)+
+        # Probably an abbreviation
+        | [A-Z]{3,}
+        # Perl/Python identifiers or Jinja templates
+        | [$%&@_]?[{]?[{]?[a-z][a-z0-9]*(?:_[a-z0-9]+)+(?:(?:->)?[\[{]\S+|}}?)?
+        # SCREAMING_SNAKE_CASE (environment variables plus -DVAR=B or $FOO)
+        | [-$%&*_]{0,2}[A-Z][A-Z0-9]*(_[A-Z0-9]+)+(?:=\S+)?
+        | \#[A-Z][A-Z0-9]*(_[A-Z0-9]+)+\#
+        # Subcommand names. Require at least two "-" to avoid skipping hypenated words
+        | [a-z][a-z0-9]*(-[a-z0-9]+){2,}
+        # Short args
+        | -[a-z0-9]+
+        # Things like 32bit
+        | \d{2,}-?[a-z]+
+        # Source package (we do not have a package without prefix/suffix because it covers 95% of all lowercase words)
+        | src:[a-z0-9][-+.a-z0-9]+
+        | [a-z0-9][-+.a-z0-9]+:(?:any|native)
+        # Version
+        | v\d+(?:[.]\S+)?
+        # chmod symbolic mode or math
+        | \S*=\S+
+    )
+""",
+    re.VERBOSE,
+)
+_LOOKS_LIKE_EMAIL = re.compile(
+    r"""
+    <[^>@\s]+@[^>@\s]+>
+""",
+    re.VERBOSE,
+)
+_NO_CORRECTIONS = tuple()
+_WORDLISTS = [
+    "debian-wordlist.dic",
+]
+_NAMELISTS = [
+    "logins-and-people.dic",
+]
+_PERSONAL_DICTS = [
+    "${HOME}/.hunspell_default",
+    "${HOME}/.hunspell_en_US",
+]
+
+
+try:
+    if not os.path.lexists(_SPELL_CHECKER_DICT) or not os.path.lexists(
+        _SPELL_CHECKER_AFF
+    ):
+        raise ImportError
+    from hunspell import HunSpell
+
+    _HAS_HUNSPELL = True
+except ImportError:
+    _HAS_HUNSPELL = False
+
+
+def _read_wordlist(
+    base_dir: str, wordlist_name: str, *, namelist: bool = False
+) -> Iterable[str]:
+    with open(os.path.join(base_dir, wordlist_name)) as fd:
+        w = [w.strip() for w in fd]
+        yield from w
+        if namelist:
+            yield from (f"{n}'s" for n in w)
+
+
+def _all_debian_archs() -> Iterable[str]:
+    try:
+        output = subprocess.check_output(["dpkg-architecture", "-L"])
+    except (FileNotFoundError, subprocess.CalledProcessError) as e:
+        _warn(f"dpkg-architecture -L failed: {e}")
+        return tuple()
+
+    return (x.strip() for x in output.decode("utf-8").splitlines())
+
+
+@functools.lru_cache
+def _builtin_exception_words() -> FrozenSet[str]:
+    basedirs = os.path.dirname(__file__)
+    release_names = (x for x in Release.releases)
+    return frozenset(
+        itertools.chain(
+            itertools.chain.from_iterable(
+                _read_wordlist(basedirs, wl) for wl in _WORDLISTS
+            ),
+            itertools.chain.from_iterable(
+                _read_wordlist(basedirs, wl, namelist=True) for wl in _NAMELISTS
+            ),
+            release_names,
+            _all_debian_archs(),
+        )
+    )
+
+
+_DEFAULT_SPELL_CHECKER: Optional["Spellchecker"] = None
+
+
+def spellcheck_line(
+    lines: List[str],
+    position_codec: LintCapablePositionCodec,
+    line_no: int,
+    line: str,
+) -> Iterable[Diagnostic]:
+    spell_checker = default_spellchecker()
+    for word, pos, endpos in spell_checker.iter_words(line):
+        corrections = spell_checker.provide_corrections_for(word)
+        if not corrections:
+            continue
+        word_range_server_units = Range(
+            Position(line_no, pos),
+            Position(line_no, endpos),
+        )
+        word_range = position_codec.range_to_client_units(
+            lines,
+            word_range_server_units,
+        )
+        yield Diagnostic(
+            word_range,
+            f'Spelling "{word}"',
+            severity=DiagnosticSeverity.Hint,
+            source="debputy",
+            data=[propose_correct_text_quick_fix(c) for c in corrections],
+        )
+
+
+def default_spellchecker() -> "Spellchecker":
+    global _DEFAULT_SPELL_CHECKER
+    spellchecker = _DEFAULT_SPELL_CHECKER
+    if spellchecker is None:
+        if _HAS_HUNSPELL:
+            spellchecker = HunspellSpellchecker()
+        else:
+            spellchecker = _do_nothing_spellchecker()
+        _DEFAULT_SPELL_CHECKER = spellchecker
+    return spellchecker
+
+
+@functools.lru_cache()
+def _do_nothing_spellchecker() -> "Spellchecker":
+    return EverythingIsCorrectSpellchecker()
+
+
+def disable_spellchecking() -> None:
+    global _DEFAULT_SPELL_CHECKER
+    _DEFAULT_SPELL_CHECKER = _do_nothing_spellchecker()
+
+
+def _skip_quoted_parts(line: str) -> Iterable[Tuple[str, int]]:
+    current_pos = 0
+    while True:
+        try:
+            m = _FIND_QUOTE_CHAR.search(line, current_pos)
+            if m is None:
+                if current_pos == 0:
+                    yield line, 0
+                else:
+                    yield line[current_pos:], current_pos
+                return
+            starting_marker_pos = m.span()[0]
+            quote_char = m.group()
+            end_marker_pos = line.index(quote_char, starting_marker_pos + 1)
+        except ValueError:
+            yield line[current_pos:], current_pos
+            return
+
+        part = line[current_pos:starting_marker_pos]
+
+        if not part.isspace():
+            yield part, current_pos
+        current_pos = end_marker_pos + 1
+
+
+def _split_line_to_words(line: str) -> Iterable[Tuple[str, int, int]]:
+    for line_part, part_pos in _skip_quoted_parts(line):
+        for m in _WORD_PARTS.finditer(line_part):
+            fullword = m.group(1)
+            if fullword.startswith("--"):
+                # CLI arg
+                continue
+            if _LOOKS_LIKE_PROGRAMMING_TERM.match(fullword):
+                continue
+            if _LOOKS_LIKE_FILENAME.match(fullword):
+                continue
+            if _LOOKS_LIKE_EMAIL.match(fullword):
+                continue
+            mpos = m.span(1)[0]
+            for sm in _PRUNE_SYMBOLS_RE.finditer(fullword):
+                pos, endpos = sm.span(1)
+                offset = part_pos + mpos
+                yield sm.group(1), pos + offset, endpos + offset
+
+
+class Spellchecker:
+
+    @staticmethod
+    def do_nothing_spellchecker() -> "Spellchecker":
+        return EverythingIsCorrectSpellchecker()
+
+    def iter_words(self, line: str) -> Iterable[Tuple[str, int, int]]:
+        yield from _split_line_to_words(line)
+
+    def provide_corrections_for(self, word: str) -> Iterable[str]:
+        raise NotImplementedError
+
+    def ignore_word(self, word: str) -> None:
+        raise NotImplementedError
+
+
+class EverythingIsCorrectSpellchecker(Spellchecker):
+    def provide_corrections_for(self, word: str) -> Iterable[str]:
+        return _NO_CORRECTIONS
+
+    def ignore_word(self, word: str) -> None:
+        # It is hard to ignore words, when you never check them in the fist place.
+        pass
+
+
+class HunspellSpellchecker(Spellchecker):
+
+    def __init__(self) -> None:
+        self._checker = HunSpell(_SPELL_CHECKER_DICT, _SPELL_CHECKER_AFF)
+        for w in _builtin_exception_words():
+            self._checker.add(w)
+        self._load_personal_exclusions()
+
+    def provide_corrections_for(self, word: str) -> Iterable[str]:
+        if word.startswith(
+            (
+                "dpkg-",
+                "dh-",
+                "dh_",
+                "debian-",
+                "debconf-",
+                "update-",
+                "DEB_",
+                "DPKG_",
+            )
+        ):
+            return _NO_CORRECTIONS
+        # 'ing is deliberately forcing a word into another word-class
+        if word.endswith(("'ing", "-nss")):
+            return _NO_CORRECTIONS
+        return self._lookup(word)
+
+    @functools.lru_cache(128)
+    def _lookup(self, word: str) -> Iterable[str]:
+        if self._checker.spell(word):
+            return _NO_CORRECTIONS
+        return self._checker.suggest(word)
+
+    def ignore_word(self, word: str) -> None:
+        self._checker.add(word)
+
+    def _load_personal_exclusions(self) -> None:
+        for filename in _PERSONAL_DICTS:
+            if filename.startswith("${"):
+                end_index = filename.index("}")
+                varname = filename[2:end_index]
+                value = os.environ.get(varname)
+                if value is None:
+                    continue
+                filename = value + filename[end_index + 1 :]
+            if os.path.isfile(filename):
+                _info(f"Loading personal spelling dictionary from {filename}")
+                self._checker.add_dic(filename)
diff --git a/src/debputy/lsp/text_edit.py b/src/debputy/lsp/text_edit.py
new file mode 100644
index 0000000..770a837
--- /dev/null
+++ b/src/debputy/lsp/text_edit.py
@@ -0,0 +1,110 @@
+# Copied and adapted from on python-lsp-server
+#
+# Copyright 2017-2020 Palantir Technologies, Inc.
+# Copyright 2021- Python Language Server Contributors.
+# License: Expat (MIT/X11)
+#
+from typing import List
+
+from lsprotocol.types import Range, TextEdit, Position
+
+
+def get_well_formatted_range(lsp_range: Range) -> Range:
+    start = lsp_range.start
+    end = lsp_range.end
+
+    if start.line > end.line or (
+        start.line == end.line and start.character > end.character
+    ):
+        return Range(end, start)
+
+    return lsp_range
+
+
+def get_well_formatted_edit(text_edit: TextEdit) -> TextEdit:
+    lsp_range = get_well_formatted_range(text_edit.range)
+    if lsp_range != text_edit.range:
+        return TextEdit(new_text=text_edit.new_text, range=lsp_range)
+
+    return text_edit
+
+
+def compare_text_edits(a: TextEdit, b: TextEdit) -> int:
+    diff = a.range.start.line - b.range.start.line
+    if diff == 0:
+        return a.range.start.character - b.range.start.character
+
+    return diff
+
+
+def merge_sort_text_edits(text_edits: List[TextEdit]) -> List[TextEdit]:
+    if len(text_edits) <= 1:
+        return text_edits
+
+    p = len(text_edits) // 2
+    left = text_edits[:p]
+    right = text_edits[p:]
+
+    merge_sort_text_edits(left)
+    merge_sort_text_edits(right)
+
+    left_idx = 0
+    right_idx = 0
+    i = 0
+    while left_idx < len(left) and right_idx < len(right):
+        ret = compare_text_edits(left[left_idx], right[right_idx])
+        if ret <= 0:
+            #  smaller_equal -> take left to preserve order
+            text_edits[i] = left[left_idx]
+            i += 1
+            left_idx += 1
+        else:
+            # greater -> take right
+            text_edits[i] = right[right_idx]
+            i += 1
+            right_idx += 1
+    while left_idx < len(left):
+        text_edits[i] = left[left_idx]
+        i += 1
+        left_idx += 1
+    while right_idx < len(right):
+        text_edits[i] = right[right_idx]
+        i += 1
+        right_idx += 1
+    return text_edits
+
+
+class OverLappingTextEditException(Exception):
+    """
+    Text edits are expected to be sorted
+    and compressed instead of overlapping.
+    This error is raised when two edits
+    are overlapping.
+    """
+
+
+def offset_at_position(lines: List[str], server_position: Position) -> int:
+    row, col = server_position.line, server_position.character
+    return col + sum(len(line) for line in lines[:row])
+
+
+def apply_text_edits(text: str, lines: List[str], text_edits: List[TextEdit]) -> str:
+    sorted_edits = merge_sort_text_edits(
+        [get_well_formatted_edit(e) for e in text_edits]
+    )
+    last_modified_offset = 0
+    spans = []
+    for e in sorted_edits:
+        start_offset = offset_at_position(lines, e.range.start)
+        if start_offset < last_modified_offset:
+            raise OverLappingTextEditException("overlapping edit")
+
+        if start_offset > last_modified_offset:
+            spans.append(text[last_modified_offset:start_offset])
+
+        if e.new_text != "":
+            spans.append(e.new_text)
+        last_modified_offset = offset_at_position(lines, e.range.end)
+
+    spans.append(text[last_modified_offset:])
+    return "".join(spans)
diff --git a/src/debputy/lsp/text_util.py b/src/debputy/lsp/text_util.py
new file mode 100644
index 0000000..d66cb28
--- /dev/null
+++ b/src/debputy/lsp/text_util.py
@@ -0,0 +1,122 @@
+from typing import List, Optional, Sequence, Union, Iterable
+
+from lsprotocol.types import (
+    TextEdit,
+    Position,
+    Range,
+    WillSaveTextDocumentParams,
+)
+
+from debputy.linting.lint_util import LinterPositionCodec
+
+try:
+    from debian._deb822_repro.locatable import Position as TEPosition, Range as TERange
+except ImportError:
+    pass
+
+try:
+    from pygls.workspace import LanguageServer, TextDocument, PositionCodec
+
+    LintCapablePositionCodec = Union[LinterPositionCodec, PositionCodec]
+except ImportError:
+    LintCapablePositionCodec = LinterPositionCodec
+
+
+try:
+    from Levenshtein import distance
+except ImportError:
+
+    def detect_possible_typo(
+        provided_value: str,
+        known_values: Iterable[str],
+    ) -> Sequence[str]:
+        return tuple()
+
+else:
+
+    def detect_possible_typo(
+        provided_value: str,
+        known_values: Iterable[str],
+    ) -> Sequence[str]:
+        k_len = len(provided_value)
+        candidates = []
+        for known_value in known_values:
+            if abs(k_len - len(known_value)) > 2:
+                continue
+            d = distance(provided_value, known_value)
+            if d > 2:
+                continue
+            candidates.append(known_value)
+        return candidates
+
+
+def normalize_dctrl_field_name(f: str) -> str:
+    if not f or not f.startswith(("x", "X")):
+        return f
+    i = 0
+    for i in range(1, len(f)):
+        if f[i] == "-":
+            i += 1
+            break
+        if f[i] not in ("b", "B", "s", "S", "c", "C"):
+            return f
+    assert i > 0
+    return f[i:]
+
+
+def on_save_trim_end_of_line_whitespace(
+    ls: "LanguageServer",
+    params: WillSaveTextDocumentParams,
+) -> Optional[Sequence[TextEdit]]:
+    doc = ls.workspace.get_text_document(params.text_document.uri)
+    return trim_end_of_line_whitespace(doc, doc.lines)
+
+
+def trim_end_of_line_whitespace(
+    doc: "TextDocument",
+    lines: List[str],
+) -> Optional[Sequence[TextEdit]]:
+    edits = []
+    for line_no, orig_line in enumerate(lines):
+        orig_len = len(orig_line)
+        if orig_line.endswith("\n"):
+            orig_len -= 1
+        stripped_len = len(orig_line.rstrip())
+        if stripped_len == orig_len:
+            continue
+
+        edit_range = doc.position_codec.range_to_client_units(
+            lines,
+            Range(
+                Position(
+                    line_no,
+                    stripped_len,
+                ),
+                Position(
+                    line_no,
+                    orig_len,
+                ),
+            ),
+        )
+        edits.append(
+            TextEdit(
+                edit_range,
+                "",
+            )
+        )
+
+    return edits
+
+
+def te_position_to_lsp(te_position: "TEPosition") -> Position:
+    return Position(
+        te_position.line_position,
+        te_position.cursor_position,
+    )
+
+
+def te_range_to_lsp(te_range: "TERange") -> Range:
+    return Range(
+        te_position_to_lsp(te_range.start_pos),
+        te_position_to_lsp(te_range.end_pos),
+    )
diff --git a/src/debputy/lsp/vendoring/__init__.py b/src/debputy/lsp/vendoring/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/lsp/vendoring/__init__.py
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/__init__.py b/src/debputy/lsp/vendoring/_deb822_repro/__init__.py
new file mode 100644
index 0000000..72fe6dc
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/__init__.py
@@ -0,0 +1,191 @@
+# The "from X import Y as Y" looks weird, but we are stuck in a fight
+# between mypy and pylint in the CI.
+#
+#    mypy --strict insists on either of following for re-exporting
+#       1) Do a "from debian._deb822_repro.X import *"
+#       2) Do a "from .X import Y"
+#       3) Do a "from debian._deb822_repro.X import Y as Z"
+#
+#    pylint on the CI fails on relative imports (it assumes "lib" is a
+#    part of the python package name in relative imports).  This rules
+#    out 2) from the mypy list.  The use of 1) would cause overlapping
+#    imports (and also it felt prudent to import only what was exported).
+#
+# This left 3) as the only option for now, which pylint then complains
+# about (not unreasonably in general).  Unfortunately, we can disable
+# that warning in this work around.  But once 2) becomes an option
+# without pylint tripping over itself on the CI, then it considerably
+# better than this approach.
+#
+
+""" Round-trip safe dictionary-like interfaces to RFC822-like files
+
+This module is a round-trip safe API for working with RFC822-like Debian data
+formats. It is primarily aimed files managed by humans, like debian/control.
+While it is be able to process any Deb822 file, you might find the debian.deb822
+module better suited for larger files such as the `Packages` and `Sources`
+from the Debian archive due to reasons explained below.
+
+Being round-trip safe means that this module will faithfully preserve the original
+formatting including whitespace and comments from the input where not modified.
+A concrete example::
+
+    >>> from debian._deb822_repro import parse_deb822_file
+    >>> example_deb822_paragraph = '''
+    ... Package: foo
+    ... # Field comment (because it becomes just before a field)
+    ... Section: main/devel
+    ... Depends: libfoo,
+    ... # Inline comment (associated with the next line)
+    ...          libbar,
+    ... '''
+    >>> deb822_file = parse_deb822_file(example_deb822_paragraph.splitlines())
+    >>> paragraph = next(iter(deb822_file))
+    >>> paragraph['Section'] = 'devel'
+    >>> output = deb822_file.dump()
+    >>> output == example_deb822_paragraph.replace('Section: main/devel', 'Section: devel')
+    True
+
+This makes it particularly good for automated changes/corrections to files (partly)
+maintained by humans.
+
+Compared to debian.deb822
+-------------------------
+
+The round-trip safe API is primarily useful when your program is editing files
+and the file in question is (likely) to be hand-edited or formated directly by
+human maintainers.  This includes files like debian/control and the
+debian/copyright using the "DEP-5" format.
+
+The round-trip safe API also supports parsing and working with invalid files.
+This enables programs to work on the file in cases where the file was a left
+with an error in an attempt to correct it (or ignore it).
+
+On the flip side, the debian.deb822 module generally uses less memory than the
+round trip safe API. In some cases, it will also have faster data structures
+because its internal data structures are simpler. Accordingly, when you are doing
+read-only work or/and working with large files a la the Packages or Sources
+files from the Debian archive, then the round-trip safe API either provides no
+advantages or its trade-offs might show up in performance statistics.
+
+The memory and runtime performance difference should generally be constant for
+valid files but not necessarily a small one.  For invalid files, some operations
+can degrade in runtime performance in particular cases (memory performance for
+invalid files are comparable to that of valid files).
+
+Converting from debian.deb822
+=============================
+
+The following is a short example for how to migrate from debian.deb822 to
+the round-trip safe API. Given the following source text::
+
+    >>> dctrl_input = b'''
+    ... Source: foo
+    ... Build-Depends: debhelper-compat (= 13)
+    ...
+    ... Package: bar
+    ... Architecture: any
+    ... Depends: ${misc:Depends},
+    ...          ${shlibs:Depends},
+    ... Description: provides some exciting feature
+    ...  yada yada yada
+    ...  .
+    ...  more deskription with a misspelling
+    ... '''.lstrip()  # To remove the leading newline
+    >>> # A few definitions to emulate file I/O (would be different in the program)
+    >>> import contextlib, os
+    >>> @contextlib.contextmanager
+    ... def open_input():
+    ...     # Works with and without keepends=True.
+    ...     # Keep the ends here to truly emulate an open file.
+    ...     yield dctrl_input.splitlines(keepends=True)
+    >>> def open_output():
+    ...    return open(os.devnull, 'wb')
+
+With debian.deb822, your code might look like this::
+
+    >>> from debian.deb822 import Deb822
+    >>> with open_input() as in_fd, open_output() as out_fd:
+    ...     for paragraph in Deb822.iter_paragraphs(in_fd):
+    ...         if 'Description' not in paragraph:
+    ...             continue
+    ...         description = paragraph['Description']
+    ...         # Fix typo
+    ...         paragraph['Description'] = description.replace('deskription', 'description')
+    ...         paragraph.dump(out_fd)
+
+With the round-trip safe API, the rewrite would look like this::
+
+    >>> from debian._deb822_repro import parse_deb822_file
+    >>> with open_input() as in_fd, open_output() as out_fd:
+    ...     parsed_file = parse_deb822_file(in_fd)
+    ...     for paragraph in parsed_file:
+    ...         if 'Description' not in paragraph:
+    ...             continue
+    ...         description = paragraph['Description']
+    ...         # Fix typo
+    ...         paragraph['Description'] = description.replace('deskription', 'description')
+    ...     parsed_file.dump(out_fd)
+
+Key changes are:
+
+ 1. Imports are different.
+ 2. Deb822.iter_paragraphs is replaced by parse_deb822_file and a reference to
+    its return value is kept for later.
+ 3. Instead of dumping paragraphs one by one, the return value from
+    parse_deb822_file is dumped at the end.
+
+    -  The round-trip safe api does support "per-paragraph" but formatting
+       and comments between paragraphs would be lost in the output. This may
+       be an acceptable tradeoff or desired for some cases.
+
+Note that the round trip safe API does not accept all the same parameters as the
+debian.deb822 module does.  Often this is because the feature is not relevant for
+the round-trip safe API (e.g., python-apt cannot be used as it discard comments)
+or is obsolete in the debian.deb822 module and therefore omitted.
+
+For list based fields, you may want to have a look at the
+Deb822ParagraphElement.as_interpreted_dict_view method.
+
+Stability of this API
+---------------------
+
+The API is subject to change based on feedback from early adoptors and beta
+testers.  That said, the code for valid files is unlikely to change in
+a backwards incompatible way.
+
+Things that might change in an incompatible way include:
+ * Whether invalid files are accepted (parsed without errors) by default.
+   (currently they are)
+ * How invalid files are parsed.  As an example, currently a syntax error acts
+   as a paragraph separator. Whether it should is open to debate.
+
+"""
+
+# pylint: disable=useless-import-alias
+from .parsing import (
+    parse_deb822_file as parse_deb822_file,
+    LIST_SPACE_SEPARATED_INTERPRETATION as LIST_SPACE_SEPARATED_INTERPRETATION,
+    LIST_COMMA_SEPARATED_INTERPRETATION as LIST_COMMA_SEPARATED_INTERPRETATION,
+    Interpretation as Interpretation,
+    # Primarily for documentation purposes / help()
+    Deb822FileElement as Deb822FileElement,
+    Deb822NoDuplicateFieldsParagraphElement,
+    Deb822ParagraphElement as Deb822ParagraphElement,
+)
+from .types import (
+    AmbiguousDeb822FieldKeyError as AmbiguousDeb822FieldKeyError,
+    SyntaxOrParseError,
+)
+
+__all__ = [
+    "parse_deb822_file",
+    "AmbiguousDeb822FieldKeyError",
+    "LIST_SPACE_SEPARATED_INTERPRETATION",
+    "LIST_COMMA_SEPARATED_INTERPRETATION",
+    "Interpretation",
+    "Deb822FileElement",
+    "Deb822NoDuplicateFieldsParagraphElement",
+    "Deb822ParagraphElement",
+    "SyntaxOrParseError",
+]
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/_util.py b/src/debputy/lsp/vendoring/_deb822_repro/_util.py
new file mode 100644
index 0000000..a79426d
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/_util.py
@@ -0,0 +1,291 @@
+import collections
+import collections.abc
+import logging
+import sys
+import textwrap
+from abc import ABC
+
+try:
+    from typing import (
+        Optional,
+        Union,
+        Iterable,
+        Callable,
+        TYPE_CHECKING,
+        Iterator,
+        Type,
+        cast,
+        List,
+        Generic,
+    )
+    from debian._util import T
+    from .types import TE, R, TokenOrElement
+
+    _combine_parts_ret_type = Callable[
+        [Iterable[Union[TokenOrElement, TE]]], Iterable[Union[TokenOrElement, R]]
+    ]
+except ImportError:
+    # pylint: disable=unnecessary-lambda-assignment
+    TYPE_CHECKING = False
+    cast = lambda t, v: v
+
+
+if TYPE_CHECKING:
+    from .parsing import Deb822Element
+    from .tokens import Deb822Token
+
+
+def print_ast(
+    ast_tree,  # type: Union[Iterable[TokenOrElement], 'Deb822Element']
+    *,
+    end_marker_after=5,  # type: Optional[int]
+    output_function=None  # type: Optional[Callable[[str], None]]
+):
+    # type: (...) -> None
+    """Debugging aid, which can dump a Deb822Element or a list of tokens/elements
+
+    :param ast_tree: Either a Deb822Element or an iterable Deb822Token/Deb822Element entries
+      (both types may be mixed in the same iterable, which enable it to dump the
+      ast tree at different stages of parse_deb822_file method)
+    :param end_marker_after: The dump will add "end of element" markers if a
+      given element spans at least this many tokens/elements. Can be disabled
+      with by passing None as value. Use 0 for unconditionally marking all
+      elements (note that tokens never get an "end of element" marker as they
+      are not an elements).
+    :param output_function: Callable that receives a single str argument and is responsible
+      for "displaying" that line. The callable may be invoked multiple times (one per line
+      of output).  Defaults to logging.info if omitted.
+
+    """
+    # Avoid circular dependency
+    # pylint: disable=import-outside-toplevel
+    from debian._deb822_repro.parsing import Deb822Element
+
+    prefix = None
+    if isinstance(ast_tree, Deb822Element):
+        ast_tree = [ast_tree]
+    stack = [(0, "", iter(ast_tree))]
+    current_no = 0
+    if output_function is None:
+        output_function = logging.info
+    while stack:
+        start_no, name, current_iter = stack[-1]
+        for current in current_iter:
+            current_no += 1
+            if prefix is None:
+                prefix = "  " * len(stack)
+            if isinstance(current, Deb822Element):
+                stack.append(
+                    (current_no, current.__class__.__name__, iter(current.iter_parts()))
+                )
+                output_function(prefix + current.__class__.__name__)
+                prefix = None
+                break
+            output_function(prefix + str(current))
+        else:
+            # current_iter is depleted
+            stack.pop()
+            prefix = None
+            if (
+                end_marker_after is not None
+                and start_no + end_marker_after <= current_no
+                and name
+            ):
+                if prefix is None:
+                    prefix = "  " * len(stack)
+                output_function(prefix + "# <-- END OF " + name)
+
+
+def combine_into_replacement(
+    source_class,  # type: Type[TE]
+    replacement_class,  # type: Type[R]
+    *,
+    constructor=None  # type: Optional[Callable[[List[TE]], R]]
+):
+    # type: (...) -> _combine_parts_ret_type[TE, R]
+    """Combines runs of one type into another type
+
+    This is primarily useful for transforming tokens (e.g, Comment tokens) into
+    the relevant element (such as the Comment element).
+    """
+    if constructor is None:
+        _constructor = cast("Callable[[List[TE]], R]", replacement_class)
+    else:
+        # Force mypy to see that constructor is no longer optional
+        _constructor = constructor
+
+    def _impl(token_stream):
+        # type: (Iterable[Union[TokenOrElement, TE]]) -> Iterable[Union[TokenOrElement, R]]
+        tokens = []
+        for token in token_stream:
+            if isinstance(token, source_class):
+                tokens.append(token)
+                continue
+
+            if tokens:
+                yield _constructor(list(tokens))
+                tokens.clear()
+            yield token
+
+        if tokens:
+            yield _constructor(tokens)
+
+    return _impl
+
+
+if sys.version_info >= (3, 9) or TYPE_CHECKING:
+    _bufferingIterator_Base = collections.abc.Iterator[T]
+else:
+    # Python 3.5 - 3.8 compat - we are not allowed to subscript the abc.Iterator
+    # - use this little hack to work around it
+    class _bufferingIterator_Base(collections.abc.Iterator, Generic[T], ABC):
+        pass
+
+
+class BufferingIterator(_bufferingIterator_Base[T], Generic[T]):
+
+    def __init__(self, stream):
+        # type: (Iterable[T]) -> None
+        self._stream = iter(stream)  # type: Iterator[T]
+        self._buffer = collections.deque()  # type: collections.deque[T]
+        self._expired = False  # type: bool
+
+    def __next__(self):
+        # type: () -> T
+        if self._buffer:
+            return self._buffer.popleft()
+        if self._expired:
+            raise StopIteration
+        return next(self._stream)
+
+    def takewhile(self, predicate):
+        # type: (Callable[[T], bool]) -> Iterable[T]
+        """Variant of itertools.takewhile except it does not discard the first non-matching token"""
+        buffer = self._buffer
+        while buffer or self._fill_buffer(5):
+            v = buffer[0]
+            if predicate(v):
+                buffer.popleft()
+                yield v
+            else:
+                break
+
+    def consume_many(self, count):
+        # type: (int) -> List[T]
+        self._fill_buffer(count)
+        buffer = self._buffer
+        if len(buffer) == count:
+            ret = list(buffer)
+            buffer.clear()
+        else:
+            ret = []
+            while buffer and count:
+                ret.append(buffer.popleft())
+                count -= 1
+        return ret
+
+    def peek_buffer(self):
+        # type: () -> List[T]
+        return list(self._buffer)
+
+    def peek_find(
+        self,
+        predicate,  # type: Callable[[T], bool]
+        limit=None,  # type: Optional[int]
+    ):
+        # type: (...) -> Optional[int]
+        buffer = self._buffer
+        i = 0
+        while limit is None or i < limit:
+            if i >= len(buffer):
+                self._fill_buffer(i + 5)
+                if i >= len(buffer):
+                    return None
+            v = buffer[i]
+            if predicate(v):
+                return i + 1
+            i += 1
+        return None
+
+    def _fill_buffer(self, number):
+        # type: (int) -> bool
+        if not self._expired:
+            while len(self._buffer) < number:
+                try:
+                    self._buffer.append(next(self._stream))
+                except StopIteration:
+                    self._expired = True
+                    break
+        return bool(self._buffer)
+
+    def peek(self):
+        # type: () -> Optional[T]
+        return self.peek_at(1)
+
+    def peek_at(self, tokens_ahead):
+        # type: (int) -> Optional[T]
+        self._fill_buffer(tokens_ahead)
+        return (
+            self._buffer[tokens_ahead - 1]
+            if len(self._buffer) >= tokens_ahead
+            else None
+        )
+
+    def peek_many(self, number):
+        # type: (int) -> List[T]
+        self._fill_buffer(number)
+        buffer = self._buffer
+        if len(buffer) == number:
+            ret = list(buffer)
+        elif number:
+            ret = []
+            for t in buffer:
+                ret.append(t)
+                number -= 1
+                if not number:
+                    break
+        else:
+            ret = []
+        return ret
+
+
+def len_check_iterator(
+    content,  # type: str
+    stream,  # type: Iterable[TE]
+    content_len=None,  # type: Optional[int]
+):
+    # type: (...) -> Iterable[TE]
+    """Flatten a parser's output into tokens and verify it covers the entire line/text"""
+    if content_len is None:
+        content_len = len(content)
+    # Fail-safe to ensure none of the value parsers incorrectly parse a value.
+    covered = 0
+    for token_or_element in stream:
+        # We use the AttributeError to discriminate between elements and tokens
+        # The cast()s are here to assist / workaround mypy not realizing that.
+        try:
+            tokens = cast("Deb822Element", token_or_element).iter_tokens()
+        except AttributeError:
+            token = cast("Deb822Token", token_or_element)
+            covered += len(token.text)
+        else:
+            for token in tokens:
+                covered += len(token.text)
+        yield token_or_element
+    if covered != content_len:
+        if covered < content_len:
+            msg = textwrap.dedent(
+                """\
+            Value parser did not fully cover the entire line with tokens (
+            missing range {covered}..{content_len}).  Occurred when parsing "{content}"
+            """
+            ).format(covered=covered, content_len=content_len, line=content)
+            raise ValueError(msg)
+        msg = textwrap.dedent(
+            """\
+                    Value parser emitted tokens for more text than was present?  Should have
+                     emitted {content_len} characters, got {covered}. Occurred when parsing
+                     "{content}"
+                    """
+        ).format(covered=covered, content_len=content_len, content=content)
+        raise ValueError(msg)
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/formatter.py b/src/debputy/lsp/vendoring/_deb822_repro/formatter.py
new file mode 100644
index 0000000..a2b797b
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/formatter.py
@@ -0,0 +1,478 @@
+import operator
+
+from ._util import BufferingIterator
+from .tokens import Deb822Token
+
+# Consider these "opaque" enum-like values.  The actual value was chosen to
+# make repr easier to implement, but they are subject to change.
+_CONTENT_TYPE_VALUE = "is_value"
+_CONTENT_TYPE_COMMENT = "is_comment"
+_CONTENT_TYPE_SEPARATOR = "is_separator"
+
+try:
+    from typing import Iterator, Union, Literal
+    from .types import TokenOrElement, FormatterCallback
+except ImportError:
+    pass
+
+
+class FormatterContentToken(object):
+    """Typed, tagged text for use with the formatting API
+
+    The FormatterContentToken is used by the formatting API and provides the
+    formatter callback with context about the textual tokens it is supposed
+    to format.
+    """
+
+    __slots__ = ("_text", "_content_type")
+
+    def __init__(self, text, content_type):
+        # type: (str, object) -> None
+        self._text = text
+        self._content_type = content_type
+
+    @classmethod
+    def from_token_or_element(cls, token_or_element):
+        # type: (TokenOrElement) -> FormatterContentToken
+        if isinstance(token_or_element, Deb822Token):
+            if token_or_element.is_comment:
+                return cls.comment_token(token_or_element.text)
+            if token_or_element.is_whitespace:
+                raise ValueError("FormatterContentType cannot be whitespace")
+            return cls.value_token(token_or_element.text)
+        # Elements are assumed to be content (this is specialized for the
+        # interpretations where comments are always tokens).
+        return cls.value_token(token_or_element.convert_to_text())
+
+    @classmethod
+    def separator_token(cls, text):
+        # type: (str) -> FormatterContentToken
+        # Special-case separators as a minor memory optimization
+        if text == " ":
+            return SPACE_SEPARATOR_FT
+        if text == ",":
+            return COMMA_SEPARATOR_FT
+        return cls(text, _CONTENT_TYPE_SEPARATOR)
+
+    @classmethod
+    def comment_token(cls, text):
+        # type: (str) -> FormatterContentToken
+        """Generates a single comment token with the provided text
+
+        Mostly useful for creating test cases
+        """
+        return cls(text, _CONTENT_TYPE_COMMENT)
+
+    @classmethod
+    def value_token(cls, text):
+        # type: (str) -> FormatterContentToken
+        """Generates a single value token with the provided text
+
+        Mostly useful for creating test cases
+        """
+        return cls(text, _CONTENT_TYPE_VALUE)
+
+    @property
+    def is_comment(self):
+        # type: () -> bool
+        """True if this formatter token represent a comment
+
+        This should be used for determining whether the token is a comment
+        or not. It might be tempting to check whether the text in the token
+        starts with a "#" but that is insufficient because a value *can*
+        start with that as well.  Whether it is a comment or a value is
+        based on the context (it is a comment if and only if the "#" was
+        at the start of a line) but the formatter often do not have the
+        context available to assert this.
+
+        The formatter *should* preserve the order of comments and interleave
+        between the value tokens in the same order as it see them.  Failing
+        to preserve the order of comments and values can cause confusing
+        comments (such as associating the comment with a different value
+        than it was written for).
+
+        The formatter *may* discard comment tokens if it does not want to
+        preserve them.  If so, they would be omitted in the output, which
+        may be acceptable in some cases.  This is a lot better than
+        re-ordering comments.
+
+        Formatters must be aware of the following special cases for comments:
+         * Comments *MUST* be emitted after a newline.  If the very first token
+           is a comment, the formatter is expected to emit a newline before it
+           as well (Fields cannot start immediately on a comment).
+        """
+        return self._content_type is _CONTENT_TYPE_COMMENT
+
+    @property
+    def is_value(self):
+        # type: () -> bool
+        """True if this formatter token represents a semantic value
+
+        The formatter *MUST* preserve values as-in in its output.  It may
+        "unpack" it from the token (as in, return it as a part of a plain
+        str) but the value content must not be changed nor re-ordered relative
+        to other value tokens (as that could change the meaning of the field).
+        """
+        return self._content_type is _CONTENT_TYPE_VALUE
+
+    @property
+    def is_separator(self):
+        # type: () -> bool
+        """True if this formatter token represents a separator token
+
+        The formatter is not required to preserve the provided separators but it
+        is required to properly separate values.  In fact, often is a lot easier
+        to discard existing separator tokens.  As an example, in whitespace
+        separated list of values space, tab and newline all counts as separator.
+        However, formatting-wise, there is a world of difference between the
+        a space, tab and a newline. In particularly, newlines must be followed
+        by an additional space or tab (to act as a value continuation line) if
+        there is a value following it (otherwise, the generated output is
+        invalid).
+        """
+        return self._content_type is _CONTENT_TYPE_SEPARATOR
+
+    @property
+    def is_whitespace(self):
+        # type: () -> bool
+        """True if this formatter token represents a whitespace token"""
+        return self._content_type is _CONTENT_TYPE_SEPARATOR and self._text.isspace()
+
+    @property
+    def text(self):
+        # type: () -> str
+        """The actual context of the token
+
+        This field *must not* be used to determine the type of token.  The
+        formatter cannot reliably tell whether "#..." is a comment or a value
+        (it can be both).  Use is_value and is_comment instead for discriminating
+        token types.
+
+        For value tokens, this the concrete value to be omitted.
+
+        For comment token, this is the full comment text.
+
+        This is the same as str(token).
+        """
+        return self._text
+
+    def __str__(self):
+        # type: () -> str
+        return self._text
+
+    def __repr__(self):
+        # type: () -> str
+        return "{}({!r}, {}=True)".format(
+            self.__class__.__name__, self._text, self._content_type
+        )
+
+
+SPACE_SEPARATOR_FT = FormatterContentToken(" ", _CONTENT_TYPE_SEPARATOR)
+COMMA_SEPARATOR_FT = FormatterContentToken(",", _CONTENT_TYPE_SEPARATOR)
+
+
+def one_value_per_line_formatter(
+    indentation,  # type: Union[int, Literal["FIELD_NAME_LENGTH"]]
+    trailing_separator=True,  # type: bool
+    immediate_empty_line=False,  # type: bool
+):
+    # type: (...) -> FormatterCallback
+    """Provide a simple formatter that can handle indentation and trailing separators
+
+    All formatters returned by this function puts exactly one value per line.  This
+    pattern is commonly seen in the "Depends" field and similar fields of
+    debian/control files.
+
+    :param indentation: Either the literal string "FIELD_NAME_LENGTH" or a positive
+    integer, which determines the indentation for fields.  If it is an integer,
+    then a fixed indentation is used (notably the value 1 ensures the shortest
+    possible indentation).  Otherwise, if it is "FIELD_NAME_LENGTH", then the
+    indentation is set such that it aligns the values based on the field name.
+    :param trailing_separator: If True, then the last value will have a trailing
+    separator token (e.g., ",") after it.
+    :param immediate_empty_line: Whether the value should always start with an
+    empty line.  If True, then the result becomes something like "Field:\n value".
+
+    """
+    if indentation != "FIELD_NAME_LENGTH" and indentation < 1:
+        raise ValueError('indentation must be at least 1 (or "FIELD_NAME_LENGTH")')
+
+    def _formatter(
+        name,  # type: str
+        sep_token,  # type: FormatterContentToken
+        formatter_tokens,  # type: Iterator[FormatterContentToken]
+    ):
+        # type: (...) -> Iterator[Union[FormatterContentToken, str]]
+        if indentation == "FIELD_NAME_LENGTH":
+            indent_len = len(name) + 2
+        else:
+            indent_len = indentation
+        indent = " " * indent_len
+
+        emitted_first_line = False
+        tok_iter = BufferingIterator(formatter_tokens)
+        is_value = operator.attrgetter("is_value")
+        if immediate_empty_line:
+            emitted_first_line = True
+            yield "\n"
+        for t in tok_iter:
+            if t.is_comment:
+                if not emitted_first_line:
+                    yield "\n"
+                yield t
+            elif t.is_value:
+                if not emitted_first_line:
+                    yield " "
+                else:
+                    yield indent
+                yield t
+                if not sep_token.is_whitespace and (
+                    trailing_separator or tok_iter.peek_find(is_value)
+                ):
+                    yield sep_token
+                yield "\n"
+            else:
+                # Skip existing separators (etc.)
+                continue
+            emitted_first_line = True
+
+    return _formatter
+
+
+one_value_per_line_trailing_separator = one_value_per_line_formatter(
+    "FIELD_NAME_LENGTH", trailing_separator=True
+)
+
+
+def format_field(
+    formatter,  # type: FormatterCallback
+    field_name,  # type: str
+    separator_token,  # type: FormatterContentToken
+    token_iter,  # type: Iterator[FormatterContentToken]
+):
+    # type: (...) -> str
+    """Format a field using a provided formatter
+
+    This function formats a series of tokens using the provided formatter.
+    It can be used as a standalone formatter engine and can be used in test
+    suites to validate third-party formatters (enabling them to test for
+    corner cases without involving parsing logic).
+
+    The formatter receives series of FormatterContentTokens (via the
+    token_iter) and is expected to yield one or more str or
+    FormatterContentTokens.  The calling function will combine all of
+    these into a single string, which will be used as the value.
+
+    The formatter is recommended to yield the provided value and comment
+    tokens interleaved with text segments of whitespace and separators
+    as part of its output.  If it preserve comment and value tokens, the
+    calling function can provide some runtime checks to catch bugs
+    (like the formatter turning a comment into a value because it forgot
+    to ensure that the comment was emitted directly after a newline
+    character).
+
+    When writing a formatter, please keep the following in mind:
+
+     * The output of the formatter is appended directly after the ":" separator.
+       Most formatters will want to emit either a space or a newline as the very
+       first character for readability.
+       (compare "Depends:foo\\n" to "Depends: foo\\n")
+
+     * The formatter must always end its output on a newline.  This is a design
+       choice of how the round-trip safe parser represent values that is imposed
+       on the formatter.
+
+     * It is often easier to discard/ignore all separator tokens from the
+       the provided token sequence and instead just yield separator tokens/str
+       where the formatter wants to place them.
+
+         - The formatter is strongly recommended to special-case formatting
+           for whitespace separators (check for `separator_token.is_whitespace`).
+
+           This is because space, tab and newline all counts as valid separators
+           and can all appear in the token sequence. If the original field uses
+           a mix of these separators it is likely to completely undermine the
+           desired result. Not to mention the additional complexity of handling
+           when a separator token happens to use the newline character which
+           affects how the formatter is supposed what comes after it
+           (see the rules for comments, empty lines and continuation line
+           markers).
+
+     * The formatter must remember to emit a "continuation line" marker
+       (typically a single space or tab) when emitting a value after
+       a newline or a comment. A `yield " "` is sufficient.
+
+        - The continuation line marker may be embedded inside a str
+          with other whitespace (such as the newline coming before it
+          or/and whitespace used for indentation purposes following
+          the marker).
+
+     * The formatter must not cause the output to contain completely
+       empty/whitespace lines as these cause syntax errors.  The first
+       line never counts as an empty line (as it will be appended after
+       the field name).
+
+     * Tokens must be discriminated via the `token.is_value` (etc.)
+       properties. Assuming that `token.text.startswith("#")` implies a
+       comment and similar stunts are wrong.  As an example, "#foo" is a
+       perfectly valid value in some contexts.
+
+     * Comment tokens *always* take up exactly one complete line including
+       the newline character at the end of the line. They must be emitted
+       directly after a newline character or another comment token.
+
+     * Special cases that are rare but can happen:
+
+       - Fields *can* start with comments and requires a formatter provided newline.
+         (Example: "Depends:\\n# Comment here\\n foo")
+
+       - Fields *can* start on a separator or have two separators in a row.
+         This is especially true for whitespace separated fields where every
+         whitespace counts as a separator, but it can also happen with other
+         separators (such as comma).
+
+       - Value tokens can contain whitespace (for non-whitespace separators).
+         When they do, the formatter must not attempt change nor "normalize"
+         the whitespace inside the value token as that might change how the
+         value is interpreted.  (If you want to normalize such whitespace,
+         the formatter is at the wrong abstraction level.  Instead, manipulate
+         the values directly in the value interpretation layer)
+
+    This function will provide *some* runtime checks of its input and the
+    output from the formatter to detect some errors early and provide
+    helpful diagnostics.  If you use the function for testing, you are
+    recommended to rely on verifying the output of the function rather than
+    relying on the runtime checks (as these are subject to change).
+
+    :param formatter: A formatter (see FormatterCallback for the type).
+    Basic formatting is provided via one_value_per_line_trailing_separator
+    (a formatter) or one_value_per_line_formatter (a formatter generator).
+    :param field_name: The name of the field.
+    :param separator_token: One of SPACE_SEPARATOR and COMMA_SEPARATOR
+    :param token_iter: An iterable of tokens to be formatted.
+
+    The following example shows how to define a formatter_callback along with
+    a few verifications.
+
+    >>> fmt_field_len_sep = one_value_per_line_trailing_separator
+    >>> fmt_shortest = one_value_per_line_formatter(
+    ...   1,
+    ...   trailing_separator=False
+    ... )
+    >>> fmt_newline_first = one_value_per_line_formatter(
+    ...   1,
+    ...   trailing_separator=False,
+    ...   immediate_empty_line=True
+    ... )
+    >>> # Omit separator tokens for in the token list for simplicity (the formatter does
+    >>> # not use them, and it enables us to keep the example simple by reusing the list)
+    >>> tokens = [
+    ...     FormatterContentToken.value_token("foo"),
+    ...     FormatterContentToken.comment_token("# some comment about bar\\n"),
+    ...     FormatterContentToken.value_token("bar"),
+    ... ]
+    >>> # Starting with fmt_dl_ts
+    >>> print(format_field(fmt_field_len_sep, "Depends", COMMA_SEPARATOR_FT, tokens), end='')
+    Depends: foo,
+    # some comment about bar
+             bar,
+    >>> print(format_field(fmt_field_len_sep, "Architecture", SPACE_SEPARATOR_FT, tokens), end='')
+    Architecture: foo
+    # some comment about bar
+                  bar
+    >>> # Control check for the special case where the field starts with a comment
+    >>> print(format_field(fmt_field_len_sep, "Depends", COMMA_SEPARATOR_FT, tokens[1:]), end='')
+    Depends:
+    # some comment about bar
+             bar,
+    >>> # Also, check single line values (to ensure it ends on a newline)
+    >>> print(format_field(fmt_field_len_sep, "Depends", COMMA_SEPARATOR_FT, tokens[2:]), end='')
+    Depends: bar,
+    >>> ### Changing format to the shortest length
+    >>> print(format_field(fmt_shortest, "Depends", COMMA_SEPARATOR_FT, tokens), end='')
+    Depends: foo,
+    # some comment about bar
+     bar
+    >>> print(format_field(fmt_shortest, "Architecture", SPACE_SEPARATOR_FT, tokens), end='')
+    Architecture: foo
+    # some comment about bar
+     bar
+    >>> # Control check for the special case where the field starts with a comment
+    >>> print(format_field(fmt_shortest, "Depends", COMMA_SEPARATOR_FT, tokens[1:]), end='')
+    Depends:
+    # some comment about bar
+     bar
+    >>> # Also, check single line values (to ensure it ends on a newline)
+    >>> print(format_field(fmt_shortest, "Depends", COMMA_SEPARATOR_FT, tokens[2:]), end='')
+    Depends: bar
+    >>> ### Changing format to the newline first format
+    >>> print(format_field(fmt_newline_first, "Depends", COMMA_SEPARATOR_FT, tokens), end='')
+    Depends:
+     foo,
+    # some comment about bar
+     bar
+    >>> print(format_field(fmt_newline_first, "Architecture", SPACE_SEPARATOR_FT, tokens), end='')
+    Architecture:
+     foo
+    # some comment about bar
+     bar
+    >>> # Control check for the special case where the field starts with a comment
+    >>> print(format_field(fmt_newline_first, "Depends", COMMA_SEPARATOR_FT, tokens[1:]), end='')
+    Depends:
+    # some comment about bar
+     bar
+    >>> # Also, check single line values (to ensure it ends on a newline)
+    >>> print(format_field(fmt_newline_first, "Depends", COMMA_SEPARATOR_FT, tokens[2:]), end='')
+    Depends:
+     bar
+    """
+    formatted_tokens = [field_name, ":"]
+    just_after_newline = False
+    last_was_value_token = False
+    if isinstance(token_iter, list):
+        # Stop people from using this to test known "invalid" cases.
+        last_token = token_iter[-1]
+        if last_token.is_comment:
+            raise ValueError(
+                "Invalid token_iter: Field values cannot end with comments"
+            )
+    for token in formatter(field_name, separator_token, token_iter):
+        token_as_text = str(token)
+        # If we are given formatter tokens, then use them to verify the output.
+        if isinstance(token, FormatterContentToken):
+            if token.is_comment:
+                if not just_after_newline:
+                    raise ValueError(
+                        "Bad format: Comments must appear directly after a newline."
+                    )
+                # for the sake of ensuring people use proper test data.
+                if not token_as_text.startswith("#"):
+                    raise ValueError("Invalid Comment token: Must start with #")
+                if not token_as_text.endswith("\n"):
+                    raise ValueError("Invalid Comment token: Must end on a newline")
+            elif token.is_value:
+                if token_as_text[0].isspace() or token_as_text[-1].isspace():
+                    raise ValueError(
+                        "Invalid Value token: It cannot start nor end on whitespace"
+                    )
+                if just_after_newline:
+                    raise ValueError("Bad format: Missing continuation line marker")
+                if last_was_value_token:
+                    raise ValueError("Bad format: Formatter omitted a separator")
+
+            last_was_value_token = token.is_value
+        else:
+            last_was_value_token = False
+
+        if just_after_newline:
+            if token_as_text[0] in ("\r", "\n"):
+                raise ValueError("Bad format: Saw completely empty line.")
+            if not token_as_text[0].isspace() and not token_as_text.startswith("#"):
+                raise ValueError("Bad format: Saw completely empty line.")
+        formatted_tokens.append(token_as_text)
+        just_after_newline = token_as_text.endswith("\n")
+
+    formatted_text = "".join(formatted_tokens)
+    if not formatted_text.endswith("\n"):
+        raise ValueError("Bad format: The field value must end on a newline")
+    return formatted_text
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/locatable.py b/src/debputy/lsp/vendoring/_deb822_repro/locatable.py
new file mode 100644
index 0000000..90bfa1c
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/locatable.py
@@ -0,0 +1,413 @@
+import dataclasses
+import itertools
+import sys
+
+from typing import Optional, TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from typing import Self
+    from .parsing import Deb822Element
+
+
+_DATA_CLASS_OPTIONAL_ARGS = {}
+if sys.version_info >= (3, 10):
+    # The `slots` feature greatly reduces the memory usage by avoiding the `__dict__`
+    # instance. But at the end of the day, performance is "nice to have" for this
+    # feature and all current consumers are at Python 3.12 (except the CI tests...)
+    _DATA_CLASS_OPTIONAL_ARGS["slots"] = True
+
+
+@dataclasses.dataclass(frozen=True, **_DATA_CLASS_OPTIONAL_ARGS)
+class Position:
+    """Describes a "cursor" position inside a file
+
+    It consists of a line position (0-based line number) and a cursor position.  This is modelled
+    after the "Position" in Language Server Protocol (LSP).
+    """
+
+    line_position: int
+    """Describes the line position as a 0-based line number
+
+    See line_number if you want a human-readable line number
+    """
+    cursor_position: int
+    """Describes a cursor position ("between two characters") or a character offset.
+
+    When this value is 0, the position is at the start of a line. When it is 1, then
+    the position is between the first and the second character (etc.).
+    """
+
+    @property
+    def line_number(self) -> int:
+        """The line number as human would count it"""
+        return self.line_position + 1
+
+    def relative_to(self, new_base: "Position") -> "Position":
+        """Offsets the position relative to another position
+
+        This is useful to avoid the `position_in_file()` method by caching where
+        the parents position and then for its children you use `range_in_parent()`
+        plus `relative_to()` to rebase the range.
+
+        >>> parent: Locatable = ...                   # doctest: +SKIP
+        >>> children: Iterable[Locatable] = ...       # doctest: +SKIP
+        >>> # This will expensive
+        >>> parent_pos = parent.position_in_file(     # doctest: +SKIP
+        ...    skip_leading_comments=False
+        ... )
+        >>> for child in children:                    # doctest: +SKIP
+        ...    child_pos = child.position_in_parent()
+        ...    # Avoid a position_in_file() for each child
+        ...    child_pos_in_file = child_pos.relative_to(parent_pos)
+        ...    ...  # Use the child_pos_in_file for something
+
+        :param new_base: The position that should have been the origin rather than
+          (0, 0).
+        :returns: The range offset relative to the base position.
+        """
+        if self.line_position == 0 and self.cursor_position == 0:
+            return new_base
+        if new_base.line_position == 0 and new_base.cursor_position == 0:
+            return self
+        if self.line_position == 0:
+            line_number = new_base.line_position
+            line_char_offset = new_base.cursor_position + self.cursor_position
+        else:
+            line_number = self.line_position + new_base.line_position
+            line_char_offset = self.cursor_position
+        return Position(
+            line_number,
+            line_char_offset,
+        )
+
+
+@dataclasses.dataclass(frozen=True, **_DATA_CLASS_OPTIONAL_ARGS)
+class Range:
+    """Describes a range inside a file
+
+    This can be useful to describe things like "from line 4, cursor position 2
+    to line 7 to cursor position 10". When describing a full line including the
+    newline, use line N, cursor position 0 to line N+1. cursor position 0.
+
+    It is also used to denote the size of objects (in that case, the start position
+    is set to START_POSITION as a convention if the precise location is not
+    specified).
+
+    This is modelled after the "Range" in Language Server Protocol (LSP).
+    """
+
+    start_pos: Position
+    end_pos: Position
+
+    @property
+    def start_line_position(self) -> int:
+        """Describes the start line position as a 0-based line number
+
+        See start_line_number if you want a human-readable line number
+        """
+        return self.start_pos.line_position
+
+    @property
+    def start_cursor_position(self) -> int:
+        """Describes the starting cursor position
+
+        When this value is 0, the position is at the start of a line. When it is 1, then
+        the position is between the first and the second character (etc.).
+        """
+        return self.start_pos.cursor_position
+
+    @property
+    def start_line_number(self) -> int:
+        """The start line number as human would count it"""
+        return self.start_pos.line_number
+
+    @property
+    def end_line_position(self) -> int:
+        """Describes the end line position as a 0-based line number
+
+        See end_line_number if you want a human-readable line number
+        """
+        return self.end_pos.line_position
+
+    @property
+    def end_line_number(self) -> int:
+        """The end line number as human would count it"""
+        return self.end_pos.line_number
+
+    @property
+    def end_cursor_position(self) -> int:
+        """Describes the end cursor position
+
+        When this value is 0, the position is at the start of a line. When it is 1, then
+        the position is between the first and the second character (etc.).
+        """
+        return self.end_pos.cursor_position
+
+    @property
+    def line_count(self) -> int:
+        """The number of lines (newlines) spanned by this range.
+
+        Will be zero when the range fits inside one line.
+        """
+        return self.end_line_position - self.start_line_position
+
+    @classmethod
+    def between(cls, a: Position, b: Position) -> "Self":
+        """Computes the range between two positions
+
+        Unlike the constructor, this will always create a "positive" range.
+        That is, the "earliest" position will always be the start position
+        regardless of the order they were passed to `between`. When using
+        the Range constructor, you have freedom to do "inverse" ranges
+        in case that is ever useful
+        """
+        if a.line_position > b.line_position or (
+            a.line_position == b.line_position and a.cursor_position > b.cursor_position
+        ):
+            # Order swap, so `a` is always the earliest position
+            a, b = b, a
+        return cls(
+            a,
+            b,
+        )
+
+    def relative_to(self, new_base: Position) -> "Range":
+        """Offsets the range relative to another position
+
+        This is useful to avoid the `position_in_file()` method by caching where
+        the parents position and then for its children you use `range_in_parent()`
+        plus `relative_to()` to rebase the range.
+
+        >>> parent: Locatable = ...                   # doctest: +SKIP
+        >>> children: Iterable[Locatable] = ...       # doctest: +SKIP
+        >>> # This will expensive
+        >>> parent_pos = parent.position_in_file(     # doctest: +SKIP
+        ...    skip_leading_comments=False
+        ... )
+        >>> for child in children:                    # doctest: +SKIP
+        ...    child_range = child.range_in_parent()
+        ...    # Avoid a position_in_file() for each child
+        ...    child_range_in_file = child_range.relative_to(parent_pos)
+        ...    ...  # Use the child_range_in_file for something
+
+        :param new_base: The position that should have been the origin rather than
+          (0, 0).
+        :returns: The range offset relative to the base position.
+        """
+        if new_base == START_POSITION:
+            return self
+        return Range(
+            self.start_pos.relative_to(new_base),
+            self.end_pos.relative_to(new_base),
+        )
+
+    def as_size(self) -> "Range":
+        """Reduces the range to a "size"
+
+        The returned range will always have its start position to (0, 0) and
+        its end position shifted accordingly if it was not already based at
+        (0, 0).
+
+        The original range is not mutated and, if it is already at (0, 0), the
+        method will just return it as-is.
+        """
+        if self.start_pos == START_POSITION:
+            return self
+        line_count = self.line_count
+        if line_count:
+            new_end_cursor_position = self.end_cursor_position
+        else:
+            delta = self.end_cursor_position - self.start_cursor_position
+            new_end_cursor_position = delta
+        return Range(
+            START_POSITION,
+            Position(
+                line_count,
+                new_end_cursor_position,
+            ),
+        )
+
+    @classmethod
+    def from_position_and_size(cls, base: Position, size: "Range") -> "Self":
+        """Compute a range from a position and the size of another range
+
+        This provides you with a range starting at the base position that has
+        the same effective span as the size parameter.
+
+        :param base: The desired starting position
+        :param size: A range, which will be used as a size (that is, it will
+          be reduced to a size via the `as_size()` method) for the resulting
+          range
+        :returns: A range at the provided base position that has the size of
+          the provided range.
+        """
+        line_position = base.line_position
+        cursor_position = base.cursor_position
+        size_rebased = size.as_size()
+        lines = size_rebased.line_count
+        if lines:
+            line_position += lines
+            cursor_position = size_rebased.end_cursor_position
+        else:
+            delta = (
+                size_rebased.end_cursor_position - size_rebased.start_cursor_position
+            )
+            cursor_position += delta
+        return cls(
+            base,
+            Position(
+                line_position,
+                cursor_position,
+            ),
+        )
+
+    @classmethod
+    def from_position_and_sizes(
+        cls, base: Position, sizes: Iterable["Range"]
+    ) -> "Self":
+        """Compute a range from a position and the size of number of ranges
+
+        :param base: The desired starting position
+        :param sizes: All the ranges that combined makes up the size of the
+          desired position. Note that order can affect the end result. Particularly
+          the end character offset gets reset everytime a size spans a line.
+        :returns: A range at the provided base position that has the size of
+          the provided range.
+        """
+        line_position = base.line_position
+        cursor_position = base.cursor_position
+        for size in sizes:
+            size_rebased = size.as_size()
+            lines = size_rebased.line_count
+            if lines:
+                line_position += lines
+                cursor_position = size_rebased.end_cursor_position
+            else:
+                delta = (
+                    size_rebased.end_cursor_position
+                    - size_rebased.start_cursor_position
+                )
+                cursor_position += delta
+        return cls(
+            base,
+            Position(
+                line_position,
+                cursor_position,
+            ),
+        )
+
+
+START_POSITION = Position(0, 0)
+SECOND_CHAR_POS = Position(0, 1)
+SECOND_LINE_POS = Position(1, 0)
+ONE_CHAR_RANGE = Range.between(START_POSITION, SECOND_CHAR_POS)
+ONE_LINE_RANGE = Range.between(START_POSITION, SECOND_LINE_POS)
+
+
+class Locatable:
+    __slots__ = ()
+
+    @property
+    def parent_element(self):
+        # type: () -> Optional[Deb822Element]
+        raise NotImplementedError
+
+    def position_in_parent(self, *, skip_leading_comments: bool = True) -> Position:
+        """The start position of this token/element inside its parent
+
+        This is operation is generally linear to the number of "parts" (elements/tokens)
+        inside the parent.
+
+        :param skip_leading_comments: If True, then if any leading comment that
+          that can be skipped will be excluded in the position of this locatable.
+          This is useful if you want the position "semantic" content of a field
+          without also highlighting a leading comment. Remember to align this
+          parameter with the `size` call, so the range does not "overshoot"
+          into the next element (or falls short and only covers part of an
+          element). Note that this option can only be used to filter out leading
+          comments when the comments are a subset of the element. It has no
+          effect on elements that are entirely made of comments.
+        """
+        # pylint: disable=unused-argument
+        # Note: The base class makes no assumptions about what tokens can be skipped,
+        # therefore, skip_leading_comments is unused here. However, I do not want the
+        # API to differ between elements and tokens.
+
+        parent = self.parent_element
+        if parent is None:
+            raise TypeError(
+                "Cannot determine the position since the object is detached"
+            )
+        relevant_parts = itertools.takewhile(
+            lambda x: x is not self, parent.iter_parts()
+        )
+        span = Range.from_position_and_sizes(
+            START_POSITION,
+            (x.size(skip_leading_comments=False) for x in relevant_parts),
+        )
+        return span.end_pos
+
+    def range_in_parent(self, *, skip_leading_comments: bool = True) -> Range:
+        """The range of this token/element inside its parent
+
+        This is operation is generally linear to the number of "parts" (elements/tokens)
+        inside the parent.
+
+        :param skip_leading_comments: If True, then if any leading comment that
+          that can be skipped will be excluded in the position of this locatable.
+          This is useful if you want the position "semantic" content of a field
+          without also highlighting a leading comment. Remember to align this
+          parameter with the `size` call, so the range does not "overshoot"
+          into the next element (or falls short and only covers part of an
+          element). Note that this option can only be used to filter out leading
+          comments when the comments are a subset of the element. It has no
+          effect on elements that are entirely made of comments.
+        """
+        pos = self.position_in_parent(skip_leading_comments=skip_leading_comments)
+        return Range.from_position_and_size(
+            pos, self.size(skip_leading_comments=skip_leading_comments)
+        )
+
+    def position_in_file(self, *, skip_leading_comments: bool = True) -> Position:
+        """The start position of this token/element in this file
+
+        This is an *expensive* operation and in many cases have to traverse
+        the entire file structure to answer the query.  Consider whether
+        you can maintain the parent's position and then use
+        `position_in_parent()` combined with
+        `child_position.relative_to(parent_position)`
+
+        :param skip_leading_comments: If True, then if any leading comment that
+          that can be skipped will be excluded in the position of this locatable.
+          This is useful if you want the position "semantic" content of a field
+          without also highlighting a leading comment. Remember to align this
+          parameter with the `size` call, so the range does not "overshoot"
+          into the next element (or falls short and only covers part of an
+          element). Note that this option can only be used to filter out leading
+          comments when the comments are a subset of the element. It has no
+          effect on elements that are entirely made of comments.
+        """
+        position = self.position_in_parent(
+            skip_leading_comments=skip_leading_comments,
+        )
+        parent = self.parent_element
+        if parent is not None:
+            parent_position = parent.position_in_file(skip_leading_comments=False)
+            position = position.relative_to(parent_position)
+        return position
+
+    def size(self, *, skip_leading_comments: bool = True) -> Range:
+        """Describe the objects size as a continuous range
+
+        :param skip_leading_comments: If True, then if any leading comment that
+          that can be skipped will be excluded in the position of this locatable.
+          This is useful if you want the position "semantic" content of a field
+          without also highlighting a leading comment. Remember to align this
+          parameter with the `position_in_file` or `position_in_parent` call,
+          so the range does not "overshoot" into the next element (or falls
+          short and only covers part of an element).  Note that this option can
+          only be used to filter out leading comments when the comments are a
+          subset of the element. It has no effect on elements that are entirely
+          made of comments.
+        """
+        raise NotImplementedError
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/parsing.py b/src/debputy/lsp/vendoring/_deb822_repro/parsing.py
new file mode 100644
index 0000000..13e59b1
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/parsing.py
@@ -0,0 +1,3497 @@
+# -*- coding: utf-8 -*- vim: fileencoding=utf-8 :
+
+import collections.abc
+import contextlib
+import sys
+import textwrap
+import weakref
+from abc import ABC
+from types import TracebackType
+from weakref import ReferenceType
+
+from ._util import (
+    combine_into_replacement,
+    BufferingIterator,
+    len_check_iterator,
+)
+from .formatter import (
+    FormatterContentToken,
+    one_value_per_line_trailing_separator,
+    format_field,
+)
+from .locatable import Locatable, START_POSITION, Position, Range
+from .tokens import (
+    Deb822Token,
+    Deb822ValueToken,
+    Deb822SemanticallySignificantWhiteSpace,
+    Deb822SpaceSeparatorToken,
+    Deb822CommentToken,
+    Deb822WhitespaceToken,
+    Deb822ValueContinuationToken,
+    Deb822NewlineAfterValueToken,
+    Deb822CommaToken,
+    Deb822FieldNameToken,
+    Deb822FieldSeparatorToken,
+    Deb822ErrorToken,
+    tokenize_deb822_file,
+    comma_split_tokenizer,
+    whitespace_split_tokenizer,
+)
+from .types import AmbiguousDeb822FieldKeyError, SyntaxOrParseError
+from debian._util import (
+    resolve_ref,
+    LinkedList,
+    LinkedListNode,
+    OrderedSet,
+    _strI,
+    default_field_sort_key,
+)
+
+try:
+    from typing import (
+        Iterable,
+        Iterator,
+        List,
+        Union,
+        Dict,
+        Optional,
+        Callable,
+        Any,
+        Generic,
+        Type,
+        Tuple,
+        IO,
+        cast,
+        overload,
+        Mapping,
+        TYPE_CHECKING,
+        Sequence,
+    )
+    from debian._util import T
+
+    # for some reason, pylint does not see that Commentish is used in typing
+    from .types import (  # pylint: disable=unused-import
+        ST,
+        VE,
+        TE,
+        ParagraphKey,
+        TokenOrElement,
+        Commentish,
+        ParagraphKeyBase,
+        FormatterCallback,
+    )
+
+    if TYPE_CHECKING:
+        StreamingValueParser = Callable[
+            [Deb822Token, BufferingIterator[Deb822Token]], VE
+        ]
+        StrToValueParser = Callable[[str], Iterable[Union["Deb822Token", VE]]]
+        KVPNode = LinkedListNode["Deb822KeyValuePairElement"]
+    else:
+        StreamingValueParser = None
+        StrToValueParser = None
+        KVPNode = None
+except ImportError:
+    if not TYPE_CHECKING:
+        # pylint: disable=unnecessary-lambda-assignment
+        cast = lambda t, v: v
+        overload = lambda f: None
+
+
+class ValueReference(Generic[TE]):
+    """Reference to a value inside a Deb822 paragraph
+
+    This is useful for cases where want to modify values "in-place" or maybe
+    conditionally remove a value after looking at it.
+
+    ValueReferences can be invalidated by various changes or actions performed
+    to the underlying provider of the value reference.  As an example, sorting
+    a list of values will generally invalidate all ValueReferences related to
+    that list.
+
+    The ValueReference will raise validity issues where it detects them but most
+    of the time it will not notice.  As a means to this end,  the ValueReference
+    will *not* keep a strong reference to the underlying value.  This enables it
+    to detect when the container goes out of scope.  However, keep in mind that
+    the timeliness of garbage collection is implementation defined (e.g., pypy
+    does not use ref-counting).
+    """
+
+    __slots__ = (
+        "_node",
+        "_render",
+        "_value_factory",
+        "_removal_handler",
+        "_mutation_notifier",
+    )
+
+    def __init__(
+        self,
+        node,  # type: LinkedListNode[TE]
+        render,  # type: Callable[[TE], str]
+        value_factory,  # type: Callable[[str], TE]
+        removal_handler,  # type: Callable[[LinkedListNode[TokenOrElement]], None]
+        mutation_notifier,  # type: Optional[Callable[[], None]]
+    ):
+        self._node = weakref.ref(
+            node
+        )  # type: Optional[ReferenceType[LinkedListNode[TE]]]
+        self._render = render
+        self._value_factory = value_factory
+        self._removal_handler = removal_handler
+        self._mutation_notifier = mutation_notifier
+
+    def _resolve_node(self):
+        # type: () -> LinkedListNode[TE]
+        # NB: We check whether the "ref" itself is None (instead of the ref resolving to None)
+        # This enables us to tell the difference between "known removal" vs. "garbage collected"
+        if self._node is None:
+            raise RuntimeError("Cannot use ValueReference after remove()")
+        node = self._node()
+        if node is None:
+            raise RuntimeError("ValueReference is invalid (garbage collected)")
+        return node
+
+    @property
+    def value(self):
+        # type: () -> str
+        """Resolve the reference into a str"""
+        return self._render(self._resolve_node().value)
+
+    @value.setter
+    def value(self, new_value):
+        # type: (str) -> None
+        """Update the reference value
+
+        Updating the value via this method will *not* invalidate the reference (or other
+        references to the same container).
+
+        This can raise an exception if the new value does not follow the requirements
+        for the referenced values.  As an example, values in whitespace separated
+        lists cannot contain spaces and would trigger an exception.
+        """
+        self._resolve_node().value = self._value_factory(new_value)
+        if self._mutation_notifier is not None:
+            self._mutation_notifier()
+
+    @property
+    def locatable(self):
+        # type: () -> Locatable
+        """Reference to a locatable that can be used to determine where this value is"""
+        return self._resolve_node().value
+
+    def remove(self):
+        # type: () -> None
+        """Remove the underlying value
+
+        This will invalidate the ValueReference (and any other ValueReferences pointing
+        to that exact value).  The validity of other ValueReferences to that container
+        remains unaffected.
+        """
+        self._removal_handler(
+            cast("LinkedListNode[TokenOrElement]", self._resolve_node())
+        )
+        self._node = None
+
+
+if sys.version_info >= (3, 9) or TYPE_CHECKING:
+    _Deb822ParsedTokenList_ContextManager = contextlib.AbstractContextManager[T]
+else:
+    # Python 3.5 - 3.8 compat - we are not allowed to subscript the abc.Iterator
+    # - use this little hack to work around it
+    # Note that Python 3.5 is so old that it does not have AbstractContextManager,
+    # so we re-implement it here.
+    class _Deb822ParsedTokenList_ContextManager(Generic[T]):
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc_val, exc_tb):
+            return None
+
+
+class Deb822ParsedTokenList(
+    Generic[VE, ST],
+    _Deb822ParsedTokenList_ContextManager["Deb822ParsedTokenList[VE, ST]"],
+):
+
+    def __init__(
+        self,
+        kvpair_element,  # type: 'Deb822KeyValuePairElement'
+        interpreted_value_element,  # type: Deb822InterpretationProxyElement
+        vtype,  # type: Type[VE]
+        stype,  # type: Type[ST]
+        str2value_parser,  # type: StrToValueParser[VE]
+        default_separator_factory,  # type: Callable[[], ST]
+        render,  # type: Callable[[VE], str]
+    ):
+        # type: (...) -> None
+        self._kvpair_element = kvpair_element
+        self._proxy_element = interpreted_value_element
+        self._token_list = LinkedList(interpreted_value_element.parts)
+        self._vtype = vtype
+        self._stype = stype
+        self._str2value_parser = str2value_parser
+        self._default_separator_factory = default_separator_factory
+        self._value_factory = _parser_to_value_factory(str2value_parser, vtype)
+        self._render = render
+        self._format_preserve_original_formatting = True
+        self._formatter = (
+            one_value_per_line_trailing_separator
+        )  # type: FormatterCallback
+        self._changed = False
+        self.__continuation_line_char = None  # type: Optional[str]
+        assert self._token_list
+        last_token = self._token_list.tail
+
+        if last_token is not None and isinstance(
+            last_token, Deb822NewlineAfterValueToken
+        ):
+            # We always remove the last newline (if present), because then
+            # adding values will happen after the last value rather than on
+            # a new line by default.
+            #
+            # On write, we always ensure the value ends on a newline (even
+            # if it did not before).  This is simpler and should be a
+            # non-issue in practise.
+            self._token_list.pop()
+
+    def __iter__(self):
+        # type: () -> Iterator[str]
+        yield from (self._render(v) for v in self.value_parts)
+
+    def __bool__(self):
+        # type: () -> bool
+        return next(iter(self), None) is not None
+
+    def __exit__(
+        self,
+        exc_type,  # type: Optional[Type[BaseException]]
+        exc_val,  # type: Optional[BaseException]
+        exc_tb,  # type: Optional[TracebackType]
+    ):
+        # type: (...) -> Optional[bool]
+        if exc_type is None and self._changed:
+            self._update_field()
+        return super().__exit__(exc_type, exc_val, exc_tb)
+
+    @property
+    def value_parts(self):
+        # type: () -> Iterator[VE]
+        yield from (v for v in self._token_list if isinstance(v, self._vtype))
+
+    def _mark_changed(self):
+        # type: () -> None
+        self._changed = True
+
+    def iter_value_references(self):
+        # type: () -> Iterator[ValueReference[VE]]
+        """Iterate over all values in the list (as ValueReferences)
+
+        This is useful for doing inplace modification of the values or even
+        streaming removal of field values.  It is in general also more
+        efficient when more than one value is updated or removed.
+        """
+        yield from (
+            ValueReference(
+                cast("LinkedListNode[VE]", n),
+                self._render,
+                self._value_factory,
+                self._remove_node,
+                self._mark_changed,
+            )
+            for n in self._token_list.iter_nodes()
+            if isinstance(n.value, self._vtype)
+        )
+
+    def append_separator(self, space_after_separator=True):
+        # type: (bool) -> None
+
+        separator_token = self._default_separator_factory()
+        if separator_token.is_whitespace:
+            space_after_separator = False
+
+        self._changed = True
+        self._append_continuation_line_token_if_necessary()
+        self._token_list.append(separator_token)
+
+        if space_after_separator and not separator_token.is_whitespace:
+            self._token_list.append(Deb822WhitespaceToken(" "))
+
+    def replace(self, orig_value, new_value):
+        # type: (str, str) -> None
+        """Replace the first instance of a value with another
+
+        This method will *not* affect the validity of ValueReferences.
+        """
+        vtype = self._vtype
+        for node in self._token_list.iter_nodes():
+            if isinstance(node.value, vtype) and self._render(node.value) == orig_value:
+                node.value = self._value_factory(new_value)
+                self._changed = True
+                break
+        else:
+            raise ValueError("list.replace(x, y): x not in list")
+
+    def remove(self, value):
+        # type: (str) -> None
+        """Remove the first instance of a value
+
+        Removal will invalidate ValueReferences to the value being removed.
+        ValueReferences to other values will be unaffected.
+        """
+        vtype = self._vtype
+        for node in self._token_list.iter_nodes():
+            if isinstance(node.value, vtype) and self._render(node.value) == value:
+                node_to_remove = node
+                break
+        else:
+            raise ValueError("list.remove(x): x not in list")
+
+        return self._remove_node(node_to_remove)
+
+    def _remove_node(self, node_to_remove):
+        # type: (LinkedListNode[TokenOrElement]) -> None
+        vtype = self._vtype
+        self._changed = True
+
+        # We naively want to remove the node and every thing to the left of it
+        # until the previous value.  That is the basic idea for now (ignoring
+        # special-cases for now).
+        #
+        # Example:
+        #
+        # """
+        # Multiline-Keywords: bar[
+        # # Comment about foo
+        #                     foo]
+        #                     baz
+        # Keywords: bar[ foo] baz
+        # Comma-List: bar[, foo], baz,
+        # Multiline-Comma-List: bar[,
+        # # Comment about foo
+        #                       foo],
+        #                       baz,
+        # """
+        #
+        # Assuming we want to remove "foo" for the lists, the []-markers
+        # show what we aim to remove.  This has the nice side-effect of
+        # preserving whether nor not the value has a trailing separator.
+        # Note that we do *not* attempt to repair missing separators but
+        # it may fix duplicated separators by "accident".
+        #
+        # Now, there are two special cases to be aware of, where this approach
+        # has short comings:
+        #
+        # 1) If foo is the only value (in which case, "delete everything"
+        #    is the only option).
+        # 2) If foo is the first value
+        # 3) If foo is not the only value on the line and we see a comment
+        #    inside the deletion range.
+        #
+        # For 2) + 3), we attempt to flip and range to delete and every
+        # thing after it (up to but exclusion "baz") instead.  This
+        # definitely fixes 3), but 2) has yet another corner case, namely:
+        #
+        # """
+        # Multiline-Comma-List: foo,
+        # # Remark about bar
+        #                       bar,
+        # Another-Case: foo
+        # # Remark, also we use leading separator
+        #             , bar
+        # """
+        #
+        # The options include:
+        #
+        #  A) Discard the comment - brain-dead simple
+        #  B) Hoist the comment up to a field comment, but then what if the
+        #     field already has a comment?
+        #  C) Clear the first value line leaving just the newline and
+        #     replace the separator before "bar" (if present) with a space.
+        #     (leaving you with the value of the form "\n# ...\n      bar")
+        #
+
+        first_value_on_lhs = None  # type: Optional[LinkedListNode[TokenOrElement]]
+        first_value_on_rhs = None  # type: Optional[LinkedListNode[TokenOrElement]]
+        comment_before_previous_value = False
+        comment_before_next_value = False
+        for past_node in node_to_remove.iter_previous(skip_current=True):
+            past_token = past_node.value
+            if isinstance(past_token, Deb822Token) and past_token.is_comment:
+                comment_before_previous_value = True
+                continue
+            if isinstance(past_token, vtype):
+                first_value_on_lhs = past_node
+                break
+
+        for future_node in node_to_remove.iter_next(skip_current=True):
+            future_token = future_node.value
+            if isinstance(future_token, Deb822Token) and future_token.is_comment:
+                comment_before_next_value = True
+                continue
+            if isinstance(future_token, vtype):
+                first_value_on_rhs = future_node
+                break
+
+        if first_value_on_rhs is None and first_value_on_lhs is None:
+            # This was the last value, just remove everything.
+            self._token_list.clear()
+            return
+
+        if first_value_on_lhs is not None and not comment_before_previous_value:
+            # Delete left
+            delete_lhs_of_node = True
+        elif first_value_on_rhs is not None and not comment_before_next_value:
+            # Delete right
+            delete_lhs_of_node = False
+        else:
+            # There is a comment on either side (or no value on one and a
+            # comment and the other). Keep it simple, we just delete to
+            # one side (preferring deleting to left if possible).
+            delete_lhs_of_node = first_value_on_lhs is not None
+
+        if delete_lhs_of_node:
+            first_remain_lhs = first_value_on_lhs
+            first_remain_rhs = node_to_remove.next_node
+        else:
+            first_remain_lhs = node_to_remove.previous_node
+            first_remain_rhs = first_value_on_rhs
+
+        # Actual deletion - with some manual labour to update HEAD/TAIL of
+        # the list in case we do a "delete everything left/right this node".
+        if first_remain_lhs is None:
+            self._token_list.head_node = first_remain_rhs
+        if first_remain_rhs is None:
+            self._token_list.tail_node = first_remain_lhs
+        LinkedListNode.link_nodes(first_remain_lhs, first_remain_rhs)
+
+    def append(self, value):
+        # type: (str) -> None
+        vt = self._value_factory(value)
+        self.append_value(vt)
+
+    def append_value(self, vt):
+        # type: (VE) -> None
+        value_parts = self._token_list
+        if value_parts:
+            needs_separator = False
+            stype = self._stype
+            vtype = self._vtype
+            for t in reversed(value_parts):
+                if isinstance(t, vtype):
+                    needs_separator = True
+                    break
+                if isinstance(t, stype):
+                    break
+
+            if needs_separator:
+                self.append_separator()
+        else:
+            # Looks nicer if there is a space before the very first value
+            self._token_list.append(Deb822WhitespaceToken(" "))
+        self._append_continuation_line_token_if_necessary()
+        self._changed = True
+        value_parts.append(vt)
+
+    def _previous_is_newline(self):
+        # type: () -> bool
+        tail = self._token_list.tail
+        return tail is not None and tail.convert_to_text().endswith("\n")
+
+    def append_newline(self):
+        # type: () -> None
+        if self._previous_is_newline():
+            raise ValueError(
+                "Cannot add a newline after a token that ends on a newline"
+            )
+        self._token_list.append(Deb822NewlineAfterValueToken())
+
+    def append_comment(self, comment_text):
+        # type: (str) -> None
+        tail = self._token_list.tail
+        if tail is None or not tail.convert_to_text().endswith("\n"):
+            self.append_newline()
+        comment_token = Deb822CommentToken(_format_comment(comment_text))
+        self._token_list.append(comment_token)
+
+    @property
+    def _continuation_line_char(self):
+        # type: () -> str
+        char = self.__continuation_line_char
+        if char is None:
+            # Use ' ' by default but match the existing field if possible.
+            char = " "
+            for token in self._token_list:
+                if isinstance(token, Deb822ValueContinuationToken):
+                    char = token.text
+                    break
+            self.__continuation_line_char = char
+        return char
+
+    def _append_continuation_line_token_if_necessary(self):
+        # type: () -> None
+        tail = self._token_list.tail
+        if tail is not None and tail.convert_to_text().endswith("\n"):
+            self._token_list.append(
+                Deb822ValueContinuationToken(self._continuation_line_char)
+            )
+
+    def reformat_when_finished(self):
+        # type: () -> None
+        self._enable_reformatting()
+        self._changed = True
+
+    def _enable_reformatting(self):
+        # type: () -> None
+        self._format_preserve_original_formatting = False
+
+    def no_reformatting_when_finished(self):
+        # type: () -> None
+        self._format_preserve_original_formatting = True
+
+    def value_formatter(
+        self,
+        formatter,  # type: FormatterCallback
+        force_reformat=False,  # type: bool
+    ):
+        # type: (...) -> None
+        """Use a custom formatter when formatting the value
+
+        :param formatter: A formatter (see debian._deb822_repro.formatter.format_field
+          for details)
+        :param force_reformat: If True, always reformat the field even if there are
+          no (other) changes performed.  By default, fields are only reformatted if
+          they are changed.
+        """
+        self._formatter = formatter
+        self._format_preserve_original_formatting = False
+        if force_reformat:
+            self._changed = True
+
+    def clear(self):
+        # type: () -> None
+        """Like list.clear() - removes all content (including comments and spaces)"""
+        if self._token_list:
+            self._changed = True
+        self._token_list.clear()
+
+    def _iter_content_as_tokens(self):
+        # type: () -> Iterable[Deb822Token]
+        for te in self._token_list:
+            if isinstance(te, Deb822Element):
+                yield from te.iter_tokens()
+            else:
+                yield te
+
+    def _generate_reformatted_field_content(self):
+        # type: () -> str
+        separator_token = self._default_separator_factory()
+        vtype = self._vtype
+        stype = self._stype
+        token_list = self._token_list
+
+        def _token_iter():
+            # type: () -> Iterator[FormatterContentToken]
+            text = ""  # type: str
+            for te in token_list:
+                if isinstance(te, Deb822Token):
+                    if te.is_comment:
+                        yield FormatterContentToken.comment_token(te.text)
+                    elif isinstance(te, stype):
+                        text = te.text
+                        yield FormatterContentToken.separator_token(text)
+                else:
+                    assert isinstance(te, vtype)
+                    text = te.convert_to_text()
+                    yield FormatterContentToken.value_token(text)
+
+        return format_field(
+            self._formatter,
+            self._kvpair_element.field_name,
+            FormatterContentToken.separator_token(separator_token.text),
+            _token_iter(),
+        )
+
+    def _generate_field_content(self):
+        # type: () -> str
+        return "".join(t.text for t in self._iter_content_as_tokens())
+
+    def _update_field(self):
+        # type: () -> None
+        kvpair_element = self._kvpair_element
+        field_name = kvpair_element.field_name
+        token_list = self._token_list
+        tail = token_list.tail
+        had_tokens = False
+
+        for t in self._iter_content_as_tokens():
+            had_tokens = True
+            if not t.is_comment and not t.is_whitespace:
+                break
+        else:
+            if had_tokens:
+                raise ValueError(
+                    "Field must be completely empty or have content "
+                    "(i.e. non-whitespace and non-comments)"
+                )
+        if tail is not None:
+            if isinstance(tail, Deb822Token) and tail.is_comment:
+                raise ValueError("Fields must not end on a comment")
+            if not tail.convert_to_text().endswith("\n"):
+                # Always end on a newline
+                self.append_newline()
+
+            if self._format_preserve_original_formatting:
+                value_text = self._generate_field_content()
+                text = ":".join((field_name, value_text))
+            else:
+                text = self._generate_reformatted_field_content()
+
+            new_content = text.splitlines(keepends=True)
+        else:
+            # Special-case for the empty list which will be mapped to
+            # an empty field.  Always end on a newline (avoids errors
+            # if there is a field after this)
+            new_content = [field_name + ":\n"]
+
+        # As absurd as it might seem, it is easier to just use the parser to
+        # construct the AST correctly
+        deb822_file = parse_deb822_file(iter(new_content))
+        error_token = deb822_file.find_first_error_element()
+        if error_token:
+            # _print_ast(deb822_file)
+            raise ValueError("Syntax error in new field value for " + field_name)
+        paragraph = next(iter(deb822_file))
+        assert isinstance(paragraph, Deb822NoDuplicateFieldsParagraphElement)
+        new_kvpair_element = paragraph.get_kvpair_element(field_name)
+        assert new_kvpair_element is not None
+        kvpair_element.value_element = new_kvpair_element.value_element
+        self._changed = False
+
+    def sort_elements(
+        self,
+        *,
+        key=None,  # type: Optional[Callable[[VE], Any]]
+        reverse=False,  # type: bool
+    ):
+        # type: (...) -> None
+        """Sort the elements (abstract values) in this list.
+
+        This method will sort the logical values of the list. It will
+        attempt to preserve comments associated with a given value where
+        possible.  Whether space and separators are preserved depends on
+        the contents of the field as well as the formatting settings.
+
+        Sorting (without reformatting) is likely to leave you with "awkward"
+        whitespace. Therefore, you almost always want to apply reformatting
+        such as the reformat_when_finished() method.
+
+        Sorting will invalidate all ValueReferences.
+        """
+        comment_start_node = None
+        vtype = self._vtype
+        stype = self._stype
+
+        def key_func(x):
+            # type: (Tuple[VE, List[TokenOrElement]]) -> Any
+            if key:
+                return key(x[0])
+            return x[0].convert_to_text()
+
+        parts = []
+
+        for node in self._token_list.iter_nodes():
+            value = node.value
+            if isinstance(value, Deb822Token) and value.is_comment:
+                if comment_start_node is None:
+                    comment_start_node = node
+                continue
+
+            if isinstance(value, vtype):
+                comments = []
+                if comment_start_node is not None:
+                    for keep_node in comment_start_node.iter_next(skip_current=False):
+                        if keep_node is node:
+                            break
+                        comments.append(keep_node.value)
+                parts.append((value, comments))
+                comment_start_node = None
+
+        parts.sort(key=key_func, reverse=reverse)
+
+        self._changed = True
+        self._token_list.clear()
+        first_value = True
+
+        separator_is_space = self._default_separator_factory().is_whitespace
+
+        for value, comments in parts:
+            if first_value:
+                first_value = False
+                if comments:
+                    # While unlikely, there could be a separator between the comments.
+                    # It would be in the way and we remove it.
+                    comments = [x for x in comments if not isinstance(x, stype)]
+                    # Comments cannot start the field, so inject a newline to
+                    # work around that
+                    self.append_newline()
+            else:
+                if not separator_is_space and not any(
+                    isinstance(x, stype) for x in comments
+                ):
+                    # While unlikely, you can hide a comma between two comments and expect
+                    # us to preserve it.  However, the more common case is that the separator
+                    # appeared before the comments and was thus omitted (leaving us to re-add
+                    # it here).
+                    self.append_separator(space_after_separator=False)
+                if comments:
+                    self.append_newline()
+                else:
+                    self._token_list.append(Deb822WhitespaceToken(" "))
+
+            self._token_list.extend(comments)
+            self.append_value(value)
+
+    def sort(
+        self,
+        *,
+        key=None,  # type: Optional[Callable[[str], Any]]
+        **kwargs,  # type: Any
+    ):
+        # type: (...) -> None
+        """Sort the values (rendered as str) in this list.
+
+        This method will sort the logical values of the list. It will
+        attempt to preserve comments associated with a given value where
+        possible.  Whether space and separators are preserved depends on
+        the contents of the field as well as the formatting settings.
+
+        Sorting (without reformatting) is likely to leave you with "awkward"
+        whitespace. Therefore, you almost always want to apply reformatting
+        such as the reformat_when_finished() method.
+
+        Sorting will invalidate all ValueReferences.
+        """
+        if key is not None:
+            render = self._render
+            kwargs["key"] = lambda vt: key(render(vt))
+        self.sort_elements(**kwargs)
+
+
+class Interpretation(Generic[T]):
+
+    def interpret(
+        self,
+        kvpair_element,  # type: Deb822KeyValuePairElement
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> T
+        raise NotImplementedError  # pragma: no cover
+
+
+class GenericContentBasedInterpretation(Interpretation[T], Generic[T, VE]):
+
+    def __init__(
+        self,
+        tokenizer,  # type: Callable[[str], Iterable['Deb822Token']]
+        value_parser,  # type: StreamingValueParser[VE]
+    ):
+        # type: (...) -> None
+        super().__init__()
+        self._tokenizer = tokenizer
+        self._value_parser = value_parser
+
+    def _high_level_interpretation(
+        self,
+        kvpair_element,  # type: Deb822KeyValuePairElement
+        proxy_element,  # type: Deb822InterpretationProxyElement
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> T
+        raise NotImplementedError  # pragma: no cover
+
+    def _parse_stream(
+        self, buffered_iterator  # type: BufferingIterator[Deb822Token]
+    ):
+        # type: (...) -> Iterable[Union[Deb822Token, VE]]
+
+        value_parser = self._value_parser
+        for token in buffered_iterator:
+            if isinstance(token, Deb822ValueToken):
+                yield value_parser(token, buffered_iterator)
+            else:
+                yield token
+
+    def _parse_kvpair(
+        self, kvpair  # type: Deb822KeyValuePairElement
+    ):
+        # type: (...) -> Deb822InterpretationProxyElement
+        value_element = kvpair.value_element
+        content = value_element.convert_to_text()
+        token_list = []  # type: List['TokenOrElement']
+        token_list.extend(self._parse_str(content))
+        return Deb822InterpretationProxyElement(value_element, token_list)
+
+    def _parse_str(self, content):
+        # type: (str) -> Iterable[Union[Deb822Token, VE]]
+        content_len = len(content)
+        biter = BufferingIterator(
+            len_check_iterator(
+                content,
+                self._tokenizer(content),
+                content_len=content_len,
+            )
+        )
+        yield from len_check_iterator(
+            content,
+            self._parse_stream(biter),
+            content_len=content_len,
+        )
+
+    def interpret(
+        self,
+        kvpair_element,  # type: Deb822KeyValuePairElement
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> T
+        proxy_element = self._parse_kvpair(kvpair_element)
+        return self._high_level_interpretation(
+            kvpair_element,
+            proxy_element,
+            discard_comments_on_read=discard_comments_on_read,
+        )
+
+
+def _parser_to_value_factory(
+    parser,  # type: StrToValueParser[VE]
+    vtype,  # type: Type[VE]
+):
+    # type: (...) -> Callable[[str], VE]
+    def _value_factory(v):
+        # type: (str) -> VE
+        if v == "":
+            raise ValueError("The empty string is not a value")
+        token_iter = iter(parser(v))
+        t1 = next(token_iter, None)  # type: Optional[Union[TokenOrElement]]
+        t2 = next(token_iter, None)
+        assert t1 is not None, (
+            'Bad parser - it returned None (or no TE) for "' + v + '"'
+        )
+        if t2 is not None:
+            msg = textwrap.dedent(
+                """\
+            The input "{v}" should have been exactly one element, but the parser provided at
+             least two.  This can happen with unnecessary leading/trailing whitespace
+             or including commas the value for a comma list.
+            """
+            ).format(v=v)
+            raise ValueError(msg)
+        if not isinstance(t1, vtype):
+            if isinstance(t1, Deb822Token) and (t1.is_comment or t1.is_whitespace):
+                raise ValueError(
+                    'The input "{v}" is whitespace or a comment: Expected a value'
+                )
+            msg = (
+                'The input "{v}" should have produced a element of type {vtype_name}, but'
+                " instead it produced {t1}"
+            )
+            raise ValueError(msg.format(v=v, vtype_name=vtype.__name__, t1=t1))
+
+        assert len(t1.convert_to_text()) == len(v), (
+            "Bad tokenizer - the token did not cover the input text"
+            " exactly ({t1_len} != {v_len}".format(
+                t1_len=len(t1.convert_to_text()), v_len=len(v)
+            )
+        )
+        return t1
+
+    return _value_factory
+
+
+class ListInterpretation(
+    GenericContentBasedInterpretation[Deb822ParsedTokenList[VE, ST], VE]
+):
+
+    def __init__(
+        self,
+        tokenizer,  # type: Callable[[str], Iterable['Deb822Token']]
+        value_parser,  # type: StreamingValueParser[VE]
+        vtype,  # type: Type[VE]
+        stype,  # type: Type[ST]
+        default_separator_factory,  # type: Callable[[], ST]
+        render_factory,  # type: Callable[[bool], Callable[[VE], str]]
+    ):
+        # type: (...) -> None
+        super().__init__(tokenizer, value_parser)
+        self._vtype = vtype
+        self._stype = stype
+        self._default_separator_factory = default_separator_factory
+        self._render_factory = render_factory
+
+    def _high_level_interpretation(
+        self,
+        kvpair_element,  # type: Deb822KeyValuePairElement
+        proxy_element,  # type: Deb822InterpretationProxyElement
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> Deb822ParsedTokenList[VE, ST]
+        return Deb822ParsedTokenList(
+            kvpair_element,
+            proxy_element,
+            self._vtype,
+            self._stype,
+            self._parse_str,
+            self._default_separator_factory,
+            self._render_factory(discard_comments_on_read),
+        )
+
+
+def _parse_whitespace_list_value(token, _):
+    # type: (Deb822Token, BufferingIterator[Deb822Token]) -> Deb822ParsedValueElement
+    return Deb822ParsedValueElement([token])
+
+
+def _is_comma_token(v):
+    # type: (TokenOrElement) -> bool
+    # Consume tokens until the next comma
+    return isinstance(v, Deb822CommaToken)
+
+
+def _parse_comma_list_value(token, buffered_iterator):
+    # type: (Deb822Token, BufferingIterator[Deb822Token]) -> Deb822ParsedValueElement
+    comma_offset = buffered_iterator.peek_find(_is_comma_token)
+    value_parts = [token]
+    if comma_offset is not None:
+        # The value is followed by a comma and now we know where it ends
+        value_parts.extend(buffered_iterator.peek_many(comma_offset - 1))
+    else:
+        # The value is the last value there is.  Consume all remaining tokens
+        # and then trim from the right.
+        value_parts.extend(buffered_iterator.peek_buffer())
+    while value_parts and not isinstance(value_parts[-1], Deb822ValueToken):
+        value_parts.pop()
+
+    buffered_iterator.consume_many(len(value_parts) - 1)
+    return Deb822ParsedValueElement(value_parts)
+
+
+def _parse_uploaders_list_value(token, buffered_iterator):
+    # type: (Deb822Token, BufferingIterator[Deb822Token]) -> Deb822ParsedValueElement
+
+    # This is similar to _parse_comma_list_value *except* that there is an extra special
+    # case.  Namely comma only counts as a true separator if it follows ">"
+    value_parts = [token]
+    comma_offset = -1  # type: Optional[int]
+    while comma_offset is not None:
+        comma_offset = buffered_iterator.peek_find(_is_comma_token)
+        if comma_offset is not None:
+            # The value is followed by a comma.  Verify that this is a terminating
+            # comma (comma may appear in the name or email)
+            #
+            # We include value_parts[-1] to easily cope with the common case of
+            # "foo <a@b.com>," where we will have 0 peeked element to examine.
+            peeked_elements = [value_parts[-1]]
+            peeked_elements.extend(buffered_iterator.peek_many(comma_offset - 1))
+            comma_was_separator = False
+            i = len(peeked_elements) - 1
+            while i >= 0:
+                token = peeked_elements[i]
+                if isinstance(token, Deb822ValueToken):
+                    if token.text.endswith(">"):
+                        # The comma terminates the value
+                        value_parts.extend(buffered_iterator.consume_many(i))
+                        assert isinstance(
+                            value_parts[-1], Deb822ValueToken
+                        ) and value_parts[-1].text.endswith(">"), "Got: " + str(
+                            value_parts
+                        )
+                        comma_was_separator = True
+                    break
+                i -= 1
+            if comma_was_separator:
+                break
+            value_parts.extend(buffered_iterator.consume_many(comma_offset))
+            assert isinstance(value_parts[-1], Deb822CommaToken)
+        else:
+            # The value is the last value there is.  Consume all remaining tokens
+            # and then trim from the right.
+            remaining_part = buffered_iterator.peek_buffer()
+            consume_elements = len(remaining_part)
+            value_parts.extend(remaining_part)
+            while value_parts and not isinstance(value_parts[-1], Deb822ValueToken):
+                value_parts.pop()
+                consume_elements -= 1
+            buffered_iterator.consume_many(consume_elements)
+
+    return Deb822ParsedValueElement(value_parts)
+
+
+class Deb822Element(Locatable):
+    """Composite elements (consists of 1 or more tokens)"""
+
+    __slots__ = ("_parent_element", "_full_size_cache", "__weakref__")
+
+    def __init__(self):
+        # type: () -> None
+        self._parent_element = None  # type: Optional[ReferenceType['Deb822Element']]
+        self._full_size_cache = None  # type: Optional[Range]
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        raise NotImplementedError  # pragma: no cover
+
+    def iter_parts_of_type(self, only_element_or_token_type):
+        # type: (Type[TE]) -> Iterable[TE]
+        for part in self.iter_parts():
+            if isinstance(part, only_element_or_token_type):
+                yield part
+
+    def iter_tokens(self):
+        # type: () -> Iterable[Deb822Token]
+        for part in self.iter_parts():
+            # Control check to catch bugs early
+            assert part._parent_element is not None
+            if isinstance(part, Deb822Element):
+                yield from part.iter_tokens()
+            else:
+                yield part
+
+    def iter_recurse(
+        self, *, only_element_or_token_type=None  # type: Optional[Type[TE]]
+    ):
+        # type: (...) -> Iterable[TE]
+        for part in self.iter_parts():
+            if only_element_or_token_type is None or isinstance(
+                part, only_element_or_token_type
+            ):
+                yield cast("TE", part)
+            if isinstance(part, Deb822Element):
+                yield from part.iter_recurse(
+                    only_element_or_token_type=only_element_or_token_type
+                )
+
+    @property
+    def is_error(self):
+        # type: () -> bool
+        return False
+
+    @property
+    def is_comment(self):
+        # type: () -> bool
+        return False
+
+    @property
+    def parent_element(self):
+        # type: () -> Optional[Deb822Element]
+        return resolve_ref(self._parent_element)
+
+    @parent_element.setter
+    def parent_element(self, new_parent):
+        # type: (Optional[Deb822Element]) -> None
+        self._parent_element = (
+            weakref.ref(new_parent) if new_parent is not None else None
+        )
+
+    def _init_parent_of_parts(self):
+        # type: () -> None
+        for part in self.iter_parts():
+            part.parent_element = self
+
+    # Deliberately not a "text" property, to signal that it is not necessary cheap.
+    def convert_to_text(self):
+        # type: () -> str
+        return "".join(t.text for t in self.iter_tokens())
+
+    def clear_parent_if_parent(self, parent):
+        # type: (Deb822Element) -> None
+        if parent is self.parent_element:
+            self._parent_element = None
+
+    def size(self, *, skip_leading_comments: bool = True) -> Range:
+        size_cache = self._full_size_cache
+        if size_cache is None:
+            size_cache = Range.from_position_and_sizes(
+                START_POSITION,
+                (p.size(skip_leading_comments=False) for p in self.iter_parts()),
+            )
+            self._full_size_cache = size_cache
+        return size_cache
+
+
+class Deb822InterpretationProxyElement(Deb822Element):
+
+    __slots__ = ("parts",)
+
+    def __init__(
+        self, real_element: Deb822Element, parts: List[TokenOrElement]
+    ) -> None:
+        super().__init__()
+        self.parent_element = real_element
+        self.parts = parts
+        for p in parts:
+            p.parent_element = self
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        return iter(self.parts)
+
+    def position_in_parent(self, *, skip_leading_comments: bool = True) -> Position:
+        parent = self.parent_element
+        if parent is None:
+            raise RuntimeError("parent was garbage collected")
+        return parent.position_in_parent()
+
+    def position_in_file(self, *, skip_leading_comments: bool = True) -> Position:
+        parent = self.parent_element
+        if parent is None:
+            raise RuntimeError("parent was garbage collected")
+        return parent.position_in_file()
+
+    def size(self, *, skip_leading_comments: bool = True) -> Range:
+        # Same as parent except we never use a cache.
+        sizes = (p.size(skip_leading_comments=False) for p in self.iter_parts())
+        return Range.from_position_and_sizes(START_POSITION, sizes)
+
+
+class Deb822ErrorElement(Deb822Element):
+    """Element representing elements or tokens that are out of place
+
+    Commonly, it will just be instances of Deb822ErrorToken, but it can be other
+    things.  As an example if a parser discovers out of order elements/tokens,
+    it can bundle them in a Deb822ErrorElement to signal that the sequence of
+    elements/tokens are invalid (even if the tokens themselves are valid).
+    """
+
+    __slots__ = ("_parts",)
+
+    def __init__(self, parts):
+        # type: (Sequence[TokenOrElement]) -> None
+        super().__init__()
+        self._parts = tuple(parts)
+        self._init_parent_of_parts()
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._parts
+
+    @property
+    def is_error(self):
+        # type: () -> bool
+        return True
+
+
+class Deb822ValueLineElement(Deb822Element):
+    """Consists of one "line" of a value"""
+
+    __slots__ = (
+        "_comment_element",
+        "_continuation_line_token",
+        "_leading_whitespace_token",
+        "_value_tokens",
+        "_trailing_whitespace_token",
+        "_newline_token",
+    )
+
+    def __init__(
+        self,
+        comment_element,  # type: Optional[Deb822CommentElement]
+        continuation_line_token,  # type: Optional[Deb822ValueContinuationToken]
+        leading_whitespace_token,  # type: Optional[Deb822WhitespaceToken]
+        value_parts,  # type: List[TokenOrElement]
+        trailing_whitespace_token,  # type: Optional[Deb822WhitespaceToken]
+        # only optional if it is the last line of the file and the file does not
+        # end with a newline.
+        newline_token,  # type: Optional[Deb822WhitespaceToken]
+    ):
+        # type: (...) -> None
+        super().__init__()
+        if comment_element is not None and continuation_line_token is None:
+            raise ValueError("Only continuation lines can have comments")
+        self._comment_element = comment_element  # type: Optional[Deb822CommentElement]
+        self._continuation_line_token = continuation_line_token
+        self._leading_whitespace_token = (
+            leading_whitespace_token
+        )  # type: Optional[Deb822WhitespaceToken]
+        self._value_tokens = value_parts  # type: List[TokenOrElement]
+        self._trailing_whitespace_token = trailing_whitespace_token
+        self._newline_token = newline_token  # type: Optional[Deb822WhitespaceToken]
+        self._init_parent_of_parts()
+
+    @property
+    def comment_element(self):
+        # type: () -> Optional[Deb822CommentElement]
+        return self._comment_element
+
+    @property
+    def continuation_line_token(self):
+        # type: () -> Optional[Deb822ValueContinuationToken]
+        return self._continuation_line_token
+
+    @property
+    def newline_token(self):
+        # type: () -> Optional[Deb822WhitespaceToken]
+        return self._newline_token
+
+    def add_newline_if_missing(self):
+        # type: () -> bool
+        if self._newline_token is None:
+            self._newline_token = Deb822NewlineAfterValueToken()
+            self._newline_token.parent_element = self
+            self._full_size_cache = None
+            return True
+        return False
+
+    def _iter_content_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        if self._leading_whitespace_token:
+            yield self._leading_whitespace_token
+        yield from self._value_tokens
+        if self._trailing_whitespace_token:
+            yield self._trailing_whitespace_token
+
+    def _iter_content_tokens(self):
+        # type: () -> Iterable[Deb822Token]
+        for part in self._iter_content_parts():
+            if isinstance(part, Deb822Element):
+                yield from part.iter_tokens()
+            else:
+                yield part
+
+    def convert_content_to_text(self):
+        # type: () -> str
+        if (
+            len(self._value_tokens) == 1
+            and not self._leading_whitespace_token
+            and not self._trailing_whitespace_token
+            and isinstance(self._value_tokens[0], Deb822Token)
+        ):
+            # By default, we get a single value spanning the entire line
+            # (minus continuation line and newline, but we are supposed to
+            # exclude those)
+            return self._value_tokens[0].text
+
+        return "".join(t.text for t in self._iter_content_tokens())
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        if self._comment_element:
+            yield self._comment_element
+        if self._continuation_line_token:
+            yield self._continuation_line_token
+        yield from self._iter_content_parts()
+        if self._newline_token:
+            yield self._newline_token
+
+    def size(self, *, skip_leading_comments: bool = True) -> Range:
+        if skip_leading_comments:
+            return Range.from_position_and_sizes(
+                START_POSITION,
+                (
+                    p.size(skip_leading_comments=False)
+                    for p in self.iter_parts()
+                    if not p.is_comment
+                ),
+            )
+        return super().size(skip_leading_comments=skip_leading_comments)
+
+    def position_in_parent(self, *, skip_leading_comments: bool = True) -> Position:
+        base_pos = super().position_in_parent(skip_leading_comments=False)
+        if skip_leading_comments:
+            for p in self.iter_parts():
+                if p.is_comment:
+                    continue
+                non_comment_pos = p.position_in_parent(skip_leading_comments=False)
+                base_pos = non_comment_pos.relative_to(base_pos)
+        return base_pos
+
+
+class Deb822ValueElement(Deb822Element):
+    __slots__ = ("_value_entry_elements",)
+
+    def __init__(self, value_entry_elements):
+        # type: (Sequence[Deb822ValueLineElement]) -> None
+        super().__init__()
+        # Split over two lines due to line length issues
+        v = tuple(value_entry_elements)
+        self._value_entry_elements = v  # type: Sequence[Deb822ValueLineElement]
+        self._init_parent_of_parts()
+
+    @property
+    def value_lines(self):
+        # type: () -> Sequence[Deb822ValueLineElement]
+        """Read-only list of value entries"""
+        return self._value_entry_elements
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._value_entry_elements
+
+    def add_final_newline_if_missing(self):
+        # type: () -> bool
+        if self._value_entry_elements:
+            changed = self._value_entry_elements[-1].add_newline_if_missing()
+            if changed:
+                self._full_size_cache = None
+            return changed
+        return False
+
+
+class Deb822ParsedValueElement(Deb822Element):
+
+    __slots__ = ("_text_cached", "_text_no_comments_cached", "_token_list")
+
+    def __init__(self, tokens):
+        # type: (List[Deb822Token]) -> None
+        super().__init__()
+        self._token_list = tokens
+        self._init_parent_of_parts()
+        if not isinstance(tokens[0], Deb822ValueToken) or not isinstance(
+            tokens[-1], Deb822ValueToken
+        ):
+            raise ValueError(
+                self.__class__.__name__ + " MUST start and end on a Deb822ValueToken"
+            )
+        if len(tokens) == 1:
+            token = tokens[0]
+            self._text_cached = token.text  # type: Optional[str]
+            self._text_no_comments_cached = token.text  # type: Optional[str]
+        else:
+            self._text_cached = None
+            self._text_no_comments_cached = None
+
+    def convert_to_text(self):
+        # type: () -> str
+        if self._text_no_comments_cached is None:
+            self._text_no_comments_cached = super().convert_to_text()
+        return self._text_no_comments_cached
+
+    def convert_to_text_without_comments(self):
+        # type: () -> str
+        if self._text_no_comments_cached is None:
+            self._text_no_comments_cached = "".join(
+                t.text for t in self.iter_tokens() if not t.is_comment
+            )
+        return self._text_no_comments_cached
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._token_list
+
+
+class Deb822CommentElement(Deb822Element):
+    __slots__ = ("_comment_tokens",)
+
+    def __init__(self, comment_tokens):
+        # type: (Sequence[Deb822CommentToken]) -> None
+        super().__init__()
+        self._comment_tokens = tuple(
+            comment_tokens
+        )  # type: Sequence[Deb822CommentToken]
+        if not comment_tokens:  # pragma: no cover
+            raise ValueError("Comment elements must have at least one comment token")
+        self._init_parent_of_parts()
+
+    @property
+    def is_comment(self):
+        # type: () -> bool
+        return True
+
+    def __len__(self):
+        # type: () -> int
+        return len(self._comment_tokens)
+
+    def __getitem__(self, item):
+        # type: (int) -> Deb822CommentToken
+        return self._comment_tokens[item]
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._comment_tokens
+
+
+class Deb822KeyValuePairElement(Deb822Element):
+    __slots__ = (
+        "_comment_element",
+        "_field_token",
+        "_separator_token",
+        "_value_element",
+    )
+
+    def __init__(
+        self,
+        comment_element,  # type: Optional[Deb822CommentElement]
+        field_token,  # type: Deb822FieldNameToken
+        separator_token,  # type: Deb822FieldSeparatorToken
+        value_element,  # type: Deb822ValueElement
+    ):
+        # type: (...) -> None
+        super().__init__()
+        self._comment_element = comment_element  # type: Optional[Deb822CommentElement]
+        self._field_token = field_token  # type: Deb822FieldNameToken
+        self._separator_token = separator_token  # type: Deb822FieldSeparatorToken
+        self._value_element = value_element  # type: Deb822ValueElement
+        self._init_parent_of_parts()
+
+    @property
+    def field_name(self):
+        # type: () -> _strI
+        return self.field_token.text
+
+    @property
+    def field_token(self):
+        # type: () -> Deb822FieldNameToken
+        return self._field_token
+
+    @property
+    def value_element(self):
+        # type: () -> Deb822ValueElement
+        return self._value_element
+
+    @value_element.setter
+    def value_element(self, new_value):
+        # type: (Deb822ValueElement) -> None
+        self._full_size_cache = None
+        self._value_element.clear_parent_if_parent(self)
+        self._value_element = new_value
+        new_value.parent_element = self
+
+    def interpret_as(
+        self,
+        interpreter,  # type: Interpretation[T]
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> T
+        return interpreter.interpret(
+            self, discard_comments_on_read=discard_comments_on_read
+        )
+
+    @property
+    def comment_element(self):
+        # type: () -> Optional[Deb822CommentElement]
+        return self._comment_element
+
+    @comment_element.setter
+    def comment_element(self, value):
+        # type: (Optional[Deb822CommentElement]) -> None
+        self._full_size_cache = None
+        if value is not None:
+            if not value[-1].text.endswith("\n"):
+                raise ValueError("Field comments must end with a newline")
+        if self._comment_element:
+            self._comment_element.clear_parent_if_parent(self)
+        if value is not None:
+            value.parent_element = self
+        self._comment_element = value
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        if self._comment_element:
+            yield self._comment_element
+        yield self._field_token
+        yield self._separator_token
+        yield self._value_element
+
+    def position_in_parent(
+        self,
+        *,
+        skip_leading_comments: bool = True,
+    ) -> Position:
+        position = super().position_in_parent(skip_leading_comments=False)
+        if skip_leading_comments:
+            if self._comment_element:
+                field_pos = self._field_token.position_in_parent()
+                position = field_pos.relative_to(position)
+        return position
+
+    def size(self, *, skip_leading_comments: bool = True) -> Range:
+        if skip_leading_comments:
+            return Range.from_position_and_sizes(
+                START_POSITION,
+                (
+                    p.size(skip_leading_comments=False)
+                    for p in self.iter_parts()
+                    if not p.is_comment
+                ),
+            )
+        return super().size(skip_leading_comments=False)
+
+
+def _format_comment(c):
+    # type: (str) -> str
+    if c == "":
+        # Special-case: Empty strings are mapped to an empty comment line
+        return "#\n"
+    if "\n" in c[:-1]:
+        raise ValueError("Comment lines must not have embedded newlines")
+    if not c.endswith("\n"):
+        c = c.rstrip() + "\n"
+    if not c.startswith("#"):
+        c = "# " + c.lstrip()
+    return c
+
+
+def _unpack_key(
+    item,  # type: ParagraphKey
+    raise_if_indexed=False,  # type: bool
+):
+    # type: (...) -> Tuple[_strI, Optional[int], Optional[Deb822FieldNameToken]]
+    index = None  # type: Optional[int]
+    name_token = None  # type: Optional[Deb822FieldNameToken]
+    if isinstance(item, tuple):
+        key, index = item
+        if raise_if_indexed:
+            # Fudge "(key, 0)" into a "key" callers to defensively support
+            # both paragraph styles with the same key.
+            if index != 0:
+                msg = 'Cannot resolve key "{key}" with index {index}. The key is not indexed'
+                raise KeyError(msg.format(key=key, index=index))
+            index = None
+        key = _strI(key)
+    else:
+        index = None
+        if isinstance(item, Deb822FieldNameToken):
+            name_token = item
+            key = name_token.text
+        else:
+            key = _strI(item)
+
+    return key, index, name_token
+
+
+def _convert_value_lines_to_lines(
+    value_lines,  # type: Iterable[Deb822ValueLineElement]
+    strip_comments,  # type: bool
+):
+    # type: (...) -> Iterable[str]
+    if not strip_comments:
+        yield from (v.convert_to_text() for v in value_lines)
+    else:
+        for element in value_lines:
+            yield "".join(x.text for x in element.iter_tokens() if not x.is_comment)
+
+
+if sys.version_info >= (3, 9) or TYPE_CHECKING:
+    _ParagraphMapping_Base = collections.abc.Mapping[ParagraphKey, T]
+else:
+    # Python 3.5 - 3.8 compat - we are not allowed to subscript the abc.Iterator
+    # - use this little hack to work around it
+    class _ParagraphMapping_Base(collections.abc.Mapping, Generic[T], ABC):
+        pass
+
+
+# Deb822ParagraphElement uses this Mixin (by having `_paragraph` return self).
+# Therefore, the Mixin needs to call the "proper" methods on the paragraph to
+# avoid doing infinite recursion.
+class AutoResolvingMixin(Generic[T], _ParagraphMapping_Base[T]):
+
+    @property
+    def _auto_resolve_ambiguous_fields(self):
+        # type: () -> bool
+        return True
+
+    @property
+    def _paragraph(self):
+        # type: () -> Deb822ParagraphElement
+        raise NotImplementedError  # pragma: no cover
+
+    def __len__(self):
+        # type: () -> int
+        return self._paragraph.kvpair_count
+
+    def __contains__(self, item):
+        # type: (object) -> bool
+        return self._paragraph.contains_kvpair_element(item)
+
+    def __iter__(self):
+        # type: () -> Iterator[ParagraphKey]
+        return iter(self._paragraph.iter_keys())
+
+    def __getitem__(self, item):
+        # type: (ParagraphKey) -> T
+        if self._auto_resolve_ambiguous_fields and isinstance(item, str):
+            v = self._paragraph.get_kvpair_element((item, 0))
+        else:
+            v = self._paragraph.get_kvpair_element(item)
+        assert v is not None
+        return self._interpret_value(item, v)
+
+    def __delitem__(self, item):
+        # type: (ParagraphKey) -> None
+        self._paragraph.remove_kvpair_element(item)
+
+    def _interpret_value(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> T
+        raise NotImplementedError  # pragma: no cover
+
+
+# Deb822ParagraphElement uses this Mixin (by having `_paragraph` return self).
+# Therefore, the Mixin needs to call the "proper" methods on the paragraph to
+# avoid doing infinite recursion.
+class Deb822ParagraphToStrWrapperMixin(AutoResolvingMixin[str], ABC):
+
+    @property
+    def _auto_map_initial_line_whitespace(self):
+        # type: () -> bool
+        return True
+
+    @property
+    def _discard_comments_on_read(self):
+        # type: () -> bool
+        return True
+
+    @property
+    def _auto_map_final_newline_in_multiline_values(self):
+        # type: () -> bool
+        return True
+
+    @property
+    def _preserve_field_comments_on_field_updates(self):
+        # type: () -> bool
+        return True
+
+    def _convert_value_to_str(self, kvpair_element):
+        # type: (Deb822KeyValuePairElement) -> str
+        value_element = kvpair_element.value_element
+        value_entries = value_element.value_lines
+        if len(value_entries) == 1:
+            # Special case single line entry (e.g. "Package: foo") as they never
+            # have comments and we can do some parts more efficient.
+            value_entry = value_entries[0]
+            t = value_entry.convert_to_text()
+            if self._auto_map_initial_line_whitespace:
+                t = t.strip()
+            return t
+
+        if self._auto_map_initial_line_whitespace or self._discard_comments_on_read:
+            converter = _convert_value_lines_to_lines(
+                value_entries,
+                self._discard_comments_on_read,
+            )
+
+            auto_map_space = self._auto_map_initial_line_whitespace
+
+            # Because we know there are more than one line, we can unconditionally inject
+            # the newline after the first line
+            as_text = "".join(
+                line.strip() + "\n" if auto_map_space and i == 1 else line
+                for i, line in enumerate(converter, start=1)
+            )
+        else:
+            # No rewrite necessary.
+            as_text = value_element.convert_to_text()
+
+        if self._auto_map_final_newline_in_multiline_values and as_text[-1] == "\n":
+            as_text = as_text[:-1]
+        return as_text
+
+    def __setitem__(self, item, value):
+        # type: (ParagraphKey, str) -> None
+        keep_comments = (
+            self._preserve_field_comments_on_field_updates
+        )  # type: Optional[bool]
+        comment = None
+        if keep_comments and self._auto_resolve_ambiguous_fields:
+            # For ambiguous fields, we have to resolve the original field as
+            # the set_field_* methods do not cope with ambiguous fields.  This
+            # means we might as well clear the keep_comments flag as we have
+            # resolved the comment.
+            keep_comments = None
+            key_lookup = item
+            if isinstance(item, str):
+                key_lookup = (item, 0)
+            orig_kvpair = self._paragraph.get_kvpair_element(key_lookup, use_get=True)
+            if orig_kvpair is not None:
+                comment = orig_kvpair.comment_element
+
+        if self._auto_map_initial_line_whitespace:
+            try:
+                idx = value.index("\n")
+            except ValueError:
+                idx = -1
+            if idx == -1 or idx == len(value):
+                self._paragraph.set_field_to_simple_value(
+                    item,
+                    value.strip(),
+                    preserve_original_field_comment=keep_comments,
+                    field_comment=comment,
+                )
+                return
+            # Regenerate the first line with normalized whitespace if necessary
+            first_line, rest = value.split("\n", 1)
+            if first_line and first_line[:1] not in ("\t", " "):
+                value = "".join((" ", first_line.strip(), "\n", rest))
+            else:
+                value = "".join((first_line, "\n", rest))
+        if not value.endswith("\n"):
+            if not self._auto_map_final_newline_in_multiline_values:
+                raise ValueError(
+                    "Values must end with a newline (or be single line"
+                    " values and use the auto whitespace mapping feature)"
+                )
+            value += "\n"
+        self._paragraph.set_field_from_raw_string(
+            item,
+            value,
+            preserve_original_field_comment=keep_comments,
+            field_comment=comment,
+        )
+
+    def _interpret_value(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> str
+        # mypy is a bit dense and cannot see that T == str
+        return self._convert_value_to_str(value)
+
+
+class AbstractDeb822ParagraphWrapper(AutoResolvingMixin[T], ABC):
+
+    def __init__(
+        self,
+        paragraph,  # type: Deb822ParagraphElement
+        *,
+        auto_resolve_ambiguous_fields=False,  # type: bool
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> None
+        self.__paragraph = paragraph
+        self.__auto_resolve_ambiguous_fields = auto_resolve_ambiguous_fields
+        self.__discard_comments_on_read = discard_comments_on_read
+
+    @property
+    def _paragraph(self):
+        # type: () -> Deb822ParagraphElement
+        return self.__paragraph
+
+    @property
+    def _discard_comments_on_read(self):
+        # type: () -> bool
+        return self.__discard_comments_on_read
+
+    @property
+    def _auto_resolve_ambiguous_fields(self):
+        # type: () -> bool
+        return self.__auto_resolve_ambiguous_fields
+
+
+class Deb822InterpretingParagraphWrapper(AbstractDeb822ParagraphWrapper[T]):
+
+    def __init__(
+        self,
+        paragraph,  # type: Deb822ParagraphElement
+        interpretation,  # type: Interpretation[T]
+        *,
+        auto_resolve_ambiguous_fields=False,  # type: bool
+        discard_comments_on_read=True,  # type: bool
+    ):
+        # type: (...) -> None
+        super().__init__(
+            paragraph,
+            auto_resolve_ambiguous_fields=auto_resolve_ambiguous_fields,
+            discard_comments_on_read=discard_comments_on_read,
+        )
+        self._interpretation = interpretation
+
+    def _interpret_value(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> T
+        return self._interpretation.interpret(value)
+
+
+class Deb822DictishParagraphWrapper(
+    AbstractDeb822ParagraphWrapper[str], Deb822ParagraphToStrWrapperMixin
+):
+
+    def __init__(
+        self,
+        paragraph,  # type: Deb822ParagraphElement
+        *,
+        discard_comments_on_read=True,  # type: bool
+        auto_map_initial_line_whitespace=True,  # type: bool
+        auto_resolve_ambiguous_fields=False,  # type: bool
+        preserve_field_comments_on_field_updates=True,  # type: bool
+        auto_map_final_newline_in_multiline_values=True,  # type: bool
+    ):
+        # type: (...) -> None
+        super().__init__(
+            paragraph,
+            auto_resolve_ambiguous_fields=auto_resolve_ambiguous_fields,
+            discard_comments_on_read=discard_comments_on_read,
+        )
+        self.__auto_map_initial_line_whitespace = auto_map_initial_line_whitespace
+        self.__preserve_field_comments_on_field_updates = (
+            preserve_field_comments_on_field_updates
+        )
+        self.__auto_map_final_newline_in_multiline_values = (
+            auto_map_final_newline_in_multiline_values
+        )
+
+    @property
+    def _auto_map_initial_line_whitespace(self):
+        # type: () -> bool
+        return self.__auto_map_initial_line_whitespace
+
+    @property
+    def _preserve_field_comments_on_field_updates(self):
+        # type: () -> bool
+        return self.__preserve_field_comments_on_field_updates
+
+    @property
+    def _auto_map_final_newline_in_multiline_values(self):
+        # type: () -> bool
+        return self.__auto_map_final_newline_in_multiline_values
+
+
+class Deb822ParagraphElement(Deb822Element, Deb822ParagraphToStrWrapperMixin, ABC):
+
+    @classmethod
+    def new_empty_paragraph(cls):
+        # type: () -> Deb822ParagraphElement
+        return Deb822NoDuplicateFieldsParagraphElement([], OrderedSet())
+
+    @classmethod
+    def from_dict(cls, mapping):
+        # type: (Mapping[str, str]) -> Deb822ParagraphElement
+        paragraph = cls.new_empty_paragraph()
+        for k, v in mapping.items():
+            paragraph[k] = v
+        return paragraph
+
+    @classmethod
+    def from_kvpairs(cls, kvpair_elements):
+        # type: (List[Deb822KeyValuePairElement]) -> Deb822ParagraphElement
+        if not kvpair_elements:
+            raise ValueError(
+                "A paragraph must consist of at least one field/value pair"
+            )
+        kvpair_order = OrderedSet(kv.field_name for kv in kvpair_elements)
+        if len(kvpair_order) == len(kvpair_elements):
+            # Each field occurs at most once, which is good because that
+            # means it is a valid paragraph and we can use the optimized
+            # implementation.
+            return Deb822NoDuplicateFieldsParagraphElement(
+                kvpair_elements, kvpair_order
+            )
+        # Fallback implementation, that can cope with the repeated field names
+        # at the cost of complexity.
+        return Deb822DuplicateFieldsParagraphElement(kvpair_elements)
+
+    @property
+    def has_duplicate_fields(self):
+        # type: () -> bool
+        """Tell whether this paragraph has duplicate fields"""
+        return False
+
+    def as_interpreted_dict_view(
+        self,
+        interpretation,  # type: Interpretation[T]
+        *,
+        auto_resolve_ambiguous_fields=True,  # type: bool
+    ):
+        # type: (...) -> Deb822InterpretingParagraphWrapper[T]
+        r"""Provide a Dict-like view of the paragraph
+
+        This method returns a dict-like object representing this paragraph and
+        is useful for accessing fields in a given interpretation. It is possible
+        to use multiple versions of this dict-like view with different interpretations
+        on the same paragraph at the same time (for different fields).
+
+            >>> example_deb822_paragraph = '''
+            ... Package: foo
+            ... # Field comment (because it becomes just before a field)
+            ... Architecture: amd64
+            ... # Inline comment (associated with the next line)
+            ...               i386
+            ... # We also support arm
+            ...               arm64
+            ...               armel
+            ... '''
+            >>> dfile = parse_deb822_file(example_deb822_paragraph.splitlines())
+            >>> paragraph = next(iter(dfile))
+            >>> list_view = paragraph.as_interpreted_dict_view(LIST_SPACE_SEPARATED_INTERPRETATION)
+            >>> # With the defaults, you only deal with the semantic values
+            >>> # - no leading or trailing whitespace on the first part of the value
+            >>> list(list_view["Package"])
+            ['foo']
+            >>> with list_view["Architecture"] as arch_list:
+            ...     orig_arch_list = list(arch_list)
+            ...     arch_list.replace('i386', 'kfreebsd-amd64')
+            >>> orig_arch_list
+            ['amd64', 'i386', 'arm64', 'armel']
+            >>> list(list_view["Architecture"])
+            ['amd64', 'kfreebsd-amd64', 'arm64', 'armel']
+            >>> print(paragraph.dump(), end='')
+            Package: foo
+            # Field comment (because it becomes just before a field)
+            Architecture: amd64
+            # Inline comment (associated with the next line)
+                          kfreebsd-amd64
+            # We also support arm
+                          arm64
+                          armel
+            >>> # Format preserved and architecture replaced
+            >>> with list_view["Architecture"] as arch_list:
+            ...     # Prettify the result as sorting will cause awkward whitespace
+            ...     arch_list.reformat_when_finished()
+            ...     arch_list.sort()
+            >>> print(paragraph.dump(), end='')
+            Package: foo
+            # Field comment (because it becomes just before a field)
+            Architecture: amd64
+            # We also support arm
+                          arm64
+                          armel
+            # Inline comment (associated with the next line)
+                          kfreebsd-amd64
+            >>> list(list_view["Architecture"])
+            ['amd64', 'arm64', 'armel', 'kfreebsd-amd64']
+            >>> # Format preserved and architecture values sorted
+
+        :param interpretation: Decides how the field values are interpreted.  As an example,
+          use LIST_SPACE_SEPARATED_INTERPRETATION for fields such as Architecture in the
+          debian/control file.
+        :param auto_resolve_ambiguous_fields: This parameter is only relevant for paragraphs
+          that contain the same field multiple times (these are generally invalid).  If the
+          caller requests an ambiguous field from an invalid paragraph via a plain field name,
+          the return dict-like object will refuse to resolve the field (not knowing which
+          version to pick).  This parameter (if set to True) instead changes the error into
+          assuming the caller wants the *first* variant.
+        """
+        return Deb822InterpretingParagraphWrapper(
+            self,
+            interpretation,
+            auto_resolve_ambiguous_fields=auto_resolve_ambiguous_fields,
+        )
+
+    def configured_view(
+        self,
+        *,
+        discard_comments_on_read=True,  # type: bool
+        auto_map_initial_line_whitespace=True,  # type: bool
+        auto_resolve_ambiguous_fields=True,  # type: bool
+        preserve_field_comments_on_field_updates=True,  # type: bool
+        auto_map_final_newline_in_multiline_values=True,  # type: bool
+    ):
+        # type: (...) -> Deb822DictishParagraphWrapper
+        r"""Provide a Dict[str, str]-like view of this paragraph with non-standard parameters
+
+        This method returns a dict-like object representing this paragraph that is
+        optionally configured differently from the default view.
+
+            >>> example_deb822_paragraph = '''
+            ... Package: foo
+            ... # Field comment (because it becomes just before a field)
+            ... Depends: libfoo,
+            ... # Inline comment (associated with the next line)
+            ...          libbar,
+            ... '''
+            >>> dfile = parse_deb822_file(example_deb822_paragraph.splitlines())
+            >>> paragraph = next(iter(dfile))
+            >>> # With the defaults, you only deal with the semantic values
+            >>> # - no leading or trailing whitespace on the first part of the value
+            >>> paragraph["Package"]
+            'foo'
+            >>> # - no inline comments in multiline values (but whitespace will be present
+            >>> #   subsequent lines.)
+            >>> print(paragraph["Depends"])
+            libfoo,
+                     libbar,
+            >>> paragraph['Foo'] = 'bar'
+            >>> paragraph.get('Foo')
+            'bar'
+            >>> paragraph.get('Unknown-Field') is None
+            True
+            >>> # But you get asymmetric behaviour with set vs. get
+            >>> paragraph['Foo'] = ' bar\n'
+            >>> paragraph['Foo']
+            'bar'
+            >>> paragraph['Bar'] = '     bar\n#Comment\n another value\n'
+            >>> # Note that the whitespace on the first line has been normalized.
+            >>> print("Bar: " + paragraph['Bar'])
+            Bar: bar
+             another value
+            >>> # The comment is present (in case you where wondering)
+            >>> print(paragraph.get_kvpair_element('Bar').convert_to_text(), end='')
+            Bar:     bar
+            #Comment
+             another value
+            >>> # On the other hand, you can choose to see the values as they are
+            >>> # - We will just reset the paragraph as a "nothing up my sleeve"
+            >>> dfile = parse_deb822_file(example_deb822_paragraph.splitlines())
+            >>> paragraph = next(iter(dfile))
+            >>> nonstd_dictview = paragraph.configured_view(
+            ...     discard_comments_on_read=False,
+            ...     auto_map_initial_line_whitespace=False,
+            ...     # For paragraphs with duplicate fields, you can choose to get an error
+            ...     # rather than the dict picking the first value available.
+            ...     auto_resolve_ambiguous_fields=False,
+            ...     auto_map_final_newline_in_multiline_values=False,
+            ... )
+            >>> # Because we have reset the state, Foo and Bar are no longer there.
+            >>> 'Bar' not in paragraph and 'Foo' not in paragraph
+            True
+            >>> # We can now see the comments (discard_comments_on_read=False)
+            >>> # (The leading whitespace in front of "libfoo" is due to
+            >>> #  auto_map_initial_line_whitespace=False)
+            >>> print(nonstd_dictview["Depends"], end='')
+             libfoo,
+            # Inline comment (associated with the next line)
+                     libbar,
+            >>> # And all the optional whitespace on the first value line
+            >>> # (auto_map_initial_line_whitespace=False)
+            >>> nonstd_dictview["Package"] == ' foo\n'
+            True
+            >>> # ... which will give you symmetric behaviour with set vs. get
+            >>> nonstd_dictview['Foo'] = '  bar \n'
+            >>> nonstd_dictview['Foo']
+            '  bar \n'
+            >>> nonstd_dictview['Bar'] = '  bar \n#Comment\n another value\n'
+            >>> nonstd_dictview['Bar']
+            '  bar \n#Comment\n another value\n'
+            >>> # But then you get no help either.
+            >>> try:
+            ...     nonstd_dictview["Baz"] = "foo"
+            ... except ValueError:
+            ...     print("Rejected")
+            Rejected
+            >>> # With auto_map_initial_line_whitespace=False, you have to include minimum a newline
+            >>> nonstd_dictview["Baz"] = "foo\n"
+            >>> # The absence of leading whitespace gives you the terse variant at the expensive
+            >>> # readability
+            >>> paragraph.get_kvpair_element('Baz').convert_to_text()
+            'Baz:foo\n'
+            >>> # But because they are views, changes performed via one view is visible in the other
+            >>> paragraph['Foo']
+            'bar'
+            >>> # The views show the values according to their own rules. Therefore, there is an
+            >>> # asymmetric between paragraph['Foo'] and nonstd_dictview['Foo']
+            >>> # Nevertheless, you can read or write the fields via either - enabling you to use
+            >>> # the view that best suit your use-case for the given field.
+            >>> 'Baz' in paragraph and nonstd_dictview.get('Baz') is not None
+            True
+            >>> # Deletion via the view also works
+            >>> del nonstd_dictview['Baz']
+            >>> 'Baz' not in paragraph and nonstd_dictview.get('Baz') is None
+            True
+
+
+        :param discard_comments_on_read: When getting a field value from the dict,
+          this parameter decides how in-line comments are handled.  When setting
+          the value, inline comments are still allowed and will be retained.
+          However, keep in mind that this option makes getter and setter assymetric
+          as a "get" following a "set" with inline comments will omit the comments
+          even if they are there (see the code example).
+        :param auto_map_initial_line_whitespace: Special-case the first value line
+          by trimming unnecessary whitespace leaving only the value. For single-line
+          values, all space including newline is pruned. For multi-line values, the
+          newline is preserved / needed to distinguish the first line from the
+          following lines.  When setting a value, this option normalizes the
+          whitespace of the initial line of the value field.
+          When this option is set to True makes the dictionary behave more like the
+          original Deb822 module.
+        :param preserve_field_comments_on_field_updates: Whether to preserve the field
+          comments when mutating the field.
+        :param auto_resolve_ambiguous_fields: This parameter is only relevant for paragraphs
+          that contain the same field multiple times (these are generally invalid).  If the
+          caller requests an ambiguous field from an invalid paragraph via a plain field name,
+          the return dict-like object will refuse to resolve the field (not knowing which
+          version to pick).  This parameter (if set to True) instead changes the error into
+          assuming the caller wants the *first* variant.
+        :param auto_map_final_newline_in_multiline_values: This parameter controls whether
+          a multiline field with have / need a trailing newline. If True, the trailing
+          newline is hidden on get and automatically added in set (if missing).
+          When this option is set to True makes the dictionary behave more like the
+          original Deb822 module.
+        """
+        return Deb822DictishParagraphWrapper(
+            self,
+            discard_comments_on_read=discard_comments_on_read,
+            auto_map_initial_line_whitespace=auto_map_initial_line_whitespace,
+            auto_resolve_ambiguous_fields=auto_resolve_ambiguous_fields,
+            preserve_field_comments_on_field_updates=preserve_field_comments_on_field_updates,
+            auto_map_final_newline_in_multiline_values=auto_map_final_newline_in_multiline_values,
+        )
+
+    @property
+    def _paragraph(self):
+        # type: () -> Deb822ParagraphElement
+        return self
+
+    def order_last(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "last" in the paragraph"""
+        raise NotImplementedError  # pragma: no cover
+
+    def order_first(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "first" in the paragraph"""
+        raise NotImplementedError  # pragma: no cover
+
+    def order_before(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly after the reference field in the paragraph
+
+        The reference field must be present."""
+        raise NotImplementedError  # pragma: no cover
+
+    def order_after(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly before the reference field in the paragraph
+
+        The reference field must be present.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @property
+    def kvpair_count(self):
+        # type: () -> int
+        raise NotImplementedError  # pragma: no cover
+
+    def iter_keys(self):
+        # type: () -> Iterable[ParagraphKey]
+        raise NotImplementedError  # pragma: no cover
+
+    def contains_kvpair_element(self, item):
+        # type: (object) -> bool
+        raise NotImplementedError  # pragma: no cover
+
+    def get_kvpair_element(
+        self,
+        item,  # type: ParagraphKey
+        use_get=False,  # type: bool
+    ):
+        # type: (...) -> Optional[Deb822KeyValuePairElement]
+        raise NotImplementedError  # pragma: no cover
+
+    def set_kvpair_element(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> None
+        raise NotImplementedError  # pragma: no cover
+
+    def remove_kvpair_element(self, key):
+        # type: (ParagraphKey) -> None
+        raise NotImplementedError  # pragma: no cover
+
+    def sort_fields(
+        self, key=None  # type: Optional[Callable[[str], Any]]
+    ):
+        # type: (...) -> None
+        """Re-order all fields
+
+        :param key: Provide a key function (same semantics as for sorted).  Keep in mind that
+          the module preserve the cases for field names - in generally, callers are recommended
+          to use "lower()" to normalize the case.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    def set_field_to_simple_value(
+        self,
+        item,  # type: ParagraphKey
+        simple_value,  # type: str
+        *,
+        preserve_original_field_comment=None,  # type: Optional[bool]
+        field_comment=None,  # type: Optional[Commentish]
+    ):
+        # type: (...) -> None
+        r"""Sets a field in this paragraph to a simple "word" or "phrase"
+
+        In many cases, it is better for callers to just use the paragraph as
+        if it was a dictionary.  However, this method does enable to you choose
+        the field comment (if any), which can be a reason for using it.
+
+        This is suitable for "simple" fields like "Package".  Example:
+
+            >>> example_deb822_paragraph = '''
+            ... Package: foo
+            ... '''
+            >>> dfile = parse_deb822_file(example_deb822_paragraph.splitlines())
+            >>> p = next(iter(dfile))
+            >>> p.set_field_to_simple_value("Package", "mscgen")
+            >>> p.set_field_to_simple_value("Architecture", "linux-any kfreebsd-any",
+            ...                             field_comment=['Only ported to linux and kfreebsd'])
+            >>> p.set_field_to_simple_value("Priority", "optional")
+            >>> print(p.dump(), end='')
+            Package: mscgen
+            # Only ported to linux and kfreebsd
+            Architecture: linux-any kfreebsd-any
+            Priority: optional
+            >>> # Values are formatted nicely by default, but it does not work with
+            >>> # multi-line values
+            >>> p.set_field_to_simple_value("Foo", "bar\nbin\n")
+            Traceback (most recent call last):
+                ...
+            ValueError: Cannot use set_field_to_simple_value for values with newlines
+
+        :param item: Name of the field to set.  If the paragraph already
+          contains the field, then it will be replaced.  If the field exists,
+          then it will preserve its order in the paragraph.  Otherwise, it is
+          added to the end of the paragraph.
+          Note this can be a "paragraph key", which enables you to control
+          *which* instance of a field is being replaced (in case of duplicate
+          fields).
+        :param simple_value: The text to use as the value.  The value must not
+          contain newlines.  Leading and trailing will be stripped but space
+          within the value is preserved.  The value cannot contain comments
+          (i.e. if the "#" token appears in the value, then it is considered
+          a value rather than "start of a comment)
+        :param preserve_original_field_comment: See the description for the
+          parameter with the same name in the set_field_from_raw_string method.
+        :param field_comment: See the description for the parameter with the same
+          name in the set_field_from_raw_string method.
+        """
+        if "\n" in simple_value:
+            raise ValueError(
+                "Cannot use set_field_to_simple_value for values with newlines"
+            )
+
+        # Reformat it with a leading space and trailing newline. The latter because it is
+        # necessary if there are any fields after it and the former because it looks nicer so
+        # have single space after the field separator
+        stripped = simple_value.strip()
+        if stripped:
+            raw_value = " " + stripped + "\n"
+        else:
+            # Special-case for empty values
+            raw_value = "\n"
+        self.set_field_from_raw_string(
+            item,
+            raw_value,
+            preserve_original_field_comment=preserve_original_field_comment,
+            field_comment=field_comment,
+        )
+
+    def set_field_from_raw_string(
+        self,
+        item,  # type: ParagraphKey
+        raw_string_value,  # type: str
+        *,
+        preserve_original_field_comment=None,  # type: Optional[bool]
+        field_comment=None,  # type: Optional[Commentish]
+    ):
+        # type: (...) -> None
+        """Sets a field in this paragraph to a given text value
+
+        In many cases, it is better for callers to just use the paragraph as
+        if it was a dictionary.  However, this method does enable to you choose
+        the field comment (if any) and lets to have a higher degree of control
+        over whitespace (on the first line), which can be a reason for using it.
+
+        Example usage:
+
+            >>> example_deb822_paragraph = '''
+            ... Package: foo
+            ... '''
+            >>> dfile = parse_deb822_file(example_deb822_paragraph.splitlines())
+            >>> p = next(iter(dfile))
+            >>> raw_value = '''
+            ... Build-Depends: debhelper-compat (= 12),
+            ...                some-other-bd,
+            ... # Comment
+            ...                another-bd,
+            ... '''.lstrip()  # Remove leading newline, but *not* the trailing newline
+            >>> fname, new_value = raw_value.split(':', 1)
+            >>> p.set_field_from_raw_string(fname, new_value)
+            >>> print(p.dump(), end='')
+            Package: foo
+            Build-Depends: debhelper-compat (= 12),
+                           some-other-bd,
+            # Comment
+                           another-bd,
+            >>> # Format preserved
+
+        :param item: Name of the field to set.  If the paragraph already
+          contains the field, then it will be replaced.  Otherwise, it is
+          added to the end of the paragraph.
+          Note this can be a "paragraph key", which enables you to control
+          *which* instance of a field is being replaced (in case of duplicate
+          fields).
+        :param raw_string_value: The text to use as the value.  The text must
+          be valid deb822 syntax and is used *exactly* as it is given.
+          Accordingly, multi-line values must include mandatory leading space
+          on continuation lines, newlines after the value, etc. On the
+          flip-side, any optional space or comments will be included.
+
+          Note that the first line will *never* be read as a comment (if the
+          first line of the value starts with a "#" then it will result
+          in "Field-Name:#..." which is parsed as a value starting with "#"
+          rather than a comment).
+        :param preserve_original_field_comment: If True, then if there is an
+          existing field and that has a comment, then the comment will remain
+          after this operation.  This is the default is the `field_comment`
+          parameter is omitted.
+          Note that if the parameter is True and the item is ambiguous, this
+          will raise an AmbiguousDeb822FieldKeyError.  When the parameter is
+          omitted, the ambiguity is resolved automatically and if the resolved
+          field has a comment then that will be preserved (assuming
+          field_comment is None).
+        :param field_comment: If not None, add or replace the comment for
+          the field.  Each string in the list will become one comment
+          line (inserted directly before the field name). Will appear in the
+          same order as they do in the list.
+
+          If you want complete control over the formatting of the comments,
+          then ensure that each line start with "#" and end with "\\n" before
+          the call.  Otherwise, leading/trailing whitespace is normalized
+          and the missing "#"/"\\n" character is inserted.
+        """
+
+        new_content = []  # type: List[str]
+        if preserve_original_field_comment is not None:
+            if field_comment is not None:
+                raise ValueError(
+                    'The "preserve_original_field_comment" conflicts with'
+                    ' "field_comment" parameter'
+                )
+        elif field_comment is not None:
+            if not isinstance(field_comment, Deb822CommentElement):
+                new_content.extend(_format_comment(x) for x in field_comment)
+                field_comment = None
+            preserve_original_field_comment = False
+
+        field_name, _, _ = _unpack_key(item)
+
+        cased_field_name = field_name
+        try:
+            original = self.get_kvpair_element(item, use_get=True)
+        except AmbiguousDeb822FieldKeyError:
+            if preserve_original_field_comment:
+                # If we were asked to preserve the original comment, then we
+                # require a strict lookup
+                raise
+            original = self.get_kvpair_element((field_name, 0), use_get=True)
+
+        if preserve_original_field_comment is None:
+            # We simplify preserve_original_field_comment after the lookup of the field.
+            # Otherwise, we can get ambiguous key errors when updating an ambiguous field
+            # when the caller did not explicitly ask for that behaviour.
+            preserve_original_field_comment = True
+
+        if original:
+            # If we already have the field, then preserve the original case
+            cased_field_name = original.field_name
+        raw = ":".join((cased_field_name, raw_string_value))
+        raw_lines = raw.splitlines(keepends=True)
+        for i, line in enumerate(raw_lines, start=1):
+            if not line.endswith("\n"):
+                raise ValueError(
+                    "Line {i} in new value was missing trailing newline".format(i=i)
+                )
+            if i != 1 and line[0] not in (" ", "\t", "#"):
+                msg = (
+                    "Line {i} in new value was invalid.  It must either start"
+                    ' with " " space (continuation line) or "#" (comment line).'
+                    ' The line started with "{line}"'
+                )
+                raise ValueError(msg.format(i=i, line=line[0]))
+        if len(raw_lines) > 1 and raw_lines[-1].startswith("#"):
+            raise ValueError("The last line in a value field cannot be a comment")
+        new_content.extend(raw_lines)
+        # As absurd as it might seem, it is easier to just use the parser to
+        # construct the AST correctly
+        deb822_file = parse_deb822_file(iter(new_content))
+        error_token = deb822_file.find_first_error_element()
+        if error_token:
+            raise ValueError("Syntax error in new field value for " + field_name)
+        paragraph = next(iter(deb822_file))
+        assert isinstance(paragraph, Deb822NoDuplicateFieldsParagraphElement)
+        value = paragraph.get_kvpair_element(field_name)
+        assert value is not None
+        if preserve_original_field_comment:
+            if original:
+                value.comment_element = original.comment_element
+                original.comment_element = None
+        elif field_comment is not None:
+            value.comment_element = field_comment
+        self.set_kvpair_element(item, value)
+
+    @overload
+    def dump(
+        self, fd  # type: IO[bytes]
+    ):
+        # type: (...) -> None
+        pass
+
+    @overload
+    def dump(self):
+        # type: () -> str
+        pass
+
+    def dump(
+        self, fd=None  # type: Optional[IO[bytes]]
+    ):
+        # type: (...) -> Optional[str]
+        if fd is None:
+            return "".join(t.text for t in self.iter_tokens())
+        for token in self.iter_tokens():
+            fd.write(token.text.encode("utf-8"))
+        return None
+
+
+class Deb822NoDuplicateFieldsParagraphElement(Deb822ParagraphElement):
+    """Paragraph implementation optimized for valid deb822 files
+
+    When there are no duplicated fields, we can use simpler and faster
+    datastructures for common operations.
+    """
+
+    def __init__(
+        self,
+        kvpair_elements,  # type: List[Deb822KeyValuePairElement]
+        kvpair_order,  # type: OrderedSet
+    ):
+        # type: (...) -> None
+        super().__init__()
+        self._kvpair_elements = {kv.field_name: kv for kv in kvpair_elements}
+        self._kvpair_order = kvpair_order
+        self._init_parent_of_parts()
+
+    @property
+    def kvpair_count(self):
+        # type: () -> int
+        return len(self._kvpair_elements)
+
+    def order_last(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "last" in the paragraph"""
+        unpacked_field, _, _ = _unpack_key(field, raise_if_indexed=True)
+        self._kvpair_order.order_last(unpacked_field)
+
+    def order_first(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "first" in the paragraph"""
+        unpacked_field, _, _ = _unpack_key(field, raise_if_indexed=True)
+        self._kvpair_order.order_first(unpacked_field)
+
+    def order_before(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly after the reference field in the paragraph
+
+        The reference field must be present."""
+        unpacked_field, _, _ = _unpack_key(field, raise_if_indexed=True)
+        unpacked_ref_field, _, _ = _unpack_key(reference_field, raise_if_indexed=True)
+        self._kvpair_order.order_before(unpacked_field, unpacked_ref_field)
+
+    def order_after(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly before the reference field in the paragraph
+
+        The reference field must be present.
+        """
+        unpacked_field, _, _ = _unpack_key(field, raise_if_indexed=True)
+        unpacked_ref_field, _, _ = _unpack_key(reference_field, raise_if_indexed=True)
+        self._kvpair_order.order_after(unpacked_field, unpacked_ref_field)
+
+    # Overload to narrow the type to just str.
+    def __iter__(self):
+        # type: () -> Iterator[str]
+        return iter(str(k) for k in self._kvpair_order)
+
+    def iter_keys(self):
+        # type: () -> Iterable[str]
+        yield from (str(k) for k in self._kvpair_order)
+
+    def remove_kvpair_element(self, key):
+        # type: (ParagraphKey) -> None
+        self._full_size_cache = None
+        key, _, _ = _unpack_key(key, raise_if_indexed=True)
+        del self._kvpair_elements[key]
+        self._kvpair_order.remove(key)
+
+    def contains_kvpair_element(self, item):
+        # type: (object) -> bool
+        if not isinstance(item, (str, tuple, Deb822FieldNameToken)):
+            return False
+        item = cast("ParagraphKey", item)
+        key, _, _ = _unpack_key(item, raise_if_indexed=True)
+        return key in self._kvpair_elements
+
+    def get_kvpair_element(
+        self,
+        item,  # type: ParagraphKey
+        use_get=False,  # type: bool
+    ):
+        # type: (...) -> Optional[Deb822KeyValuePairElement]
+        item, _, _ = _unpack_key(item, raise_if_indexed=True)
+        if use_get:
+            return self._kvpair_elements.get(item)
+        return self._kvpair_elements[item]
+
+    def set_kvpair_element(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> None
+        key, _, _ = _unpack_key(key, raise_if_indexed=True)
+        if isinstance(key, Deb822FieldNameToken):
+            if key is not value.field_token:
+                raise ValueError(
+                    "Key is a Deb822FieldNameToken, but not *the* Deb822FieldNameToken"
+                    " for the value"
+                )
+            key = value.field_name
+        else:
+            if key != value.field_name:
+                raise ValueError(
+                    "Cannot insert value under a different field value than field name"
+                    " from its Deb822FieldNameToken implies"
+                )
+            # Use the string from the Deb822FieldNameToken as we need to keep that in memory either
+            # way
+            key = value.field_name
+        original_value = self._kvpair_elements.get(key)
+        self._full_size_cache = None
+        self._kvpair_elements[key] = value
+        self._kvpair_order.append(key)
+        if original_value is not None:
+            original_value.parent_element = None
+        value.parent_element = self
+
+    def sort_fields(self, key=None):
+        # type: (Optional[Callable[[str], Any]]) -> None
+        """Re-order all fields
+
+        :param key: Provide a key function (same semantics as for sorted).  Keep in mind that
+          the module preserve the cases for field names - in generally, callers are recommended
+          to use "lower()" to normalize the case.
+        """
+        for last_field_name in reversed(self._kvpair_order):
+            last_kvpair = self._kvpair_elements[cast("_strI", last_field_name)]
+            if last_kvpair.value_element.add_final_newline_if_missing():
+                self._full_size_cache = None
+            break
+
+        if key is None:
+            key = default_field_sort_key
+
+        self._kvpair_order = OrderedSet(sorted(self._kvpair_order, key=key))
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from (
+            self._kvpair_elements[x]
+            for x in cast("Iterable[_strI]", self._kvpair_order)
+        )
+
+
+class Deb822DuplicateFieldsParagraphElement(Deb822ParagraphElement):
+
+    def __init__(self, kvpair_elements):
+        # type: (List[Deb822KeyValuePairElement]) -> None
+        super().__init__()
+        self._kvpair_order = LinkedList()  # type: LinkedList[Deb822KeyValuePairElement]
+        self._kvpair_elements = {}  # type: Dict[_strI, List[KVPNode]]
+        self._init_kvpair_fields(kvpair_elements)
+        self._init_parent_of_parts()
+
+    @property
+    def has_duplicate_fields(self):
+        # type: () -> bool
+        # Most likely, the answer is "True" but if the caller "fixes" the problem
+        # then this can return "False"
+        return len(self._kvpair_order) > len(self._kvpair_elements)
+
+    def _init_kvpair_fields(self, kvpairs):
+        # type: (Iterable[Deb822KeyValuePairElement]) -> None
+        assert not self._kvpair_order
+        assert not self._kvpair_elements
+        for kv in kvpairs:
+            field_name = kv.field_name
+            node = self._kvpair_order.append(kv)
+            if field_name not in self._kvpair_elements:
+                self._kvpair_elements[field_name] = [node]
+            else:
+                self._kvpair_elements[field_name].append(node)
+
+    def _nodes_being_relocated(self, field):
+        # type: (ParagraphKey) -> Tuple[List[KVPNode], List[KVPNode]]
+        key, index, name_token = _unpack_key(field)
+        nodes = self._kvpair_elements[key]
+        nodes_being_relocated = []
+
+        if name_token is not None or index is not None:
+            single_node = self._resolve_to_single_node(nodes, key, index, name_token)
+            assert single_node is not None
+            nodes_being_relocated.append(single_node)
+        else:
+            nodes_being_relocated = nodes
+        return nodes, nodes_being_relocated
+
+    def order_last(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "last" in the paragraph"""
+        nodes, nodes_being_relocated = self._nodes_being_relocated(field)
+        assert len(nodes_being_relocated) == 1 or len(nodes) == len(
+            nodes_being_relocated
+        )
+
+        kvpair_order = self._kvpair_order
+        for node in nodes_being_relocated:
+            if kvpair_order.tail_node is node:
+                # Special case for relocating a single node that happens to be the last.
+                continue
+            kvpair_order.remove_node(node)
+            # assertion for mypy
+            assert kvpair_order.tail_node is not None
+            kvpair_order.insert_node_after(node, kvpair_order.tail_node)
+
+        if (
+            len(nodes_being_relocated) == 1
+            and nodes_being_relocated[0] is not nodes[-1]
+        ):
+            single_node = nodes_being_relocated[0]
+            nodes.remove(single_node)
+            nodes.append(single_node)
+
+    def order_first(self, field):
+        # type: (ParagraphKey) -> None
+        """Re-order the given field so it is "first" in the paragraph"""
+        nodes, nodes_being_relocated = self._nodes_being_relocated(field)
+        assert len(nodes_being_relocated) == 1 or len(nodes) == len(
+            nodes_being_relocated
+        )
+
+        kvpair_order = self._kvpair_order
+        for node in nodes_being_relocated:
+            if kvpair_order.head_node is node:
+                # Special case for relocating a single node that happens to be the first.
+                continue
+            kvpair_order.remove_node(node)
+            # assertion for mypy
+            assert kvpair_order.head_node is not None
+            kvpair_order.insert_node_before(node, kvpair_order.head_node)
+
+        if len(nodes_being_relocated) == 1 and nodes_being_relocated[0] is not nodes[0]:
+            single_node = nodes_being_relocated[0]
+            nodes.remove(single_node)
+            nodes.insert(0, single_node)
+
+    def order_before(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly after the reference field in the paragraph
+
+        The reference field must be present."""
+        nodes, nodes_being_relocated = self._nodes_being_relocated(field)
+        assert len(nodes_being_relocated) == 1 or len(nodes) == len(
+            nodes_being_relocated
+        )
+        # For "before" we always use the "first" variant as reference in case of doubt
+        _, reference_nodes = self._nodes_being_relocated(reference_field)
+        reference_node = reference_nodes[0]
+        if reference_node in nodes_being_relocated:
+            raise ValueError("Cannot re-order a field relative to itself")
+
+        kvpair_order = self._kvpair_order
+        for node in nodes_being_relocated:
+            kvpair_order.remove_node(node)
+            kvpair_order.insert_node_before(node, reference_node)
+
+        if len(nodes_being_relocated) == 1 and len(nodes) > 1:
+            # Regenerate the (new) relative field order.
+            field_name = nodes_being_relocated[0].value.field_name
+            self._regenerate_relative_kvapir_order(field_name)
+
+    def order_after(self, field, reference_field):
+        # type: (ParagraphKey, ParagraphKey) -> None
+        """Re-order the given field so appears directly before the reference field in the paragraph
+
+        The reference field must be present.
+        """
+        nodes, nodes_being_relocated = self._nodes_being_relocated(field)
+        assert len(nodes_being_relocated) == 1 or len(nodes) == len(
+            nodes_being_relocated
+        )
+        _, reference_nodes = self._nodes_being_relocated(reference_field)
+        # For "after" we always use the "last" variant as reference in case of doubt
+        reference_node = reference_nodes[-1]
+        if reference_node in nodes_being_relocated:
+            raise ValueError("Cannot re-order a field relative to itself")
+
+        kvpair_order = self._kvpair_order
+        # Use "reversed" to preserve the relative order of the nodes assuming a bulk reorder
+        for node in reversed(nodes_being_relocated):
+            kvpair_order.remove_node(node)
+            kvpair_order.insert_node_after(node, reference_node)
+
+        if len(nodes_being_relocated) == 1 and len(nodes) > 1:
+            # Regenerate the (new) relative field order.
+            field_name = nodes_being_relocated[0].value.field_name
+            self._regenerate_relative_kvapir_order(field_name)
+
+    def _regenerate_relative_kvapir_order(self, field_name):
+        # type: (_strI) -> None
+        nodes = []
+        for node in self._kvpair_order.iter_nodes():
+            if node.value.field_name == field_name:
+                nodes.append(node)
+        self._kvpair_elements[field_name] = nodes
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._kvpair_order
+
+    @property
+    def kvpair_count(self):
+        # type: () -> int
+        return len(self._kvpair_order)
+
+    def iter_keys(self):
+        # type: () -> Iterable[ParagraphKey]
+        yield from (kv.field_name for kv in self._kvpair_order)
+
+    def _resolve_to_single_node(
+        self,
+        nodes,  # type: List[KVPNode]
+        key,  # type: str
+        index,  # type: Optional[int]
+        name_token,  # type: Optional[Deb822FieldNameToken]
+        use_get=False,  # type: bool
+    ):
+        # type: (...) -> Optional[KVPNode]
+        if index is None:
+            if len(nodes) != 1:
+                if name_token is not None:
+                    node = self._find_node_via_name_token(name_token, nodes)
+                    if node is not None:
+                        return node
+                msg = (
+                    "Ambiguous key {key} - the field appears {res_len} times. Use"
+                    " ({key}, index) to denote which instance of the field you want.  (Index"
+                    " can be 0..{res_len_1} or e.g. -1 to denote the last field)"
+                )
+                raise AmbiguousDeb822FieldKeyError(
+                    msg.format(key=key, res_len=len(nodes), res_len_1=len(nodes) - 1)
+                )
+            index = 0
+        try:
+            return nodes[index]
+        except IndexError:
+            if use_get:
+                return None
+            msg = 'Field "{key}" was present but the index "{index}" was invalid.'
+            raise KeyError(msg.format(key=key, index=index))
+
+    def get_kvpair_element(
+        self,
+        item,  # type: ParagraphKey
+        use_get=False,  # type: bool
+    ):
+        # type: (...) -> Optional[Deb822KeyValuePairElement]
+        key, index, name_token = _unpack_key(item)
+        if use_get:
+            nodes = self._kvpair_elements.get(key)
+            if nodes is None:
+                return None
+        else:
+            nodes = self._kvpair_elements[key]
+        node = self._resolve_to_single_node(
+            nodes, key, index, name_token, use_get=use_get
+        )
+        if node is not None:
+            return node.value
+        return None
+
+    @staticmethod
+    def _find_node_via_name_token(
+        name_token,  # type: Deb822FieldNameToken
+        elements,  # type: Iterable[KVPNode]
+    ):
+        # type: (...) -> Optional[KVPNode]
+        # if we are given a name token, then it is non-ambiguous if we have exactly
+        # that name token in our list of nodes.  It will be an O(n) lookup but we
+        # probably do not have that many duplicate fields (and even if do, it is not
+        # exactly a valid file, so there little reason to optimize for it)
+        for node in elements:
+            if name_token is node.value.field_token:
+                return node
+        return None
+
+    def contains_kvpair_element(self, item):
+        # type: (object) -> bool
+        if not isinstance(item, (str, tuple, Deb822FieldNameToken)):
+            return False
+        item = cast("ParagraphKey", item)
+        try:
+            return self.get_kvpair_element(item, use_get=True) is not None
+        except AmbiguousDeb822FieldKeyError:
+            return True
+
+    def set_kvpair_element(self, key, value):
+        # type: (ParagraphKey, Deb822KeyValuePairElement) -> None
+        key, index, name_token = _unpack_key(key)
+        if name_token:
+            if name_token is not value.field_token:
+                original_nodes = self._kvpair_elements.get(value.field_name)
+                original_node = None
+                if original_nodes is not None:
+                    original_node = self._find_node_via_name_token(
+                        name_token, original_nodes
+                    )
+
+                if original_node is None:
+                    raise ValueError(
+                        "Key is a Deb822FieldNameToken, but not *the*"
+                        " Deb822FieldNameToken for the value nor the"
+                        " Deb822FieldNameToken for an existing field in the paragraph"
+                    )
+                # Primarily for mypy's sake
+                assert original_nodes is not None
+                # Rely on the index-based code below to handle update.
+                index = original_nodes.index(original_node)
+            key = value.field_name
+        else:
+            if key != value.field_name:
+                raise ValueError(
+                    "Cannot insert value under a different field value than field name"
+                    " from its Deb822FieldNameToken implies"
+                )
+            # Use the string from the Deb822FieldNameToken as it is a _strI and has the same value
+            # (memory optimization)
+            key = value.field_name
+        self._full_size_cache = None
+        original_nodes = self._kvpair_elements.get(key)
+        if original_nodes is None or not original_nodes:
+            if index is not None and index != 0:
+                msg = (
+                    "Cannot replace field ({key}, {index}) as the field does not exist"
+                    " in the first place.  Please index-less key or ({key}, 0) if you"
+                    " want to add the field."
+                )
+                raise KeyError(msg.format(key=key, index=index))
+            node = self._kvpair_order.append(value)
+            if key not in self._kvpair_elements:
+                self._kvpair_elements[key] = [node]
+            else:
+                self._kvpair_elements[key].append(node)
+            return
+
+        replace_all = False
+        if index is None:
+            replace_all = True
+            node = original_nodes[0]
+            if len(original_nodes) != 1:
+                self._kvpair_elements[key] = [node]
+        else:
+            # We insist on there being an original node, which as a side effect ensures
+            # you cannot add additional copies of the field.  This means that you cannot
+            # make the problem worse.
+            node = original_nodes[index]
+
+        # Replace the value of the existing node plus do a little dance
+        # for the parent element part.
+        node.value.parent_element = None
+        value.parent_element = self
+        node.value = value
+
+        if replace_all and len(original_nodes) != 1:
+            # If we were in a replace-all mode, discard any remaining nodes
+            for n in original_nodes[1:]:
+                n.value.parent_element = None
+                self._kvpair_order.remove_node(n)
+
+    def remove_kvpair_element(self, key):
+        # type: (ParagraphKey) -> None
+        key, idx, name_token = _unpack_key(key)
+        field_list = self._kvpair_elements[key]
+
+        if name_token is None and idx is None:
+            self._full_size_cache = None
+            # Remove all case
+            for node in field_list:
+                node.value.parent_element = None
+                self._kvpair_order.remove_node(node)
+            del self._kvpair_elements[key]
+            return
+
+        if name_token is not None:
+            # Indirection between original_node and node for mypy's sake
+            original_node = self._find_node_via_name_token(name_token, field_list)
+            if original_node is None:
+                msg = 'The field "{key}" is present but key used to access it is not.'
+                raise KeyError(msg.format(key=key))
+            node = original_node
+        else:
+            assert idx is not None
+            try:
+                node = field_list[idx]
+            except KeyError:
+                msg = 'The field "{key}" is present, but the index "{idx}" was invalid.'
+                raise KeyError(msg.format(key=key, idx=idx))
+
+        self._full_size_cache = None
+        if len(field_list) == 1:
+            del self._kvpair_elements[key]
+        else:
+            field_list.remove(node)
+        node.value.parent_element = None
+        self._kvpair_order.remove_node(node)
+
+    def sort_fields(self, key=None):
+        # type: (Optional[Callable[[str], Any]]) -> None
+        """Re-order all fields
+
+        :param key: Provide a key function (same semantics as for sorted).   Keep in mind that
+          the module preserve the cases for field names - in generally, callers are recommended
+          to use "lower()" to normalize the case.
+        """
+
+        if key is None:
+            key = default_field_sort_key
+
+        # Work around mypy that cannot seem to shred the Optional notion
+        # without this little indirection
+        key_impl = key
+
+        def _actual_key(kvpair):
+            # type: (Deb822KeyValuePairElement) -> Any
+            return key_impl(kvpair.field_name)
+
+        for last_kvpair in reversed(self._kvpair_order):
+            if last_kvpair.value_element.add_final_newline_if_missing():
+                self._full_size_cache = None
+            break
+
+        sorted_kvpair_list = sorted(self._kvpair_order, key=_actual_key)
+        self._kvpair_order = LinkedList()
+        self._kvpair_elements = {}
+        self._init_kvpair_fields(sorted_kvpair_list)
+
+
+class Deb822FileElement(Deb822Element):
+    """Represents the entire deb822 file"""
+
+    def __init__(self, token_and_elements):
+        # type: (LinkedList[TokenOrElement]) -> None
+        super().__init__()
+        self._token_and_elements = token_and_elements
+        self._init_parent_of_parts()
+
+    @classmethod
+    def new_empty_file(cls):
+        # type: () -> Deb822FileElement
+        """Creates a new Deb822FileElement with no contents
+
+        Note that a deb822 file must be non-empty to be considered valid
+        """
+        return cls(LinkedList())
+
+    @property
+    def is_valid_file(self):
+        # type: () -> bool
+        """Returns true if the file is valid
+
+        Invalid elements include error elements (Deb822ErrorElement) but also
+        issues such as paragraphs with duplicate fields or "empty" files
+        (a valid deb822 file contains at least one paragraph).
+        """
+        had_paragraph = False
+        for paragraph in self:
+            had_paragraph = True
+            if not paragraph or paragraph.has_duplicate_fields:
+                return False
+
+        if not had_paragraph:
+            return False
+
+        return self.find_first_error_element() is None
+
+    def find_first_error_element(self):
+        # type: () -> Optional[Deb822ErrorElement]
+        """Returns the first Deb822ErrorElement (or None) in the file"""
+        return next(
+            iter(self.iter_recurse(only_element_or_token_type=Deb822ErrorElement)), None
+        )
+
+    def __iter__(self):
+        # type: () -> Iterator[Deb822ParagraphElement]
+        return iter(self.iter_parts_of_type(Deb822ParagraphElement))
+
+    def iter_parts(self):
+        # type: () -> Iterable[TokenOrElement]
+        yield from self._token_and_elements
+
+    def insert(self, idx, para):
+        # type: (int, Deb822ParagraphElement) -> None
+        """Inserts a paragraph into the file at the given "index" of paragraphs
+
+        Note that if the index is between two paragraphs containing a "free
+        floating" comment (e.g. paragrah/start-of-file, empty line, comment,
+        empty line, paragraph) then it is unspecified which "side" of the
+        comment the new paragraph will appear and this may change between
+        versions of python-debian.
+
+
+        >>> original = '''
+        ... Package: libfoo-dev
+        ... Depends: libfoo1 (= ${binary:Version}), ${shlib:Depends}, ${misc:Depends}
+        ... '''.lstrip()
+        >>> deb822_file = parse_deb822_file(original.splitlines())
+        >>> para1 = Deb822ParagraphElement.new_empty_paragraph()
+        >>> para1["Source"] = "foo"
+        >>> para1["Build-Depends"] = "debhelper-compat (= 13)"
+        >>> para2 = Deb822ParagraphElement.new_empty_paragraph()
+        >>> para2["Package"] = "libfoo1"
+        >>> para2["Depends"] = "${shlib:Depends}, ${misc:Depends}"
+        >>> deb822_file.insert(0, para1)
+        >>> deb822_file.insert(1, para2)
+        >>> expected = '''
+        ... Source: foo
+        ... Build-Depends: debhelper-compat (= 13)
+        ...
+        ... Package: libfoo1
+        ... Depends: ${shlib:Depends}, ${misc:Depends}
+        ...
+        ... Package: libfoo-dev
+        ... Depends: libfoo1 (= ${binary:Version}), ${shlib:Depends}, ${misc:Depends}
+        ... '''.lstrip()
+        >>> deb822_file.dump() == expected
+        True
+        """
+
+        anchor_node = None
+        needs_newline = True
+        self._full_size_cache = None
+        if idx == 0:
+            # Special-case, if idx is 0, then we insert it before everything else.
+            # This is mostly a cosmetic choice for corner cases involving free-floating
+            # comments in the file.
+            if not self._token_and_elements:
+                self.append(para)
+                return
+            anchor_node = self._token_and_elements.head_node
+            needs_newline = bool(self._token_and_elements)
+        else:
+            i = 0
+            for node in self._token_and_elements.iter_nodes():
+                entry = node.value
+                if isinstance(entry, Deb822ParagraphElement):
+                    i += 1
+                if idx == i - 1:
+                    anchor_node = node
+                    break
+
+        if anchor_node is None:
+            # Empty list or idx after the last paragraph both degenerate into append
+            self.append(para)
+        else:
+            if needs_newline:
+                # Remember to inject the "separating" newline between two paragraphs
+                nl_token = self._set_parent(Deb822WhitespaceToken("\n"))
+                anchor_node = self._token_and_elements.insert_before(
+                    nl_token, anchor_node
+                )
+            self._token_and_elements.insert_before(self._set_parent(para), anchor_node)
+
+    def append(self, paragraph):
+        # type: (Deb822ParagraphElement) -> None
+        """Appends a paragraph to the file
+
+        >>> deb822_file = Deb822FileElement.new_empty_file()
+        >>> para1 = Deb822ParagraphElement.new_empty_paragraph()
+        >>> para1["Source"] = "foo"
+        >>> para1["Build-Depends"] = "debhelper-compat (= 13)"
+        >>> para2 = Deb822ParagraphElement.new_empty_paragraph()
+        >>> para2["Package"] = "foo"
+        >>> para2["Depends"] = "${shlib:Depends}, ${misc:Depends}"
+        >>> deb822_file.append(para1)
+        >>> deb822_file.append(para2)
+        >>> expected = '''
+        ... Source: foo
+        ... Build-Depends: debhelper-compat (= 13)
+        ...
+        ... Package: foo
+        ... Depends: ${shlib:Depends}, ${misc:Depends}
+        ... '''.lstrip()
+        >>> deb822_file.dump() == expected
+        True
+        """
+        tail_element = self._token_and_elements.tail
+        if paragraph.parent_element is not None:
+            if paragraph.parent_element is self:
+                raise ValueError("Paragraph is already a part of this file")
+            raise ValueError("Paragraph is already part of another Deb822File")
+
+        self._full_size_cache = None
+        # We need a separating newline if there is not a whitespace token at the end of the file.
+        # Note the special case where the file ends on a comment; here we insert a whitespace too
+        # to be sure.  Otherwise, we would have to check that there is an empty line before that
+        # comment and that is too much effort.
+        if tail_element and not isinstance(tail_element, Deb822WhitespaceToken):
+            self._token_and_elements.append(
+                self._set_parent(Deb822WhitespaceToken("\n"))
+            )
+        self._token_and_elements.append(self._set_parent(paragraph))
+
+    def remove(self, paragraph):
+        # type: (Deb822ParagraphElement) -> None
+        if paragraph.parent_element is not self:
+            raise ValueError("Paragraph is part of a different file")
+        node = None
+        for node in self._token_and_elements.iter_nodes():
+            if node.value is paragraph:
+                break
+        if node is None:
+            raise RuntimeError("unable to find paragraph")
+        self._full_size_cache = None
+        previous_node = node.previous_node
+        next_node = node.next_node
+        self._token_and_elements.remove_node(node)
+        if next_node is None:
+            if previous_node and isinstance(previous_node.value, Deb822WhitespaceToken):
+                self._token_and_elements.remove_node(previous_node)
+        else:
+            if isinstance(next_node.value, Deb822WhitespaceToken):
+                self._token_and_elements.remove_node(next_node)
+        paragraph.parent_element = None
+
+    def _set_parent(self, t):
+        # type: (TE) -> TE
+        t.parent_element = self
+        return t
+
+    def position_in_parent(self, *, skip_leading_comments: bool = True) -> Position:
+        # Recursive base-case
+        return START_POSITION
+
+    def position_in_file(self, *, skip_leading_comments: bool = True) -> Position:
+        # By definition
+        return START_POSITION
+
+    @overload
+    def dump(
+        self, fd  # type: IO[bytes]
+    ):
+        # type: (...) -> None
+        pass
+
+    @overload
+    def dump(self):
+        # type: () -> str
+        pass
+
+    def dump(
+        self, fd=None  # type: Optional[IO[bytes]]
+    ):
+        # type: (...) -> Optional[str]
+        if fd is None:
+            return "".join(t.text for t in self.iter_tokens())
+        for token in self.iter_tokens():
+            fd.write(token.text.encode("utf-8"))
+        return None
+
+
+_combine_error_tokens_into_elements = combine_into_replacement(
+    Deb822ErrorToken, Deb822ErrorElement
+)
+_combine_comment_tokens_into_elements = combine_into_replacement(
+    Deb822CommentToken, Deb822CommentElement
+)
+_combine_vl_elements_into_value_elements = combine_into_replacement(
+    Deb822ValueLineElement, Deb822ValueElement
+)
+_combine_kvp_elements_into_paragraphs = combine_into_replacement(
+    Deb822KeyValuePairElement,
+    Deb822ParagraphElement,
+    constructor=Deb822ParagraphElement.from_kvpairs,
+)
+
+
+def _parsed_value_render_factory(discard_comments):
+    # type: (bool) -> Callable[[Deb822ParsedValueElement], str]
+    return (
+        Deb822ParsedValueElement.convert_to_text_without_comments
+        if discard_comments
+        else Deb822ParsedValueElement.convert_to_text
+    )
+
+
+LIST_SPACE_SEPARATED_INTERPRETATION = ListInterpretation(
+    whitespace_split_tokenizer,
+    _parse_whitespace_list_value,
+    Deb822ParsedValueElement,
+    Deb822SemanticallySignificantWhiteSpace,
+    lambda: Deb822SpaceSeparatorToken(" "),
+    _parsed_value_render_factory,
+)
+LIST_COMMA_SEPARATED_INTERPRETATION = ListInterpretation(
+    comma_split_tokenizer,
+    _parse_comma_list_value,
+    Deb822ParsedValueElement,
+    Deb822CommaToken,
+    Deb822CommaToken,
+    _parsed_value_render_factory,
+)
+LIST_UPLOADERS_INTERPRETATION = ListInterpretation(
+    comma_split_tokenizer,
+    _parse_uploaders_list_value,
+    Deb822ParsedValueElement,
+    Deb822CommaToken,
+    Deb822CommaToken,
+    _parsed_value_render_factory,
+)
+
+
+def _non_end_of_line_token(v):
+    # type: (TokenOrElement) -> bool
+    # Consume tokens until the newline
+    return not isinstance(v, Deb822WhitespaceToken) or v.text != "\n"
+
+
+def _build_value_line(
+    token_stream,  # type: Iterable[Union[TokenOrElement, Deb822CommentElement]]
+):
+    # type: (...) -> Iterable[Union[TokenOrElement, Deb822ValueLineElement]]
+    """Parser helper - consumes tokens part of a Deb822ValueEntryElement and turns them into one"""
+    buffered_stream = BufferingIterator(token_stream)
+
+    # Deb822ValueLineElement is a bit tricky because of how we handle whitespace
+    # and comments.
+    #
+    # In relation to comments, then only continuation lines can have comments.
+    # If there is a comment before a "K: V" line, then the comment is associated
+    # with the field rather than the value.
+    #
+    # On the whitespace front, then we separate syntactical mandatory whitespace
+    # from optional whitespace.  As an example:
+    #
+    # """
+    # # some comment associated with the Depends field
+    # Depends:_foo_$
+    # # some comment associated with the line containing "bar"
+    # !________bar_$
+    # """
+    #
+    # Where "$" and "!" represents mandatory whitespace (the newline and the first
+    # space are required for the file to be parsed correctly), where as "_" is
+    # "optional" whitespace (from a syntactical point of view).
+    #
+    # This distinction enable us to facilitate APIs for easy removal/normalization
+    # of redundant whitespaces without having programmers worry about trashing
+    # the file.
+    #
+    #
+
+    comment_element = None
+    continuation_line_token = None
+    token = None  # type: Optional[TokenOrElement]
+
+    for token in buffered_stream:
+        start_of_value_entry = False
+        if isinstance(token, Deb822ValueContinuationToken):
+            continuation_line_token = token
+            start_of_value_entry = True
+            token = None
+        elif isinstance(token, Deb822FieldSeparatorToken):
+            start_of_value_entry = True
+        elif isinstance(token, Deb822CommentElement):
+            next_token = buffered_stream.peek()
+            # If the next token is a continuation line token, then this comment
+            # belong to a value and we might as well just start the value
+            # parsing now.
+            #
+            # Note that we rely on this behaviour to avoid emitting the comment
+            # token (failing to do so would cause the comment to appear twice
+            # in the file).
+            if isinstance(next_token, Deb822ValueContinuationToken):
+                start_of_value_entry = True
+                comment_element = token
+                token = None
+                # Use next with None to avoid raising StopIteration inside a generator
+                # It won't happen, but pylint cannot see that, so we do this instead.
+                continuation_line_token = cast(
+                    "Deb822ValueContinuationToken", next(buffered_stream, None)
+                )
+                assert continuation_line_token is not None
+
+        if token is not None:
+            yield token
+        if start_of_value_entry:
+            tokens_in_value = list(buffered_stream.takewhile(_non_end_of_line_token))
+            eol_token = cast("Deb822WhitespaceToken", next(buffered_stream, None))
+            assert eol_token is None or eol_token.text == "\n"
+            leading_whitespace = None
+            trailing_whitespace = None
+            # "Depends:\n foo" would cause tokens_in_value to be empty for the
+            # first "value line" (the empty part between ":" and "\n")
+            if tokens_in_value:
+                # Another special-case, "Depends: \n foo" (i.e. space after colon)
+                # should not introduce an IndexError
+                if isinstance(tokens_in_value[-1], Deb822WhitespaceToken):
+                    trailing_whitespace = cast(
+                        "Deb822WhitespaceToken", tokens_in_value.pop()
+                    )
+                if tokens_in_value and isinstance(
+                    tokens_in_value[-1], Deb822WhitespaceToken
+                ):
+                    leading_whitespace = cast(
+                        "Deb822WhitespaceToken", tokens_in_value[0]
+                    )
+                    tokens_in_value = tokens_in_value[1:]
+            yield Deb822ValueLineElement(
+                comment_element,
+                continuation_line_token,
+                leading_whitespace,
+                tokens_in_value,
+                trailing_whitespace,
+                eol_token,
+            )
+            comment_element = None
+            continuation_line_token = None
+
+
+def _build_field_with_value(
+    token_stream,  # type: Iterable[Union[TokenOrElement, Deb822ValueElement]]
+):
+    # type: (...) -> Iterable[Union[TokenOrElement, Deb822KeyValuePairElement]]
+    buffered_stream = BufferingIterator(token_stream)
+    for token_or_element in buffered_stream:
+        start_of_field = False
+        comment_element = None
+        if isinstance(token_or_element, Deb822FieldNameToken):
+            start_of_field = True
+        elif isinstance(token_or_element, Deb822CommentElement):
+            comment_element = token_or_element
+            next_token = buffered_stream.peek()
+            start_of_field = isinstance(next_token, Deb822FieldNameToken)
+            if start_of_field:
+                # Remember to consume the field token
+                try:
+                    token_or_element = next(buffered_stream)
+                except StopIteration:  # pragma: no cover
+                    raise AssertionError
+
+        if start_of_field:
+            field_name = token_or_element
+            separator = next(buffered_stream, None)
+            value_element = next(buffered_stream, None)
+            if separator is None or value_element is None:
+                # Early EOF - should not be possible with how the tokenizer works
+                # right now, but now it is future-proof.
+                if comment_element:
+                    yield comment_element
+                error_elements = [field_name]
+                if separator is not None:
+                    error_elements.append(separator)
+                yield Deb822ErrorElement(error_elements)
+                return
+
+            if isinstance(separator, Deb822FieldSeparatorToken) and isinstance(
+                value_element, Deb822ValueElement
+            ):
+                yield Deb822KeyValuePairElement(
+                    comment_element,
+                    cast("Deb822FieldNameToken", field_name),
+                    separator,
+                    value_element,
+                )
+            else:
+                # We had a parse error, consume until the newline.
+                error_tokens = [token_or_element]  # type: List[TokenOrElement]
+                error_tokens.extend(buffered_stream.takewhile(_non_end_of_line_token))
+                nl = buffered_stream.peek()
+                # Take the newline as well if present
+                if nl and isinstance(nl, Deb822NewlineAfterValueToken):
+                    next(buffered_stream, None)
+                    error_tokens.append(nl)
+                yield Deb822ErrorElement(error_tokens)
+        else:
+            # Token is not part of a field, emit it as-is
+            yield token_or_element
+
+
+def _abort_on_error_tokens(sequence):
+    # type: (Iterable[TokenOrElement]) -> Iterable[TokenOrElement]
+    line_no = 1
+    for token in sequence:
+        # We are always called while the sequence consists entirely of tokens
+        if token.is_error:
+            error_as_text = token.convert_to_text().replace("\n", "\\n")
+            raise SyntaxOrParseError(
+                'Syntax or Parse error on or near line {line_no}: "{error_as_text}"'.format(
+                    error_as_text=error_as_text, line_no=line_no
+                )
+            )
+        line_no += token.convert_to_text().count("\n")
+        yield token
+
+
+def parse_deb822_file(
+    sequence,  # type: Union[Iterable[Union[str, bytes]], str]
+    *,
+    accept_files_with_error_tokens=False,  # type: bool
+    accept_files_with_duplicated_fields=False,  # type: bool
+    encoding="utf-8",  # type: str
+):
+    # type: (...) -> Deb822FileElement
+    """
+
+    :param sequence: An iterable over lines of str or bytes (an open file for
+      reading will do).  If line endings are provided in the input, then they
+      must be present on every line (except the last) will be preserved as-is.
+      If omitted and the content is at least 2 lines, then parser will assume
+      implicit newlines.
+    :param accept_files_with_error_tokens: If True, files with critical syntax
+      or parse errors will be returned as "successfully" parsed. Usually,
+      working on files with this kind of errors are not desirable as it is
+      hard to make sense of such files (and they might in fact not be a deb822
+      file at all).  When set to False (the default) a ValueError is raised if
+      there is a critical syntax or parse error.
+      Note that duplicated fields in a paragraph is not considered a critical
+      parse error by this parser as the implementation can gracefully cope
+      with these. Use accept_files_with_duplicated_fields to determine if
+      such files should be accepted.
+    :param accept_files_with_duplicated_fields: If True, then
+      files containing paragraphs with duplicated fields will be returned as
+      "successfully" parsed even though they are invalid according to the
+      specification.  The paragraphs will prefer the first appearance of the
+      field unless caller explicitly requests otherwise (e.g., via
+      Deb822ParagraphElement.configured_view).  If False, then this method
+      will raise a ValueError if any duplicated fields are seen inside any
+      paragraph.
+    :param encoding: The encoding to use (this is here to support Deb822-like
+       APIs, new code should not use this parameter).
+    """
+
+    if isinstance(sequence, (str, bytes)):
+        # Match the deb822 API.
+        sequence = sequence.splitlines(True)
+
+    # The order of operations are important here.  As an example,
+    # _build_value_line assumes that all comment tokens have been merged
+    # into comment elements.  Likewise, _build_field_and_value assumes
+    # that value tokens (along with their comments) have been combined
+    # into elements.
+    tokens = tokenize_deb822_file(
+        sequence, encoding=encoding
+    )  # type: Iterable[TokenOrElement]
+    if not accept_files_with_error_tokens:
+        tokens = _abort_on_error_tokens(tokens)
+    tokens = _combine_comment_tokens_into_elements(tokens)
+    tokens = _build_value_line(tokens)
+    tokens = _combine_vl_elements_into_value_elements(tokens)
+    tokens = _build_field_with_value(tokens)
+    tokens = _combine_kvp_elements_into_paragraphs(tokens)
+    # Combine any free-floating error tokens into error elements.  We do
+    # this last as it enables other parts of the parser to include error
+    # tokens in their error elements if they discover something is wrong.
+    tokens = _combine_error_tokens_into_elements(tokens)
+
+    deb822_file = Deb822FileElement(LinkedList(tokens))
+
+    if not accept_files_with_duplicated_fields:
+        for no, paragraph in enumerate(deb822_file):
+            if isinstance(paragraph, Deb822DuplicateFieldsParagraphElement):
+                field_names = set()
+                dup_field = None
+                for field in paragraph.keys():
+                    field_name, _, _ = _unpack_key(field)
+                    # assert for mypy
+                    assert isinstance(field_name, str)
+                    if field_name in field_names:
+                        dup_field = field_name
+                        break
+                    field_names.add(field_name)
+                if dup_field is not None:
+                    msg = 'Duplicate field "{dup_field}" in paragraph number {no}'
+                    raise ValueError(msg.format(dup_field=dup_field, no=no))
+
+    return deb822_file
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import doctest
+
+    doctest.testmod()
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/tokens.py b/src/debputy/lsp/vendoring/_deb822_repro/tokens.py
new file mode 100644
index 0000000..4e5fa16
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/tokens.py
@@ -0,0 +1,516 @@
+import re
+import sys
+import weakref
+from weakref import ReferenceType
+
+from ._util import BufferingIterator
+from .locatable import (
+    Locatable,
+    START_POSITION,
+    Range,
+    ONE_CHAR_RANGE,
+    ONE_LINE_RANGE,
+    Position,
+)
+from debian._util import resolve_ref, _strI
+
+try:
+    from typing import Optional, cast, TYPE_CHECKING, Iterable, Union, Dict, Callable
+except ImportError:
+    # pylint: disable=unnecessary-lambda-assignment
+    TYPE_CHECKING = False
+    cast = lambda t, v: v
+
+if TYPE_CHECKING:
+    from .parsing import Deb822Element
+
+
+# Consume whitespace and a single word.
+_RE_WHITESPACE_SEPARATED_WORD_LIST = re.compile(
+    r"""
+    (?P<space_before>\s*)                # Consume any whitespace before the word
+                                         # The space only occurs in practise if the line starts
+                                         # with space.
+
+                                         # Optionally consume a word (needed to handle the case
+                                         # when there are no words left and someone applies this
+                                         # pattern to the remaining text). This is mostly here as
+                                         # a fail-safe.
+
+    (?P<word>\S+)                        # Consume the word (if present)
+    (?P<trailing_whitespace>\s*)         # Consume trailing whitespace
+""",
+    re.VERBOSE,
+)
+_RE_COMMA_SEPARATED_WORD_LIST = re.compile(
+    r"""
+    # This regex is slightly complicated by the fact that it should work with
+    # finditer and comsume the entire value.
+    #
+    # To do this, we structure the regex so it always starts on a comma (except
+    # for the first iteration, where we permit the absence of a comma)
+
+    (?:                                      # Optional space followed by a mandatory comma unless
+                                             # it is the start of the "line" (in which case, we
+                                             # allow the comma to be omitted)
+        ^
+        |
+        (?:
+            (?P<space_before_comma>\s*)      # This space only occurs in practise if the line
+                                             # starts with space + comma.
+            (?P<comma> ,)
+        )
+    )
+
+    # From here it is "optional space, maybe a word and then optional space" again.  One reason why
+    # all of it is optional is to gracefully cope with trailing commas.
+    (?P<space_before_word>\s*)
+    (?P<word> [^,\s] (?: [^,]*[^,\s])? )?    # "Words" can contain spaces for comma separated list.
+                                             # But surrounding whitespace is ignored
+    (?P<space_after_word>\s*)
+""",
+    re.VERBOSE,
+)
+
+# From Policy 5.1:
+#
+#    The field name is composed of US-ASCII characters excluding control
+#    characters, space, and colon (i.e., characters in the ranges U+0021
+#    (!) through U+0039 (9), and U+003B (;) through U+007E (~),
+#    inclusive). Field names must not begin with the comment character
+#    (U+0023 #), nor with the hyphen character (U+002D -).
+#
+# That combines to this regex of questionable readability
+_RE_FIELD_LINE = re.compile(
+    r"""
+    ^                                          # Start of line
+    (?P<field_name>                            # Capture group for the field name
+        [\x21\x22\x24-\x2C\x2F-\x39\x3B-\x7F]  # First character
+        [\x21-\x39\x3B-\x7F]*                  # Subsequent characters (if any)
+    )
+    (?P<separator> : )
+    (?P<space_before_value> \s* )
+    (?:                                        # Field values are not mandatory on the same line
+                                               # as the field name.
+
+      (?P<value>  \S(?:.*\S)?  )               # Values must start and end on a "non-space"
+      (?P<space_after_value> \s* )             # We can have optional space after the value
+    )?
+""",
+    re.VERBOSE,
+)
+
+
+class Deb822Token(Locatable):
+    """A token is an atomic syntactical element from a deb822 file
+
+    A file is parsed into a series of tokens.  If these tokens are converted to
+    text in exactly the same order, you get exactly the same file - bit-for-bit.
+    Accordingly ever bit of text in a file must be assigned to exactly one
+    Deb822Token.
+    """
+
+    __slots__ = ("_text", "_parent_element", "_token_size", "__weakref__")
+
+    def __init__(self, text):
+        # type: (str) -> None
+        if text == "":  # pragma: no cover
+            raise ValueError("Tokens must have content")
+        self._text = text  # type: str
+        self._parent_element = None  # type: Optional[ReferenceType['Deb822Element']]
+        self._token_size = None  # type: Optional[Range]
+        self._verify_token_text()
+
+    def __repr__(self):
+        # type: () -> str
+        return "{clsname}('{text}')".format(
+            clsname=self.__class__.__name__, text=self._text.replace("\n", "\\n")
+        )
+
+    def _verify_token_text(self):
+        # type: () -> None
+        if "\n" in self._text:
+            is_single_line_token = False
+            if self.is_comment or self.is_error:
+                is_single_line_token = True
+            if not is_single_line_token and not self.is_whitespace:
+                raise ValueError(
+                    "Only whitespace, error and comment tokens may contain newlines"
+                )
+            if not self.text.endswith("\n"):
+                raise ValueError("Tokens containing whitespace must end on a newline")
+            if is_single_line_token and "\n" in self.text[:-1]:
+                raise ValueError(
+                    "Comments and error tokens must not contain embedded newlines"
+                    " (only end on one)"
+                )
+
+    @property
+    def is_whitespace(self):
+        # type: () -> bool
+        return False
+
+    @property
+    def is_comment(self):
+        # type: () -> bool
+        return False
+
+    @property
+    def is_error(self):
+        # type: () -> bool
+        return False
+
+    @property
+    def text(self):
+        # type: () -> str
+        return self._text
+
+    # To support callers that want a simple interface for converting tokens and elements to text
+    def convert_to_text(self):
+        # type: () -> str
+        return self._text
+
+    def size(self, *, skip_leading_comments: bool = False) -> Range:
+        # As tokens are an atomtic unit
+        token_size = self._token_size
+        if token_size is not None:
+            return token_size
+        token_len = len(self._text)
+        if token_len == 1:
+            # The indirection with `r` because mypy gets confused and thinks that `token_size`
+            # cannot have any type at all.
+            token_size = ONE_CHAR_RANGE if self._text != "\n" else ONE_LINE_RANGE
+        else:
+            new_lines = self._text.count("\n")
+            assert not new_lines or self._text[-1] == "\n"
+            end_pos = Position(new_lines, 0) if new_lines else Position(0, token_len)
+            token_size = Range(START_POSITION, end_pos)
+        self._token_size = token_size
+        return token_size
+
+    @property
+    def parent_element(self):
+        # type: () -> Optional[Deb822Element]
+        return resolve_ref(self._parent_element)
+
+    @parent_element.setter
+    def parent_element(self, new_parent):
+        # type: (Optional[Deb822Element]) -> None
+        self._parent_element = (
+            weakref.ref(new_parent) if new_parent is not None else None
+        )
+
+    def clear_parent_if_parent(self, parent):
+        # type: (Deb822Element) -> None
+        if parent is self.parent_element:
+            self._parent_element = None
+
+
+class Deb822WhitespaceToken(Deb822Token):
+    """The token is a kind of whitespace.
+
+    Some whitespace tokens are critical for the format (such as the Deb822ValueContinuationToken,
+    spaces that separate words in list separated by spaces or newlines), while other whitespace
+    tokens are truly insignificant (space before a newline, space after a comma in a comma
+    list, etc.).
+    """
+
+    __slots__ = ()
+
+    @property
+    def is_whitespace(self):
+        # type: () -> bool
+        return True
+
+
+class Deb822SemanticallySignificantWhiteSpace(Deb822WhitespaceToken):
+    """Whitespace that (if removed) would change the meaning of the file (or cause syntax errors)"""
+
+    __slots__ = ()
+
+
+class Deb822NewlineAfterValueToken(Deb822SemanticallySignificantWhiteSpace):
+    """The newline after a value token.
+
+    If not followed by a continuation token, this also marks the end of the field.
+    """
+
+    __slots__ = ()
+
+    def __init__(self):
+        # type: () -> None
+        super().__init__("\n")
+
+
+class Deb822ValueContinuationToken(Deb822SemanticallySignificantWhiteSpace):
+    """The whitespace denoting a value spanning an additional line (the first space on a line)"""
+
+    __slots__ = ()
+
+
+class Deb822SpaceSeparatorToken(Deb822SemanticallySignificantWhiteSpace):
+    """Whitespace between values in a space list (e.g. "Architectures")"""
+
+    __slots__ = ()
+
+
+class Deb822ErrorToken(Deb822Token):
+    """Token that represents a syntactical error"""
+
+    __slots__ = ()
+
+    @property
+    def is_error(self):
+        # type: () -> bool
+        return True
+
+
+class Deb822CommentToken(Deb822Token):
+
+    __slots__ = ()
+
+    @property
+    def is_comment(self):
+        # type: () -> bool
+        return True
+
+
+class Deb822FieldNameToken(Deb822Token):
+
+    __slots__ = ()
+
+    def __init__(self, text):
+        # type: (str) -> None
+        if not isinstance(text, _strI):
+            text = _strI(sys.intern(text))
+        super().__init__(text)
+
+    @property
+    def text(self):
+        # type: () -> _strI
+        return cast("_strI", self._text)
+
+
+# The colon after the field name, parenthesis, etc.
+class Deb822SeparatorToken(Deb822Token):
+
+    __slots__ = ()
+
+
+class Deb822FieldSeparatorToken(Deb822Token):
+
+    __slots__ = ()
+
+    def __init__(self):
+        # type: () -> None
+        super().__init__(":")
+
+
+class Deb822CommaToken(Deb822SeparatorToken):
+    """Used by the comma-separated list value parsers to denote a comma between two value tokens."""
+
+    __slots__ = ()
+
+    def __init__(self):
+        # type: () -> None
+        super().__init__(",")
+
+
+class Deb822PipeToken(Deb822SeparatorToken):
+    """Used in some dependency fields as OR relation"""
+
+    __slots__ = ()
+
+    def __init__(self):
+        # type: () -> None
+        super().__init__("|")
+
+
+class Deb822ValueToken(Deb822Token):
+    """A field value can be split into multi "Deb822ValueToken"s (as well as separator tokens)"""
+
+    __slots__ = ()
+
+
+class Deb822ValueDependencyToken(Deb822Token):
+    """Package name, architecture name, a version number, or a profile name in a dependency field"""
+
+    __slots__ = ()
+
+
+class Deb822ValueDependencyVersionRelationOperatorToken(Deb822Token):
+
+    __slots__ = ()
+
+
+def tokenize_deb822_file(sequence, encoding="utf-8"):
+    # type: (Iterable[Union[str, bytes]], str) -> Iterable[Deb822Token]
+    """Tokenize a deb822 file
+
+    :param sequence: An iterable of lines (a file open for reading will do)
+    :param encoding: The encoding to use (this is here to support Deb822-like
+       APIs, new code should not use this parameter).
+    """
+    current_field_name = None
+    field_name_cache = {}  # type: Dict[str, _strI]
+
+    def _normalize_input(s):
+        # type: (Iterable[Union[str, bytes]]) -> Iterable[str]
+        for x in s:
+            if isinstance(x, bytes):
+                x = x.decode(encoding)
+            if not x.endswith("\n"):
+                # We always end on a newline because it makes a lot of code simpler.  The pain
+                # points relates to mutations that add content after the last field.  Sadly, these
+                # mutations can happen via adding fields, reordering fields, etc. and are too hard
+                # to track to make it worth it to support the special case that makes up missing
+                # a newline at the end of the file.
+                x += "\n"
+            yield x
+
+    text_stream = BufferingIterator(
+        _normalize_input(sequence)
+    )  # type: BufferingIterator[str]
+
+    for line in text_stream:
+        if line.isspace():
+            if current_field_name:
+                # Blank lines terminate fields
+                current_field_name = None
+
+            # If there are multiple whitespace-only lines, we combine them
+            # into one token.
+            r = list(text_stream.takewhile(str.isspace))
+            if r:
+                line += "".join(r)
+
+            # whitespace tokens are likely to have duplicate cases (like
+            # single newline tokens), so we intern the strings there.
+            yield Deb822WhitespaceToken(sys.intern(line))
+            continue
+
+        if line[0] == "#":
+            yield Deb822CommentToken(line)
+            continue
+
+        if line[0] in (" ", "\t"):
+            if current_field_name is not None:
+                # We emit a separate whitespace token for the newline as it makes some
+                # things easier later (see _build_value_line)
+                leading = sys.intern(line[0])
+                # Pull out the leading space and newline
+                line = line[1:-1]
+                yield Deb822ValueContinuationToken(leading)
+                yield Deb822ValueToken(line)
+                yield Deb822NewlineAfterValueToken()
+            else:
+                yield Deb822ErrorToken(line)
+            continue
+
+        field_line_match = _RE_FIELD_LINE.match(line)
+        if field_line_match:
+            # The line is a field, which means there is a bit to unpack
+            # - note that by definition, leading and trailing whitespace is insignificant
+            #   on the value part directly after the field separator
+            (field_name, _, space_before, value, space_after) = (
+                field_line_match.groups()
+            )
+
+            current_field_name = field_name_cache.get(field_name)
+
+            if value is None or value == "":
+                # If there is no value, then merge the two space elements into space_after
+                # as it makes it easier to handle the newline.
+                space_after = (
+                    space_before + space_after if space_after else space_before
+                )
+                space_before = ""
+
+            if space_after:
+                # We emit a separate whitespace token for the newline as it makes some
+                # things easier later (see _build_value_line)
+                if space_after.endswith("\n"):
+                    space_after = space_after[:-1]
+
+            if current_field_name is None:
+                field_name = sys.intern(field_name)
+                current_field_name = _strI(field_name)
+                field_name_cache[field_name] = current_field_name
+
+            # We use current_field_name from here as it is a _strI.
+            # Delete field_name to avoid accidentally using it and getting bugs
+            # that should not happen.
+            del field_name
+
+            yield Deb822FieldNameToken(current_field_name)
+            yield Deb822FieldSeparatorToken()
+            if space_before:
+                yield Deb822WhitespaceToken(sys.intern(space_before))
+            if value:
+                yield Deb822ValueToken(value)
+            if space_after:
+                yield Deb822WhitespaceToken(sys.intern(space_after))
+            yield Deb822NewlineAfterValueToken()
+        else:
+            yield Deb822ErrorToken(line)
+
+
+def _value_line_tokenizer(func):
+    # type: (Callable[[str], Iterable[Deb822Token]]) -> (Callable[[str], Iterable[Deb822Token]])
+    def impl(v):
+        # type: (str) -> Iterable[Deb822Token]
+        first_line = True
+        for no, line in enumerate(v.splitlines(keepends=True)):
+            assert not v.isspace() or no == 0
+            if line.startswith("#"):
+                yield Deb822CommentToken(line)
+                continue
+            has_newline = False
+            continuation_line_marker = None
+            if not first_line:
+                continuation_line_marker = line[0]
+                line = line[1:]
+            first_line = False
+            if line.endswith("\n"):
+                has_newline = True
+                line = line[:-1]
+            if continuation_line_marker is not None:
+                yield Deb822ValueContinuationToken(sys.intern(continuation_line_marker))
+            yield from func(line)
+            if has_newline:
+                yield Deb822NewlineAfterValueToken()
+
+    return impl
+
+
+@_value_line_tokenizer
+def whitespace_split_tokenizer(v):
+    # type: (str) -> Iterable[Deb822Token]
+    assert "\n" not in v
+    for match in _RE_WHITESPACE_SEPARATED_WORD_LIST.finditer(v):
+        space_before, word, space_after = match.groups()
+        if space_before:
+            yield Deb822SpaceSeparatorToken(sys.intern(space_before))
+        yield Deb822ValueToken(word)
+        if space_after:
+            yield Deb822SpaceSeparatorToken(sys.intern(space_after))
+
+
+@_value_line_tokenizer
+def comma_split_tokenizer(v):
+    # type: (str) -> Iterable[Deb822Token]
+    assert "\n" not in v
+    for match in _RE_COMMA_SEPARATED_WORD_LIST.finditer(v):
+        space_before_comma, comma, space_before_word, word, space_after_word = (
+            match.groups()
+        )
+        if space_before_comma:
+            yield Deb822WhitespaceToken(sys.intern(space_before_comma))
+        if comma:
+            yield Deb822CommaToken()
+        if space_before_word:
+            yield Deb822WhitespaceToken(sys.intern(space_before_word))
+        if word:
+            yield Deb822ValueToken(word)
+        if space_after_word:
+            yield Deb822WhitespaceToken(sys.intern(space_after_word))
diff --git a/src/debputy/lsp/vendoring/_deb822_repro/types.py b/src/debputy/lsp/vendoring/_deb822_repro/types.py
new file mode 100644
index 0000000..7b78024
--- /dev/null
+++ b/src/debputy/lsp/vendoring/_deb822_repro/types.py
@@ -0,0 +1,93 @@
+try:
+    from typing import TypeVar, Union, Tuple, List, Callable, Iterator, TYPE_CHECKING
+
+    if TYPE_CHECKING:
+        from .tokens import Deb822Token, Deb822FieldNameToken
+        from .parsing import (
+            Deb822Element,
+            Deb822CommentElement,
+            Deb822ParsedValueElement,
+        )
+        from .formatter import FormatterContentToken
+
+    TokenOrElement = Union["Deb822Element", "Deb822Token"]
+    TE = TypeVar("TE", bound=TokenOrElement)
+
+    # Used as a resulting element for "mapping" functions that map TE -> R (see _combine_parts)
+    R = TypeVar("R", bound="Deb822Element")
+
+    VE = TypeVar("VE", bound="Deb822Element")
+
+    ST = TypeVar("ST", bound="Deb822Token")
+
+    # Internal type for part of the paragraph key.  Used to facility _unpack_key.
+    ParagraphKeyBase = Union["Deb822FieldNameToken", str]
+
+    ParagraphKey = Union[ParagraphKeyBase, Tuple[str, int]]
+
+    Commentish = Union[List[str], "Deb822CommentElement"]
+
+    FormatterCallback = Callable[
+        [str, "FormatterContentToken", Iterator["FormatterContentToken"]],
+        Iterator[Union["FormatterContentToken", str]],
+    ]
+    try:
+        # Set __doc__ attributes if possible
+        TE.__doc__ = """
+        Generic "Token or Element" type
+        """
+        R.__doc__ = """
+        For internal usage in _deb822_repro
+        """
+        VE.__doc__ = """
+        Value type/element in a list interpretation of a field value
+        """
+        ST.__doc__ = """
+        Separator type/token in a list interpretation of a field value
+        """
+        ParagraphKeyBase.__doc__ = """
+        For internal usage in _deb822_repro
+        """
+        ParagraphKey.__doc__ = """
+        Anything accepted as a key for a paragraph field lookup.  The simple case being
+        a str. Alternative variants are mostly interesting for paragraphs with repeated
+        fields (to enable unambiguous lookups)
+        """
+        Commentish.__doc__ = """
+        Anything accepted as input for a Comment. The simple case is the list
+        of string (each element being a line of comment). The alternative format is
+        there for enable reuse of an existing element (e.g. to avoid "unpacking"
+        only to "re-pack" an existing comment element).
+        """
+        FormatterCallback.__doc__ = """\
+        Formatter callback used with the round-trip safe parser
+    
+        See debian._repro_deb822.formatter.format_field for details
+        """
+    except AttributeError:
+        # Python 3.5 does not allow update to the __doc__ attribute - ignore that
+        pass
+except ImportError:
+    pass
+
+
+class AmbiguousDeb822FieldKeyError(KeyError):
+    """Specialized version of KeyError to denote a valid but ambiguous field name
+
+    This exception occurs if:
+      * the field is accessed via a str on a configured view that does not automatically
+        resolve ambiguous field names (see Deb822ParagraphElement.configured_view), AND
+      * a concrete paragraph contents a repeated field (which is not valid in deb822
+        but the module supports parsing them)
+
+    Note that the default is to automatically resolve ambiguous fields. Accordingly
+    you will only see this exception if you have "opted in" on wanting to know that
+    the lookup was ambiguous.
+
+    The ambiguity can be resolved by using a tuple of (<field-name>, <filed-index>)
+    instead of <field-name>.
+    """
+
+
+class SyntaxOrParseError(ValueError):
+    """Specialized version of ValueError for syntax/parse errors."""
diff --git a/src/debputy/maintscript_snippet.py b/src/debputy/maintscript_snippet.py
new file mode 100644
index 0000000..ca81ca5
--- /dev/null
+++ b/src/debputy/maintscript_snippet.py
@@ -0,0 +1,184 @@
+import dataclasses
+from typing import Sequence, Optional, List, Literal, Iterable, Dict, Self
+
+from debputy.manifest_parser.base_types import DebputyDispatchableType
+from debputy.manifest_parser.util import AttributePath
+
+STD_CONTROL_SCRIPTS = frozenset(
+    {
+        "preinst",
+        "prerm",
+        "postinst",
+        "postrm",
+    }
+)
+UDEB_CONTROL_SCRIPTS = frozenset(
+    {
+        "postinst",
+        "menutest",
+        "isinstallable",
+    }
+)
+ALL_CONTROL_SCRIPTS = STD_CONTROL_SCRIPTS | UDEB_CONTROL_SCRIPTS | {"config"}
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class MaintscriptSnippet:
+    definition_source: str
+    snippet: str
+    snippet_order: Optional[Literal["service"]] = None
+
+    def script_content(self) -> str:
+        lines = [
+            f"# Snippet source: {self.definition_source}\n",
+            self.snippet,
+        ]
+        if not self.snippet.endswith("\n"):
+            lines.append("\n")
+        return "".join(lines)
+
+
+class MaintscriptSnippetContainer:
+    def __init__(self) -> None:
+        self._generic_snippets: List[MaintscriptSnippet] = []
+        self._snippets_by_order: Dict[Literal["service"], List[MaintscriptSnippet]] = {}
+
+    def copy(self) -> "MaintscriptSnippetContainer":
+        instance = self.__class__()
+        instance._generic_snippets = self._generic_snippets.copy()
+        instance._snippets_by_order = self._snippets_by_order.copy()
+        return instance
+
+    def append(self, maintscript_snippet: MaintscriptSnippet) -> None:
+        if maintscript_snippet.snippet_order is None:
+            self._generic_snippets.append(maintscript_snippet)
+        else:
+            if maintscript_snippet.snippet_order not in self._snippets_by_order:
+                self._snippets_by_order[maintscript_snippet.snippet_order] = []
+            self._snippets_by_order[maintscript_snippet.snippet_order].append(
+                maintscript_snippet
+            )
+
+    def has_content(self, snippet_order: Optional[Literal["service"]] = None) -> bool:
+        if snippet_order is None:
+            return bool(self._generic_snippets)
+        if snippet_order not in self._snippets_by_order:
+            return False
+        return bool(self._snippets_by_order[snippet_order])
+
+    def all_snippets(self) -> Iterable[MaintscriptSnippet]:
+        yield from self._generic_snippets
+        for snippets in self._snippets_by_order.values():
+            yield from snippets
+
+    def generate_snippet(
+        self,
+        tool_with_version: Optional[str] = None,
+        snippet_order: Optional[Literal["service"]] = None,
+        reverse: bool = False,
+    ) -> Optional[str]:
+        inner_content = ""
+        if snippet_order is None:
+            snippets = (
+                reversed(self._generic_snippets) if reverse else self._generic_snippets
+            )
+            inner_content = "".join(s.script_content() for s in snippets)
+        elif snippet_order in self._snippets_by_order:
+            snippets = self._snippets_by_order[snippet_order]
+            if reverse:
+                snippets = reversed(snippets)
+            inner_content = "".join(s.script_content() for s in snippets)
+
+        if not inner_content:
+            return None
+
+        if tool_with_version:
+            return (
+                f"# Automatically added by {tool_with_version}\n"
+                + inner_content
+                + "# End automatically added section"
+            )
+        return inner_content
+
+
+class DpkgMaintscriptHelperCommand(DebputyDispatchableType):
+    __slots__ = ("cmdline", "definition_source")
+
+    def __init__(self, cmdline: Sequence[str], definition_source: str):
+        self.cmdline = cmdline
+        self.definition_source = definition_source
+
+    @classmethod
+    def _finish_cmd(
+        cls,
+        definition_source: str,
+        cmdline: List[str],
+        prior_version: Optional[str],
+        owning_package: Optional[str],
+    ) -> Self:
+        if prior_version is not None:
+            cmdline.append(prior_version)
+        if owning_package is not None:
+            if prior_version is None:
+                # Empty is allowed according to `man dpkg-maintscript-helper`
+                cmdline.append("")
+            cmdline.append(owning_package)
+        return cls(
+            tuple(cmdline),
+            definition_source,
+        )
+
+    @classmethod
+    def rm_conffile(
+        cls,
+        definition_source: AttributePath,
+        conffile: str,
+        prior_version: Optional[str] = None,
+        owning_package: Optional[str] = None,
+    ) -> Self:
+        cmdline = ["rm_conffile", conffile]
+        return cls._finish_cmd(
+            definition_source.path, cmdline, prior_version, owning_package
+        )
+
+    @classmethod
+    def mv_conffile(
+        cls,
+        definition_source: AttributePath,
+        old_conffile: str,
+        new_confile: str,
+        prior_version: Optional[str] = None,
+        owning_package: Optional[str] = None,
+    ) -> Self:
+        cmdline = ["mv_conffile", old_conffile, new_confile]
+        return cls._finish_cmd(
+            definition_source.path, cmdline, prior_version, owning_package
+        )
+
+    @classmethod
+    def symlink_to_dir(
+        cls,
+        definition_source: AttributePath,
+        pathname: str,
+        old_target: str,
+        prior_version: Optional[str] = None,
+        owning_package: Optional[str] = None,
+    ) -> Self:
+        cmdline = ["symlink_to_dir", pathname, old_target]
+        return cls._finish_cmd(
+            definition_source.path, cmdline, prior_version, owning_package
+        )
+
+    @classmethod
+    def dir_to_symlink(
+        cls,
+        definition_source: AttributePath,
+        pathname: str,
+        new_target: str,
+        prior_version: Optional[str] = None,
+        owning_package: Optional[str] = None,
+    ) -> Self:
+        cmdline = ["dir_to_symlink", pathname, new_target]
+        return cls._finish_cmd(
+            definition_source.path, cmdline, prior_version, owning_package
+        )
diff --git a/src/debputy/manifest_conditions.py b/src/debputy/manifest_conditions.py
new file mode 100644
index 0000000..0f5c298
--- /dev/null
+++ b/src/debputy/manifest_conditions.py
@@ -0,0 +1,239 @@
+import dataclasses
+from enum import Enum
+from typing import List, Callable, Optional, Sequence
+
+from debian.debian_support import DpkgArchTable
+
+from debputy._deb_options_profiles import DebBuildOptionsAndProfiles
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.manifest_parser.base_types import DebputyDispatchableType
+from debputy.packages import BinaryPackage
+from debputy.substitution import Substitution
+from debputy.util import active_profiles_match
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ConditionContext:
+    binary_package: Optional[BinaryPackage]
+    build_env: DebBuildOptionsAndProfiles
+    substitution: Substitution
+    dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable
+    dpkg_arch_query_table: DpkgArchTable
+
+
+class ManifestCondition(DebputyDispatchableType):
+    __slots__ = ()
+
+    def describe(self) -> str:
+        raise NotImplementedError
+
+    def negated(self) -> "ManifestCondition":
+        return NegatedManifestCondition(self)
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        raise NotImplementedError
+
+    @classmethod
+    def _manifest_group(
+        cls,
+        match_type: "_ConditionGroupMatchType",
+        conditions: "Sequence[ManifestCondition]",
+    ) -> "ManifestCondition":
+        condition = conditions[0]
+        if (
+            isinstance(condition, ManifestConditionGroup)
+            and condition.match_type == match_type
+        ):
+            return condition.extend(conditions[1:])
+        return ManifestConditionGroup(match_type, conditions)
+
+    @classmethod
+    def any_of(cls, conditions: "Sequence[ManifestCondition]") -> "ManifestCondition":
+        return cls._manifest_group(_ConditionGroupMatchType.ANY_OF, conditions)
+
+    @classmethod
+    def all_of(cls, conditions: "Sequence[ManifestCondition]") -> "ManifestCondition":
+        return cls._manifest_group(_ConditionGroupMatchType.ALL_OF, conditions)
+
+    @classmethod
+    def is_cross_building(cls) -> "ManifestCondition":
+        return _IS_CROSS_BUILDING
+
+    @classmethod
+    def can_execute_compiled_binaries(cls) -> "ManifestCondition":
+        return _CAN_EXECUTE_COMPILED_BINARIES
+
+    @classmethod
+    def run_build_time_tests(cls) -> "ManifestCondition":
+        return _RUN_BUILD_TIME_TESTS
+
+
+class NegatedManifestCondition(ManifestCondition):
+    __slots__ = ("_condition",)
+
+    def __init__(self, condition: ManifestCondition) -> None:
+        self._condition = condition
+
+    def negated(self) -> "ManifestCondition":
+        return self._condition
+
+    def describe(self) -> str:
+        return f"not ({self._condition.describe()})"
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        return not self._condition.evaluate(context)
+
+
+class _ConditionGroupMatchType(Enum):
+    ANY_OF = (any, "At least one of: [{conditions}]")
+    ALL_OF = (all, "All of: [{conditions}]")
+
+    def describe(self, conditions: Sequence[ManifestCondition]) -> str:
+        return self.value[1].format(
+            conditions=", ".join(x.describe() for x in conditions)
+        )
+
+    def evaluate(
+        self, conditions: Sequence[ManifestCondition], context: ConditionContext
+    ) -> bool:
+        return self.value[0](c.evaluate(context) for c in conditions)
+
+
+class ManifestConditionGroup(ManifestCondition):
+    __slots__ = ("match_type", "_conditions")
+
+    def __init__(
+        self,
+        match_type: _ConditionGroupMatchType,
+        conditions: Sequence[ManifestCondition],
+    ) -> None:
+        self.match_type = match_type
+        self._conditions = conditions
+
+    def describe(self) -> str:
+        return self.match_type.describe(self._conditions)
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        return self.match_type.evaluate(self._conditions, context)
+
+    def extend(
+        self,
+        conditions: Sequence[ManifestCondition],
+    ) -> "ManifestConditionGroup":
+        combined = list(self._conditions)
+        combined.extend(conditions)
+        return ManifestConditionGroup(
+            self.match_type,
+            combined,
+        )
+
+
+class ArchMatchManifestConditionBase(ManifestCondition):
+    __slots__ = ("_arch_spec", "_is_negated")
+
+    def __init__(self, arch_spec: List[str], *, is_negated: bool = False) -> None:
+        self._arch_spec = arch_spec
+        self._is_negated = is_negated
+
+    def negated(self) -> "ManifestCondition":
+        return self.__class__(self._arch_spec, is_negated=not self._is_negated)
+
+
+class SourceContextArchMatchManifestCondition(ArchMatchManifestConditionBase):
+    def describe(self) -> str:
+        if self._is_negated:
+            return f'architecture (for source package) matches *none* of [{", ".join(self._arch_spec)}]'
+        return f'architecture (for source package) matches any of [{", ".join(self._arch_spec)}]'
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        arch = context.dpkg_architecture_variables.current_host_arch
+        match = context.dpkg_arch_query_table.architecture_is_concerned(
+            arch, self._arch_spec
+        )
+        return not match if self._is_negated else match
+
+
+class BinaryPackageContextArchMatchManifestCondition(ArchMatchManifestConditionBase):
+    def describe(self) -> str:
+        if self._is_negated:
+            return f'architecture (for binary package) matches *none* of [{", ".join(self._arch_spec)}]'
+        return f'architecture (for binary package) matches any of [{", ".join(self._arch_spec)}]'
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        binary_package = context.binary_package
+        if binary_package is None:
+            raise RuntimeError(
+                "Condition only applies in the context of a BinaryPackage, but was evaluated"
+                " without one"
+            )
+        arch = binary_package.resolved_architecture
+        match = context.dpkg_arch_query_table.architecture_is_concerned(
+            arch, self._arch_spec
+        )
+        return not match if self._is_negated else match
+
+
+class BuildProfileMatch(ManifestCondition):
+    __slots__ = ("_profile_spec", "_is_negated")
+
+    def __init__(self, profile_spec: str, *, is_negated: bool = False) -> None:
+        self._profile_spec = profile_spec
+        self._is_negated = is_negated
+
+    def negated(self) -> "ManifestCondition":
+        return self.__class__(self._profile_spec, is_negated=not self._is_negated)
+
+    def describe(self) -> str:
+        if self._is_negated:
+            return f"DEB_BUILD_PROFILES matches *none* of [{self._profile_spec}]"
+        return f"DEB_BUILD_PROFILES matches any of [{self._profile_spec}]"
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        match = active_profiles_match(
+            self._profile_spec, context.build_env.deb_build_profiles
+        )
+        return not match if self._is_negated else match
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class _SingletonCondition(ManifestCondition):
+    description: str
+    implementation: Callable[[ConditionContext], bool]
+
+    def describe(self) -> str:
+        return self.description
+
+    def evaluate(self, context: ConditionContext) -> bool:
+        return self.implementation(context)
+
+
+def _can_run_built_binaries(context: ConditionContext) -> bool:
+    if not context.dpkg_architecture_variables.is_cross_compiling:
+        return True
+    # User / Builder asserted that we could even though we are cross-compiling, so we have to assume it is true
+    return "crossbuildcanrunhostbinaries" in context.build_env.deb_build_options
+
+
+_IS_CROSS_BUILDING = _SingletonCondition(
+    "Cross Compiling (i.e., DEB_HOST_GNU_TYPE != DEB_BUILD_GNU_TYPE)",
+    lambda c: c.dpkg_architecture_variables.is_cross_compiling,
+)
+
+_CAN_EXECUTE_COMPILED_BINARIES = _SingletonCondition(
+    "Can run built binaries (natively or via transparent emulation)",
+    _can_run_built_binaries,
+)
+
+_RUN_BUILD_TIME_TESTS = _SingletonCondition(
+    "Run build time tests",
+    lambda c: "nocheck" not in c.build_env.deb_build_options,
+)
+
+_BUILD_DOCS_BDO = _SingletonCondition(
+    "Build docs (nodocs not in DEB_BUILD_OPTIONS)",
+    lambda c: "nodocs" not in c.build_env.deb_build_options,
+)
+
+
+del _SingletonCondition
+del _can_run_built_binaries
diff --git a/src/debputy/manifest_parser/__init__.py b/src/debputy/manifest_parser/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/manifest_parser/__init__.py
diff --git a/src/debputy/manifest_parser/base_types.py b/src/debputy/manifest_parser/base_types.py
new file mode 100644
index 0000000..865e320
--- /dev/null
+++ b/src/debputy/manifest_parser/base_types.py
@@ -0,0 +1,440 @@
+import dataclasses
+import os
+from functools import lru_cache
+from typing import (
+    TypedDict,
+    NotRequired,
+    Sequence,
+    Optional,
+    Union,
+    Literal,
+    Tuple,
+    Mapping,
+    Iterable,
+    TYPE_CHECKING,
+    Callable,
+    Type,
+    Generic,
+)
+
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.util import (
+    AttributePath,
+    _SymbolicModeSegment,
+    parse_symbolic_mode,
+)
+from debputy.path_matcher import MatchRule, ExactFileSystemPath
+from debputy.substitution import Substitution
+from debputy.types import S
+from debputy.util import _normalize_path, T
+
+if TYPE_CHECKING:
+    from debputy.manifest_conditions import ManifestCondition
+    from debputy.manifest_parser.parser_data import ParserContextData
+
+
+class DebputyParsedContent(TypedDict):
+    pass
+
+
+class DebputyDispatchableType:
+    __slots__ = ()
+
+
+class DebputyParsedContentStandardConditional(DebputyParsedContent):
+    when: NotRequired["ManifestCondition"]
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class OwnershipDefinition:
+    entity_name: str
+    entity_id: int
+
+
+@dataclasses.dataclass
+class TypeMapping(Generic[S, T]):
+    target_type: Type[T]
+    source_type: Type[S]
+    mapper: Callable[[S, AttributePath, Optional["ParserContextData"]], T]
+
+
+ROOT_DEFINITION = OwnershipDefinition("root", 0)
+
+
+BAD_OWNER_NAMES = {
+    "_apt",  # All things owned by _apt are generated by apt after installation
+    "nogroup",  # It is not supposed to own anything as it is an entity used for dropping permissions
+    "nobody",  # It is not supposed to own anything as it is an entity used for dropping permissions
+}
+BAD_OWNER_IDS = {
+    65534,  # ID of nobody / nogroup
+}
+
+
+def _parse_ownership(
+    v: Union[str, int],
+    attribute_path: AttributePath,
+) -> Tuple[Optional[str], Optional[int]]:
+    if isinstance(v, str) and ":" in v:
+        if v == ":":
+            raise ManifestParseException(
+                f'Invalid ownership value "{v}" at {attribute_path.path}: Ownership is redundant if it is ":"'
+                f" (blank name and blank id).  Please provide non-default values or remove the definition."
+            )
+        entity_name: Optional[str]
+        entity_id: Optional[int]
+        entity_name, entity_id_str = v.split(":")
+        if entity_name == "":
+            entity_name = None
+        if entity_id_str != "":
+            entity_id = int(entity_id_str)
+        else:
+            entity_id = None
+        return entity_name, entity_id
+
+    if isinstance(v, int):
+        return None, v
+    if v.isdigit():
+        raise ManifestParseException(
+            f'Invalid ownership value "{v}" at {attribute_path.path}: The provided value "{v}" is a string (implying'
+            " name lookup), but it contains an integer (implying id lookup).  Please use a regular int for id lookup"
+            f' (removing the quotes) or add a ":" in the end ("{v}:") as a disambiguation if you are *really* looking'
+            " for an entity with that name."
+        )
+    return v, None
+
+
+@lru_cache
+def _load_ownership_table_from_file(
+    name: Literal["passwd.master", "group.master"],
+) -> Tuple[Mapping[str, OwnershipDefinition], Mapping[int, OwnershipDefinition]]:
+    filename = os.path.join("/usr/share/base-passwd", name)
+    name_table = {}
+    uid_table = {}
+    for owner_def in _read_ownership_def_from_base_password_template(filename):
+        # Could happen if base-passwd template has two users with the same ID.  We assume this will not occur.
+        assert owner_def.entity_name not in name_table
+        assert owner_def.entity_id not in uid_table
+        name_table[owner_def.entity_name] = owner_def
+        uid_table[owner_def.entity_id] = owner_def
+
+    return name_table, uid_table
+
+
+def _read_ownership_def_from_base_password_template(
+    template_file: str,
+) -> Iterable[OwnershipDefinition]:
+    with open(template_file) as fd:
+        for line in fd:
+            entity_name, _star, entity_id, _remainder = line.split(":", 3)
+            if entity_id == "0" and entity_name == "root":
+                yield ROOT_DEFINITION
+            else:
+                yield OwnershipDefinition(entity_name, int(entity_id))
+
+
+class FileSystemMode:
+    @classmethod
+    def parse_filesystem_mode(
+        cls,
+        mode_raw: str,
+        attribute_path: AttributePath,
+    ) -> "FileSystemMode":
+        if mode_raw and mode_raw[0].isdigit():
+            return OctalMode.parse_filesystem_mode(mode_raw, attribute_path)
+        return SymbolicMode.parse_filesystem_mode(mode_raw, attribute_path)
+
+    def compute_mode(self, current_mode: int, is_dir: bool) -> int:
+        raise NotImplementedError
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class SymbolicMode(FileSystemMode):
+    provided_mode: str
+    segments: Sequence[_SymbolicModeSegment]
+
+    @classmethod
+    def parse_filesystem_mode(
+        cls,
+        mode_raw: str,
+        attribute_path: AttributePath,
+    ) -> "SymbolicMode":
+        segments = list(parse_symbolic_mode(mode_raw, attribute_path))
+        return SymbolicMode(mode_raw, segments)
+
+    def __str__(self) -> str:
+        return self.symbolic_mode()
+
+    @property
+    def is_symbolic_mode(self) -> bool:
+        return False
+
+    def symbolic_mode(self) -> str:
+        return self.provided_mode
+
+    def compute_mode(self, current_mode: int, is_dir: bool) -> int:
+        final_mode = current_mode
+        for segment in self.segments:
+            final_mode = segment.apply(final_mode, is_dir)
+        return final_mode
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class OctalMode(FileSystemMode):
+    octal_mode: int
+
+    @classmethod
+    def parse_filesystem_mode(
+        cls,
+        mode_raw: str,
+        attribute_path: AttributePath,
+    ) -> "FileSystemMode":
+        try:
+            mode = int(mode_raw, base=8)
+        except ValueError as e:
+            error_msg = 'An octal mode must be all digits between 0-7 (such as "644")'
+            raise ManifestParseException(
+                f"Cannot parse {attribute_path.path} as an octal mode: {error_msg}"
+            ) from e
+        return OctalMode(mode)
+
+    @property
+    def is_octal_mode(self) -> bool:
+        return True
+
+    def compute_mode(self, _current_mode: int, _is_dir: bool) -> int:
+        return self.octal_mode
+
+    def __str__(self) -> str:
+        return f"0{oct(self.octal_mode)[2:]}"
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class _StaticFileSystemOwnerGroup:
+    ownership_definition: OwnershipDefinition
+
+    @property
+    def entity_name(self) -> str:
+        return self.ownership_definition.entity_name
+
+    @property
+    def entity_id(self) -> int:
+        return self.ownership_definition.entity_id
+
+    @classmethod
+    def from_manifest_value(
+        cls,
+        raw_input: Union[str, int],
+        attribute_path: AttributePath,
+    ) -> "_StaticFileSystemOwnerGroup":
+        provided_name, provided_id = _parse_ownership(raw_input, attribute_path)
+        owner_def = cls._resolve(raw_input, provided_name, provided_id, attribute_path)
+        if (
+            owner_def.entity_name in BAD_OWNER_NAMES
+            or owner_def.entity_id in BAD_OWNER_IDS
+        ):
+            raise ManifestParseException(
+                f'Refusing to use "{raw_input}" as {cls._owner_type()} (defined at {attribute_path.path})'
+                f' as it resolves to "{owner_def.entity_name}:{owner_def.entity_id}" and no path should have this'
+                f" entity as {cls._owner_type()} as it is unsafe."
+            )
+        return cls(owner_def)
+
+    @classmethod
+    def _resolve(
+        cls,
+        raw_input: Union[str, int],
+        provided_name: Optional[str],
+        provided_id: Optional[int],
+        attribute_path: AttributePath,
+    ) -> OwnershipDefinition:
+        table_name = cls._ownership_table_name()
+        name_table, id_table = _load_ownership_table_from_file(table_name)
+        name_match = (
+            name_table.get(provided_name) if provided_name is not None else None
+        )
+        id_match = id_table.get(provided_id) if provided_id is not None else None
+        if id_match is None and name_match is None:
+            name_part = provided_name if provided_name is not None else "N/A"
+            id_part = provided_id if provided_id is not None else "N/A"
+            raise ManifestParseException(
+                f'Cannot resolve "{raw_input}" as {cls._owner_type()} (from {attribute_path.path}):'
+                f" It is not known to be a static {cls._owner_type()} from base-passwd."
+                f' The value was interpreted as name: "{name_part}" and id: {id_part}'
+            )
+        if id_match is None:
+            assert name_match is not None
+            return name_match
+        if name_match is None:
+            assert id_match is not None
+            return id_match
+        if provided_name != id_match.entity_name:
+            raise ManifestParseException(
+                f"Bad {cls._owner_type()} declaration: The id {provided_id} resolves to {id_match.entity_name}"
+                f" according to base-passwd, but the packager declared to should have been {provided_name}"
+                f" at {attribute_path.path}"
+            )
+        if provided_id != name_match.entity_id:
+            raise ManifestParseException(
+                f"Bad {cls._owner_type} declaration: The name {provided_name} resolves to {name_match.entity_id}"
+                f" according to base-passwd, but the packager declared to should have been {provided_id}"
+                f" at {attribute_path.path}"
+            )
+        return id_match
+
+    @classmethod
+    def _owner_type(cls) -> Literal["owner", "group"]:
+        raise NotImplementedError
+
+    @classmethod
+    def _ownership_table_name(cls) -> Literal["passwd.master", "group.master"]:
+        raise NotImplementedError
+
+
+class StaticFileSystemOwner(_StaticFileSystemOwnerGroup):
+    @classmethod
+    def _owner_type(cls) -> Literal["owner", "group"]:
+        return "owner"
+
+    @classmethod
+    def _ownership_table_name(cls) -> Literal["passwd.master", "group.master"]:
+        return "passwd.master"
+
+
+class StaticFileSystemGroup(_StaticFileSystemOwnerGroup):
+    @classmethod
+    def _owner_type(cls) -> Literal["owner", "group"]:
+        return "group"
+
+    @classmethod
+    def _ownership_table_name(cls) -> Literal["passwd.master", "group.master"]:
+        return "group.master"
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class SymlinkTarget:
+    raw_symlink_target: str
+    attribute_path: AttributePath
+    symlink_target: str
+
+    @classmethod
+    def parse_symlink_target(
+        cls,
+        raw_symlink_target: str,
+        attribute_path: AttributePath,
+        substitution: Substitution,
+    ) -> "SymlinkTarget":
+        return SymlinkTarget(
+            raw_symlink_target,
+            attribute_path,
+            substitution.substitute(raw_symlink_target, attribute_path.path),
+        )
+
+
+class FileSystemMatchRule:
+    @property
+    def raw_match_rule(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def attribute_path(self) -> AttributePath:
+        raise NotImplementedError
+
+    @property
+    def match_rule(self) -> MatchRule:
+        raise NotImplementedError
+
+    @classmethod
+    def parse_path_match(
+        cls,
+        raw_match_rule: str,
+        attribute_path: AttributePath,
+        parser_context: "ParserContextData",
+    ) -> "FileSystemMatchRule":
+        return cls.from_path_match(
+            raw_match_rule, attribute_path, parser_context.substitution
+        )
+
+    @classmethod
+    def from_path_match(
+        cls,
+        raw_match_rule: str,
+        attribute_path: AttributePath,
+        substitution: "Substitution",
+    ) -> "FileSystemMatchRule":
+        try:
+            mr = MatchRule.from_path_or_glob(
+                raw_match_rule,
+                attribute_path.path,
+                substitution=substitution,
+            )
+        except ValueError as e:
+            raise ManifestParseException(
+                f'Could not parse "{raw_match_rule}" (defined at {attribute_path.path})'
+                f" as a path or a glob: {e.args[0]}"
+            )
+
+        if isinstance(mr, ExactFileSystemPath):
+            return FileSystemExactMatchRule(
+                raw_match_rule,
+                attribute_path,
+                mr,
+            )
+        return FileSystemGenericMatch(
+            raw_match_rule,
+            attribute_path,
+            mr,
+        )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class FileSystemGenericMatch(FileSystemMatchRule):
+    raw_match_rule: str
+    attribute_path: AttributePath
+    match_rule: MatchRule
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class FileSystemExactMatchRule(FileSystemMatchRule):
+    raw_match_rule: str
+    attribute_path: AttributePath
+    match_rule: ExactFileSystemPath
+
+    @classmethod
+    def from_path_match(
+        cls,
+        raw_match_rule: str,
+        attribute_path: AttributePath,
+        substitution: "Substitution",
+    ) -> "FileSystemExactMatchRule":
+        try:
+            normalized = _normalize_path(raw_match_rule)
+        except ValueError as e:
+            raise ManifestParseException(
+                f'The path "{raw_match_rule}" provided in {attribute_path.path} should be relative to the'
+                ' root of the package and not use any ".." or "." segments.'
+            ) from e
+        if normalized == ".":
+            raise ManifestParseException(
+                f'The path "{raw_match_rule}" matches a file system root and that is not a valid match'
+                f' at "{attribute_path.path}". Please narrow the provided path.'
+            )
+        mr = ExactFileSystemPath(
+            substitution.substitute(normalized, attribute_path.path)
+        )
+        if mr.path.endswith("/") and issubclass(cls, FileSystemExactNonDirMatchRule):
+            raise ManifestParseException(
+                f'The path "{raw_match_rule}" at {attribute_path.path} resolved to'
+                f' "{mr.path}". Since the resolved path ends with a slash ("/"), this'
+                " means only a directory can match. However, this attribute should"
+                " match a *non*-directory"
+            )
+        return cls(
+            raw_match_rule,
+            attribute_path,
+            mr,
+        )
+
+
+class FileSystemExactNonDirMatchRule(FileSystemExactMatchRule):
+    pass
diff --git a/src/debputy/manifest_parser/declarative_parser.py b/src/debputy/manifest_parser/declarative_parser.py
new file mode 100644
index 0000000..32e93fe
--- /dev/null
+++ b/src/debputy/manifest_parser/declarative_parser.py
@@ -0,0 +1,1893 @@
+import collections
+import dataclasses
+import itertools
+from typing import (
+    Any,
+    Callable,
+    Tuple,
+    TypedDict,
+    Dict,
+    get_type_hints,
+    Annotated,
+    get_args,
+    get_origin,
+    TypeVar,
+    Generic,
+    FrozenSet,
+    Mapping,
+    Optional,
+    cast,
+    is_typeddict,
+    Type,
+    Union,
+    List,
+    Collection,
+    NotRequired,
+    Iterable,
+    Literal,
+    Sequence,
+)
+
+from debputy.manifest_parser.base_types import (
+    DebputyParsedContent,
+    StaticFileSystemOwner,
+    StaticFileSystemGroup,
+    FileSystemMode,
+    OctalMode,
+    SymlinkTarget,
+    FileSystemMatchRule,
+    FileSystemExactMatchRule,
+    FileSystemExactNonDirMatchRule,
+    DebputyDispatchableType,
+    TypeMapping,
+)
+from debputy.manifest_parser.exceptions import (
+    ManifestParseException,
+)
+from debputy.manifest_parser.mapper_code import (
+    type_mapper_str2package,
+    normalize_into_list,
+    wrap_into_list,
+    map_each_element,
+)
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath, unpack_type, find_annotation
+from debputy.packages import BinaryPackage
+from debputy.plugin.api.impl_types import (
+    DeclarativeInputParser,
+    TD,
+    _ALL_PACKAGE_TYPES,
+    resolve_package_type_selectors,
+)
+from debputy.plugin.api.spec import ParserDocumentation, PackageTypeSelector
+from debputy.util import _info, _warn, assume_not_none
+
+try:
+    from Levenshtein import distance
+except ImportError:
+    _WARN_ONCE = False
+
+    def _detect_possible_typo(
+        _key: str,
+        _value: object,
+        _manifest_attributes: Mapping[str, "AttributeDescription"],
+        _path: "AttributePath",
+    ) -> None:
+        global _WARN_ONCE
+        if not _WARN_ONCE:
+            _WARN_ONCE = True
+            _info(
+                "Install python3-levenshtein to have debputy try to detect typos in the manifest."
+            )
+
+else:
+
+    def _detect_possible_typo(
+        key: str,
+        value: object,
+        manifest_attributes: Mapping[str, "AttributeDescription"],
+        path: "AttributePath",
+    ) -> None:
+        k_len = len(key)
+        key_path = path[key]
+        matches: List[str] = []
+        current_match_strength = 0
+        for acceptable_key, attr in manifest_attributes.items():
+            if abs(k_len - len(acceptable_key)) > 2:
+                continue
+            d = distance(key, acceptable_key)
+            if d > 2:
+                continue
+            try:
+                attr.type_validator.ensure_type(value, key_path)
+            except ManifestParseException:
+                if attr.type_validator.base_type_match(value):
+                    match_strength = 1
+                else:
+                    match_strength = 0
+            else:
+                match_strength = 2
+
+            if match_strength < current_match_strength:
+                continue
+            if match_strength > current_match_strength:
+                current_match_strength = match_strength
+                matches.clear()
+            matches.append(acceptable_key)
+
+        if not matches:
+            return
+        ref = f'at "{path.path}"' if path else "at the manifest root level"
+        if len(matches) == 1:
+            possible_match = repr(matches[0])
+            _warn(
+                f'Possible typo: The key "{key}" {ref} should probably have been {possible_match}'
+            )
+        else:
+            matches.sort()
+            possible_matches = ", ".join(repr(a) for a in matches)
+            _warn(
+                f'Possible typo: The key "{key}" {ref} should probably have been one of {possible_matches}'
+            )
+
+
+SF = TypeVar("SF")
+T = TypeVar("T")
+S = TypeVar("S")
+
+
+_NONE_TYPE = type(None)
+
+
+# These must be able to appear in an "isinstance" check and must be builtin types.
+BASIC_SIMPLE_TYPES = {
+    str: "string",
+    int: "integer",
+    bool: "boolean",
+}
+
+
+class AttributeTypeHandler:
+    __slots__ = ("_description", "_ensure_type", "base_type", "mapper")
+
+    def __init__(
+        self,
+        description: str,
+        ensure_type: Callable[[Any, AttributePath], None],
+        *,
+        base_type: Optional[Type[Any]] = None,
+        mapper: Optional[
+            Callable[[Any, AttributePath, Optional["ParserContextData"]], Any]
+        ] = None,
+    ) -> None:
+        self._description = description
+        self._ensure_type = ensure_type
+        self.base_type = base_type
+        self.mapper = mapper
+
+    def describe_type(self) -> str:
+        return self._description
+
+    def ensure_type(self, obj: object, path: AttributePath) -> None:
+        self._ensure_type(obj, path)
+
+    def base_type_match(self, obj: object) -> bool:
+        base_type = self.base_type
+        return base_type is not None and isinstance(obj, base_type)
+
+    def map_type(
+        self,
+        value: Any,
+        path: AttributePath,
+        parser_context: Optional["ParserContextData"],
+    ) -> Any:
+        mapper = self.mapper
+        if mapper is not None:
+            return mapper(value, path, parser_context)
+        return value
+
+    def combine_mapper(
+        self,
+        mapper: Optional[
+            Callable[[Any, AttributePath, Optional["ParserContextData"]], Any]
+        ],
+    ) -> "AttributeTypeHandler":
+        if mapper is None:
+            return self
+        if self.mapper is not None:
+            m = self.mapper
+
+            def _combined_mapper(
+                value: Any,
+                path: AttributePath,
+                parser_context: Optional["ParserContextData"],
+            ) -> Any:
+                return mapper(m(value, path, parser_context), path, parser_context)
+
+        else:
+            _combined_mapper = mapper
+
+        return AttributeTypeHandler(
+            self._description,
+            self._ensure_type,
+            base_type=self.base_type,
+            mapper=_combined_mapper,
+        )
+
+
+@dataclasses.dataclass(slots=True)
+class AttributeDescription:
+    source_attribute_name: str
+    target_attribute: str
+    attribute_type: Any
+    type_validator: AttributeTypeHandler
+    annotations: Tuple[Any, ...]
+    conflicting_attributes: FrozenSet[str]
+    conditional_required: Optional["ConditionalRequired"]
+    parse_hints: Optional["DetectedDebputyParseHint"] = None
+    is_optional: bool = False
+
+
+def _extract_path_hint(v: Any, attribute_path: AttributePath) -> bool:
+    if attribute_path.path_hint is not None:
+        return True
+    if isinstance(v, str):
+        attribute_path.path_hint = v
+        return True
+    elif isinstance(v, list) and len(v) > 0 and isinstance(v[0], str):
+        attribute_path.path_hint = v[0]
+        return True
+    return False
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DeclarativeNonMappingInputParser(DeclarativeInputParser[TD], Generic[TD, SF]):
+    alt_form_parser: AttributeDescription
+    inline_reference_documentation: Optional[ParserDocumentation] = None
+
+    def parse_input(
+        self,
+        value: object,
+        path: AttributePath,
+        *,
+        parser_context: Optional["ParserContextData"] = None,
+    ) -> TD:
+        if self.reference_documentation_url is not None:
+            doc_ref = f" (Documentation: {self.reference_documentation_url})"
+        else:
+            doc_ref = ""
+
+        alt_form_parser = self.alt_form_parser
+        if value is None:
+            form_note = f" The value must have type: {alt_form_parser.type_validator.describe_type()}"
+            if self.reference_documentation_url is not None:
+                doc_ref = f" Please see {self.reference_documentation_url} for the documentation."
+            raise ManifestParseException(
+                f"The attribute {path.path} was missing a value. {form_note}{doc_ref}"
+            )
+        _extract_path_hint(value, path)
+        alt_form_parser.type_validator.ensure_type(value, path)
+        attribute = alt_form_parser.target_attribute
+        alias_mapping = {
+            attribute: ("", None),
+        }
+        v = alt_form_parser.type_validator.map_type(value, path, parser_context)
+        path.alias_mapping = alias_mapping
+        return cast("TD", {attribute: v})
+
+
+@dataclasses.dataclass(slots=True)
+class DeclarativeMappingInputParser(DeclarativeInputParser[TD], Generic[TD, SF]):
+    input_time_required_parameters: FrozenSet[str]
+    all_parameters: FrozenSet[str]
+    manifest_attributes: Mapping[str, "AttributeDescription"]
+    source_attributes: Mapping[str, "AttributeDescription"]
+    at_least_one_of: FrozenSet[FrozenSet[str]]
+    alt_form_parser: Optional[AttributeDescription]
+    mutually_exclusive_attributes: FrozenSet[FrozenSet[str]] = frozenset()
+    _per_attribute_conflicts_cache: Optional[Mapping[str, FrozenSet[str]]] = None
+    inline_reference_documentation: Optional[ParserDocumentation] = None
+    path_hint_source_attributes: Sequence[str] = tuple()
+
+    def parse_input(
+        self,
+        value: object,
+        path: AttributePath,
+        *,
+        parser_context: Optional["ParserContextData"] = None,
+    ) -> TD:
+        if self.reference_documentation_url is not None:
+            doc_ref = f" (Documentation: {self.reference_documentation_url})"
+        else:
+            doc_ref = ""
+        if value is None:
+            form_note = " The attribute must be a mapping."
+            if self.alt_form_parser is not None:
+                form_note = (
+                    " The attribute can be a mapping or a non-mapping format"
+                    ' (usually, "non-mapping format" means a string or a list of strings).'
+                )
+            if self.reference_documentation_url is not None:
+                doc_ref = f" Please see {self.reference_documentation_url} for the documentation."
+            raise ManifestParseException(
+                f"The attribute {path.path} was missing a value. {form_note}{doc_ref}"
+            )
+        if not isinstance(value, dict):
+            alt_form_parser = self.alt_form_parser
+            if alt_form_parser is None:
+                raise ManifestParseException(
+                    f"The attribute {path.path} must be a mapping.{doc_ref}"
+                )
+            _extract_path_hint(value, path)
+            alt_form_parser.type_validator.ensure_type(value, path)
+            assert (
+                value is not None
+            ), "The alternative form was None, but the parser should have rejected None earlier."
+            attribute = alt_form_parser.target_attribute
+            alias_mapping = {
+                attribute: ("", None),
+            }
+            v = alt_form_parser.type_validator.map_type(value, path, parser_context)
+            path.alias_mapping = alias_mapping
+            return cast("TD", {attribute: v})
+
+        unknown_keys = value.keys() - self.all_parameters
+        if unknown_keys:
+            for k in unknown_keys:
+                if isinstance(k, str):
+                    _detect_possible_typo(k, value[k], self.manifest_attributes, path)
+            unused_keys = self.all_parameters - value.keys()
+            if unused_keys:
+                k = ", ".join(unused_keys)
+                raise ManifestParseException(
+                    f'Unknown keys "{unknown_keys}" at {path.path}".  Keys that could be used here are: {k}.{doc_ref}'
+                )
+            raise ManifestParseException(
+                f'Unknown keys "{unknown_keys}" at {path.path}".  Please remove them.{doc_ref}'
+            )
+        missing_keys = self.input_time_required_parameters - value.keys()
+        if missing_keys:
+            required = ", ".join(repr(k) for k in sorted(missing_keys))
+            raise ManifestParseException(
+                f"The following keys were required but not present at {path.path}: {required}{doc_ref}"
+            )
+        for maybe_required in self.all_parameters - value.keys():
+            attr = self.manifest_attributes[maybe_required]
+            assert attr.conditional_required is None or parser_context is not None
+            if (
+                attr.conditional_required is not None
+                and attr.conditional_required.condition_applies(
+                    assume_not_none(parser_context)
+                )
+            ):
+                reason = attr.conditional_required.reason
+                raise ManifestParseException(
+                    f'Missing the *conditionally* required attribute "{maybe_required}" at {path.path}. {reason}{doc_ref}'
+                )
+        for keyset in self.at_least_one_of:
+            matched_keys = value.keys() & keyset
+            if not matched_keys:
+                conditionally_required = ", ".join(repr(k) for k in sorted(keyset))
+                raise ManifestParseException(
+                    f"At least one of the following keys must be present at {path.path}:"
+                    f" {conditionally_required}{doc_ref}"
+                )
+        for group in self.mutually_exclusive_attributes:
+            matched = value.keys() & group
+            if len(matched) > 1:
+                ck = ", ".join(repr(k) for k in sorted(matched))
+                raise ManifestParseException(
+                    f"Could not parse {path.path}: The following attributes are"
+                    f" mutually exclusive: {ck}{doc_ref}"
+                )
+        result = {}
+        per_attribute_conflicts = self._per_attribute_conflicts()
+        alias_mapping = {}
+        for path_hint_source_attributes in self.path_hint_source_attributes:
+            v = value.get(path_hint_source_attributes)
+            if v is not None and _extract_path_hint(v, path):
+                break
+        for k, v in value.items():
+            attr = self.manifest_attributes[k]
+            matched = value.keys() & per_attribute_conflicts[k]
+            if matched:
+                ck = ", ".join(repr(k) for k in sorted(matched))
+                raise ManifestParseException(
+                    f'The attribute "{k}" at {path.path} cannot be used with the following'
+                    f" attributes: {ck}{doc_ref}"
+                )
+            nk = attr.target_attribute
+            key_path = path[k]
+            attr.type_validator.ensure_type(v, key_path)
+            if v is None:
+                continue
+            if k != nk:
+                alias_mapping[nk] = k, None
+            v = attr.type_validator.map_type(v, key_path, parser_context)
+            result[nk] = v
+        if alias_mapping:
+            path.alias_mapping = alias_mapping
+        return cast("TD", result)
+
+    def _per_attribute_conflicts(self) -> Mapping[str, FrozenSet[str]]:
+        conflicts = self._per_attribute_conflicts_cache
+        if conflicts is not None:
+            return conflicts
+        attrs = self.source_attributes
+        conflicts = {
+            a.source_attribute_name: frozenset(
+                attrs[ca].source_attribute_name for ca in a.conflicting_attributes
+            )
+            for a in attrs.values()
+        }
+        self._per_attribute_conflicts_cache = conflicts
+        return self._per_attribute_conflicts_cache
+
+
+class DebputyParseHint:
+    @classmethod
+    def target_attribute(cls, target_attribute: str) -> "DebputyParseHint":
+        """Define this source attribute to have a different target attribute name
+
+        As an example:
+
+            >>> class SourceType(TypedDict):
+            ...     source: Annotated[NotRequired[str], DebputyParseHint.target_attribute("sources")]
+            ...     sources: NotRequired[List[str]]
+            >>> class TargetType(TypedDict):
+            ...     sources: List[str]
+            >>> pg = ParserGenerator()
+            >>> parser = pg.parser_from_typed_dict(TargetType, source_content=SourceType)
+
+        In this example, the user can provide either `source` or `sources` and the parser will
+        map them to the `sources` attribute in the `TargetType`.  Note this example relies on
+        the builtin mapping of `str` to `List[str]` to align the types between `source` (from
+        SourceType) and `sources` (from TargetType).
+
+        The following rules apply:
+
+         * All source attributes that map to the same target attribute will be mutually exclusive
+           (that is, the user cannot give `source` *and* `sources` as input).
+         * When the target attribute is required, the source attributes are conditionally
+           mandatory requiring the user to provide exactly one of them.
+         * When multiple source attributes point to a single target attribute, none of the source
+           attributes can be Required.
+         * The annotation can only be used for the source type specification and the source type
+           specification must be different from the target type specification.
+
+        The `target_attribute` annotation can be used without having multiple source attributes. This
+        can be useful if the source attribute name is not valid as a python variable identifier to
+        rename it to a valid python identifier.
+
+        :param target_attribute: The attribute name in the target content
+        :return: The annotation.
+        """
+        return TargetAttribute(target_attribute)
+
+    @classmethod
+    def conflicts_with_source_attributes(
+        cls,
+        *conflicting_source_attributes: str,
+    ) -> "DebputyParseHint":
+        """Declare a conflict with one or more source attributes
+
+        Example:
+
+            >>> class SourceType(TypedDict):
+            ...     source: Annotated[NotRequired[str], DebputyParseHint.target_attribute("sources")]
+            ...     sources: NotRequired[List[str]]
+            ...     into_dir: NotRequired[str]
+            ...     renamed_to: Annotated[
+            ...         NotRequired[str],
+            ...         DebputyParseHint.conflicts_with_source_attributes("sources", "into_dir")
+            ... ]
+            >>> class TargetType(TypedDict):
+            ...     sources: List[str]
+            ...     into_dir: NotRequired[str]
+            ...     renamed_to: NotRequired[str]
+            >>> pg = ParserGenerator()
+            >>> parser = pg.parser_from_typed_dict(TargetType, source_content=SourceType)
+
+        In this example, if the user was to provide `renamed_to` with `sources` or `into_dir` the parser would report
+        an error. However, the parser will allow `renamed_to` with `source` as the conflict is considered only for
+        the input source. That is, it is irrelevant that `sources` and `source´ happens to "map" to the same target
+        attribute.
+
+        The following rules apply:
+          * It is not possible for a target attribute to declare conflicts unless the target type spec is reused as
+            source type spec.
+          * All attributes involved in a conflict must be NotRequired.  If any of the attributes are Required, then
+            the parser generator will reject the input.
+          * All attributes listed in the conflict must be valid attributes in the source type spec.
+
+        Note you do not have to specify conflicts between two attributes with the same target attribute name.  The
+         `target_attribute` annotation will handle that for you.
+
+        :param conflicting_source_attributes: All source attributes that cannot be used with this attribute.
+        :return: The annotation.
+        """
+        if len(conflicting_source_attributes) < 1:
+            raise ValueError(
+                "DebputyParseHint.conflicts_with_source_attributes requires at least one attribute as input"
+            )
+        return ConflictWithSourceAttribute(frozenset(conflicting_source_attributes))
+
+    @classmethod
+    def required_when_single_binary(
+        cls,
+        *,
+        package_type: PackageTypeSelector = _ALL_PACKAGE_TYPES,
+    ) -> "DebputyParseHint":
+        """Declare a source attribute as required when the source package produces exactly one binary package
+
+        The attribute in question must always be declared as `NotRequired` in the TypedDict and this condition
+        can only be used for source attributes.
+        """
+        resolved_package_types = resolve_package_type_selectors(package_type)
+        reason = "The field is required for source packages producing exactly one binary package"
+        if resolved_package_types != _ALL_PACKAGE_TYPES:
+            types = ", ".join(sorted(resolved_package_types))
+            reason += f" of type {types}"
+            return ConditionalRequired(
+                reason,
+                lambda c: len(
+                    [
+                        p
+                        for p in c.binary_packages.values()
+                        if p.package_type in package_type
+                    ]
+                )
+                == 1,
+            )
+        return ConditionalRequired(
+            reason,
+            lambda c: c.is_single_binary_package,
+        )
+
+    @classmethod
+    def required_when_multi_binary(
+        cls,
+        *,
+        package_type: PackageTypeSelector = _ALL_PACKAGE_TYPES,
+    ) -> "DebputyParseHint":
+        """Declare a source attribute as required when the source package produces two or more binary package
+
+        The attribute in question must always be declared as `NotRequired` in the TypedDict and this condition
+        can only be used for source attributes.
+        """
+        resolved_package_types = resolve_package_type_selectors(package_type)
+        reason = "The field is required for source packages producing two or more binary packages"
+        if resolved_package_types != _ALL_PACKAGE_TYPES:
+            types = ", ".join(sorted(resolved_package_types))
+            reason = (
+                "The field is required for source packages producing not producing exactly one binary packages"
+                f" of type {types}"
+            )
+            return ConditionalRequired(
+                reason,
+                lambda c: len(
+                    [
+                        p
+                        for p in c.binary_packages.values()
+                        if p.package_type in package_type
+                    ]
+                )
+                != 1,
+            )
+        return ConditionalRequired(
+            reason,
+            lambda c: not c.is_single_binary_package,
+        )
+
+    @classmethod
+    def manifest_attribute(cls, attribute: str) -> "DebputyParseHint":
+        """Declare what the attribute name (as written in the manifest) should be
+
+        By default, debputy will do an attribute normalizing that will take valid python identifiers such
+        as `dest_dir` and remap it to the manifest variant (such as `dest-dir`) automatically.  If you have
+        a special case, where this built-in normalization is insufficient or the python name is considerably
+        different from what the user would write in the manifest, you can use this parse hint to set the
+        name that the user would have to write in the manifest for this attribute.
+
+            >>> class SourceType(TypedDict):
+            ...     source: List[FileSystemMatchRule]
+            ...     # Use "as" in the manifest because "as_" was not pretty enough
+            ...     install_as: Annotated[NotRequired[FileSystemExactMatchRule], DebputyParseHint.manifest_attribute("as")]
+
+        In this example, we use the parse hint to use "as" as the name in the manifest, because we cannot
+        use "as" a valid python identifier (it is a keyword).  While debputy would map `as_` to `as` for us,
+        we have chosen to use `install_as` as a python identifier.
+        """
+        return ManifestAttribute(attribute)
+
+    @classmethod
+    def not_path_error_hint(cls) -> "DebputyParseHint":
+        """Mark this attribute as not a "path hint" when it comes to reporting errors
+
+        By default, `debputy` will pick up attributes that uses path names (FileSystemMatchRule) as
+        candidates for parse error hints (the little "<Search for: VALUE>" in error messages).
+
+        Most rules only have one active path-based attribute and paths tends to be unique enough
+        that it helps people spot the issue faster. However, in rare cases, you can have multiple
+        attributes that fit the bill. In this case, this hint can be used to "hide" the suboptimal
+        choice. As an example:
+
+            >>> class SourceType(TypedDict):
+            ...     source: List[FileSystemMatchRule]
+            ...     install_as: Annotated[NotRequired[FileSystemExactMatchRule], DebputyParseHint.not_path_error_hint()]
+
+        In this case, without the hint, `debputy` might pick up `install_as` as the attribute to
+        use as hint for error reporting. However, here we have decided that we never want `install_as`
+        leaving `source` as the only option.
+
+        Generally, this type hint must be placed on the **source** format. Any source attribute matching
+        the parsed format will be ignored.
+
+        Mind the assymmetry: The annotation is placed in the **source** format while `debputy` looks at
+        the type of the target attribute to determine if it counts as path.
+        """
+        return NOT_PATH_HINT
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class TargetAttribute(DebputyParseHint):
+    attribute: str
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ConflictWithSourceAttribute(DebputyParseHint):
+    conflicting_attributes: FrozenSet[str]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ConditionalRequired(DebputyParseHint):
+    reason: str
+    condition: Callable[["ParserContextData"], bool]
+
+    def condition_applies(self, context: "ParserContextData") -> bool:
+        return self.condition(context)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ManifestAttribute(DebputyParseHint):
+    attribute: str
+
+
+class NotPathHint(DebputyParseHint):
+    pass
+
+
+NOT_PATH_HINT = NotPathHint()
+
+
+def _is_path_attribute_candidate(
+    source_attribute: AttributeDescription, target_attribute: AttributeDescription
+) -> bool:
+    if (
+        source_attribute.parse_hints
+        and not source_attribute.parse_hints.applicable_as_path_hint
+    ):
+        return False
+    target_type = target_attribute.attribute_type
+    _, origin, args = unpack_type(target_type, False)
+    match_type = target_type
+    if origin == list:
+        match_type = args[0]
+    return isinstance(match_type, type) and issubclass(match_type, FileSystemMatchRule)
+
+
+class ParserGenerator:
+    def __init__(self) -> None:
+        self._registered_types: Dict[Any, TypeMapping[Any, Any]] = {}
+
+    def register_mapped_type(self, mapped_type: TypeMapping) -> None:
+        existing = self._registered_types.get(mapped_type.target_type)
+        if existing is not None:
+            raise ValueError(f"The type {existing} is already registered")
+        self._registered_types[mapped_type.target_type] = mapped_type
+
+    def discard_mapped_type(self, mapped_type: Type[T]) -> None:
+        del self._registered_types[mapped_type]
+
+    def parser_from_typed_dict(
+        self,
+        parsed_content: Type[TD],
+        *,
+        source_content: Optional[SF] = None,
+        allow_optional: bool = False,
+        inline_reference_documentation: Optional[ParserDocumentation] = None,
+    ) -> DeclarativeInputParser[TD]:
+        """Derive a parser from a TypedDict
+
+        Generates a parser for a segment of the manifest (think the `install-docs` snippet) from a TypedDict
+        or two that are used as a description.
+
+        In its most simple use-case, the caller provides a TypedDict of the expected attributed along with
+        their types. As an example:
+
+          >>> class InstallDocsRule(DebputyParsedContent):
+          ...     sources: List[str]
+          ...     into: List[str]
+          >>> pg = ParserGenerator()
+          >>> simple_parser = pg.parser_from_typed_dict(InstallDocsRule)
+
+        This will create a parser that would be able to interpret something like:
+
+        ```yaml
+           install-docs:
+             sources: ["docs/*"]
+             into: ["my-pkg"]
+        ```
+
+        While this is sufficient for programmers, it is a bit ridig for the packager writing the manifest.  Therefore,
+        you can also provide a TypedDict descriping the input, enabling more flexibility:
+
+          >>> class InstallDocsRule(DebputyParsedContent):
+          ...     sources: List[str]
+          ...     into: List[str]
+          >>> class InputDocsRuleInputFormat(TypedDict):
+          ...     source: NotRequired[Annotated[str, DebputyParseHint.target_attribute("sources")]]
+          ...     sources: NotRequired[List[str]]
+          ...     into: Union[str, List[str]]
+          >>> pg = ParserGenerator()
+          >>> flexible_parser = pg.parser_from_typed_dict(
+          ...    InstallDocsRule,
+          ...    source_content=InputDocsRuleInputFormat,
+          ... )
+
+        In this case, the `sources` field can either come from a single `source` in the manifest (which must be a string)
+        or `sources` (which must be a list of strings). The parser also ensures that only one of `source` or `sources`
+        is used to ensure the input is not ambigious. For the `into` parameter, the parser will accept it being a str
+        or a list of strings.  Regardless of how the input was provided, the parser will normalize the input such that
+        both `sources` and `into` in the result is a list of strings.  As an example, this parser can accept
+        both the previous input but also the following input:
+
+        ```yaml
+           install-docs:
+             source: "docs/*"
+             into: "my-pkg"
+        ```
+
+        The `source` and `into` attributes are then normalized to lists as if the user had written them as lists
+        with a single string in them. As noted above, the name of the `source` attribute will also be normalized
+        while parsing.
+
+        In the cases where only one field is required by the user, it can sometimes make sense to allow a non-dict
+        as part of the input.  Example:
+
+          >>> class DiscardRule(DebputyParsedContent):
+          ...     paths: List[str]
+          >>> class DiscardRuleInputDictFormat(TypedDict):
+          ...     path: NotRequired[Annotated[str, DebputyParseHint.target_attribute("paths")]]
+          ...     paths: NotRequired[List[str]]
+          >>> # This format relies on DiscardRule having exactly one Required attribute
+          >>> DiscardRuleInputWithAltFormat = Union[
+          ...    DiscardRuleInputDictFormat,
+          ...    str,
+          ...    List[str],
+          ... ]
+          >>> pg = ParserGenerator()
+          >>> flexible_parser = pg.parser_from_typed_dict(
+          ...    DiscardRule,
+          ...    source_content=DiscardRuleInputWithAltFormat,
+          ... )
+
+
+        Supported types:
+          * `List` - must have a fixed type argument (such as `List[str]`)
+          * `str`
+          * `int`
+          * `BinaryPackage` - When provided (or required), the user must provide a package name listed
+                              in the debian/control file. The code receives the BinaryPackage instance
+                              matching that input.
+          * `FileSystemMode` - When provided (or required), the user must provide a file system mode in any
+                               format that `debputy' provides (such as `0644` or `a=rw,go=rw`).
+          * `FileSystemOwner` - When provided (or required), the user must a file system owner that is
+                                available statically on all Debian systems (must be in `base-passwd`).
+                                The user has multiple options for how to specify it (either via name or id).
+          * `FileSystemGroup` - When provided (or required), the user must a file system group that is
+                                available statically on all Debian systems (must be in `base-passwd`).
+                                The user has multiple options for how to specify it (either via name or id).
+          * `ManifestCondition` - When provided (or required), the user must specify a conditional rule to apply.
+                                  Usually, it is better to extend `DebputyParsedContentStandardConditional`, which
+                                  provides the `debputy' default `when` parameter for conditionals.
+
+        Supported special type-like parameters:
+
+          * `Required` / `NotRequired` to mark a field as `Required` or `NotRequired`. Must be provided at the
+             outermost level.  Cannot vary between `parsed_content` and `source_content`.
+          * `Annotated`. Accepted at the outermost level (inside Required/NotRequired) but ignored at the moment.
+          * `Union`. Must be the outermost level (inside `Annotated` or/and `Required`/`NotRequired` if these are present).
+            Automapping (see below) is restricted to two members in the Union.
+
+        Notable non-supported types:
+          * `Mapping` and all variants therefore (such as `dict`). In the future, nested `TypedDict`s may be allowed.
+          * `Optional` (or `Union[..., None]`): Use `NotRequired` for optional fields.
+
+        Automatic mapping rules from `source_content` to `parsed_content`:
+          - `Union[T, List[T]]` can be narrowed automatically to `List[T]`.  Transformation is basically:
+            `lambda value: value if isinstance(value, list) else [value]`
+          - `T` can be mapped automatically to `List[T]`, Transformation being: `lambda value: [value]`
+
+        Additionally, types can be annotated (`Annotated[str, ...]`) with `DebputyParseHint`s.  Check its classmethod
+        for concrete features that may be useful to you.
+
+        :param parsed_content: A DebputyParsedContent / TypedDict describing the desired model of the input once parsed.
+          (DebputyParsedContent is a TypedDict subclass that work around some inadequate type checkers)
+        :param source_content: Optionally, a TypedDict describing the input allowed by the user.  This can be useful
+          to describe more variations than in `parsed_content` that the parser will normalize for you. If omitted,
+          the parsed_content is also considered the source_content (which affects what annotations are allowed in it).
+          Note you should never pass the parsed_content as source_content directly.
+        :param allow_optional: In rare cases, you want to support explicitly provided vs. optional.  In this case, you
+          should set this to True.  Though, in 99.9% of all cases, you want `NotRequired` rather than `Optional` (and
+          can keep this False).
+        :param inline_reference_documentation: Optionally, programmatic documentation
+        :return: An input parser capable of reading input matching the TypedDict(s) used as reference.
+        """
+        if not is_typeddict(parsed_content):
+            raise ValueError(
+                f"Unsupported parsed_content descriptor: {parsed_content.__qualname__}."
+                ' Only "TypedDict"-based types supported.'
+            )
+        if source_content is parsed_content:
+            raise ValueError(
+                "Do not provide source_content if it is the same as parsed_content"
+            )
+
+        target_attributes = self._parse_types(
+            parsed_content,
+            allow_source_attribute_annotations=source_content is None,
+            forbid_optional=not allow_optional,
+        )
+        required_target_parameters = frozenset(parsed_content.__required_keys__)
+        parsed_alt_form = None
+        non_mapping_source_only = False
+
+        if source_content is not None:
+            default_target_attribute = None
+            if len(required_target_parameters) == 1:
+                default_target_attribute = next(iter(required_target_parameters))
+
+            source_typed_dict, alt_source_forms = _extract_typed_dict(
+                source_content,
+                default_target_attribute,
+            )
+            if alt_source_forms:
+                parsed_alt_form = self._parse_alt_form(
+                    alt_source_forms,
+                    default_target_attribute,
+                )
+            if source_typed_dict is not None:
+                source_content_attributes = self._parse_types(
+                    source_typed_dict,
+                    allow_target_attribute_annotation=True,
+                    allow_source_attribute_annotations=True,
+                    forbid_optional=not allow_optional,
+                )
+                source_content_parameter = "source_content"
+                source_and_parsed_differs = True
+            else:
+                source_typed_dict = parsed_content
+                source_content_attributes = target_attributes
+                source_content_parameter = "parsed_content"
+                source_and_parsed_differs = True
+                non_mapping_source_only = True
+        else:
+            source_typed_dict = parsed_content
+            source_content_attributes = target_attributes
+            source_content_parameter = "parsed_content"
+            source_and_parsed_differs = False
+
+        sources = collections.defaultdict(set)
+        seen_targets = set()
+        seen_source_names: Dict[str, str] = {}
+        source_attributes: Dict[str, AttributeDescription] = {}
+        path_hint_source_attributes = []
+
+        for k in source_content_attributes:
+            ia = source_content_attributes[k]
+
+            ta = (
+                target_attributes.get(ia.target_attribute)
+                if source_and_parsed_differs
+                else ia
+            )
+            if ta is None:
+                # Error message would be wrong if this assertion is false.
+                assert source_and_parsed_differs
+                raise ValueError(
+                    f'The attribute "{k}" from the "source_content" parameter should have mapped'
+                    f' to "{ia.target_attribute}", but that parameter does not exist in "parsed_content"'
+                )
+            if _is_path_attribute_candidate(ia, ta):
+                path_hint_source_attributes.append(ia.source_attribute_name)
+            existing_source_name = seen_source_names.get(ia.source_attribute_name)
+            if existing_source_name:
+                raise ValueError(
+                    f'The attribute "{k}" and "{existing_source_name}" both share the source name'
+                    f' "{ia.source_attribute_name}". Please change the {source_content_parameter} parameter,'
+                    f' so only one attribute use "{ia.source_attribute_name}".'
+                )
+            seen_source_names[ia.source_attribute_name] = k
+            seen_targets.add(ta.target_attribute)
+            sources[ia.target_attribute].add(k)
+            if source_and_parsed_differs:
+                bridge_mapper = self._type_normalize(
+                    k, ia.attribute_type, ta.attribute_type, False
+                )
+                ia.type_validator = ia.type_validator.combine_mapper(bridge_mapper)
+            source_attributes[k] = ia
+
+        def _as_attr_names(td_name: Iterable[str]) -> FrozenSet[str]:
+            return frozenset(
+                source_content_attributes[a].source_attribute_name for a in td_name
+            )
+
+        _check_attributes(
+            parsed_content,
+            source_typed_dict,
+            source_content_attributes,
+            sources,
+        )
+
+        at_least_one_of = frozenset(
+            _as_attr_names(g)
+            for k, g in sources.items()
+            if len(g) > 1 and k in required_target_parameters
+        )
+
+        if source_and_parsed_differs and seen_targets != target_attributes.keys():
+            missing = ", ".join(
+                repr(k) for k in (target_attributes.keys() - seen_targets)
+            )
+            raise ValueError(
+                'The following attributes in "parsed_content" did not have a source field in "source_content":'
+                f" {missing}"
+            )
+        all_mutually_exclusive_fields = frozenset(
+            _as_attr_names(g) for g in sources.values() if len(g) > 1
+        )
+
+        all_parameters = (
+            source_typed_dict.__required_keys__ | source_typed_dict.__optional_keys__
+        )
+        _check_conflicts(
+            source_content_attributes,
+            source_typed_dict.__required_keys__,
+            all_parameters,
+        )
+
+        manifest_attributes = {
+            a.source_attribute_name: a for a in source_content_attributes.values()
+        }
+
+        if parsed_alt_form is not None:
+            target_attribute = parsed_alt_form.target_attribute
+            if (
+                target_attribute not in required_target_parameters
+                and required_target_parameters
+                or len(required_target_parameters) > 1
+            ):
+                raise NotImplementedError(
+                    "When using alternative source formats (Union[TypedDict, ...]), then the"
+                    " target must have at most one require parameter"
+                )
+            bridge_mapper = self._type_normalize(
+                target_attribute,
+                parsed_alt_form.attribute_type,
+                target_attributes[target_attribute].attribute_type,
+                False,
+            )
+            parsed_alt_form.type_validator = (
+                parsed_alt_form.type_validator.combine_mapper(bridge_mapper)
+            )
+
+        _verify_inline_reference_documentation(
+            source_content_attributes,
+            inline_reference_documentation,
+            parsed_alt_form is not None,
+        )
+        if non_mapping_source_only:
+            return DeclarativeNonMappingInputParser(
+                assume_not_none(parsed_alt_form),
+                inline_reference_documentation=inline_reference_documentation,
+            )
+        else:
+            return DeclarativeMappingInputParser(
+                _as_attr_names(source_typed_dict.__required_keys__),
+                _as_attr_names(all_parameters),
+                manifest_attributes,
+                source_attributes,
+                mutually_exclusive_attributes=all_mutually_exclusive_fields,
+                alt_form_parser=parsed_alt_form,
+                at_least_one_of=at_least_one_of,
+                inline_reference_documentation=inline_reference_documentation,
+                path_hint_source_attributes=tuple(path_hint_source_attributes),
+            )
+
+    def _as_type_validator(
+        self,
+        attribute: str,
+        provided_type: Any,
+        parsing_typed_dict_attribute: bool,
+    ) -> AttributeTypeHandler:
+        assert not isinstance(provided_type, tuple)
+
+        if isinstance(provided_type, type) and issubclass(
+            provided_type, DebputyDispatchableType
+        ):
+            return _dispatch_parser(provided_type)
+
+        unmapped_type = self._strip_mapped_types(
+            provided_type,
+            parsing_typed_dict_attribute,
+        )
+        type_normalizer = self._type_normalize(
+            attribute,
+            unmapped_type,
+            provided_type,
+            parsing_typed_dict_attribute,
+        )
+        t_unmapped, t_orig, t_args = unpack_type(
+            unmapped_type,
+            parsing_typed_dict_attribute,
+        )
+
+        if (
+            t_orig == Union
+            and t_args
+            and len(t_args) == 2
+            and any(v is _NONE_TYPE for v in t_args)
+        ):
+            _, _, args = unpack_type(provided_type, parsing_typed_dict_attribute)
+            actual_type = [a for a in args if a is not _NONE_TYPE][0]
+            validator = self._as_type_validator(
+                attribute, actual_type, parsing_typed_dict_attribute
+            )
+
+            def _validator(v: Any, path: AttributePath) -> None:
+                if v is None:
+                    return
+                validator.ensure_type(v, path)
+
+            return AttributeTypeHandler(
+                validator.describe_type(),
+                _validator,
+                base_type=validator.base_type,
+                mapper=type_normalizer,
+            )
+
+        if unmapped_type in BASIC_SIMPLE_TYPES:
+            type_name = BASIC_SIMPLE_TYPES[unmapped_type]
+
+            type_mapping = self._registered_types.get(provided_type)
+            if type_mapping is not None:
+                simple_type = f" ({type_name})"
+                type_name = type_mapping.target_type.__name__
+            else:
+                simple_type = ""
+
+            def _validator(v: Any, path: AttributePath) -> None:
+                if not isinstance(v, unmapped_type):
+                    _validation_type_error(
+                        path, f"The attribute must be a {type_name}{simple_type}"
+                    )
+
+            return AttributeTypeHandler(
+                type_name,
+                _validator,
+                base_type=unmapped_type,
+                mapper=type_normalizer,
+            )
+        if t_orig == list:
+            if not t_args:
+                raise ValueError(
+                    f'The attribute "{attribute}" is List but does not have Generics (Must use List[X])'
+                )
+            _, t_provided_orig, t_provided_args = unpack_type(
+                provided_type,
+                parsing_typed_dict_attribute,
+            )
+            genetic_type = t_args[0]
+            key_mapper = self._as_type_validator(
+                attribute,
+                genetic_type,
+                parsing_typed_dict_attribute,
+            )
+
+            def _validator(v: Any, path: AttributePath) -> None:
+                if not isinstance(v, list):
+                    _validation_type_error(path, "The attribute must be a list")
+                for i, v in enumerate(v):
+                    key_mapper.ensure_type(v, path[i])
+
+            list_mapper = (
+                map_each_element(key_mapper.mapper)
+                if key_mapper.mapper is not None
+                else None
+            )
+
+            return AttributeTypeHandler(
+                f"List of {key_mapper.describe_type()}",
+                _validator,
+                base_type=list,
+                mapper=type_normalizer,
+            ).combine_mapper(list_mapper)
+        if is_typeddict(provided_type):
+            subparser = self.parser_from_typed_dict(cast("Type[TD]", provided_type))
+            return AttributeTypeHandler(
+                description=f"{provided_type.__name__} (Typed Mapping)",
+                ensure_type=lambda v, ap: None,
+                base_type=dict,
+                mapper=lambda v, ap, cv: subparser.parse_input(
+                    v, ap, parser_context=cv
+                ),
+            )
+        if t_orig == dict:
+            if not t_args or len(t_args) != 2:
+                raise ValueError(
+                    f'The attribute "{attribute}" is Dict but does not have Generics (Must use Dict[str, Y])'
+                )
+            if t_args[0] != str:
+                raise ValueError(
+                    f'The attribute "{attribute}" is Dict and has a non-str type as key.'
+                    " Currently, only `str` is supported (Dict[str, Y])"
+                )
+            key_mapper = self._as_type_validator(
+                attribute,
+                t_args[0],
+                parsing_typed_dict_attribute,
+            )
+            value_mapper = self._as_type_validator(
+                attribute,
+                t_args[1],
+                parsing_typed_dict_attribute,
+            )
+
+            if key_mapper.base_type is None:
+                raise ValueError(
+                    f'The attribute "{attribute}" is Dict and the key did not have a trivial base type.  Key types'
+                    f" without trivial base types (such as `str`) are not supported at the moment."
+                )
+
+            if value_mapper.mapper is not None:
+                raise ValueError(
+                    f'The attribute "{attribute}" is Dict and the value requires mapping.'
+                    " Currently, this is not supported. Consider a simpler type (such as Dict[str, str] or Dict[str, Any])."
+                    " Better typing may come later"
+                )
+
+            def _validator(uv: Any, path: AttributePath) -> None:
+                if not isinstance(uv, dict):
+                    _validation_type_error(path, "The attribute must be a mapping")
+                key_name = "the first key in the mapping"
+                for i, (k, v) in enumerate(uv.items()):
+                    if not key_mapper.base_type_match(k):
+                        kp = path.copy_with_path_hint(key_name)
+                        _validation_type_error(
+                            kp,
+                            f'The key number {i + 1} in attribute "{kp}" must be a {key_mapper.describe_type()}',
+                        )
+                    key_name = f"the key after {k}"
+                    value_mapper.ensure_type(v, path[k])
+
+            return AttributeTypeHandler(
+                f"Mapping of {value_mapper.describe_type()}",
+                _validator,
+                base_type=dict,
+                mapper=type_normalizer,
+            ).combine_mapper(key_mapper.mapper)
+        if t_orig == Union:
+            if _is_two_arg_x_list_x(t_args):
+                # Force the order to be "X, List[X]" as it simplifies the code
+                x_list_x = (
+                    t_args if get_origin(t_args[1]) == list else (t_args[1], t_args[0])
+                )
+
+                # X, List[X] could match if X was List[Y].  However, our code below assumes
+                # that X is a non-list.  The `_is_two_arg_x_list_x` returns False for this
+                # case to avoid this assert and fall into the "generic case".
+                assert get_origin(x_list_x[0]) != list
+                x_subtype_checker = self._as_type_validator(
+                    attribute,
+                    x_list_x[0],
+                    parsing_typed_dict_attribute,
+                )
+                list_x_subtype_checker = self._as_type_validator(
+                    attribute,
+                    x_list_x[1],
+                    parsing_typed_dict_attribute,
+                )
+                type_description = x_subtype_checker.describe_type()
+                type_description = f"{type_description} or a list of {type_description}"
+
+                def _validator(v: Any, path: AttributePath) -> None:
+                    if isinstance(v, list):
+                        list_x_subtype_checker.ensure_type(v, path)
+                    else:
+                        x_subtype_checker.ensure_type(v, path)
+
+                return AttributeTypeHandler(
+                    type_description,
+                    _validator,
+                    mapper=type_normalizer,
+                )
+            else:
+                subtype_checker = [
+                    self._as_type_validator(attribute, a, parsing_typed_dict_attribute)
+                    for a in t_args
+                ]
+                type_description = "one-of: " + ", ".join(
+                    f"{sc.describe_type()}" for sc in subtype_checker
+                )
+                mapper = subtype_checker[0].mapper
+                if any(mapper != sc.mapper for sc in subtype_checker):
+                    raise ValueError(
+                        f'Cannot handle the union "{provided_type}" as the target types need different'
+                        " type normalization/mapping logic.  Unions are generally limited to Union[X, List[X]]"
+                        " where X is a non-collection type."
+                    )
+
+                def _validator(v: Any, path: AttributePath) -> None:
+                    partial_matches = []
+                    for sc in subtype_checker:
+                        try:
+                            sc.ensure_type(v, path)
+                            return
+                        except ManifestParseException as e:
+                            if sc.base_type_match(v):
+                                partial_matches.append((sc, e))
+
+                    if len(partial_matches) == 1:
+                        raise partial_matches[0][1]
+                    _validation_type_error(
+                        path, f"Could not match against: {type_description}"
+                    )
+
+                return AttributeTypeHandler(
+                    type_description,
+                    _validator,
+                    mapper=type_normalizer,
+                )
+        if t_orig == Literal:
+            # We want "x" for string values; repr provides 'x'
+            pretty = ", ".join(
+                f'"{v}"' if isinstance(v, str) else str(v) for v in t_args
+            )
+
+            def _validator(v: Any, path: AttributePath) -> None:
+                if v not in t_args:
+                    value_hint = ""
+                    if isinstance(v, str):
+                        value_hint = f"({v}) "
+                    _validation_type_error(
+                        path,
+                        f"Value {value_hint}must be one of the following literal values: {pretty}",
+                    )
+
+            return AttributeTypeHandler(
+                f"One of the following literal values: {pretty}",
+                _validator,
+            )
+
+        if provided_type == Any:
+            return AttributeTypeHandler(
+                "any (unvalidated)",
+                lambda *a: None,
+            )
+        raise ValueError(
+            f'The attribute "{attribute}" had/contained a type {provided_type}, which is not supported'
+        )
+
+    def _parse_types(
+        self,
+        spec: Type[TypedDict],
+        allow_target_attribute_annotation: bool = False,
+        allow_source_attribute_annotations: bool = False,
+        forbid_optional: bool = True,
+    ) -> Dict[str, AttributeDescription]:
+        annotations = get_type_hints(spec, include_extras=True)
+        return {
+            k: self._attribute_description(
+                k,
+                t,
+                k in spec.__required_keys__,
+                allow_target_attribute_annotation=allow_target_attribute_annotation,
+                allow_source_attribute_annotations=allow_source_attribute_annotations,
+                forbid_optional=forbid_optional,
+            )
+            for k, t in annotations.items()
+        }
+
+    def _attribute_description(
+        self,
+        attribute: str,
+        orig_td: Any,
+        is_required: bool,
+        forbid_optional: bool = True,
+        allow_target_attribute_annotation: bool = False,
+        allow_source_attribute_annotations: bool = False,
+    ) -> AttributeDescription:
+        td, anno, is_optional = _parse_type(
+            attribute, orig_td, forbid_optional=forbid_optional
+        )
+        type_validator = self._as_type_validator(attribute, td, True)
+        parsed_annotations = DetectedDebputyParseHint.parse_annotations(
+            anno,
+            f' Seen with attribute "{attribute}".',
+            attribute,
+            is_required,
+            allow_target_attribute_annotation=allow_target_attribute_annotation,
+            allow_source_attribute_annotations=allow_source_attribute_annotations,
+        )
+        return AttributeDescription(
+            target_attribute=parsed_annotations.target_attribute,
+            attribute_type=td,
+            type_validator=type_validator,
+            annotations=anno,
+            is_optional=is_optional,
+            conflicting_attributes=parsed_annotations.conflict_with_source_attributes,
+            conditional_required=parsed_annotations.conditional_required,
+            source_attribute_name=assume_not_none(
+                parsed_annotations.source_manifest_attribute
+            ),
+            parse_hints=parsed_annotations,
+        )
+
+    def _parse_alt_form(
+        self,
+        alt_form,
+        default_target_attribute: Optional[str],
+    ) -> AttributeDescription:
+        td, anno, is_optional = _parse_type(
+            "source_format alternative form",
+            alt_form,
+            forbid_optional=True,
+            parsing_typed_dict_attribute=False,
+        )
+        type_validator = self._as_type_validator(
+            "source_format alternative form",
+            td,
+            True,
+        )
+        parsed_annotations = DetectedDebputyParseHint.parse_annotations(
+            anno,
+            f" The alternative for source_format.",
+            None,
+            False,
+            default_target_attribute=default_target_attribute,
+            allow_target_attribute_annotation=True,
+            allow_source_attribute_annotations=False,
+        )
+        return AttributeDescription(
+            target_attribute=parsed_annotations.target_attribute,
+            attribute_type=td,
+            type_validator=type_validator,
+            annotations=anno,
+            is_optional=is_optional,
+            conflicting_attributes=parsed_annotations.conflict_with_source_attributes,
+            conditional_required=parsed_annotations.conditional_required,
+            source_attribute_name="Alt form of the source_format",
+        )
+
+    def _union_narrowing(
+        self,
+        input_type: Any,
+        target_type: Any,
+        parsing_typed_dict_attribute: bool,
+    ) -> Optional[Callable[[Any, AttributePath, Optional["ParserContextData"]], Any]]:
+        _, input_orig, input_args = unpack_type(
+            input_type, parsing_typed_dict_attribute
+        )
+        _, target_orig, target_args = unpack_type(
+            target_type, parsing_typed_dict_attribute
+        )
+
+        if input_orig != Union or not input_args:
+            raise ValueError("input_type must be a Union[...] with non-empty args")
+
+        # Currently, we only support Union[X, List[X]] -> List[Y] narrowing or Union[X, List[X]] -> Union[Y, Union[Y]]
+        # - Where X = Y or there is a simple standard transformation from X to Y.
+
+        if target_orig not in (Union, list) or not target_args:
+            # Not supported
+            return None
+
+        if target_orig == Union and set(input_args) == set(target_args):
+            # Not needed (identity mapping)
+            return None
+
+        if target_orig == list and not any(get_origin(a) == list for a in input_args):
+            # Not supported
+            return None
+
+        target_arg = target_args[0]
+        simplified_type = self._strip_mapped_types(
+            target_arg, parsing_typed_dict_attribute
+        )
+        acceptable_types = {
+            target_arg,
+            List[target_arg],  # type: ignore
+            simplified_type,
+            List[simplified_type],  # type: ignore
+        }
+        target_format = (
+            target_arg,
+            List[target_arg],  # type: ignore
+        )
+        in_target_format = 0
+        in_simple_format = 0
+        for input_arg in input_args:
+            if input_arg not in acceptable_types:
+                # Not supported
+                return None
+            if input_arg in target_format:
+                in_target_format += 1
+            else:
+                in_simple_format += 1
+
+        assert in_simple_format or in_target_format
+
+        if in_target_format and not in_simple_format:
+            # Union[X, List[X]] -> List[X]
+            return normalize_into_list
+        mapped = self._registered_types[target_arg]
+        if not in_target_format and in_simple_format:
+            # Union[X, List[X]] -> List[Y]
+
+            def _mapper_x_list_y(
+                x: Union[Any, List[Any]],
+                ap: AttributePath,
+                pc: Optional["ParserContextData"],
+            ) -> List[Any]:
+                in_list_form: List[Any] = normalize_into_list(x, ap, pc)
+
+                return [mapped.mapper(x, ap, pc) for x in in_list_form]
+
+            return _mapper_x_list_y
+
+        # Union[Y, List[X]] -> List[Y]
+        if not isinstance(target_arg, type):
+            raise ValueError(
+                f"Cannot narrow {input_type} -> {target_type}: The automatic conversion does"
+                f" not support mixed types.  Please use either {simplified_type} or {target_arg}"
+                f" in the source content (but both a mix of both)"
+            )
+
+        def _mapper_mixed_list_y(
+            x: Union[Any, List[Any]],
+            ap: AttributePath,
+            pc: Optional["ParserContextData"],
+        ) -> List[Any]:
+            in_list_form: List[Any] = normalize_into_list(x, ap, pc)
+
+            return [
+                x if isinstance(x, target_arg) else mapped.mapper(x, ap, pc)
+                for x in in_list_form
+            ]
+
+        return _mapper_mixed_list_y
+
+    def _type_normalize(
+        self,
+        attribute: str,
+        input_type: Any,
+        target_type: Any,
+        parsing_typed_dict_attribute: bool,
+    ) -> Optional[Callable[[Any, AttributePath, Optional["ParserContextData"]], Any]]:
+        if input_type == target_type:
+            return None
+        _, input_orig, input_args = unpack_type(
+            input_type, parsing_typed_dict_attribute
+        )
+        _, target_orig, target_args = unpack_type(
+            target_type,
+            parsing_typed_dict_attribute,
+        )
+        if input_orig == Union:
+            result = self._union_narrowing(
+                input_type, target_type, parsing_typed_dict_attribute
+            )
+            if result:
+                return result
+        elif target_orig == list and target_args[0] == input_type:
+            return wrap_into_list
+
+        mapped = self._registered_types.get(target_type)
+        if mapped is not None and input_type == mapped.source_type:
+            # Source -> Target
+            return mapped.mapper
+        if target_orig == list and target_args:
+            mapped = self._registered_types.get(target_args[0])
+            if mapped is not None:
+                # mypy is dense and forgots `mapped` cannot be optional in the comprehensions.
+                mapped_type: TypeMapping = mapped
+                if input_type == mapped.source_type:
+                    # Source -> List[Target]
+                    return lambda x, ap, pc: [mapped_type.mapper(x, ap, pc)]
+                if (
+                    input_orig == list
+                    and input_args
+                    and input_args[0] == mapped_type.source_type
+                ):
+                    # List[Source] -> List[Target]
+                    return lambda xs, ap, pc: [
+                        mapped_type.mapper(x, ap, pc) for x in xs
+                    ]
+
+        raise ValueError(
+            f'Unsupported type normalization for "{attribute}": Cannot automatically map/narrow'
+            f" {input_type} to {target_type}"
+        )
+
+    def _strip_mapped_types(
+        self, orig_td: Any, parsing_typed_dict_attribute: bool
+    ) -> Any:
+        m = self._registered_types.get(orig_td)
+        if m is not None:
+            return m.source_type
+        _, v, args = unpack_type(orig_td, parsing_typed_dict_attribute)
+        if v == list:
+            arg = args[0]
+            m = self._registered_types.get(arg)
+            if m:
+                return List[m.source_type]  # type: ignore
+        if v == Union:
+            stripped_args = tuple(
+                self._strip_mapped_types(x, parsing_typed_dict_attribute) for x in args
+            )
+            if stripped_args != args:
+                return Union[stripped_args]
+        return orig_td
+
+
+def _verify_inline_reference_documentation(
+    source_content_attributes: Mapping[str, AttributeDescription],
+    inline_reference_documentation: Optional[ParserDocumentation],
+    has_alt_form: bool,
+) -> None:
+    if inline_reference_documentation is None:
+        return
+    attribute_doc = inline_reference_documentation.attribute_doc
+    if attribute_doc:
+        seen = set()
+        for attr_doc in attribute_doc:
+            for attr_name in attr_doc.attributes:
+                attr = source_content_attributes.get(attr_name)
+                if attr is None:
+                    raise ValueError(
+                        f'The inline_reference_documentation references an attribute "{attr_name}", which does not'
+                        f" exist in the source format."
+                    )
+                if attr_name in seen:
+                    raise ValueError(
+                        f'The inline_reference_documentation has documentation for "{attr_name}" twice,'
+                        f" which is not supported.  Please document it at most once"
+                    )
+                seen.add(attr_name)
+
+        undocumented = source_content_attributes.keys() - seen
+        if undocumented:
+            undocumented_attrs = ", ".join(undocumented)
+            raise ValueError(
+                "The following attributes were not documented.  If this is deliberate, then please"
+                ' declare each them as undocumented (via undocumented_attr("foo")):'
+                f" {undocumented_attrs}"
+            )
+
+    if inline_reference_documentation.alt_parser_description and not has_alt_form:
+        raise ValueError(
+            "The inline_reference_documentation had documentation for an non-mapping format,"
+            " but the source format does not have a non-mapping format."
+        )
+
+
+def _check_conflicts(
+    input_content_attributes: Dict[str, AttributeDescription],
+    required_attributes: FrozenSet[str],
+    all_attributes: FrozenSet[str],
+) -> None:
+    for attr_name, attr in input_content_attributes.items():
+        if attr_name in required_attributes and attr.conflicting_attributes:
+            c = ", ".join(repr(a) for a in attr.conflicting_attributes)
+            raise ValueError(
+                f'The attribute "{attr_name}" is required and conflicts with the attributes: {c}.'
+                " This makes it impossible to use these attributes. Either remove the attributes"
+                f' (along with the conflicts for them), adjust the conflicts or make "{attr_name}"'
+                " optional (NotRequired)"
+            )
+        else:
+            required_conflicts = attr.conflicting_attributes & required_attributes
+            if required_conflicts:
+                c = ", ".join(repr(a) for a in required_conflicts)
+                raise ValueError(
+                    f'The attribute "{attr_name}" conflicts with the following *required* attributes: {c}.'
+                    f' This makes it impossible to use the "{attr_name}" attribute. Either remove it,'
+                    f" adjust the conflicts or make the listed attributes optional (NotRequired)"
+                )
+        unknown_attributes = attr.conflicting_attributes - all_attributes
+        if unknown_attributes:
+            c = ", ".join(repr(a) for a in unknown_attributes)
+            raise ValueError(
+                f'The attribute "{attr_name}" declares a conflict with the following unknown attributes: {c}.'
+                f" None of these attributes were declared in the input."
+            )
+
+
+def _check_attributes(
+    content: Type[TypedDict],
+    input_content: Type[TypedDict],
+    input_content_attributes: Dict[str, AttributeDescription],
+    sources: Mapping[str, Collection[str]],
+) -> None:
+    target_required_keys = content.__required_keys__
+    input_required_keys = input_content.__required_keys__
+    all_input_keys = input_required_keys | input_content.__optional_keys__
+
+    for input_name in all_input_keys:
+        attr = input_content_attributes[input_name]
+        target_name = attr.target_attribute
+        source_names = sources[target_name]
+        input_is_required = input_name in input_required_keys
+        target_is_required = target_name in target_required_keys
+
+        assert source_names
+
+        if input_is_required and len(source_names) > 1:
+            raise ValueError(
+                f'The source attribute "{input_name}" is required, but it maps to "{target_name}",'
+                f' which has multiple sources "{source_names}". If "{input_name}" should be required,'
+                f' then there is no need for additional sources for "{target_name}". Alternatively,'
+                f' "{input_name}" might be missing a NotRequired type'
+                f' (example: "{input_name}: NotRequired[<OriginalTypeHere>]")'
+            )
+        if not input_is_required and target_is_required and len(source_names) == 1:
+            raise ValueError(
+                f'The source attribute "{input_name}" is not marked as required and maps to'
+                f' "{target_name}", which is marked as required. As there are no other attributes'
+                f' mapping to "{target_name}", then "{input_name}" must be required as well'
+                f' ("{input_name}: Required[<Type>]"). Alternatively, "{target_name}" should be optional'
+                f' ("{target_name}: NotRequired[<Type>]") or an "MappingHint.aliasOf" might be missing.'
+            )
+
+
+def _validation_type_error(path: AttributePath, message: str) -> None:
+    raise ManifestParseException(
+        f'The attribute "{path.path}" did not have a valid structure/type: {message}'
+    )
+
+
+def _is_two_arg_x_list_x(t_args: Tuple[Any, ...]) -> bool:
+    if len(t_args) != 2:
+        return False
+    lhs, rhs = t_args
+    if get_origin(lhs) == list:
+        if get_origin(rhs) == list:
+            # It could still match X, List[X] - but we do not allow this case for now as the caller
+            # does not support it.
+            return False
+        l_args = get_args(lhs)
+        return bool(l_args and l_args[0] == rhs)
+    if get_origin(rhs) == list:
+        r_args = get_args(rhs)
+        return bool(r_args and r_args[0] == lhs)
+    return False
+
+
+def _extract_typed_dict(
+    base_type,
+    default_target_attribute: Optional[str],
+) -> Tuple[Optional[Type[TypedDict]], Any]:
+    if is_typeddict(base_type):
+        return base_type, None
+    _, origin, args = unpack_type(base_type, False)
+    if origin != Union:
+        if isinstance(base_type, type) and issubclass(base_type, (dict, Mapping)):
+            raise ValueError(
+                "The source_format cannot be nor contain a (non-TypedDict) dict"
+            )
+        return None, base_type
+    typed_dicts = [x for x in args if is_typeddict(x)]
+    if len(typed_dicts) > 1:
+        raise ValueError(
+            "When source_format is a Union, it must contain at most one TypedDict"
+        )
+    typed_dict = typed_dicts[0] if typed_dicts else None
+
+    if any(x is None or x is _NONE_TYPE for x in args):
+        raise ValueError(
+            "The source_format cannot be nor contain Optional[X] or Union[X, None]"
+        )
+
+    if any(
+        isinstance(x, type) and issubclass(x, (dict, Mapping))
+        for x in args
+        if x is not typed_dict
+    ):
+        raise ValueError(
+            "The source_format cannot be nor contain a (non-TypedDict) dict"
+        )
+    remaining = [x for x in args if x is not typed_dict]
+    has_target_attribute = False
+    anno = None
+    if len(remaining) == 1:
+        base_type, anno, _ = _parse_type(
+            "source_format alternative form",
+            remaining[0],
+            forbid_optional=True,
+            parsing_typed_dict_attribute=False,
+        )
+        has_target_attribute = bool(anno) and any(
+            isinstance(x, TargetAttribute) for x in anno
+        )
+        target_type = base_type
+    else:
+        target_type = Union[tuple(remaining)]
+
+    if default_target_attribute is None and not has_target_attribute:
+        raise ValueError(
+            'The alternative format must be Union[TypedDict,Annotated[X, DebputyParseHint.target_attribute("...")]]'
+            " OR the parsed_content format must have exactly one attribute that is required."
+        )
+    if anno:
+        final_anno = [target_type]
+        final_anno.extend(anno)
+        return typed_dict, Annotated[tuple(final_anno)]
+    return typed_dict, target_type
+
+
+def _dispatch_parse_generator(
+    dispatch_type: Type[DebputyDispatchableType],
+) -> Callable[[Any, AttributePath, Optional["ParserContextData"]], Any]:
+    def _dispatch_parse(
+        value: Any,
+        attribute_path: AttributePath,
+        parser_context: Optional["ParserContextData"],
+    ):
+        assert parser_context is not None
+        dispatching_parser = parser_context.dispatch_parser_table_for(dispatch_type)
+        return dispatching_parser.parse(
+            value, attribute_path, parser_context=parser_context
+        )
+
+    return _dispatch_parse
+
+
+def _dispatch_parser(
+    dispatch_type: Type[DebputyDispatchableType],
+) -> AttributeTypeHandler:
+    return AttributeTypeHandler(
+        dispatch_type.__name__,
+        lambda *a: None,
+        mapper=_dispatch_parse_generator(dispatch_type),
+    )
+
+
+def _parse_type(
+    attribute: str,
+    orig_td: Any,
+    forbid_optional: bool = True,
+    parsing_typed_dict_attribute: bool = True,
+) -> Tuple[Any, Tuple[Any, ...], bool]:
+    td, v, args = unpack_type(orig_td, parsing_typed_dict_attribute)
+    md: Tuple[Any, ...] = tuple()
+    optional = False
+    if v is not None:
+        if v == Annotated:
+            anno = get_args(td)
+            md = anno[1:]
+            td, v, args = unpack_type(anno[0], parsing_typed_dict_attribute)
+
+        if td is _NONE_TYPE:
+            raise ValueError(
+                f'The attribute "{attribute}" resolved to type "None".  "Nil" / "None" fields are not allowed in the'
+                " debputy manifest, so this attribute does not make sense in its current form."
+            )
+        if forbid_optional and v == Union and any(a is _NONE_TYPE for a in args):
+            raise ValueError(
+                f'Detected use of Optional in "{attribute}", which is not allowed here.'
+                " Please use NotRequired for optional fields"
+            )
+
+    return td, md, optional
+
+
+def _normalize_attribute_name(attribute: str) -> str:
+    if attribute.endswith("_"):
+        attribute = attribute[:-1]
+    return attribute.replace("_", "-")
+
+
+@dataclasses.dataclass
+class DetectedDebputyParseHint:
+    target_attribute: str
+    source_manifest_attribute: Optional[str]
+    conflict_with_source_attributes: FrozenSet[str]
+    conditional_required: Optional[ConditionalRequired]
+    applicable_as_path_hint: bool
+
+    @classmethod
+    def parse_annotations(
+        cls,
+        anno: Tuple[Any, ...],
+        error_context: str,
+        default_attribute_name: Optional[str],
+        is_required: bool,
+        default_target_attribute: Optional[str] = None,
+        allow_target_attribute_annotation: bool = False,
+        allow_source_attribute_annotations: bool = False,
+    ) -> "DetectedDebputyParseHint":
+        target_attr_anno = find_annotation(anno, TargetAttribute)
+        if target_attr_anno:
+            if not allow_target_attribute_annotation:
+                raise ValueError(
+                    f"The DebputyParseHint.target_attribute annotation is not allowed in this context.{error_context}"
+                )
+            target_attribute = target_attr_anno.attribute
+        elif default_target_attribute is not None:
+            target_attribute = default_target_attribute
+        elif default_attribute_name is not None:
+            target_attribute = default_attribute_name
+        else:
+            if default_attribute_name is None:
+                raise ValueError(
+                    "allow_target_attribute_annotation must be True OR "
+                    "default_attribute_name/default_target_attribute must be not None"
+                )
+            raise ValueError(
+                f"Missing DebputyParseHint.target_attribute annotation.{error_context}"
+            )
+        source_attribute_anno = find_annotation(anno, ManifestAttribute)
+        _source_attribute_allowed(
+            allow_source_attribute_annotations, error_context, source_attribute_anno
+        )
+        if source_attribute_anno:
+            source_attribute_name = source_attribute_anno.attribute
+        elif default_attribute_name is not None:
+            source_attribute_name = _normalize_attribute_name(default_attribute_name)
+        else:
+            source_attribute_name = None
+        mutual_exclusive_with_anno = find_annotation(anno, ConflictWithSourceAttribute)
+        if mutual_exclusive_with_anno:
+            _source_attribute_allowed(
+                allow_source_attribute_annotations,
+                error_context,
+                mutual_exclusive_with_anno,
+            )
+            conflicting_attributes = mutual_exclusive_with_anno.conflicting_attributes
+        else:
+            conflicting_attributes = frozenset()
+        conditional_required = find_annotation(anno, ConditionalRequired)
+
+        if conditional_required and is_required:
+            if default_attribute_name is None:
+                raise ValueError(
+                    f"is_required cannot be True without default_attribute_name being not None"
+                )
+            raise ValueError(
+                f'The attribute "{default_attribute_name}" is Required while also being conditionally required.'
+                ' Please make the attribute "NotRequired" or remove the conditional requirement.'
+            )
+
+        not_path_hint_anno = find_annotation(anno, NotPathHint)
+        applicable_as_path_hint = not_path_hint_anno is None
+
+        return DetectedDebputyParseHint(
+            target_attribute=target_attribute,
+            source_manifest_attribute=source_attribute_name,
+            conflict_with_source_attributes=conflicting_attributes,
+            conditional_required=conditional_required,
+            applicable_as_path_hint=applicable_as_path_hint,
+        )
+
+
+def _source_attribute_allowed(
+    source_attribute_allowed: bool,
+    error_context: str,
+    annotation: Optional[DebputyParseHint],
+) -> None:
+    if source_attribute_allowed or annotation is None:
+        return
+    raise ValueError(
+        f'The annotation "{annotation}" cannot be used here. {error_context}'
+    )
diff --git a/src/debputy/manifest_parser/exceptions.py b/src/debputy/manifest_parser/exceptions.py
new file mode 100644
index 0000000..671ec1b
--- /dev/null
+++ b/src/debputy/manifest_parser/exceptions.py
@@ -0,0 +1,9 @@
+from debputy.exceptions import DebputyRuntimeError
+
+
+class ManifestParseException(DebputyRuntimeError):
+    pass
+
+
+class ManifestTypeException(ManifestParseException):
+    pass
diff --git a/src/debputy/manifest_parser/mapper_code.py b/src/debputy/manifest_parser/mapper_code.py
new file mode 100644
index 0000000..d7a08c3
--- /dev/null
+++ b/src/debputy/manifest_parser/mapper_code.py
@@ -0,0 +1,77 @@
+from typing import (
+    TypeVar,
+    Optional,
+    Union,
+    List,
+    Callable,
+)
+
+from debputy.manifest_parser.exceptions import ManifestTypeException
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.util import assume_not_none
+
+S = TypeVar("S")
+T = TypeVar("T")
+
+
+def type_mapper_str2package(
+    raw_package_name: str,
+    ap: AttributePath,
+    opc: Optional[ParserContextData],
+) -> BinaryPackage:
+    pc = assume_not_none(opc)
+    if "{{" in raw_package_name:
+        resolved_package_name = pc.substitution.substitute(raw_package_name, ap.path)
+    else:
+        resolved_package_name = raw_package_name
+
+    package_name_in_message = raw_package_name
+    if resolved_package_name != raw_package_name:
+        package_name_in_message = f'"{resolved_package_name}" ["{raw_package_name}"]'
+
+    if not pc.is_known_package(resolved_package_name):
+        package_names = ", ".join(pc.binary_packages)
+        raise ManifestTypeException(
+            f'The value {package_name_in_message} (from "{ap.path}") does not reference a package declared in'
+            f" debian/control. Valid options are: {package_names}"
+        )
+    package_data = pc.binary_package_data(resolved_package_name)
+    if package_data.is_auto_generated_package:
+        package_names = ", ".join(pc.binary_packages)
+        raise ManifestTypeException(
+            f'The package name {package_name_in_message} (from "{ap.path}") references an auto-generated package.'
+            " However, auto-generated packages are now permitted here. Valid options are:"
+            f" {package_names}"
+        )
+    return package_data.binary_package
+
+
+def wrap_into_list(
+    x: T,
+    _ap: AttributePath,
+    _pc: Optional["ParserContextData"],
+) -> List[T]:
+    return [x]
+
+
+def normalize_into_list(
+    x: Union[T, List[T]],
+    _ap: AttributePath,
+    _pc: Optional["ParserContextData"],
+) -> List[T]:
+    return x if isinstance(x, list) else [x]
+
+
+def map_each_element(
+    mapper: Callable[[S, AttributePath, Optional["ParserContextData"]], T],
+) -> Callable[[List[S], AttributePath, Optional["ParserContextData"]], List[T]]:
+    def _generated_mapper(
+        xs: List[S],
+        ap: AttributePath,
+        pc: Optional["ParserContextData"],
+    ) -> List[T]:
+        return [mapper(s, ap[i], pc) for i, s in enumerate(xs)]
+
+    return _generated_mapper
diff --git a/src/debputy/manifest_parser/parser_data.py b/src/debputy/manifest_parser/parser_data.py
new file mode 100644
index 0000000..3c36815
--- /dev/null
+++ b/src/debputy/manifest_parser/parser_data.py
@@ -0,0 +1,133 @@
+import contextlib
+from typing import (
+    Iterator,
+    Optional,
+    Mapping,
+    NoReturn,
+    Union,
+    Any,
+    TYPE_CHECKING,
+    Tuple,
+)
+
+from debian.debian_support import DpkgArchTable
+
+from debputy._deb_options_profiles import DebBuildOptionsAndProfiles
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.manifest_conditions import ManifestCondition
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.plugin.api.impl_types import (
+    _ALL_PACKAGE_TYPES,
+    resolve_package_type_selectors,
+    TP,
+    DispatchingTableParser,
+    TTP,
+    DispatchingObjectParser,
+)
+from debputy.plugin.api.spec import PackageTypeSelector
+from debputy.substitution import Substitution
+
+
+if TYPE_CHECKING:
+    from debputy.highlevel_manifest import PackageTransformationDefinition
+
+
+class ParserContextData:
+    @property
+    def binary_packages(self) -> Mapping[str, BinaryPackage]:
+        raise NotImplementedError
+
+    @property
+    def _package_states(self) -> Mapping[str, "PackageTransformationDefinition"]:
+        raise NotImplementedError
+
+    @property
+    def is_single_binary_package(self) -> bool:
+        return len(self.binary_packages) == 1
+
+    def single_binary_package(
+        self,
+        attribute_path: AttributePath,
+        *,
+        package_type: PackageTypeSelector = _ALL_PACKAGE_TYPES,
+        package_attribute: Optional[str] = None,
+    ) -> Optional[BinaryPackage]:
+        resolved_package_types = resolve_package_type_selectors(package_type)
+        possible_matches = [
+            p
+            for p in self.binary_packages.values()
+            if p.package_type in resolved_package_types
+        ]
+        if len(possible_matches) == 1:
+            return possible_matches[0]
+
+        if package_attribute is not None:
+            raise ManifestParseException(
+                f"The {attribute_path.path} rule needs the attribute `{package_attribute}`"
+                " for this source package."
+            )
+
+        if not possible_matches:
+            _package_types = ", ".join(sorted(resolved_package_types))
+            raise ManifestParseException(
+                f"The {attribute_path.path} rule is not applicable to this source package"
+                f" (it only applies to source packages that builds exactly one of"
+                f" the following package types: {_package_types})."
+            )
+        raise ManifestParseException(
+            f"The {attribute_path.path} rule is not applicable to multi-binary packages."
+        )
+
+    def _error(self, msg: str) -> "NoReturn":
+        raise ManifestParseException(msg)
+
+    def is_known_package(self, package_name: str) -> bool:
+        return package_name in self._package_states
+
+    def binary_package_data(
+        self,
+        package_name: str,
+    ) -> "PackageTransformationDefinition":
+        if package_name not in self._package_states:
+            self._error(
+                f'The package "{package_name}" is not present in the debian/control file (could not find'
+                f' "Package: {package_name}" in a binary stanza) nor is it a -dbgsym package for one'
+                " for a package in debian/control."
+            )
+        return self._package_states[package_name]
+
+    @property
+    def dpkg_architecture_variables(self) -> DpkgArchitectureBuildProcessValuesTable:
+        raise NotImplementedError
+
+    @property
+    def dpkg_arch_query_table(self) -> DpkgArchTable:
+        raise NotImplementedError
+
+    @property
+    def build_env(self) -> DebBuildOptionsAndProfiles:
+        raise NotImplementedError
+
+    @contextlib.contextmanager
+    def binary_package_context(
+        self,
+        package_name: str,
+    ) -> Iterator["PackageTransformationDefinition"]:
+        raise NotImplementedError
+
+    @property
+    def substitution(self) -> Substitution:
+        raise NotImplementedError
+
+    @property
+    def current_binary_package_state(self) -> "PackageTransformationDefinition":
+        raise NotImplementedError
+
+    @property
+    def is_in_binary_package_state(self) -> bool:
+        raise NotImplementedError
+
+    def dispatch_parser_table_for(self, rule_type: TTP) -> DispatchingTableParser[TP]:
+        raise NotImplementedError
diff --git a/src/debputy/manifest_parser/util.py b/src/debputy/manifest_parser/util.py
new file mode 100644
index 0000000..1600a90
--- /dev/null
+++ b/src/debputy/manifest_parser/util.py
@@ -0,0 +1,314 @@
+import dataclasses
+from typing import (
+    Iterator,
+    Union,
+    Self,
+    Optional,
+    List,
+    Tuple,
+    Mapping,
+    get_origin,
+    get_args,
+    Any,
+    Type,
+    TypeVar,
+    TYPE_CHECKING,
+)
+
+if TYPE_CHECKING:
+    from debputy.manifest_parser.declarative_parser import DebputyParseHint
+
+
+MP = TypeVar("MP", bound="DebputyParseHint")
+StrOrInt = Union[str, int]
+AttributePathAliasMapping = Mapping[
+    StrOrInt, Tuple[StrOrInt, Optional["AttributePathAliasMapping"]]
+]
+
+
+class AttributePath(object):
+    __slots__ = ("parent", "name", "alias_mapping", "path_hint")
+
+    def __init__(
+        self,
+        parent: Optional["AttributePath"],
+        key: Optional[Union[str, int]],
+        *,
+        alias_mapping: Optional[AttributePathAliasMapping] = None,
+    ) -> None:
+        self.parent = parent
+        self.name = key
+        self.path_hint: Optional[str] = None
+        self.alias_mapping = alias_mapping
+
+    @classmethod
+    def root_path(cls) -> "AttributePath":
+        return AttributePath(None, None)
+
+    @classmethod
+    def builtin_path(cls) -> "AttributePath":
+        return AttributePath(None, "$builtin$")
+
+    @classmethod
+    def test_path(cls) -> "AttributePath":
+        return AttributePath(None, "$test$")
+
+    def __bool__(self) -> bool:
+        return self.name is not None or self.parent is not None
+
+    def copy_with_path_hint(self, path_hint: str) -> "AttributePath":
+        p = self.__class__(self.parent, self.name, alias_mapping=self.alias_mapping)
+        p.path_hint = path_hint
+        return p
+
+    @property
+    def path(self) -> str:
+        segments = list(self._iter_path())
+        segments.reverse()
+        parts: List[str] = []
+        path_hint = None
+
+        for s in segments:
+            k = s.name
+            s_path_hint = s.path_hint
+            if s_path_hint is not None:
+                path_hint = s_path_hint
+            if isinstance(k, int):
+                parts.append(f"[{k}]")
+            elif k is not None:
+                if parts:
+                    parts.append(".")
+                parts.append(k)
+        if path_hint:
+            parts.append(f" <Search for: {path_hint}>")
+        if not parts:
+            return "document root"
+        return "".join(parts)
+
+    def __str__(self) -> str:
+        return self.path
+
+    def __getitem__(self, item: Union[str, int]) -> "AttributePath":
+        alias_mapping = None
+        if self.alias_mapping:
+            match = self.alias_mapping.get(item)
+            if match:
+                item, alias_mapping = match
+                if item == "":
+                    # Support `sources[0]` mapping to `source` by `sources -> source` and `0 -> ""`.
+                    return AttributePath(
+                        self.parent, self.name, alias_mapping=alias_mapping
+                    )
+        return AttributePath(self, item, alias_mapping=alias_mapping)
+
+    def _iter_path(self) -> Iterator["AttributePath"]:
+        current = self
+        yield current
+        while True:
+            parent = current.parent
+            if not parent:
+                break
+            current = parent
+            yield current
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class _SymbolicModeSegment:
+    base_mode: int
+    base_mask: int
+    cap_x_mode: int
+    cap_x_mask: int
+
+    def apply(self, current_mode: int, is_dir: bool) -> int:
+        if current_mode & 0o111 or is_dir:
+            chosen_mode = self.cap_x_mode
+            mode_mask = self.cap_x_mask
+        else:
+            chosen_mode = self.base_mode
+            mode_mask = self.base_mask
+        # set ("="): mode mask clears relevant segment and current_mode are the desired bits
+        # add ("+"): mode mask keeps everything and current_mode are the desired bits
+        # remove ("-"): mode mask clears relevant bits and current_mode are 0
+        return (current_mode & mode_mask) | chosen_mode
+
+
+def _symbolic_mode_bit_inverse(v: int) -> int:
+    # The & part is necessary because otherwise python narrows the inversion to the minimum number of bits
+    # required, which is not what we want.
+    return ~v & 0o7777
+
+
+def parse_symbolic_mode(
+    symbolic_mode: str,
+    attribute_path: Optional[AttributePath],
+) -> Iterator[_SymbolicModeSegment]:
+    sticky_bit = 0o01000
+    setuid_bit = 0o04000
+    setgid_bit = 0o02000
+    mode_group_flag = 0o7
+    subject_mask_and_shift = {
+        "u": (mode_group_flag << 6, 6),
+        "g": (mode_group_flag << 3, 3),
+        "o": (mode_group_flag << 0, 0),
+    }
+    bits = {
+        "r": (0o4, 0o4),
+        "w": (0o2, 0o2),
+        "x": (0o1, 0o1),
+        "X": (0o0, 0o1),
+        "s": (0o0, 0o0),  # Special-cased below (it depends on the subject)
+        "t": (0o0, 0o0),  # Special-cased below
+    }
+    modifiers = {
+        "+",
+        "-",
+        "=",
+    }
+    in_path = f" in {attribute_path.path}" if attribute_path is not None else ""
+    for orig_part in symbolic_mode.split(","):
+        base_mode = 0
+        cap_x_mode = 0
+        part = orig_part
+        subjects = set()
+        while part and part[0] in ("u", "g", "o", "a"):
+            subject = part[0]
+            if subject == "a":
+                subjects = {"u", "g", "o"}
+            else:
+                subjects.add(subject)
+            part = part[1:]
+        if not subjects:
+            subjects = {"u", "g", "o"}
+
+        if part and part[0] in modifiers:
+            modifier = part[0]
+        elif not part:
+            raise ValueError(
+                f'Invalid symbolic mode{in_path}: expected [+-=] to be present (from "{orig_part}")'
+            )
+        else:
+            raise ValueError(
+                f'Invalid symbolic mode{in_path}: Expected "{part[0]}" to be one of [+-=]'
+                f' (from "{orig_part}")'
+            )
+        part = part[1:]
+        s_bit_seen = False
+        t_bit_seen = False
+        while part and part[0] in bits:
+            if part == "s":
+                s_bit_seen = True
+            elif part == "t":
+                t_bit_seen = True
+            elif part in ("u", "g", "o"):
+                raise NotImplementedError(
+                    f"Cannot parse symbolic mode{in_path}: Sorry, we do not support referencing an"
+                    " existing subject's permissions (a=u) in symbolic modes."
+                )
+            else:
+                matched_bits = bits.get(part[0])
+                if matched_bits is None:
+                    valid_bits = "".join(bits)
+                    raise ValueError(
+                        f'Invalid symbolic mode{in_path}: Expected "{part[0]}" to be one of the letters'
+                        f' in "{valid_bits}" (from "{orig_part}")'
+                    )
+                base_mode_bits, cap_x_mode_bits = bits[part[0]]
+                base_mode |= base_mode_bits
+                cap_x_mode |= cap_x_mode_bits
+            part = part[1:]
+
+        if part:
+            raise ValueError(
+                f'Invalid symbolic mode{in_path}: Could not parse "{part[0]}" from "{orig_part}"'
+            )
+
+        final_base_mode = 0
+        final_cap_x_mode = 0
+        segment_mask = 0
+        for subject in subjects:
+            mask, shift = subject_mask_and_shift[subject]
+            segment_mask |= mask
+            final_base_mode |= base_mode << shift
+            final_cap_x_mode |= cap_x_mode << shift
+        if modifier == "=":
+            segment_mask |= setuid_bit if "u" in subjects else 0
+            segment_mask |= setgid_bit if "g" in subjects else 0
+            segment_mask |= sticky_bit if "o" in subjects else 0
+        if s_bit_seen:
+            if "u" in subjects:
+                final_base_mode |= setuid_bit
+                final_cap_x_mode |= setuid_bit
+            if "g" in subjects:
+                final_base_mode |= setgid_bit
+                final_cap_x_mode |= setgid_bit
+        if t_bit_seen:
+            final_base_mode |= sticky_bit
+            final_cap_x_mode |= sticky_bit
+        if modifier == "+":
+            final_base_mask = ~0
+            final_cap_x_mask = ~0
+        elif modifier == "-":
+            final_base_mask = _symbolic_mode_bit_inverse(final_base_mode)
+            final_cap_x_mask = _symbolic_mode_bit_inverse(final_cap_x_mode)
+            final_base_mode = 0
+            final_cap_x_mode = 0
+        elif modifier == "=":
+            # FIXME: Handle "unmentioned directory's setgid/setuid bits"
+            inverted_mask = _symbolic_mode_bit_inverse(segment_mask)
+            final_base_mask = inverted_mask
+            final_cap_x_mask = inverted_mask
+        else:
+            raise AssertionError(
+                f"Unknown modifier in symbolic mode: {modifier} - should not have happened"
+            )
+        yield _SymbolicModeSegment(
+            base_mode=final_base_mode,
+            base_mask=final_base_mask,
+            cap_x_mode=final_cap_x_mode,
+            cap_x_mask=final_cap_x_mask,
+        )
+
+
+def unpack_type(
+    orig_type: Any,
+    parsing_typed_dict_attribute: bool,
+) -> Tuple[Any, Optional[Any], Tuple[Any, ...]]:
+    raw_type = orig_type
+    origin = get_origin(raw_type)
+    args = get_args(raw_type)
+    if not parsing_typed_dict_attribute and repr(origin) in (
+        "typing.NotRequired",
+        "typing.Required",
+    ):
+        raise ValueError(
+            f"The Required/NotRequired attributes cannot be used outside typed dicts,"
+            f" the type that triggered the error: {orig_type}"
+        )
+
+    while repr(origin) in ("typing.NotRequired", "typing.Required"):
+        if len(args) != 1:
+            raise ValueError(
+                f"The type {raw_type} should have exactly one type parameter"
+            )
+        raw_type = args[0]
+        origin = get_origin(raw_type)
+        args = get_args(raw_type)
+
+    assert not isinstance(raw_type, tuple)
+
+    return raw_type, origin, args
+
+
+def find_annotation(
+    annotations: Tuple[Any, ...],
+    anno_class: Type[MP],
+) -> Optional[MP]:
+    m = None
+    for anno in annotations:
+        if isinstance(anno, anno_class):
+            if m is not None:
+                raise ValueError(
+                    f"The annotation {anno_class.__name__} was used more than once"
+                )
+            m = anno
+    return m
diff --git a/src/debputy/package_build/__init__.py b/src/debputy/package_build/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/package_build/__init__.py
diff --git a/src/debputy/package_build/assemble_deb.py b/src/debputy/package_build/assemble_deb.py
new file mode 100644
index 0000000..bed60e6
--- /dev/null
+++ b/src/debputy/package_build/assemble_deb.py
@@ -0,0 +1,255 @@
+import json
+import os
+import subprocess
+from typing import Optional, Sequence, List, Tuple
+
+from debputy import DEBPUTY_ROOT_DIR
+from debputy.commands.debputy_cmd.context import CommandContext
+from debputy.deb_packaging_support import setup_control_files
+from debputy.debhelper_emulation import dhe_dbgsym_root_dir
+from debputy.filesystem_scan import FSRootDir
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.intermediate_manifest import IntermediateManifest
+from debputy.plugin.api.impl_types import PackageDataTable
+from debputy.util import (
+    escape_shell,
+    _error,
+    compute_output_filename,
+    scratch_dir,
+    ensure_dir,
+    _warn,
+    assume_not_none,
+)
+
+
+_RRR_DEB_ASSEMBLY_KEYWORD = "debputy/deb-assembly"
+_WARNED_ABOUT_FALLBACK_ASSEMBLY = False
+
+
+def _serialize_intermediate_manifest(members: IntermediateManifest) -> str:
+    serial_format = [m.to_manifest() for m in members]
+    return json.dumps(serial_format)
+
+
+def determine_assembly_method(
+    package: str,
+    intermediate_manifest: IntermediateManifest,
+) -> Tuple[bool, bool, List[str]]:
+    paths_needing_root = (
+        tm for tm in intermediate_manifest if tm.owner != "root" or tm.group != "root"
+    )
+    matched_path = next(paths_needing_root, None)
+    if matched_path is None:
+        return False, False, []
+    rrr = os.environ.get("DEB_RULES_REQUIRES_ROOT")
+    if rrr and _RRR_DEB_ASSEMBLY_KEYWORD in rrr:
+        gain_root_cmd = os.environ.get("DEB_GAIN_ROOT_CMD")
+        if not gain_root_cmd:
+            _error(
+                "DEB_RULES_REQUIRES_ROOT contains a debputy keyword but DEB_GAIN_ROOT_CMD does not contain a "
+                '"gain root" command'
+            )
+        return True, False, gain_root_cmd.split()
+    if rrr == "no":
+        global _WARNED_ABOUT_FALLBACK_ASSEMBLY
+        if not _WARNED_ABOUT_FALLBACK_ASSEMBLY:
+            _warn(
+                'Using internal assembly method due to "Rules-Requires-Root" being "no" and dpkg-deb assembly would'
+                " require (fake)root for binary packages that needs it."
+            )
+            _WARNED_ABOUT_FALLBACK_ASSEMBLY = True
+        return True, True, []
+
+    _error(
+        f'Due to the path "{matched_path.member_path}" in {package}, the package assembly will require (fake)root.'
+        " However, this command is not run as root nor was debputy requested to use a root command via"
+        f' "Rules-Requires-Root".  Please consider adding "{_RRR_DEB_ASSEMBLY_KEYWORD}" to "Rules-Requires-Root"'
+        " in debian/control. Though, due to #1036865, you may have to revert to"
+        ' "Rules-Requires-Root: binary-targets" depending on which version of dpkg you need to support.'
+        ' Alternatively, you can set "Rules-Requires-Root: no" in debian/control and debputy will assemble'
+        " the package anyway. In this case, dpkg-deb will not be used, but the output should be bit-for-bit"
+        " compatible with what debputy would have produced with dpkg-deb (and root/fakeroot)."
+    )
+
+
+def assemble_debs(
+    context: CommandContext,
+    manifest: HighLevelManifest,
+    package_data_table: PackageDataTable,
+    is_dh_rrr_only_mode: bool,
+) -> None:
+    parsed_args = context.parsed_args
+    output_path = parsed_args.output
+    upstream_args = parsed_args.upstream_args
+    deb_materialize = str(DEBPUTY_ROOT_DIR / "deb_materialization.py")
+    mtime = context.mtime
+
+    for dctrl_bin in manifest.active_packages:
+        package = dctrl_bin.name
+        dbgsym_package_name = f"{package}-dbgsym"
+        dctrl_data = package_data_table[package]
+        fs_root = dctrl_data.fs_root
+        control_output_dir = assume_not_none(dctrl_data.control_output_dir)
+        package_metadata_context = dctrl_data.package_metadata_context
+        if (
+            dbgsym_package_name in package_data_table
+            or "noautodbgsym" in manifest.build_env.deb_build_options
+            or "noddebs" in manifest.build_env.deb_build_options
+        ):
+            # Discard the dbgsym part if it conflicts with a real package, or
+            # we were asked not to build it.
+            dctrl_data.dbgsym_info.dbgsym_fs_root = FSRootDir()
+            dctrl_data.dbgsym_info.dbgsym_ids.clear()
+        dbgsym_fs_root = dctrl_data.dbgsym_info.dbgsym_fs_root
+        dbgsym_ids = dctrl_data.dbgsym_info.dbgsym_ids
+        intermediate_manifest = manifest.finalize_data_tar_contents(
+            package, fs_root, mtime
+        )
+
+        setup_control_files(
+            dctrl_data,
+            manifest,
+            dbgsym_fs_root,
+            dbgsym_ids,
+            package_metadata_context,
+            allow_ctrl_file_management=not is_dh_rrr_only_mode,
+        )
+
+        needs_root, use_fallback_assembly, gain_root_cmd = determine_assembly_method(
+            package, intermediate_manifest
+        )
+
+        if not dctrl_bin.is_udeb and any(
+            f for f in dbgsym_fs_root.all_paths() if f.is_file
+        ):
+            # We never built udebs due to #797391. We currently do not generate a control
+            # file for it either for the same reason.
+            dbgsym_root = dhe_dbgsym_root_dir(dctrl_bin)
+            if not os.path.isdir(output_path):
+                _error(
+                    "Cannot produce a dbgsym package when output path is not a directory."
+                )
+            dbgsym_intermediate_manifest = manifest.finalize_data_tar_contents(
+                dbgsym_package_name,
+                dbgsym_fs_root,
+                mtime,
+            )
+            _assemble_deb(
+                dbgsym_package_name,
+                deb_materialize,
+                dbgsym_intermediate_manifest,
+                mtime,
+                os.path.join(dbgsym_root, "DEBIAN"),
+                output_path,
+                upstream_args,
+                is_udeb=dctrl_bin.is_udeb,  # Review this if we ever do dbgsyms for udebs
+                use_fallback_assembly=False,
+                needs_root=False,
+            )
+
+        _assemble_deb(
+            package,
+            deb_materialize,
+            intermediate_manifest,
+            mtime,
+            control_output_dir,
+            output_path,
+            upstream_args,
+            is_udeb=dctrl_bin.is_udeb,
+            use_fallback_assembly=use_fallback_assembly,
+            needs_root=needs_root,
+            gain_root_cmd=gain_root_cmd,
+        )
+
+
+def _assemble_deb(
+    package: str,
+    deb_materialize_cmd: str,
+    intermediate_manifest: IntermediateManifest,
+    mtime: int,
+    control_output_dir: str,
+    output_path: str,
+    upstream_args: Optional[List[str]],
+    is_udeb: bool = False,
+    use_fallback_assembly: bool = False,
+    needs_root: bool = False,
+    gain_root_cmd: Optional[Sequence[str]] = None,
+) -> None:
+    scratch_root_dir = scratch_dir()
+    materialization_dir = os.path.join(
+        scratch_root_dir, "materialization-dirs", package
+    )
+    ensure_dir(os.path.dirname(materialization_dir))
+    materialize_cmd: List[str] = []
+    assert not use_fallback_assembly or not gain_root_cmd
+    if needs_root and gain_root_cmd:
+        # Only use the gain_root_cmd if we absolutely need it.
+        # Note that gain_root_cmd will be empty unless R³ is set to the relevant keyword
+        # that would make us use targeted promotion. Therefore, we do not need to check other
+        # conditions than the package needing root. (R³: binary-targets implies `needs_root=True`
+        # without a gain_root_cmd)
+        materialize_cmd.extend(gain_root_cmd)
+    materialize_cmd.extend(
+        [
+            deb_materialize_cmd,
+            "materialize-deb",
+            "--intermediate-package-manifest",
+            "-",
+            "--may-move-control-files",
+            "--may-move-data-files",
+            "--source-date-epoch",
+            str(mtime),
+            "--discard-existing-output",
+            control_output_dir,
+            materialization_dir,
+        ]
+    )
+    output = output_path
+    if is_udeb:
+        materialize_cmd.append("--udeb")
+        output = os.path.join(
+            output_path, compute_output_filename(control_output_dir, True)
+        )
+
+    assembly_method = "debputy" if needs_root and use_fallback_assembly else "dpkg-deb"
+    combined_materialization_and_assembly = not needs_root
+    if combined_materialization_and_assembly:
+        materialize_cmd.extend(
+            ["--build-method", assembly_method, "--assembled-deb-output", output]
+        )
+
+    if upstream_args:
+        materialize_cmd.append("--")
+        materialize_cmd.extend(upstream_args)
+
+    if combined_materialization_and_assembly:
+        print(
+            f"Materializing and assembling {package} via: {escape_shell(*materialize_cmd)}"
+        )
+    else:
+        print(f"Materializing {package} via: {escape_shell(*materialize_cmd)}")
+    proc = subprocess.Popen(materialize_cmd, stdin=subprocess.PIPE)
+    proc.communicate(
+        _serialize_intermediate_manifest(intermediate_manifest).encode("utf-8")
+    )
+    if proc.returncode != 0:
+        _error(f"{escape_shell(deb_materialize_cmd)} exited with a non-zero exit code!")
+
+    if not combined_materialization_and_assembly:
+        build_materialization = [
+            deb_materialize_cmd,
+            "build-materialized-deb",
+            materialization_dir,
+            assembly_method,
+            "--output",
+            output,
+        ]
+        print(f"Assembling {package} via: {escape_shell(*build_materialization)}")
+        try:
+            subprocess.check_call(build_materialization)
+        except subprocess.CalledProcessError as e:
+            exit_code = f" with exit code {e.returncode}" if e.returncode else ""
+            _error(
+                f"Assembly command for {package} failed{exit_code}. Please review the output of the command"
+                f" for more details on the problem."
+            )
diff --git a/src/debputy/packager_provided_files.py b/src/debputy/packager_provided_files.py
new file mode 100644
index 0000000..6d74999
--- /dev/null
+++ b/src/debputy/packager_provided_files.py
@@ -0,0 +1,323 @@
+import collections
+import dataclasses
+from typing import Mapping, Iterable, Dict, List, Optional, Tuple
+
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import VirtualPath
+from debputy.plugin.api.impl_types import PackagerProvidedFileClassSpec
+from debputy.util import _error
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PackagerProvidedFile:
+    path: VirtualPath
+    package_name: str
+    installed_as_basename: str
+    provided_key: str
+    definition: PackagerProvidedFileClassSpec
+    match_priority: int = 0
+    fuzzy_match: bool = False
+
+    def compute_dest(self) -> Tuple[str, str]:
+        return self.definition.compute_dest(
+            self.installed_as_basename,
+            owning_package=self.package_name,
+            path=self.path,
+        )
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PerPackagePackagerProvidedResult:
+    auto_installable: List[PackagerProvidedFile]
+    reserved_only: Dict[str, List[PackagerProvidedFile]]
+
+
+def _find_package_name_prefix(
+    binary_packages: Mapping[str, BinaryPackage],
+    main_binary_package: str,
+    max_periods_in_package_name: int,
+    path: VirtualPath,
+    *,
+    allow_fuzzy_matches: bool = False,
+) -> Iterable[Tuple[str, str, bool, bool]]:
+    if max_periods_in_package_name < 1:
+        prefix, remaining = path.name.split(".", 1)
+        package_name = prefix
+        bug_950723 = False
+        if allow_fuzzy_matches and package_name.endswith("@"):
+            package_name = package_name[:-1]
+            bug_950723 = True
+        if package_name in binary_packages:
+            yield package_name, remaining, True, bug_950723
+        else:
+            yield main_binary_package, path.name, False, False
+        return
+
+    parts = path.name.split(".", max_periods_in_package_name + 1)
+    for p in range(len(parts) - 1, 0, -1):
+        name = ".".join(parts[0:p])
+        bug_950723 = False
+        if allow_fuzzy_matches and name.endswith("@"):
+            name = name[:-1]
+            bug_950723 = True
+
+        if name in binary_packages:
+            remaining = ".".join(parts[p:])
+            yield name, remaining, True, bug_950723
+    # main package case
+    yield main_binary_package, path.name, False, False
+
+
+def _find_definition(
+    packager_provided_files: Mapping[str, PackagerProvidedFileClassSpec],
+    basename: str,
+) -> Tuple[Optional[str], Optional[PackagerProvidedFileClassSpec]]:
+    definition = packager_provided_files.get(basename)
+    if definition is not None:
+        return None, definition
+    install_as_name = basename
+    file_class = ""
+    while "." in install_as_name:
+        install_as_name, file_class_part = install_as_name.rsplit(".", 1)
+        file_class = (
+            file_class_part + "." + file_class if file_class != "" else file_class_part
+        )
+        definition = packager_provided_files.get(file_class)
+        if definition is not None:
+            return install_as_name, definition
+    return None, None
+
+
+def _check_mismatches(
+    path: VirtualPath,
+    definition: PackagerProvidedFileClassSpec,
+    owning_package: BinaryPackage,
+    install_as_name: Optional[str],
+    had_arch: bool,
+) -> None:
+    if install_as_name is not None and not definition.allow_name_segment:
+        _error(
+            f'The file "{path.fs_path}" looks like a packager provided file for'
+            f' {owning_package.name} of type {definition.stem} with the custom name "{install_as_name}".'
+            " However, this file type does not allow custom naming. The file type was registered"
+            f" by {definition.debputy_plugin_metadata.plugin_name} in case you disagree and want"
+            " to file a bug/feature request."
+        )
+    if had_arch:
+        if owning_package.is_arch_all:
+            _error(
+                f'The file "{path.fs_path}" looks like an architecture specific packager provided file for'
+                f" {owning_package.name} of type {definition.stem}."
+                " However, the package in question is arch:all. The use of architecture specific files"
+                " for arch:all packages does not make sense."
+            )
+        if not definition.allow_architecture_segment:
+            _error(
+                f'The file "{path.fs_path}" looks like an architecture specific packager provided file for'
+                f" {owning_package.name} of type {definition.stem}."
+                " However, this file type does not allow architecture specific variants. The file type was registered"
+                f" by {definition.debputy_plugin_metadata.plugin_name} in case you disagree and want"
+                " to file a bug/feature request."
+            )
+
+
+def _split_path(
+    packager_provided_files: Mapping[str, PackagerProvidedFileClassSpec],
+    binary_packages: Mapping[str, BinaryPackage],
+    main_binary_package: str,
+    max_periods_in_package_name: int,
+    path: VirtualPath,
+    *,
+    allow_fuzzy_matches: bool = False,
+) -> Iterable[PackagerProvidedFile]:
+    owning_package_name = main_binary_package
+    basename = path.name
+    match_priority = 0
+    had_arch = False
+    if "." not in basename:
+        definition = packager_provided_files.get(basename)
+        if definition is None:
+            return
+        if definition.packageless_is_fallback_for_all_packages:
+            yield from (
+                PackagerProvidedFile(
+                    path=path,
+                    package_name=n,
+                    installed_as_basename=n,
+                    provided_key=".UNNAMED.",
+                    definition=definition,
+                    match_priority=match_priority,
+                    fuzzy_match=False,
+                )
+                for n in binary_packages
+            )
+        else:
+            yield PackagerProvidedFile(
+                path=path,
+                package_name=owning_package_name,
+                installed_as_basename=owning_package_name,
+                provided_key=".UNNAMED.",
+                definition=definition,
+                match_priority=match_priority,
+                fuzzy_match=False,
+            )
+        return
+
+    for (
+        owning_package_name,
+        basename,
+        explicit_package,
+        bug_950723,
+    ) in _find_package_name_prefix(
+        binary_packages,
+        main_binary_package,
+        max_periods_in_package_name,
+        path,
+        allow_fuzzy_matches=allow_fuzzy_matches,
+    ):
+        owning_package = binary_packages[owning_package_name]
+        match_priority = 1 if explicit_package else 0
+        fuzzy_match = False
+
+        if allow_fuzzy_matches and basename.endswith(".in") and len(basename) > 3:
+            basename = basename[:-3]
+            fuzzy_match = True
+
+        if "." in basename:
+            remaining, last_word = basename.rsplit(".", 1)
+            # We cannot use "resolved_architecture" as it would return "all".
+            if last_word == owning_package.package_deb_architecture_variable("ARCH"):
+                match_priority = 3
+                basename = remaining
+                had_arch = True
+            elif last_word == owning_package.package_deb_architecture_variable(
+                "ARCH_OS"
+            ):
+                match_priority = 2
+                basename = remaining
+                had_arch = True
+            elif last_word == "all" and owning_package.is_arch_all:
+                # This case does not make sense, but we detect it so we can report an error
+                # via _check_mismatches.
+                match_priority = -1
+                basename = remaining
+                had_arch = True
+
+        install_as_name, definition = _find_definition(
+            packager_provided_files, basename
+        )
+        if definition is None:
+            continue
+
+        # Note: bug_950723 implies allow_fuzzy_matches
+        if bug_950723 and not definition.bug_950723:
+            continue
+
+        _check_mismatches(
+            path,
+            definition,
+            owning_package,
+            install_as_name,
+            had_arch,
+        )
+        if (
+            definition.packageless_is_fallback_for_all_packages
+            and install_as_name is None
+            and not had_arch
+            and not explicit_package
+        ):
+            yield from (
+                PackagerProvidedFile(
+                    path=path,
+                    package_name=n,
+                    installed_as_basename=f"{n}@" if bug_950723 else n,
+                    provided_key=".UNNAMED." if bug_950723 else ".UNNAMED@.",
+                    definition=definition,
+                    match_priority=match_priority,
+                    fuzzy_match=fuzzy_match,
+                )
+                for n in binary_packages
+            )
+        else:
+            provided_key = (
+                install_as_name if install_as_name is not None else ".UNNAMED."
+            )
+            basename = (
+                install_as_name if install_as_name is not None else owning_package_name
+            )
+            if bug_950723:
+                provided_key = f"{provided_key}@"
+                basename = f"{basename}@"
+            yield PackagerProvidedFile(
+                path=path,
+                package_name=owning_package_name,
+                installed_as_basename=basename,
+                provided_key=provided_key,
+                definition=definition,
+                match_priority=match_priority,
+                fuzzy_match=fuzzy_match,
+            )
+        return
+
+
+def detect_all_packager_provided_files(
+    packager_provided_files: Mapping[str, PackagerProvidedFileClassSpec],
+    debian_dir: VirtualPath,
+    binary_packages: Mapping[str, BinaryPackage],
+    *,
+    allow_fuzzy_matches: bool = False,
+) -> Dict[str, PerPackagePackagerProvidedResult]:
+    main_binary_package = [
+        p.name for p in binary_packages.values() if p.is_main_package
+    ][0]
+    provided_files: Dict[str, Dict[Tuple[str, str], PackagerProvidedFile]] = {
+        n: {} for n in binary_packages
+    }
+    max_periods_in_package_name = max(name.count(".") for name in binary_packages)
+
+    for entry in debian_dir.iterdir:
+        if entry.is_dir:
+            continue
+        matching_ppfs = _split_path(
+            packager_provided_files,
+            binary_packages,
+            main_binary_package,
+            max_periods_in_package_name,
+            entry,
+            allow_fuzzy_matches=allow_fuzzy_matches,
+        )
+        for packager_provided_file in matching_ppfs:
+            provided_files_for_package = provided_files[
+                packager_provided_file.package_name
+            ]
+            match_key = (
+                packager_provided_file.definition.stem,
+                packager_provided_file.provided_key,
+            )
+            existing = provided_files_for_package.get(match_key)
+            if (
+                existing is not None
+                and existing.match_priority > packager_provided_file.match_priority
+            ):
+                continue
+            provided_files_for_package[match_key] = packager_provided_file
+
+    result = {}
+    for package_name, provided_file_data in provided_files.items():
+        auto_install_list = [
+            x for x in provided_file_data.values() if not x.definition.reservation_only
+        ]
+        reservation_only = collections.defaultdict(list)
+        for packager_provided_file in provided_file_data.values():
+            if not packager_provided_file.definition.reservation_only:
+                continue
+            reservation_only[packager_provided_file.definition.stem].append(
+                packager_provided_file
+            )
+
+        result[package_name] = PerPackagePackagerProvidedResult(
+            auto_install_list,
+            reservation_only,
+        )
+
+    return result
diff --git a/src/debputy/packages.py b/src/debputy/packages.py
new file mode 100644
index 0000000..3204f46
--- /dev/null
+++ b/src/debputy/packages.py
@@ -0,0 +1,332 @@
+from typing import (
+    Dict,
+    Union,
+    Tuple,
+    Optional,
+    Set,
+    cast,
+    Mapping,
+    FrozenSet,
+    TYPE_CHECKING,
+)
+
+from debian.deb822 import Deb822
+from debian.debian_support import DpkgArchTable
+
+from ._deb_options_profiles import DebBuildOptionsAndProfiles
+from .architecture_support import (
+    DpkgArchitectureBuildProcessValuesTable,
+    dpkg_architecture_table,
+)
+from .util import DEFAULT_PACKAGE_TYPE, UDEB_PACKAGE_TYPE, _error, active_profiles_match
+
+if TYPE_CHECKING:
+    from .plugin.api import VirtualPath
+
+
+_MANDATORY_BINARY_PACKAGE_FIELD = [
+    "Package",
+    "Architecture",
+]
+
+
+def parse_source_debian_control(
+    debian_control: "VirtualPath",
+    selected_packages: Union[Set[str], FrozenSet[str]],
+    excluded_packages: Union[Set[str], FrozenSet[str]],
+    select_arch_all: bool,
+    select_arch_any: bool,
+    dpkg_architecture_variables: Optional[
+        DpkgArchitectureBuildProcessValuesTable
+    ] = None,
+    dpkg_arch_query_table: Optional[DpkgArchTable] = None,
+    build_env: Optional[DebBuildOptionsAndProfiles] = None,
+) -> Tuple["SourcePackage", Dict[str, "BinaryPackage"]]:
+    if dpkg_architecture_variables is None:
+        dpkg_architecture_variables = dpkg_architecture_table()
+    if dpkg_arch_query_table is None:
+        dpkg_arch_query_table = DpkgArchTable.load_arch_table()
+    if build_env is None:
+        build_env = DebBuildOptionsAndProfiles.instance()
+
+    # If no selection option is set, then all packages are acted on (except the
+    # excluded ones)
+    if not selected_packages and not select_arch_all and not select_arch_any:
+        select_arch_all = True
+        select_arch_any = True
+
+    with debian_control.open() as fd:
+        dctrl_paragraphs = list(Deb822.iter_paragraphs(fd))
+
+    if len(dctrl_paragraphs) < 2:
+        _error(
+            "debian/control must contain at least two stanza (1 Source + 1-N Package stanza)"
+        )
+
+    source_package = SourcePackage(dctrl_paragraphs[0])
+
+    bin_pkgs = [
+        _create_binary_package(
+            p,
+            selected_packages,
+            excluded_packages,
+            select_arch_all,
+            select_arch_any,
+            dpkg_architecture_variables,
+            dpkg_arch_query_table,
+            build_env,
+            i,
+        )
+        for i, p in enumerate(dctrl_paragraphs[1:], 1)
+    ]
+    bin_pkgs_table = {p.name: p for p in bin_pkgs}
+    if not selected_packages.issubset(bin_pkgs_table.keys()):
+        unknown = selected_packages - bin_pkgs_table.keys()
+        _error(
+            f"The following *selected* packages (-p) are not listed in debian/control: {sorted(unknown)}"
+        )
+    if not excluded_packages.issubset(bin_pkgs_table.keys()):
+        unknown = selected_packages - bin_pkgs_table.keys()
+        _error(
+            f"The following *excluded* packages (-N) are not listed in debian/control: {sorted(unknown)}"
+        )
+
+    return source_package, bin_pkgs_table
+
+
+def _check_package_sets(
+    provided_packages: Set[str],
+    valid_package_names: Set[str],
+    option_name: str,
+) -> None:
+    # SonarLint proposes to use `provided_packages > valid_package_names`, which is valid for boolean
+    # logic, but not for set logic.  We want to assert that provided_packages is a proper subset
+    # of valid_package_names.  The rewrite would cause no errors for {'foo'} > {'bar'} - in set logic,
+    # neither is a superset / subset of the other, but we want an error for this case.
+    #
+    # Bug filed:
+    # https://community.sonarsource.com/t/sonarlint-python-s1940-rule-does-not-seem-to-take-set-logic-into-account/79718
+    if not (provided_packages <= valid_package_names):
+        non_existing_packages = sorted(provided_packages - valid_package_names)
+        invalid_package_list = ", ".join(non_existing_packages)
+        msg = (
+            f"Invalid package names passed to {option_name}: {invalid_package_list}: "
+            f'Valid package names are: {", ".join(valid_package_names)}'
+        )
+        _error(msg)
+
+
+def _create_binary_package(
+    paragraph: Union[Deb822, Dict[str, str]],
+    selected_packages: Union[Set[str], FrozenSet[str]],
+    excluded_packages: Union[Set[str], FrozenSet[str]],
+    select_arch_all: bool,
+    select_arch_any: bool,
+    dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+    dpkg_arch_query_table: DpkgArchTable,
+    build_env: DebBuildOptionsAndProfiles,
+    paragraph_index: int,
+) -> "BinaryPackage":
+    try:
+        package_name = paragraph["Package"]
+    except KeyError:
+        _error(f'Missing mandatory field "Package" in stanza number {paragraph_index}')
+        # The raise is there to help PyCharm type-checking (which fails at "NoReturn")
+        raise
+
+    for mandatory_field in _MANDATORY_BINARY_PACKAGE_FIELD:
+        if mandatory_field not in paragraph:
+            _error(
+                f'Missing mandatory field "{mandatory_field}" for binary package {package_name}'
+                f" (stanza number {paragraph_index})"
+            )
+
+    architecture = paragraph["Architecture"]
+
+    if paragraph_index < 1:
+        raise ValueError("stanza index must be 1-indexed (1, 2, ...)")
+    is_main_package = paragraph_index == 1
+
+    if package_name in excluded_packages:
+        should_act_on = False
+    elif package_name in selected_packages:
+        should_act_on = True
+    elif architecture == "all":
+        should_act_on = select_arch_all
+    else:
+        should_act_on = select_arch_any
+
+    profiles_raw = paragraph.get("Build-Profiles", "").strip()
+    if should_act_on and profiles_raw:
+        try:
+            should_act_on = active_profiles_match(
+                profiles_raw, build_env.deb_build_profiles
+            )
+        except ValueError as e:
+            _error(f"Invalid Build-Profiles field for {package_name}: {e.args[0]}")
+
+    return BinaryPackage(
+        paragraph,
+        dpkg_architecture_variables,
+        dpkg_arch_query_table,
+        should_be_acted_on=should_act_on,
+        is_main_package=is_main_package,
+    )
+
+
+def _check_binary_arch(
+    arch_table: DpkgArchTable,
+    binary_arch: str,
+    declared_arch: str,
+) -> bool:
+    if binary_arch == "all":
+        return True
+    arch_wildcards = declared_arch.split()
+    for arch_wildcard in arch_wildcards:
+        if arch_table.matches_architecture(binary_arch, arch_wildcard):
+            return True
+    return False
+
+
+class BinaryPackage:
+    __slots__ = [
+        "_package_fields",
+        "_dbgsym_binary_package",
+        "_should_be_acted_on",
+        "_dpkg_architecture_variables",
+        "_declared_arch_matches_output_arch",
+        "_is_main_package",
+        "_substvars",
+        "_maintscript_snippets",
+    ]
+
+    def __init__(
+        self,
+        fields: Union[Mapping[str, str], Deb822],
+        dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+        dpkg_arch_query: DpkgArchTable,
+        *,
+        is_main_package: bool = False,
+        should_be_acted_on: bool = True,
+    ) -> None:
+        super(BinaryPackage, self).__init__()
+        # Typing-wise, Deb822 is *not* a Mapping[str, str] but it behaves enough
+        # like one that we rely on it and just cast it.
+        self._package_fields = cast("Mapping[str, str]", fields)
+        self._dbgsym_binary_package = None
+        self._should_be_acted_on = should_be_acted_on
+        self._dpkg_architecture_variables = dpkg_architecture_variables
+        self._is_main_package = is_main_package
+        self._declared_arch_matches_output_arch = _check_binary_arch(
+            dpkg_arch_query, self.resolved_architecture, self.declared_architecture
+        )
+
+    @property
+    def name(self) -> str:
+        return self.fields["Package"]
+
+    @property
+    def archive_section(self) -> str:
+        value = self.fields.get("Section")
+        if value is None:
+            return "Unknown"
+        return value
+
+    @property
+    def archive_component(self) -> str:
+        component = ""
+        section = self.archive_section
+        if "/" in section:
+            component = section.rsplit("/", 1)[0]
+            # The "main" component is always shortened to ""
+            if component == "main":
+                component = ""
+        return component
+
+    @property
+    def is_essential(self) -> bool:
+        return self._package_fields.get("Essential") == "yes"
+
+    @property
+    def is_udeb(self) -> bool:
+        return self.package_type == UDEB_PACKAGE_TYPE
+
+    @property
+    def should_be_acted_on(self) -> bool:
+        return self._should_be_acted_on and self._declared_arch_matches_output_arch
+
+    @property
+    def fields(self) -> Mapping[str, str]:
+        return self._package_fields
+
+    @property
+    def resolved_architecture(self) -> str:
+        arch = self.declared_architecture
+        if arch == "all":
+            return arch
+        if self._x_dh_build_for_type == "target":
+            return self._dpkg_architecture_variables["DEB_TARGET_ARCH"]
+        return self._dpkg_architecture_variables.current_host_arch
+
+    def package_deb_architecture_variable(self, variable_suffix: str) -> str:
+        if self._x_dh_build_for_type == "target":
+            return self._dpkg_architecture_variables[f"DEB_TARGET_{variable_suffix}"]
+        return self._dpkg_architecture_variables[f"DEB_HOST_{variable_suffix}"]
+
+    @property
+    def deb_multiarch(self) -> str:
+        return self.package_deb_architecture_variable("MULTIARCH")
+
+    @property
+    def _x_dh_build_for_type(self) -> str:
+        v = self._package_fields.get("X-DH-Build-For-Type")
+        if v is None:
+            return "host"
+        return v.lower()
+
+    @property
+    def package_type(self) -> str:
+        """Short for Package-Type (with proper default if absent)"""
+        v = self.fields.get("Package-Type")
+        if v is None:
+            return DEFAULT_PACKAGE_TYPE
+        return v
+
+    @property
+    def is_main_package(self) -> bool:
+        return self._is_main_package
+
+    def cross_command(self, command: str) -> str:
+        arch_table = self._dpkg_architecture_variables
+        if self._x_dh_build_for_type == "target":
+            target_gnu_type = arch_table["DEB_TARGET_GNU_TYPE"]
+            if arch_table["DEB_HOST_GNU_TYPE"] != target_gnu_type:
+                return f"{target_gnu_type}-{command}"
+        if arch_table.is_cross_compiling:
+            return f"{arch_table['DEB_HOST_GNU_TYPE']}-{command}"
+        return command
+
+    @property
+    def declared_architecture(self) -> str:
+        return self.fields["Architecture"]
+
+    @property
+    def is_arch_all(self) -> bool:
+        return self.declared_architecture == "all"
+
+
+class SourcePackage:
+    __slots__ = ("_package_fields",)
+
+    def __init__(self, fields: Union[Mapping[str, str], Deb822]):
+        # Typing-wise, Deb822 is *not* a Mapping[str, str] but it behaves enough
+        # like one that we rely on it and just cast it.
+        self._package_fields = cast("Mapping[str, str]", fields)
+
+    @property
+    def fields(self) -> Mapping[str, str]:
+        return self._package_fields
+
+    @property
+    def name(self) -> str:
+        return self._package_fields["Source"]
diff --git a/src/debputy/packaging/__init__.py b/src/debputy/packaging/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/packaging/__init__.py
diff --git a/src/debputy/packaging/alternatives.py b/src/debputy/packaging/alternatives.py
new file mode 100644
index 0000000..249fa9e
--- /dev/null
+++ b/src/debputy/packaging/alternatives.py
@@ -0,0 +1,225 @@
+import textwrap
+from typing import List, Dict, Tuple, Mapping
+
+from debian.deb822 import Deb822
+
+from debputy.maintscript_snippet import MaintscriptSnippetContainer, MaintscriptSnippet
+from debputy.packager_provided_files import PackagerProvidedFile
+from debputy.packages import BinaryPackage
+from debputy.packaging.makeshlibs import resolve_reserved_provided_file
+from debputy.plugin.api import VirtualPath
+from debputy.util import _error, escape_shell, POSTINST_DEFAULT_CONDITION
+
+# Match debhelper (minus one space in each end, which comes
+# via join).
+LINE_PREFIX = "\\\n            "
+
+
+def process_alternatives(
+    binary_package: BinaryPackage,
+    fs_root: VirtualPath,
+    reserved_packager_provided_files: Dict[str, List[PackagerProvidedFile]],
+    maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+) -> None:
+    if binary_package.is_udeb:
+        return
+
+    provided_alternatives_file = resolve_reserved_provided_file(
+        "alternatives",
+        reserved_packager_provided_files,
+    )
+    if provided_alternatives_file is None:
+        return
+
+    with provided_alternatives_file.open() as fd:
+        alternatives = list(Deb822.iter_paragraphs(fd))
+
+    for no, alternative in enumerate(alternatives):
+        process_alternative(
+            provided_alternatives_file.fs_path,
+            fs_root,
+            alternative,
+            no,
+            maintscript_snippets,
+        )
+
+
+def process_alternative(
+    provided_alternatives_fs_path: str,
+    fs_root: VirtualPath,
+    alternative_deb822: Deb822,
+    no: int,
+    maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+) -> None:
+    name = _mandatory_key(
+        "Name",
+        alternative_deb822,
+        provided_alternatives_fs_path,
+        f"Stanza number {no}",
+    )
+    error_context = f"Alternative named {name}"
+    link_path = _mandatory_key(
+        "Link",
+        alternative_deb822,
+        provided_alternatives_fs_path,
+        error_context,
+    )
+    impl_path = _mandatory_key(
+        "Alternative",
+        alternative_deb822,
+        provided_alternatives_fs_path,
+        error_context,
+    )
+    priority = _mandatory_key(
+        "Priority",
+        alternative_deb822,
+        provided_alternatives_fs_path,
+        error_context,
+    )
+    if "/" in name:
+        _error(
+            f'The "Name" ({link_path}) key must be a basename and cannot contain slashes'
+            f" ({error_context} in {provided_alternatives_fs_path})"
+        )
+    if link_path == impl_path:
+        _error(
+            f'The "Link" key and the "Alternative" key must not have the same value'
+            f" ({error_context} in {provided_alternatives_fs_path})"
+        )
+    impl = fs_root.lookup(impl_path)
+    if impl is None or impl.is_dir:
+        _error(
+            f'The path listed in "Alternative" ("{impl_path}") does not exist'
+            f" in the package. ({error_context} in {provided_alternatives_fs_path})"
+        )
+    for key in ["Slave", "Slaves", "Slave-Links"]:
+        if key in alternative_deb822:
+            _error(
+                f'Please use "Dependents" instead of "{key}".'
+                f" ({error_context} in {provided_alternatives_fs_path})"
+            )
+    dependents = alternative_deb822.get("Dependents")
+    install_command = [
+        escape_shell(
+            "update-alternatives",
+            "--install",
+            link_path,
+            name,
+            impl_path,
+            priority,
+        )
+    ]
+    remove_command = [
+        escape_shell(
+            "update-alternatives",
+            "--remove",
+            link_path,
+            impl_path,
+        )
+    ]
+    if dependents:
+        seen_link_path = set()
+        for line in dependents.splitlines():
+            line = line.strip()
+            if not line:  # First line is usually empty
+                continue
+            dlink_path, dlink_name, dimpl_path = parse_dependent_link(
+                line,
+                error_context,
+                provided_alternatives_fs_path,
+            )
+            if dlink_path in seen_link_path:
+                _error(
+                    f'The Dependent link path "{dlink_path}" was used twice.'
+                    f" ({error_context} in {provided_alternatives_fs_path})"
+                )
+            dimpl = fs_root.lookup(dimpl_path)
+            if dimpl is None or dimpl.is_dir:
+                _error(
+                    f'The path listed in "Dependents" ("{dimpl_path}") does not exist'
+                    f" in the package. ({error_context} in {provided_alternatives_fs_path})"
+                )
+            seen_link_path.add(dlink_path)
+            install_command.append(LINE_PREFIX)
+            install_command.append(
+                escape_shell(
+                    # update-alternatives still uses this old option name :-/
+                    "--slave",
+                    dlink_path,
+                    dlink_name,
+                    dimpl_path,
+                )
+            )
+    postinst = textwrap.dedent(
+        """\
+    if {CONDITION}; then
+        {COMMAND}
+    fi
+    """
+    ).format(
+        CONDITION=POSTINST_DEFAULT_CONDITION,
+        COMMAND=" ".join(install_command),
+    )
+
+    prerm = textwrap.dedent(
+        """\
+    if [ "$1" = "remove" ]; then
+        {COMMAND}
+    fi
+    """
+    ).format(COMMAND=" ".join(remove_command))
+    maintscript_snippets["postinst"].append(
+        MaintscriptSnippet(
+            f"debputy (via {provided_alternatives_fs_path})",
+            snippet=postinst,
+        )
+    )
+    maintscript_snippets["prerm"].append(
+        MaintscriptSnippet(
+            f"debputy (via {provided_alternatives_fs_path})",
+            snippet=prerm,
+        )
+    )
+
+
+def parse_dependent_link(
+    line: str,
+    error_context: str,
+    provided_alternatives_file: str,
+) -> Tuple[str, str, str]:
+    parts = line.split()
+    if len(parts) != 3:
+        if len(parts) > 1:
+            pass
+        _error(
+            f"The each line in Dependents links must have exactly 3 space separated parts."
+            f' The "{line}" split into {len(parts)} part(s).'
+            f" ({error_context} in {provided_alternatives_file})"
+        )
+
+    dlink_path, dlink_name, dimpl_path = parts
+    if "/" in dlink_name:
+        _error(
+            f'The Dependent link name "{dlink_path}" must be a basename and cannot contain slashes'
+            f" ({error_context} in {provided_alternatives_file})"
+        )
+    if dlink_path == dimpl_path:
+        _error(
+            f'The Dependent Link path and Alternative must not have the same value ["{dlink_path}"]'
+            f" ({error_context} in {provided_alternatives_file})"
+        )
+    return dlink_path, dlink_name, dimpl_path
+
+
+def _mandatory_key(
+    key: str,
+    alternative_deb822: Mapping[str, str],
+    provided_alternatives_file: str,
+    error_context: str,
+) -> str:
+    try:
+        return alternative_deb822[key]
+    except KeyError:
+        _error(
+            f'Missing mandatory key "{key}" in {provided_alternatives_file} ({error_context})'
+        )
diff --git a/src/debputy/packaging/debconf_templates.py b/src/debputy/packaging/debconf_templates.py
new file mode 100644
index 0000000..b827763
--- /dev/null
+++ b/src/debputy/packaging/debconf_templates.py
@@ -0,0 +1,77 @@
+import os.path
+import shutil
+import subprocess
+import textwrap
+from typing import List, Dict
+
+from debputy.maintscript_snippet import MaintscriptSnippetContainer, MaintscriptSnippet
+from debputy.packager_provided_files import PackagerProvidedFile
+from debputy.packages import BinaryPackage
+from debputy.packaging.makeshlibs import resolve_reserved_provided_file
+from debputy.plugin.api.spec import FlushableSubstvars
+from debputy.util import _error, escape_shell
+
+# Match debhelper (minus one space in each end, which comes
+# via join).
+LINE_PREFIX = "\\\n            "
+
+
+def process_debconf_templates(
+    binary_package: BinaryPackage,
+    reserved_packager_provided_files: Dict[str, List[PackagerProvidedFile]],
+    maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+    substvars: FlushableSubstvars,
+    control_output_dir: str,
+) -> None:
+    provided_templates_file = resolve_reserved_provided_file(
+        "templates",
+        reserved_packager_provided_files,
+    )
+    if provided_templates_file is None:
+        return
+
+    templates_file = os.path.join(control_output_dir, "templates")
+    debian_dir = provided_templates_file.parent_dir
+    po_template_dir = debian_dir.get("po") if debian_dir is not None else None
+    if po_template_dir is not None and po_template_dir.is_dir:
+        with open(templates_file, "wb") as fd:
+            cmd = [
+                "po2debconf",
+                provided_templates_file.fs_path,
+            ]
+            print(f"   {escape_shell(*cmd)} > {templates_file}")
+            try:
+                subprocess.check_call(
+                    cmd,
+                    stdout=fd.fileno(),
+                )
+            except subprocess.CalledProcessError:
+                _error(
+                    f"Failed to generate the templates files for {binary_package.name}. Please review "
+                    f" the output of {escape_shell('po-debconf', provided_templates_file.fs_path)}"
+                    " to understand the issue."
+                )
+    else:
+        shutil.copyfile(provided_templates_file.fs_path, templates_file)
+
+    dependency = (
+        "cdebconf-udeb" if binary_package.is_udeb else "debconf (>= 0.5) | debconf-2.0"
+    )
+    substvars.add_dependency("misc:Depends", dependency)
+    if not binary_package.is_udeb:
+        # udebs do not have `postrm` scripts
+        maintscript_snippets["postrm"].append(
+            MaintscriptSnippet(
+                f"debputy (due to {provided_templates_file.fs_path})",
+                # FIXME: `debconf` sourcing should be an overarching feature
+                snippet=textwrap.dedent(
+                    """\
+                    if [ "$1" = purge ] && [ -e /usr/share/debconf/confmodule ]; then
+                        . /usr/share/debconf/confmodule
+                        db_purge
+                        db_stop
+                    fi
+                """
+                ),
+            )
+        )
diff --git a/src/debputy/packaging/makeshlibs.py b/src/debputy/packaging/makeshlibs.py
new file mode 100644
index 0000000..127a64d
--- /dev/null
+++ b/src/debputy/packaging/makeshlibs.py
@@ -0,0 +1,314 @@
+import collections
+import dataclasses
+import os
+import re
+import shutil
+import stat
+import subprocess
+import tempfile
+from contextlib import suppress
+from typing import Optional, Set, List, Tuple, TYPE_CHECKING, Dict, IO
+
+from debputy import elf_util
+from debputy.elf_util import ELF_LINKING_TYPE_DYNAMIC
+from debputy.exceptions import DebputyDpkgGensymbolsError
+from debputy.packager_provided_files import PackagerProvidedFile
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import VirtualPath, PackageProcessingContext, BinaryCtrlAccessor
+from debputy.util import (
+    print_command,
+    escape_shell,
+    assume_not_none,
+    _normalize_link_target,
+    _warn,
+    _error,
+)
+
+if TYPE_CHECKING:
+    from debputy.highlevel_manifest import HighLevelManifest
+
+
+HAS_SONAME = re.compile(r"\s+SONAME\s+(\S+)")
+SHLIBS_LINE_READER = re.compile(r"^(?:(\S*):)?\s*(\S+)\s*(\S+)\s*(\S.+)$")
+SONAME_FORMATS = [
+    re.compile(r"\s+SONAME\s+((.*)[.]so[.](.*))"),
+    re.compile(r"\s+SONAME\s+((.*)-(\d.*)[.]so)"),
+]
+
+
+@dataclasses.dataclass
+class SONAMEInfo:
+    path: VirtualPath
+    full_soname: str
+    library: str
+    major_version: Optional[str]
+
+
+class ShlibsContent:
+    def __init__(self) -> None:
+        self._deb_lines: List[str] = []
+        self._udeb_lines: List[str] = []
+        self._seen: Set[Tuple[str, str, str]] = set()
+
+    def add_library(
+        self,
+        library: str,
+        major_version: str,
+        dependency: str,
+        *,
+        udeb_dependency: Optional[str] = None,
+    ) -> None:
+        line = f"{library} {major_version} {dependency}\n"
+        seen_key = ("deb", library, major_version)
+        if seen_key not in self._seen:
+            self._deb_lines.append(line)
+            self._seen.add(seen_key)
+        if udeb_dependency is not None:
+            seen_key = ("udeb", library, major_version)
+            udeb_line = f"udeb: {library} {major_version} {udeb_dependency}\n"
+            if seen_key not in self._seen:
+                self._udeb_lines.append(udeb_line)
+                self._seen.add(seen_key)
+
+    def __bool__(self) -> bool:
+        return bool(self._deb_lines) or bool(self._udeb_lines)
+
+    def add_entries_from_shlibs_file(self, fd: IO[str]) -> None:
+        for line in fd:
+            if line.startswith("#") or line.isspace():
+                continue
+            m = SHLIBS_LINE_READER.match(line)
+            if not m:
+                continue
+            shtype, library, major_version, dependency = m.groups()
+            if shtype is None or shtype == "":
+                shtype = "deb"
+            seen_key = (shtype, library, major_version)
+            if seen_key in self._seen:
+                continue
+            self._seen.add(seen_key)
+            if shtype == "udeb":
+                self._udeb_lines.append(line)
+            else:
+                self._deb_lines.append(line)
+
+    def write_to(self, fd: IO[str]) -> None:
+        fd.writelines(self._deb_lines)
+        fd.writelines(self._udeb_lines)
+
+
+def extract_so_name(
+    binary_package: BinaryPackage,
+    path: VirtualPath,
+) -> Optional[SONAMEInfo]:
+    objdump = binary_package.cross_command("objdump")
+    output = subprocess.check_output([objdump, "-p", path.fs_path], encoding="utf-8")
+    for r in SONAME_FORMATS:
+        m = r.search(output)
+        if m:
+            full_soname, library, major_version = m.groups()
+            return SONAMEInfo(path, full_soname, library, major_version)
+    m = HAS_SONAME.search(output)
+    if not m:
+        return None
+    full_soname = m.group(1)
+    return SONAMEInfo(path, full_soname, full_soname, None)
+
+
+def extract_soname_info(
+    binary_package: BinaryPackage,
+    fs_root: VirtualPath,
+) -> List[SONAMEInfo]:
+    so_files = elf_util.find_all_elf_files(
+        fs_root,
+        with_linking_type=ELF_LINKING_TYPE_DYNAMIC,
+    )
+    result = []
+    for so_file in so_files:
+        soname_info = extract_so_name(binary_package, so_file)
+        if not soname_info:
+            continue
+        result.append(soname_info)
+    return result
+
+
+def _compute_shlibs_content(
+    binary_package: BinaryPackage,
+    manifest: "HighLevelManifest",
+    soname_info_list: List[SONAMEInfo],
+    udeb_package_name: Optional[str],
+    combined_shlibs: ShlibsContent,
+) -> Tuple[ShlibsContent, bool]:
+    shlibs_file_contents = ShlibsContent()
+    unversioned_so_seen = False
+    strict_version = manifest.package_state_for(binary_package.name).binary_version
+    if strict_version is not None:
+        upstream_version = re.sub(r"-[^-]+$", "", strict_version)
+    else:
+        strict_version = manifest.substitution.substitute(
+            "{{DEB_VERSION}}", "<internal-usage>"
+        )
+        upstream_version = manifest.substitution.substitute(
+            "{{DEB_VERSION_EPOCH_UPSTREAM}}", "<internal-usage>"
+        )
+
+    dependency = f"{binary_package.name} (>= {upstream_version})"
+    strict_dependency = f"{binary_package.name} (= {strict_version})"
+    udeb_dependency = None
+
+    if udeb_package_name is not None:
+        udeb_dependency = f"{udeb_package_name} (>= {upstream_version})"
+
+    for soname_info in soname_info_list:
+        if soname_info.major_version is None:
+            unversioned_so_seen = True
+            continue
+        shlibs_file_contents.add_library(
+            soname_info.library,
+            soname_info.major_version,
+            dependency,
+            udeb_dependency=udeb_dependency,
+        )
+        combined_shlibs.add_library(
+            soname_info.library,
+            soname_info.major_version,
+            strict_dependency,
+            udeb_dependency=udeb_dependency,
+        )
+
+    return shlibs_file_contents, unversioned_so_seen
+
+
+def resolve_reserved_provided_file(
+    basename: str,
+    reserved_packager_provided_files: Dict[str, List[PackagerProvidedFile]],
+) -> Optional[VirtualPath]:
+    matches = reserved_packager_provided_files.get(basename)
+    if matches is None:
+        return None
+    assert len(matches) < 2
+    if matches:
+        return matches[0].path
+    return None
+
+
+def generate_shlib_dirs(
+    pkg: BinaryPackage,
+    root_dir: str,
+    soname_info_list: List[SONAMEInfo],
+    materialized_dirs: List[str],
+) -> None:
+    dir_scanned: Dict[str, Dict[str, Set[str]]] = {}
+    dirs: Dict[str, str] = {}
+
+    for soname_info in soname_info_list:
+        elf_binary = soname_info.path
+        p = assume_not_none(elf_binary.parent_dir)
+        matches = dir_scanned.get(p.absolute)
+        materialized_dir = dirs.get(p.absolute)
+        if matches is None:
+            matches = collections.defaultdict(set)
+            for child in p.iterdir:
+                if not child.is_symlink:
+                    continue
+                target = _normalize_link_target(child.readlink())
+                if "/" in target:
+                    # The shlib symlinks (we are interested in) are relative to the same folder
+                    continue
+                matches[target].add(child.name)
+            dir_scanned[p.absolute] = matches
+        symlinks = matches.get(elf_binary.name)
+        if not symlinks:
+            _warn(
+                f"Could not find any SO symlinks pointing to {elf_binary.absolute} in {pkg.name} !?"
+            )
+            continue
+        if materialized_dir is None:
+            materialized_dir = tempfile.mkdtemp(prefix=f"{pkg.name}_", dir=root_dir)
+            materialized_dirs.append(materialized_dir)
+            dirs[p.absolute] = materialized_dir
+
+        os.symlink(elf_binary.fs_path, os.path.join(materialized_dir, elf_binary.name))
+        for link in symlinks:
+            os.symlink(elf_binary.name, os.path.join(materialized_dir, link))
+
+
+def compute_shlibs(
+    binary_package: BinaryPackage,
+    control_output_dir: str,
+    fs_root: VirtualPath,
+    manifest: "HighLevelManifest",
+    udeb_package_name: Optional[str],
+    ctrl: BinaryCtrlAccessor,
+    reserved_packager_provided_files: Dict[str, List[PackagerProvidedFile]],
+    combined_shlibs: ShlibsContent,
+) -> List[SONAMEInfo]:
+    assert not binary_package.is_udeb
+    shlibs_file = os.path.join(control_output_dir, "shlibs")
+    need_ldconfig = False
+    so_files = elf_util.find_all_elf_files(
+        fs_root,
+        with_linking_type=ELF_LINKING_TYPE_DYNAMIC,
+    )
+    sonames = extract_soname_info(binary_package, fs_root)
+    provided_shlibs_file = resolve_reserved_provided_file(
+        "shlibs",
+        reserved_packager_provided_files,
+    )
+    symbols_template_file = resolve_reserved_provided_file(
+        "symbols",
+        reserved_packager_provided_files,
+    )
+
+    if provided_shlibs_file:
+        need_ldconfig = True
+        unversioned_so_seen = False
+        shutil.copyfile(provided_shlibs_file.fs_path, shlibs_file)
+        with open(shlibs_file) as fd:
+            combined_shlibs.add_entries_from_shlibs_file(fd)
+    else:
+        shlibs_file_contents, unversioned_so_seen = _compute_shlibs_content(
+            binary_package,
+            manifest,
+            sonames,
+            udeb_package_name,
+            combined_shlibs,
+        )
+
+        if shlibs_file_contents:
+            need_ldconfig = True
+            with open(shlibs_file, "wt", encoding="utf-8") as fd:
+                shlibs_file_contents.write_to(fd)
+
+    if symbols_template_file:
+        symbols_file = os.path.join(control_output_dir, "symbols")
+        symbols_cmd = [
+            "dpkg-gensymbols",
+            f"-p{binary_package.name}",
+            f"-I{symbols_template_file.fs_path}",
+            f"-P{control_output_dir}",
+            f"-O{symbols_file}",
+        ]
+
+        if so_files:
+            symbols_cmd.extend(f"-e{x.fs_path}" for x in so_files)
+            print_command(*symbols_cmd)
+            try:
+                subprocess.check_call(symbols_cmd)
+            except subprocess.CalledProcessError as e:
+                # Wrap in a special error, so debputy can run the other packages.
+                # The kde symbols helper relies on this behaviour
+                raise DebputyDpkgGensymbolsError(
+                    f"Error while running command for {binary_package.name}: {escape_shell(*symbols_cmd)}"
+                ) from e
+
+        with suppress(FileNotFoundError):
+            st = os.stat(symbols_file)
+            if stat.S_ISREG(st.st_mode) and st.st_size == 0:
+                os.unlink(symbols_file)
+            elif unversioned_so_seen:
+                need_ldconfig = True
+
+    if need_ldconfig:
+        ctrl.dpkg_trigger("activate-noawait", "ldconfig")
+    return sonames
diff --git a/src/debputy/path_matcher.py b/src/debputy/path_matcher.py
new file mode 100644
index 0000000..47e5c91
--- /dev/null
+++ b/src/debputy/path_matcher.py
@@ -0,0 +1,529 @@
+import fnmatch
+import glob
+import itertools
+import os
+import re
+from enum import Enum
+from typing import (
+    Callable,
+    Optional,
+    TypeVar,
+    Iterable,
+    Union,
+    Sequence,
+    Tuple,
+)
+
+from debputy.intermediate_manifest import PathType
+from debputy.plugin.api import VirtualPath
+from debputy.substitution import Substitution, NULL_SUBSTITUTION
+from debputy.types import VP
+from debputy.util import _normalize_path, _error, escape_shell
+
+MR = TypeVar("MR")
+_GLOB_PARTS = re.compile(r"[*?]|\[]?[^]]+]")
+
+
+def _lookup_path(fs_root: VP, path: str) -> Optional[VP]:
+    if not path.startswith("./"):
+        raise ValueError("Directory must be normalized (and not the root directory)")
+    if fs_root.name != "." or fs_root.parent_dir is not None:
+        raise ValueError("Provided fs_root must be the root directory")
+    # TODO: Strictly speaking, this is unsound. (E.g., FSRootDir does not return FSRootDir on a lookup)
+    return fs_root.lookup(path[2:])
+
+
+def _compile_basename_glob(
+    basename_glob: str,
+) -> Tuple[Optional[str], Callable[[str], bool]]:
+    remainder = None
+    if not glob.has_magic(basename_glob):
+        return escape_shell(basename_glob), lambda x: x == basename_glob
+
+    if basename_glob.startswith("*"):
+        if basename_glob.endswith("*"):
+            remainder = basename_glob[1:-1]
+            possible_quick_match = lambda x: remainder in x
+            escaped_pattern = "*" + escape_shell(remainder) + "*"
+        else:
+            remainder = basename_glob[1:]
+            possible_quick_match = lambda x: x.endswith(remainder)
+            escaped_pattern = "*" + escape_shell(remainder)
+    else:
+        remainder = basename_glob[:-1]
+        possible_quick_match = lambda x: x.startswith(remainder)
+        escaped_pattern = escape_shell(remainder) + "*"
+
+    if not glob.has_magic(remainder):
+        return escaped_pattern, possible_quick_match
+    slow_pattern = re.compile(fnmatch.translate(basename_glob))
+    return None, lambda x: bool(slow_pattern.match(x))
+
+
+def _apply_match(
+    fs_path: VP,
+    match_part: Union[Callable[[str], bool], str],
+) -> Iterable[VP]:
+    if isinstance(match_part, str):
+        m = fs_path.lookup(match_part)
+        if m:
+            yield m
+    else:
+        yield from (p for p in fs_path.iterdir if match_part(p.name))
+
+
+class MatchRuleType(Enum):
+    EXACT_MATCH = "exact"
+    BASENAME_GLOB = "basename-glob"
+    DIRECT_CHILDREN_OF_DIR = "direct-children-of-dir"
+    ANYTHING_BENEATH_DIR = "anything-beneath-dir"
+    GENERIC_GLOB = "generic-glob"
+    MATCH_ANYTHING = "match-anything"
+
+
+class MatchRule:
+    __slots__ = ("_rule_type",)
+
+    def __init__(self, rule_type: MatchRuleType) -> None:
+        self._rule_type = rule_type
+
+    @property
+    def rule_type(self) -> MatchRuleType:
+        return self._rule_type
+
+    def finditer(
+        self,
+        fs_root: VP,
+        *,
+        ignore_paths: Optional[Callable[[VP], bool]] = None,
+    ) -> Iterable[VP]:
+        # TODO: Strictly speaking, this is unsound. (E.g., FSRootDir does not return FSRootDir on a lookup)
+        raise NotImplementedError
+
+    def _full_pattern(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def path_type(self) -> Optional[PathType]:
+        return None
+
+    def describe_match_short(self) -> str:
+        return self._full_pattern()
+
+    def describe_match_exact(self) -> str:
+        raise NotImplementedError
+
+    def shell_escape_pattern(self) -> str:
+        raise TypeError("Pattern not suitable or not supported for shell escape")
+
+    @classmethod
+    def recursive_beneath_directory(
+        cls,
+        directory: str,
+        definition_source: str,
+        path_type: Optional[PathType] = None,
+        substitution: Substitution = NULL_SUBSTITUTION,
+    ) -> "MatchRule":
+        if directory in (".", "/"):
+            return MATCH_ANYTHING
+        assert not glob.has_magic(directory)
+        return DirectoryBasedMatch(
+            MatchRuleType.ANYTHING_BENEATH_DIR,
+            substitution.substitute(_normalize_path(directory), definition_source),
+            path_type=path_type,
+        )
+
+    @classmethod
+    def from_path_or_glob(
+        cls,
+        path_or_glob: str,
+        definition_source: str,
+        path_type: Optional[PathType] = None,
+        substitution: Substitution = NULL_SUBSTITUTION,
+    ) -> "MatchRule":
+        # TODO: Handle '{a,b,c}' patterns too
+        # FIXME: Better error handling!
+        normalized_no_prefix = _normalize_path(path_or_glob, with_prefix=False)
+        if path_or_glob in ("*", "**/*", ".", "/"):
+            assert path_type is None
+            return MATCH_ANYTHING
+
+        # We do not support {a,b} at the moment. This check is not perfect, but it should catch the most obvious
+        # unsupported usage.
+        if (
+            "{" in path_or_glob
+            and ("," in path_or_glob or ".." in path_or_glob)
+            and re.search(r"[{][^},.]*(?:,|[.][.])[^},.]*[}]", path_or_glob)
+        ):
+            m = re.search(r"(.*)[{]([^},.]*(?:,|[.][.])[^},.]*[}])", path_or_glob)
+            assert m is not None
+            replacement = m.group(1) + "{{OPEN_CURLY_BRACE}}" + m.group(2)
+            _error(
+                f'The pattern "{path_or_glob}" (defined in {definition_source}) looks like it contains a'
+                f' brace expansion (such as "{{a,b}}" or "{{a..b}}").  Brace expansions are not supported.'
+                " If you wanted to match the literal path a brace in it, please use a substitution to insert"
+                f' the opening brace.  As an example: "{replacement}"'
+            )
+
+        normalized_with_prefix = "./" + normalized_no_prefix
+        # TODO: Check for escapes here  "foo[?]/bar" can be written as an exact match for foo?/bar
+        # - similar holds for "foo[?]/*" being a directory match (etc.).
+        if not glob.has_magic(normalized_with_prefix):
+            assert path_type is None
+            return ExactFileSystemPath(
+                substitution.substitute(normalized_with_prefix, definition_source)
+            )
+
+        directory = os.path.dirname(normalized_with_prefix)
+        basename = os.path.basename(normalized_with_prefix)
+
+        if ("**" in directory and directory != "./**") or "**" in basename:
+            raise ValueError(
+                f'Cannot process pattern "{path_or_glob}" from {definition_source}: The double-star'
+                ' glob ("**") is not supported in general.  Only "**/<basename-glob>" supported.'
+            )
+
+        if basename == "*" and not glob.has_magic(directory):
+            return DirectoryBasedMatch(
+                MatchRuleType.DIRECT_CHILDREN_OF_DIR,
+                substitution.substitute(directory, definition_source),
+                path_type=path_type,
+            )
+        elif directory == "./**" or not glob.has_magic(directory):
+            basename_glob = substitution.substitute(
+                basename, definition_source, escape_glob_characters=True
+            )
+            if directory in (".", "./**"):
+                return BasenameGlobMatch(
+                    basename_glob,
+                    path_type=path_type,
+                    recursive_match=True,
+                )
+            return BasenameGlobMatch(
+                basename_glob,
+                only_when_in_directory=substitution.substitute(
+                    directory, definition_source
+                ),
+                path_type=path_type,
+                recursive_match=False,
+            )
+
+        return GenericGlobImplementation(normalized_with_prefix, path_type=path_type)
+
+
+def _match_file_type(path_type: PathType, path: VirtualPath) -> bool:
+    if path_type == PathType.FILE and path.is_file:
+        return True
+    if path_type == PathType.DIRECTORY and path.is_dir:
+        return True
+    if path_type == PathType.SYMLINK and path.is_symlink:
+        return True
+    assert path_type in (PathType.FILE, PathType.DIRECTORY, PathType.SYMLINK)
+    return False
+
+
+class MatchAnything(MatchRule):
+    def __init__(self) -> None:
+        super().__init__(MatchRuleType.MATCH_ANYTHING)
+
+    def _full_pattern(self) -> str:
+        return "**/*"
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        if ignore_paths is not None:
+            yield from (p for p in fs_root.all_paths() if not ignore_paths(p))
+        yield from fs_root.all_paths()
+
+    def describe_match_exact(self) -> str:
+        return "**/* (Match anything)"
+
+
+MATCH_ANYTHING: MatchRule = MatchAnything()
+
+del MatchAnything
+
+
+class ExactFileSystemPath(MatchRule):
+    __slots__ = "_path"
+
+    def __init__(self, path: str) -> None:
+        super().__init__(MatchRuleType.EXACT_MATCH)
+        self._path = path
+
+    def _full_pattern(self) -> str:
+        return self._path
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        p = _lookup_path(fs_root, self._path)
+        if p is not None and (ignore_paths is None or not ignore_paths(p)):
+            yield p
+
+    def describe_match_exact(self) -> str:
+        return f"{self._path} (the exact path / no globbing)"
+
+    @property
+    def path(self) -> str:
+        return self._path
+
+    def shell_escape_pattern(self) -> str:
+        return escape_shell(self._path.lstrip("."))
+
+
+class DirectoryBasedMatch(MatchRule):
+    __slots__ = "_directory", "_path_type"
+
+    def __init__(
+        self,
+        rule_type: MatchRuleType,
+        directory: str,
+        path_type: Optional[PathType] = None,
+    ) -> None:
+        super().__init__(rule_type)
+        self._directory = directory
+        self._path_type = path_type
+        assert rule_type in (
+            MatchRuleType.DIRECT_CHILDREN_OF_DIR,
+            MatchRuleType.ANYTHING_BENEATH_DIR,
+        )
+        assert not self._directory.endswith("/")
+
+    def _full_pattern(self) -> str:
+        return self._directory
+
+    def finditer(
+        self,
+        fs_root: VP,
+        *,
+        ignore_paths: Optional[Callable[[VP], bool]] = None,
+    ) -> Iterable[VP]:
+        p = _lookup_path(fs_root, self._directory)
+        if p is None or not p.is_dir:
+            return
+        if self._rule_type == MatchRuleType.ANYTHING_BENEATH_DIR:
+            path_iter = p.all_paths()
+        else:
+            path_iter = p.iterdir
+        if ignore_paths is not None:
+            path_iter = (p for p in path_iter if not ignore_paths(p))
+        if self._path_type is None:
+            yield from path_iter
+        else:
+            yield from (m for m in path_iter if _match_file_type(self._path_type, m))
+
+    def describe_match_short(self) -> str:
+        path_type_match = (
+            ""
+            if self._path_type is None
+            else f" <only for path type {self._path_type.manifest_key}>"
+        )
+        if self._rule_type == MatchRuleType.ANYTHING_BENEATH_DIR:
+            return f"{self._directory}/**/*{path_type_match}"
+        return f"{self._directory}/*{path_type_match}"
+
+    def describe_match_exact(self) -> str:
+        if self._rule_type == MatchRuleType.ANYTHING_BENEATH_DIR:
+            return f"{self._directory}/**/* (anything below the directory)"
+        return f"{self.describe_match_short()} (anything directly in the directory)"
+
+    @property
+    def path_type(self) -> Optional[PathType]:
+        return self._path_type
+
+    @property
+    def directory(self) -> str:
+        return self._directory
+
+    def shell_escape_pattern(self) -> str:
+        if self._rule_type == MatchRuleType.ANYTHING_BENEATH_DIR:
+            return super().shell_escape_pattern()
+        return escape_shell(self._directory.lstrip(".")) + "/*"
+
+
+class BasenameGlobMatch(MatchRule):
+    __slots__ = (
+        "_basename_glob",
+        "_directory",
+        "_matcher",
+        "_path_type",
+        "_recursive_match",
+        "_escaped_basename_pattern",
+    )
+
+    def __init__(
+        self,
+        basename_glob: str,
+        only_when_in_directory: Optional[str] = None,
+        path_type: Optional[PathType] = None,
+        recursive_match: Optional[bool] = None,  # TODO: Can this just be = False (?)
+    ) -> None:
+        super().__init__(MatchRuleType.BASENAME_GLOB)
+        self._basename_glob = basename_glob
+        self._directory = only_when_in_directory
+        self._path_type = path_type
+        self._recursive_match = recursive_match
+        if self._directory is None and not recursive_match:
+            self._recursive_match = True
+        assert self._directory is None or not self._directory.endswith("/")
+        assert "/" not in basename_glob  # Not a basename if it contains /
+        assert "**" not in basename_glob  # Also not a (true) basename if it has **
+        self._escaped_basename_pattern, self._matcher = _compile_basename_glob(
+            basename_glob
+        )
+
+    def _full_pattern(self) -> str:
+        if self._directory is not None:
+            maybe_recursive = "**/" if self._recursive_match else ""
+            return f"{self._directory}/{maybe_recursive}{self._basename_glob}"
+        return self._basename_glob
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        search_root = fs_root
+        if self._directory is not None:
+            p = _lookup_path(fs_root, self._directory)
+            if p is None or not p.is_dir:
+                return
+            search_root = p
+        path_iter = (
+            search_root.all_paths() if self._recursive_match else search_root.iterdir
+        )
+        if ignore_paths is not None:
+            path_iter = (p for p in path_iter if not ignore_paths(p))
+        if self._path_type is None:
+            yield from (m for m in path_iter if self._matcher(m.name))
+        else:
+            yield from (
+                m
+                for m in path_iter
+                if self._matcher(m.name) and _match_file_type(self._path_type, m)
+            )
+
+    def describe_match_short(self) -> str:
+        path_type_match = (
+            ""
+            if self._path_type is None
+            else f" <only for path type {self._path_type.manifest_key}>"
+        )
+        return (
+            self._full_pattern()
+            if path_type_match == ""
+            else f"{self._full_pattern()}{path_type_match}"
+        )
+
+    def describe_match_exact(self) -> str:
+        if self._directory is not None:
+            return f"{self.describe_match_short()} (glob / directly in the directory)"
+        return f"{self.describe_match_short()} (basename match)"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, BasenameGlobMatch):
+            return NotImplemented
+        return (
+            self._basename_glob == other._basename_glob
+            and self._directory == other._directory
+            and self._path_type == other._path_type
+            and self._recursive_match == other._recursive_match
+        )
+
+    @property
+    def path_type(self) -> Optional[PathType]:
+        return self._path_type
+
+    @property
+    def directory(self) -> Optional[str]:
+        return self._directory
+
+    def shell_escape_pattern(self) -> str:
+        if self._directory is None or self._escaped_basename_pattern is None:
+            return super().shell_escape_pattern()
+        return (
+            escape_shell(self._directory.lstrip("."))
+            + f"/{self._escaped_basename_pattern}"
+        )
+
+
+class GenericGlobImplementation(MatchRule):
+    __slots__ = "_glob_pattern", "_path_type", "_match_parts"
+
+    def __init__(
+        self,
+        glob_pattern: str,
+        path_type: Optional[PathType] = None,
+    ) -> None:
+        super().__init__(MatchRuleType.GENERIC_GLOB)
+        if glob_pattern.startswith("./"):
+            glob_pattern = glob_pattern[2:]
+        self._glob_pattern = glob_pattern
+        self._path_type = path_type
+        assert "**" not in glob_pattern  # No recursive globs
+        assert glob.has_magic(
+            glob_pattern
+        )  # If it has no glob, then it could have been an exact match
+        assert (
+            "/" in glob_pattern
+        )  # If it does not have a / then a BasenameGlob could have been used instead
+        self._match_parts = self._compile_glob()
+
+    def _full_pattern(self) -> str:
+        return self._glob_pattern
+
+    def finditer(self, fs_root: VP, *, ignore_paths=None) -> Iterable[VP]:
+        search_history = [fs_root]
+        for part in self._match_parts:
+            next_layer = itertools.chain.from_iterable(
+                _apply_match(m, part) for m in search_history
+            )
+            # TODO: Figure out why we need to materialize next_layer into a list for this to work.
+            search_history = list(next_layer)
+            if not search_history:
+                # While we have it as a list, we might as well have an "early exit".
+                return
+
+        if self._path_type is None:
+            if ignore_paths is None:
+                yield from search_history
+            else:
+                yield from (p for p in search_history if not ignore_paths(p))
+        elif ignore_paths is None:
+            yield from (
+                m for m in search_history if _match_file_type(self._path_type, m)
+            )
+        else:
+            yield from (
+                m
+                for m in search_history
+                if _match_file_type(self._path_type, m) and not ignore_paths(m)
+            )
+
+    def describe_match_short(self) -> str:
+        path_type_match = (
+            ""
+            if self._path_type is None
+            else f" <only for path type {self._path_type.manifest_key}>"
+        )
+        return (
+            self._full_pattern()
+            if path_type_match == ""
+            else f"{self._full_pattern()}{path_type_match}"
+        )
+
+    def describe_match_exact(self) -> str:
+        return f"{self.describe_match_short()} (glob)"
+
+    def _compile_glob(self) -> Sequence[Union[Callable[[str], bool], str]]:
+        assert self._glob_pattern.strip("/") == self._glob_pattern
+        return [
+            _compile_basename_glob(part) if glob.has_magic(part) else part
+            for part in self._glob_pattern.split("/")
+        ]
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, GenericGlobImplementation):
+            return NotImplemented
+        return (
+            self._glob_pattern == other._glob_pattern
+            and self._path_type == other._path_type
+        )
+
+    @property
+    def path_type(self) -> Optional[PathType]:
+        return self._path_type
diff --git a/src/debputy/plugin/__init__.py b/src/debputy/plugin/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/plugin/__init__.py
diff --git a/src/debputy/plugin/api/__init__.py b/src/debputy/plugin/api/__init__.py
new file mode 100644
index 0000000..0fa24be
--- /dev/null
+++ b/src/debputy/plugin/api/__init__.py
@@ -0,0 +1,37 @@
+from ...exceptions import (
+    DebputyPluginRuntimeError,
+    DebputyMetadataAccessError,
+)
+from .spec import (
+    DebputyPluginInitializer,
+    PackageProcessingContext,
+    MetadataAutoDetector,
+    DpkgTriggerType,
+    Maintscript,
+    VirtualPath,
+    BinaryCtrlAccessor,
+    PluginInitializationEntryPoint,
+    undocumented_attr,
+    documented_attr,
+    reference_documentation,
+    virtual_path_def,
+    packager_provided_file_reference_documentation,
+)
+
+__all__ = [
+    "DebputyPluginInitializer",
+    "PackageProcessingContext",
+    "MetadataAutoDetector",
+    "DpkgTriggerType",
+    "Maintscript",
+    "BinaryCtrlAccessor",
+    "VirtualPath",
+    "PluginInitializationEntryPoint",
+    "documented_attr",
+    "undocumented_attr",
+    "reference_documentation",
+    "virtual_path_def",
+    "DebputyPluginRuntimeError",
+    "DebputyMetadataAccessError",
+    "packager_provided_file_reference_documentation",
+]
diff --git a/src/debputy/plugin/api/example_processing.py b/src/debputy/plugin/api/example_processing.py
new file mode 100644
index 0000000..3bde8c3
--- /dev/null
+++ b/src/debputy/plugin/api/example_processing.py
@@ -0,0 +1,99 @@
+import dataclasses
+from enum import Enum
+from typing import Set, Tuple, List, cast, Dict, Sequence
+
+from debputy.filesystem_scan import build_virtual_fs
+from debputy.plugin.api import VirtualPath
+from debputy.plugin.api.impl_types import (
+    AutomaticDiscardRuleExample,
+    PluginProvidedDiscardRule,
+)
+from debputy.util import _normalize_path
+
+
+class DiscardVerdict(Enum):
+    INCONSISTENT_CODE_KEPT = (
+        None,
+        "INCONSISTENT (code kept the path, but should have discarded)",
+    )
+    INCONSISTENT_CODE_DISCARDED = (
+        None,
+        "INCONSISTENT (code discarded the path, but should have kept it)",
+    )
+    KEPT = (False, "Kept")
+    DISCARDED_BY_CODE = (True, "Discarded (directly by the rule)")
+    DISCARDED_BY_DIRECTORY = (True, "Discarded (directory was discarded)")
+
+    @property
+    def message(self) -> str:
+        return cast("str", self.value[1])
+
+    @property
+    def is_consistent(self) -> bool:
+        return self.value[0] is not None
+
+    @property
+    def is_discarded(self) -> bool:
+        return self.value[0] is True
+
+    @property
+    def is_kept(self) -> bool:
+        return self.value[0] is False
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ProcessedDiscardRuleExample:
+    rendered_paths: Sequence[Tuple[VirtualPath, DiscardVerdict]]
+    inconsistent_paths: Set[VirtualPath]
+    # To avoid the parents being garbage collected
+    fs_root: VirtualPath
+
+
+def process_discard_rule_example(
+    discard_rule: PluginProvidedDiscardRule,
+    example: AutomaticDiscardRuleExample,
+) -> ProcessedDiscardRuleExample:
+    fs_root: VirtualPath = build_virtual_fs([p for p, _ in example.content])
+
+    actual_discarded: Dict[str, bool] = {}
+    expected_output = {
+        "/" + _normalize_path(p.path_name, with_prefix=False): v
+        for p, v in example.content
+    }
+    inconsistent_paths = set()
+    rendered_paths = []
+
+    for p in fs_root.all_paths():
+        parent = p.parent_dir
+        discard_carry_over = False
+        path_name = p.absolute
+        if parent and actual_discarded[parent.absolute]:
+            verdict = True
+            discard_carry_over = True
+        else:
+            verdict = discard_rule.should_discard(p)
+
+        actual_discarded[path_name] = verdict
+        expected = expected_output.get(path_name)
+        if expected is not None:
+            inconsistent = expected != verdict
+            if inconsistent:
+                inconsistent_paths.add(p)
+        else:
+            continue
+
+        if inconsistent:
+            if verdict:
+                verdict_code = DiscardVerdict.INCONSISTENT_CODE_DISCARDED
+            else:
+                verdict_code = DiscardVerdict.INCONSISTENT_CODE_KEPT
+        elif verdict:
+            if discard_carry_over:
+                verdict_code = DiscardVerdict.DISCARDED_BY_DIRECTORY
+            else:
+                verdict_code = DiscardVerdict.DISCARDED_BY_CODE
+        else:
+            verdict_code = DiscardVerdict.KEPT
+        rendered_paths.append((p, verdict_code))
+
+    return ProcessedDiscardRuleExample(rendered_paths, inconsistent_paths, fs_root)
diff --git a/src/debputy/plugin/api/feature_set.py b/src/debputy/plugin/api/feature_set.py
new file mode 100644
index 0000000..6552361
--- /dev/null
+++ b/src/debputy/plugin/api/feature_set.py
@@ -0,0 +1,91 @@
+import dataclasses
+from typing import Dict, List, Tuple, Sequence, Any
+
+from debputy.manifest_parser.declarative_parser import ParserGenerator
+from debputy.plugin.api.impl_types import (
+    DebputyPluginMetadata,
+    PackagerProvidedFileClassSpec,
+    MetadataOrMaintscriptDetector,
+    TTP,
+    DispatchingTableParser,
+    TP,
+    SUPPORTED_DISPATCHABLE_TABLE_PARSERS,
+    DispatchingObjectParser,
+    SUPPORTED_DISPATCHABLE_OBJECT_PARSERS,
+    PluginProvidedManifestVariable,
+    PluginProvidedPackageProcessor,
+    PluginProvidedDiscardRule,
+    ServiceManagerDetails,
+    PluginProvidedKnownPackagingFile,
+    PluginProvidedTypeMapping,
+)
+
+
+@dataclasses.dataclass(slots=True)
+class PluginProvidedFeatureSet:
+    plugin_data: Dict[str, DebputyPluginMetadata] = dataclasses.field(
+        default_factory=dict
+    )
+    packager_provided_files: Dict[str, PackagerProvidedFileClassSpec] = (
+        dataclasses.field(default_factory=dict)
+    )
+    metadata_maintscript_detectors: Dict[str, List[MetadataOrMaintscriptDetector]] = (
+        dataclasses.field(default_factory=dict)
+    )
+    dispatchable_table_parsers: Dict[TTP, "DispatchingTableParser[TP]"] = (
+        dataclasses.field(
+            default_factory=lambda: {
+                rt: DispatchingTableParser(rt, path)
+                for rt, path in SUPPORTED_DISPATCHABLE_TABLE_PARSERS.items()
+            }
+        )
+    )
+    dispatchable_object_parsers: Dict[str, "DispatchingObjectParser"] = (
+        dataclasses.field(
+            default_factory=lambda: {
+                path: DispatchingObjectParser(path, parser_documentation=ref_doc)
+                for path, ref_doc in SUPPORTED_DISPATCHABLE_OBJECT_PARSERS.items()
+            }
+        )
+    )
+    manifest_variables: Dict[str, PluginProvidedManifestVariable] = dataclasses.field(
+        default_factory=dict
+    )
+    all_package_processors: Dict[Tuple[str, str], PluginProvidedPackageProcessor] = (
+        dataclasses.field(default_factory=dict)
+    )
+    auto_discard_rules: Dict[str, PluginProvidedDiscardRule] = dataclasses.field(
+        default_factory=dict
+    )
+    service_managers: Dict[str, ServiceManagerDetails] = dataclasses.field(
+        default_factory=dict
+    )
+    known_packaging_files: Dict[str, PluginProvidedKnownPackagingFile] = (
+        dataclasses.field(default_factory=dict)
+    )
+    mapped_types: Dict[Any, PluginProvidedTypeMapping] = dataclasses.field(
+        default_factory=dict
+    )
+    manifest_parser_generator: ParserGenerator = dataclasses.field(
+        default_factory=ParserGenerator
+    )
+
+    def package_processors_in_order(self) -> Sequence[PluginProvidedPackageProcessor]:
+        order = []
+        delayed = []
+        for plugin_processor in self.all_package_processors.values():
+            if not plugin_processor.dependencies:
+                order.append(plugin_processor)
+            else:
+                delayed.append(plugin_processor)
+
+        # At the time of writing, insert order will work as a plugin cannot declare
+        # dependencies out of order in the current version.  However, we want to
+        # ensure dependencies are taken a bit seriously, so we ensure that processors
+        # without dependencies are run first.  This should weed out anything that
+        # needs dependencies but do not add them.
+        #
+        # It is still far from as any dependency issues will be hidden if you just
+        # add a single dependency.
+        order.extend(delayed)
+        return order
diff --git a/src/debputy/plugin/api/impl.py b/src/debputy/plugin/api/impl.py
new file mode 100644
index 0000000..e25713f
--- /dev/null
+++ b/src/debputy/plugin/api/impl.py
@@ -0,0 +1,1926 @@
+import contextlib
+import dataclasses
+import functools
+import importlib
+import importlib.util
+import itertools
+import json
+import os
+import re
+import subprocess
+import sys
+from abc import ABC
+from json import JSONDecodeError
+from typing import (
+    Optional,
+    Callable,
+    Dict,
+    Tuple,
+    Iterable,
+    Sequence,
+    Type,
+    List,
+    Union,
+    Set,
+    Iterator,
+    IO,
+    Mapping,
+    AbstractSet,
+    cast,
+    FrozenSet,
+    Any,
+)
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy.exceptions import (
+    DebputySubstitutionError,
+    PluginConflictError,
+    PluginMetadataError,
+    PluginBaseError,
+    PluginInitializationError,
+    PluginAPIViolationError,
+    PluginNotFoundError,
+)
+from debputy.maintscript_snippet import (
+    STD_CONTROL_SCRIPTS,
+    MaintscriptSnippetContainer,
+    MaintscriptSnippet,
+)
+from debputy.manifest_parser.base_types import TypeMapping
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.plugin.api.impl_types import (
+    DebputyPluginMetadata,
+    PackagerProvidedFileClassSpec,
+    MetadataOrMaintscriptDetector,
+    PluginProvidedTrigger,
+    TTP,
+    DIPHandler,
+    PF,
+    SF,
+    DIPKWHandler,
+    PluginProvidedManifestVariable,
+    PluginProvidedPackageProcessor,
+    PluginProvidedDiscardRule,
+    AutomaticDiscardRuleExample,
+    PPFFormatParam,
+    ServiceManagerDetails,
+    resolve_package_type_selectors,
+    KnownPackagingFileInfo,
+    PluginProvidedKnownPackagingFile,
+    InstallPatternDHCompatRule,
+    PluginProvidedTypeMapping,
+)
+from debputy.plugin.api.plugin_parser import (
+    PLUGIN_METADATA_PARSER,
+    PluginJsonMetadata,
+    PLUGIN_PPF_PARSER,
+    PackagerProvidedFileJsonDescription,
+    PLUGIN_MANIFEST_VARS_PARSER,
+    PLUGIN_KNOWN_PACKAGING_FILES_PARSER,
+)
+from debputy.plugin.api.spec import (
+    MaintscriptAccessor,
+    Maintscript,
+    DpkgTriggerType,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+    MetadataAutoDetector,
+    PluginInitializationEntryPoint,
+    DebputyPluginInitializer,
+    PackageTypeSelector,
+    FlushableSubstvars,
+    ParserDocumentation,
+    PackageProcessor,
+    VirtualPath,
+    ServiceIntegrator,
+    ServiceDetector,
+    ServiceRegistry,
+    ServiceDefinition,
+    DSD,
+    ServiceUpgradeRule,
+    PackagerProvidedFileReferenceDocumentation,
+    packager_provided_file_reference_documentation,
+    TypeMappingDocumentation,
+)
+from debputy.substitution import (
+    Substitution,
+    VariableNameState,
+    SUBST_VAR_RE,
+    VariableContext,
+)
+from debputy.util import (
+    _normalize_path,
+    POSTINST_DEFAULT_CONDITION,
+    _error,
+    print_command,
+    _warn,
+)
+
+PLUGIN_TEST_SUFFIX = re.compile(r"_(?:t|test|check)(?:_([a-z0-9_]+))?[.]py$")
+
+
+def _validate_known_packaging_file_dh_compat_rules(
+    dh_compat_rules: Optional[List[InstallPatternDHCompatRule]],
+) -> None:
+    max_compat = None
+    if not dh_compat_rules:
+        return
+    dh_compat_rule: InstallPatternDHCompatRule
+    for idx, dh_compat_rule in enumerate(dh_compat_rules):
+        dh_version = dh_compat_rule.get("starting_with_debhelper_version")
+        compat = dh_compat_rule.get("starting_with_compat_level")
+
+        remaining = dh_compat_rule.keys() - {
+            "after_debhelper_version",
+            "starting_with_compat_level",
+        }
+        if not remaining:
+            raise ValueError(
+                f"The dh compat-rule at index {idx} does not affect anything not have any rules!? So why have it?"
+            )
+        if dh_version is None and compat is None and idx < len(dh_compat_rules) - 1:
+            raise ValueError(
+                f"The dh compat-rule at index {idx} is not the last and is missing either"
+                " before-debhelper-version or before-compat-level"
+            )
+        if compat is not None and compat < 0:
+            raise ValueError(
+                f"There is no compat below 1 but dh compat-rule at {idx} wants to declare some rule"
+                f" for something that appeared when migrating from {compat} to {compat + 1}."
+            )
+
+        if max_compat is None:
+            max_compat = compat
+        elif compat is not None:
+            if compat >= max_compat:
+                raise ValueError(
+                    f"The dh compat-rule at {idx} should be moved earlier than the entry for compat {max_compat}."
+                )
+            max_compat = compat
+
+        install_pattern = dh_compat_rule.get("install_pattern")
+        if (
+            install_pattern is not None
+            and _normalize_path(install_pattern, with_prefix=False) != install_pattern
+        ):
+            raise ValueError(
+                f"The install-pattern in dh compat-rule at {idx} must be normalized as"
+                f' "{_normalize_path(install_pattern, with_prefix=False)}".'
+            )
+
+
+class DebputyPluginInitializerProvider(DebputyPluginInitializer):
+    __slots__ = (
+        "_plugin_metadata",
+        "_feature_set",
+        "_plugin_detector_ids",
+        "_substitution",
+        "_unloaders",
+        "_load_started",
+    )
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        feature_set: PluginProvidedFeatureSet,
+        substitution: Substitution,
+    ) -> None:
+        self._plugin_metadata: DebputyPluginMetadata = plugin_metadata
+        self._feature_set = feature_set
+        self._plugin_detector_ids: Set[str] = set()
+        self._substitution = substitution
+        self._unloaders: List[Callable[[], None]] = []
+        self._load_started = False
+
+    def unload_plugin(self) -> None:
+        if self._load_started:
+            for unloader in self._unloaders:
+                unloader()
+            del self._feature_set.plugin_data[self._plugin_name]
+
+    def load_plugin(self) -> None:
+        metadata = self._plugin_metadata
+        if metadata.plugin_name in self._feature_set.plugin_data:
+            raise PluginConflictError(
+                f'The plugin "{metadata.plugin_name}" has already been loaded!?'
+            )
+        assert (
+            metadata.api_compat_version == 1
+        ), f"Unsupported plugin API compat version {metadata.api_compat_version}"
+        self._feature_set.plugin_data[metadata.plugin_name] = metadata
+        self._load_started = True
+        assert not metadata.is_initialized
+        try:
+            metadata.initialize_plugin(self)
+        except Exception as e:
+            initializer = metadata.plugin_initializer
+            if (
+                isinstance(e, TypeError)
+                and initializer is not None
+                and not callable(initializer)
+            ):
+                raise PluginMetadataError(
+                    f"The specified entry point for plugin {metadata.plugin_name} does not appear to be a"
+                    f" callable (callable returns False). The specified entry point identifies"
+                    f' itself as "{initializer.__qualname__}".'
+                ) from e
+            elif isinstance(e, PluginBaseError):
+                raise
+            raise PluginInitializationError(
+                f"Exception while attempting to load plugin {metadata.plugin_name}"
+            ) from e
+
+    def packager_provided_file(
+        self,
+        stem: str,
+        installed_path: str,
+        *,
+        default_mode: int = 0o0644,
+        default_priority: Optional[int] = None,
+        allow_name_segment: bool = True,
+        allow_architecture_segment: bool = False,
+        post_formatting_rewrite: Optional[Callable[[str], str]] = None,
+        packageless_is_fallback_for_all_packages: bool = False,
+        reservation_only: bool = False,
+        format_callback: Optional[
+            Callable[[str, PPFFormatParam, VirtualPath], str]
+        ] = None,
+        reference_documentation: Optional[
+            PackagerProvidedFileReferenceDocumentation
+        ] = None,
+    ) -> None:
+        packager_provided_files = self._feature_set.packager_provided_files
+        existing = packager_provided_files.get(stem)
+
+        if format_callback is not None and self._plugin_name != "debputy":
+            raise ValueError(
+                "Sorry; Using format_callback is a debputy-internal"
+                f" API. Triggered by plugin {self._plugin_name}"
+            )
+
+        if installed_path.endswith("/"):
+            raise ValueError(
+                f'The installed_path ends with "/" indicating it is a directory, but it must be a file.'
+                f" Triggered by plugin {self._plugin_name}."
+            )
+
+        installed_path = _normalize_path(installed_path)
+
+        has_name_var = "{name}" in installed_path
+
+        if installed_path.startswith("./DEBIAN") or reservation_only:
+            # Special-case, used for control files.
+            if self._plugin_name != "debputy":
+                raise ValueError(
+                    "Sorry; Using DEBIAN as install path or/and reservation_only is a debputy-internal"
+                    f" API. Triggered by plugin {self._plugin_name}"
+                )
+        elif not has_name_var and "{owning_package}" not in installed_path:
+            raise ValueError(
+                'The installed_path must contain a "{name}" (preferred) or a "{owning_package}"'
+                " substitution (or have installed_path end with a slash).  Otherwise, the installed"
+                f" path would caused file-conflicts. Triggered by plugin {self._plugin_name}"
+            )
+
+        if allow_name_segment and not has_name_var:
+            raise ValueError(
+                'When allow_name_segment is True, the installed_path must have a "{name}" substitution'
+                " variable. Otherwise, the name segment will not work properly. Triggered by"
+                f" plugin {self._plugin_name}"
+            )
+
+        if (
+            default_priority is not None
+            and "{priority}" not in installed_path
+            and "{priority:02}" not in installed_path
+        ):
+            raise ValueError(
+                'When default_priority is not None, the installed_path should have a "{priority}"'
+                ' or a "{priority:02}" substitution variable. Otherwise, the priority would be lost.'
+                f" Triggered by plugin {self._plugin_name}"
+            )
+
+        if existing is not None:
+            if existing.debputy_plugin_metadata.plugin_name != self._plugin_name:
+                message = (
+                    f'The stem "{stem}" is registered twice for packager provided files.'
+                    f" Once by {existing.debputy_plugin_metadata.plugin_name} and once"
+                    f" by {self._plugin_name}"
+                )
+            else:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' stem "{stem}" twice for packager provided files.'
+                )
+            raise PluginConflictError(
+                message, existing.debputy_plugin_metadata, self._plugin_metadata
+            )
+        packager_provided_files[stem] = PackagerProvidedFileClassSpec(
+            self._plugin_metadata,
+            stem,
+            installed_path,
+            default_mode=default_mode,
+            default_priority=default_priority,
+            allow_name_segment=allow_name_segment,
+            allow_architecture_segment=allow_architecture_segment,
+            post_formatting_rewrite=post_formatting_rewrite,
+            packageless_is_fallback_for_all_packages=packageless_is_fallback_for_all_packages,
+            reservation_only=reservation_only,
+            formatting_callback=format_callback,
+            reference_documentation=reference_documentation,
+        )
+
+        def _unload() -> None:
+            del packager_provided_files[stem]
+
+        self._unloaders.append(_unload)
+
+    def metadata_or_maintscript_detector(
+        self,
+        auto_detector_id: str,
+        auto_detector: MetadataAutoDetector,
+        *,
+        package_type: PackageTypeSelector = "deb",
+    ) -> None:
+        if auto_detector_id in self._plugin_detector_ids:
+            raise ValueError(
+                f"The plugin {self._plugin_name} tried to register"
+                f' "{auto_detector_id}" twice'
+            )
+        self._plugin_detector_ids.add(auto_detector_id)
+        all_detectors = self._feature_set.metadata_maintscript_detectors
+        if self._plugin_name not in all_detectors:
+            all_detectors[self._plugin_name] = []
+        package_types = resolve_package_type_selectors(package_type)
+        all_detectors[self._plugin_name].append(
+            MetadataOrMaintscriptDetector(
+                detector_id=auto_detector_id,
+                detector=auto_detector,
+                plugin_metadata=self._plugin_metadata,
+                applies_to_package_types=package_types,
+                enabled=True,
+            )
+        )
+
+        def _unload() -> None:
+            if self._plugin_name in all_detectors:
+                del all_detectors[self._plugin_name]
+
+        self._unloaders.append(_unload)
+
+    def document_builtin_variable(
+        self,
+        variable_name: str,
+        variable_reference_documentation: str,
+        *,
+        is_context_specific: bool = False,
+        is_for_special_case: bool = False,
+    ) -> None:
+        manifest_variables = self._feature_set.manifest_variables
+        self._restricted_api()
+        state = self._substitution.variable_state(variable_name)
+        if state == VariableNameState.UNDEFINED:
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to document built-in {variable_name},"
+                f" but it is not known to be a variable"
+            )
+
+        assert variable_name not in manifest_variables
+
+        manifest_variables[variable_name] = PluginProvidedManifestVariable(
+            self._plugin_metadata,
+            variable_name,
+            None,
+            is_context_specific_variable=is_context_specific,
+            variable_reference_documentation=variable_reference_documentation,
+            is_documentation_placeholder=True,
+            is_for_special_case=is_for_special_case,
+        )
+
+        def _unload() -> None:
+            del manifest_variables[variable_name]
+
+        self._unloaders.append(_unload)
+
+    def manifest_variable_provider(
+        self,
+        provider: Callable[[VariableContext], Mapping[str, str]],
+        variables: Union[Sequence[str], Mapping[str, Optional[str]]],
+    ) -> None:
+        self._restricted_api()
+        cached_provider = functools.lru_cache(None)(provider)
+        permitted_variables = frozenset(variables)
+        variables_iter: Iterable[Tuple[str, Optional[str]]]
+        if not isinstance(variables, Mapping):
+            variables_iter = zip(variables, itertools.repeat(None))
+        else:
+            variables_iter = variables.items()
+
+        checked_vars = False
+        manifest_variables = self._feature_set.manifest_variables
+        plugin_name = self._plugin_name
+
+        def _value_resolver_generator(
+            variable_name: str,
+        ) -> Callable[[VariableContext], str]:
+            def _value_resolver(variable_context: VariableContext) -> str:
+                res = cached_provider(variable_context)
+                nonlocal checked_vars
+                if not checked_vars:
+                    if permitted_variables != res.keys():
+                        expected = ", ".join(sorted(permitted_variables))
+                        actual = ", ".join(sorted(res))
+                        raise PluginAPIViolationError(
+                            f"The plugin {plugin_name} claimed to provide"
+                            f" the following variables {expected},"
+                            f" but when resolving the variables, the plugin provided"
+                            f" {actual}.  These two lists should have been the same."
+                        )
+                    checked_vars = False
+                return res[variable_name]
+
+            return _value_resolver
+
+        for varname, vardoc in variables_iter:
+            self._check_variable_name(varname)
+            manifest_variables[varname] = PluginProvidedManifestVariable(
+                self._plugin_metadata,
+                varname,
+                _value_resolver_generator(varname),
+                is_context_specific_variable=False,
+                variable_reference_documentation=vardoc,
+            )
+
+        def _unload() -> None:
+            raise PluginInitializationError(
+                "Cannot unload manifest_variable_provider (not implemented)"
+            )
+
+        self._unloaders.append(_unload)
+
+    def _check_variable_name(self, variable_name: str) -> None:
+        manifest_variables = self._feature_set.manifest_variables
+        existing = manifest_variables.get(variable_name)
+
+        if existing is not None:
+            if existing.plugin_metadata.plugin_name == self._plugin_name:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' manifest variable "{variable_name}" twice.'
+                )
+            else:
+                message = (
+                    f"The plugins {existing.plugin_metadata.plugin_name} and {self._plugin_name}"
+                    f" both tried to provide the manifest variable {variable_name}"
+                )
+            raise PluginConflictError(
+                message, existing.plugin_metadata, self._plugin_metadata
+            )
+        if not SUBST_VAR_RE.match("{{" + variable_name + "}}"):
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to declare {variable_name},"
+                f" which is not a valid variable name"
+            )
+
+        namespace = ""
+        variable_basename = variable_name
+        if ":" in variable_name:
+            namespace, variable_basename = variable_name.rsplit(":", 1)
+            assert namespace != ""
+            assert variable_name != ""
+
+        if namespace != "" and namespace not in ("token", "path"):
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to declare {variable_name},"
+                f" which is in the reserved namespace {namespace}"
+            )
+
+        variable_name_upper = variable_name.upper()
+        if (
+            variable_name_upper.startswith(("DEB_", "DPKG_", "DEBPUTY"))
+            or variable_basename.startswith("_")
+            or variable_basename.upper().startswith("DEBPUTY")
+        ) and self._plugin_name != "debputy":
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to declare {variable_name},"
+                f" which is a variable name reserved by debputy"
+            )
+
+        state = self._substitution.variable_state(variable_name)
+        if state != VariableNameState.UNDEFINED and self._plugin_name != "debputy":
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to declare {variable_name},"
+                f" which would shadow a built-in variable"
+            )
+
+    def package_processor(
+        self,
+        processor_id: str,
+        processor: PackageProcessor,
+        *,
+        depends_on_processor: Iterable[str] = tuple(),
+        package_type: PackageTypeSelector = "deb",
+    ) -> None:
+        self._restricted_api(allowed_plugins={"lua"})
+        package_processors = self._feature_set.all_package_processors
+        dependencies = set()
+        processor_key = (self._plugin_name, processor_id)
+
+        if processor_key in package_processors:
+            raise PluginConflictError(
+                f"The plugin {self._plugin_name} already registered a processor with id {processor_id}",
+                self._plugin_metadata,
+                self._plugin_metadata,
+            )
+
+        for depends_ref in depends_on_processor:
+            if isinstance(depends_ref, str):
+                if (self._plugin_name, depends_ref) in package_processors:
+                    depends_key = (self._plugin_name, depends_ref)
+                elif ("debputy", depends_ref) in package_processors:
+                    depends_key = ("debputy", depends_ref)
+                else:
+                    raise ValueError(
+                        f'Could not resolve dependency "{depends_ref}" for'
+                        f' "{processor_id}". It was not provided by the plugin itself'
+                        f" ({self._plugin_name}) nor debputy."
+                    )
+            else:
+                # TODO: Add proper dependencies first, at which point we should probably resolve "name"
+                #  via the direct dependencies.
+                assert False
+
+            existing_processor = package_processors.get(depends_key)
+            if existing_processor is None:
+                # We currently require the processor to be declared already.  If this ever changes,
+                # PluginProvidedFeatureSet.package_processors_in_order will need an update
+                dplugin_name, dprocessor_name = depends_key
+                available_processors = ", ".join(
+                    n for p, n in package_processors.keys() if p == dplugin_name
+                )
+                raise ValueError(
+                    f"The plugin {dplugin_name} does not provide a processor called"
+                    f" {dprocessor_name}. Available processors for that plugin are:"
+                    f" {available_processors}"
+                )
+            dependencies.add(depends_key)
+
+        package_processors[processor_key] = PluginProvidedPackageProcessor(
+            processor_id,
+            resolve_package_type_selectors(package_type),
+            processor,
+            frozenset(dependencies),
+            self._plugin_metadata,
+        )
+
+        def _unload() -> None:
+            del package_processors[processor_key]
+
+        self._unloaders.append(_unload)
+
+    def automatic_discard_rule(
+        self,
+        name: str,
+        should_discard: Callable[[VirtualPath], bool],
+        *,
+        rule_reference_documentation: Optional[str] = None,
+        examples: Union[
+            AutomaticDiscardRuleExample, Sequence[AutomaticDiscardRuleExample]
+        ] = tuple(),
+    ) -> None:
+        """Register an automatic discard rule
+
+        An automatic discard rule is basically applied to *every* path about to be installed in to any package.
+        If any discard rule concludes that a path should not be installed, then the path is not installed.
+        In the case where the discard path is a:
+
+         * directory: Then the entire directory is excluded along with anything beneath it.
+         * symlink: Then the symlink itself (but not its target) is excluded.
+         * hardlink: Then the current hardlink will not be installed, but other instances of it will be.
+
+        Note: Discarded files are *never* deleted by `debputy`. They just make `debputy` skip the file.
+
+        Automatic discard rules should be written with the assumption that directories will be tested
+        before their content *when it is relevant* for the discard rule to examine whether the directory
+        can be excluded.
+
+        The packager can via the manifest overrule automatic discard rules by explicitly listing the path
+        without any globs. As example:
+
+            installations:
+              - install:
+                  sources:
+                  - usr/lib/libfoo.la  # <-- This path is always installed
+                                       #     (Discard rules are never asked in this case)
+                                       #
+                  - usr/lib/*.so*      # <-- Discard rules applies to any path beneath usr/lib and can exclude matches
+                                       #     Though, they will not examine `libfoo.la` as it has already been installed
+                                       #
+                                       # Note: usr/lib itself is never tested in this case (it is assumed to be
+                                       # explicitly requested). But any subdir of usr/lib will be examined.
+
+        When an automatic discard rule is evaluated, it can see the source path currently being considered
+        for installation.  While it can look at "surrounding" context (like parent directory), it will not
+        know whether those paths are to be installed or will be installed.
+
+        :param name: A user visible name discard rule. It can be used on the command line, so avoid shell
+           metacharacters and spaces.
+        :param should_discard: A callable that is the implementation of the automatic discard rule. It will receive
+          a VirtualPath representing the *source* path about to be installed.  If callable returns `True`, then the
+          path is discarded. If it returns `False`, the path is not discarded (by this rule at least).
+          A source path will either be from the root of the source tree or the root of a search directory such as
+          `debian/tmp`.  Where the path will be installed is not available at the time the discard rule is
+          evaluated.
+        :param rule_reference_documentation: Optionally, the reference documentation to be shown when a user
+          looks up this automatic discard rule.
+        :param examples: Provide examples for the rule. Use the automatic_discard_rule_example function to
+          generate the examples.
+
+        """
+        self._restricted_api()
+        auto_discard_rules = self._feature_set.auto_discard_rules
+        existing = auto_discard_rules.get(name)
+        if existing is not None:
+            if existing.plugin_metadata.plugin_name == self._plugin_name:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' automatic discard rule "{name}" twice.'
+                )
+            else:
+                message = (
+                    f"The plugins {existing.plugin_metadata.plugin_name} and {self._plugin_name}"
+                    f" both tried to provide the automatic discard rule {name}"
+                )
+            raise PluginConflictError(
+                message, existing.plugin_metadata, self._plugin_metadata
+            )
+        examples = (
+            (examples,)
+            if isinstance(examples, AutomaticDiscardRuleExample)
+            else tuple(examples)
+        )
+        auto_discard_rules[name] = PluginProvidedDiscardRule(
+            name,
+            self._plugin_metadata,
+            should_discard,
+            rule_reference_documentation,
+            examples,
+        )
+
+        def _unload() -> None:
+            del auto_discard_rules[name]
+
+        self._unloaders.append(_unload)
+
+    def service_provider(
+        self,
+        service_manager: str,
+        detector: ServiceDetector,
+        integrator: ServiceIntegrator,
+    ) -> None:
+        self._restricted_api()
+        service_managers = self._feature_set.service_managers
+        existing = service_managers.get(service_manager)
+        if existing is not None:
+            if existing.plugin_metadata.plugin_name == self._plugin_name:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' service manager "{service_manager}" twice.'
+                )
+            else:
+                message = (
+                    f"The plugins {existing.plugin_metadata.plugin_name} and {self._plugin_name}"
+                    f' both tried to provide the service manager "{service_manager}"'
+                )
+            raise PluginConflictError(
+                message, existing.plugin_metadata, self._plugin_metadata
+            )
+        service_managers[service_manager] = ServiceManagerDetails(
+            service_manager,
+            detector,
+            integrator,
+            self._plugin_metadata,
+        )
+
+        def _unload() -> None:
+            del service_managers[service_manager]
+
+        self._unloaders.append(_unload)
+
+    def manifest_variable(
+        self,
+        variable_name: str,
+        value: str,
+        variable_reference_documentation: Optional[str] = None,
+    ) -> None:
+        self._check_variable_name(variable_name)
+        manifest_variables = self._feature_set.manifest_variables
+        try:
+            resolved_value = self._substitution.substitute(
+                value, "Plugin initialization"
+            )
+            depends_on_variable = resolved_value != value
+        except DebputySubstitutionError:
+            depends_on_variable = True
+        if depends_on_variable:
+            raise ValueError(
+                f"The plugin {self._plugin_name} attempted to declare {variable_name} with value {value!r}."
+                f" This value depends on another variable, which is not supported. This restriction may be"
+                f" lifted in the future."
+            )
+
+        manifest_variables[variable_name] = PluginProvidedManifestVariable(
+            self._plugin_metadata,
+            variable_name,
+            value,
+            is_context_specific_variable=False,
+            variable_reference_documentation=variable_reference_documentation,
+        )
+
+        def _unload() -> None:
+            # We need to check it was never resolved
+            raise PluginInitializationError(
+                "Cannot unload manifest_variable (not implemented)"
+            )
+
+        self._unloaders.append(_unload)
+
+    @property
+    def _plugin_name(self) -> str:
+        return self._plugin_metadata.plugin_name
+
+    def provide_manifest_keyword(
+        self,
+        rule_type: TTP,
+        rule_name: Union[str, List[str]],
+        handler: DIPKWHandler,
+        *,
+        inline_reference_documentation: Optional[ParserDocumentation] = None,
+    ) -> None:
+        self._restricted_api()
+        if rule_type not in self._feature_set.dispatchable_table_parsers:
+            types = ", ".join(
+                sorted(x.__name__ for x in self._feature_set.dispatchable_table_parsers)
+            )
+            raise ValueError(
+                f"The rule_type was not a supported type. It must be one of {types}"
+            )
+        dispatching_parser = self._feature_set.dispatchable_table_parsers[rule_type]
+        dispatching_parser.register_keyword(
+            rule_name,
+            handler,
+            self._plugin_metadata,
+            inline_reference_documentation=inline_reference_documentation,
+        )
+
+        def _unload() -> None:
+            raise PluginInitializationError(
+                "Cannot unload provide_manifest_keyword (not implemented)"
+            )
+
+        self._unloaders.append(_unload)
+
+    def plugable_object_parser(
+        self,
+        rule_type: str,
+        rule_name: str,
+        *,
+        object_parser_key: Optional[str] = None,
+        on_end_parse_step: Optional[
+            Callable[
+                [str, Optional[Mapping[str, Any]], AttributePath, ParserContextData],
+                None,
+            ]
+        ] = None,
+    ) -> None:
+        self._restricted_api()
+        if object_parser_key is None:
+            object_parser_key = rule_name
+        dispatchable_object_parsers = self._feature_set.dispatchable_object_parsers
+        if rule_type not in dispatchable_object_parsers:
+            types = ", ".join(sorted(dispatchable_object_parsers))
+            raise ValueError(
+                f"The rule_type was not a supported type. It must be one of {types}"
+            )
+        if object_parser_key not in dispatchable_object_parsers:
+            types = ", ".join(sorted(dispatchable_object_parsers))
+            raise ValueError(
+                f"The object_parser_key was not a supported type. It must be one of {types}"
+            )
+        parent_dispatcher = dispatchable_object_parsers[rule_type]
+        child_dispatcher = dispatchable_object_parsers[object_parser_key]
+        parent_dispatcher.register_child_parser(
+            rule_name,
+            child_dispatcher,
+            self._plugin_metadata,
+            on_end_parse_step=on_end_parse_step,
+        )
+
+        def _unload() -> None:
+            raise PluginInitializationError(
+                "Cannot unload plugable_object_parser (not implemented)"
+            )
+
+        self._unloaders.append(_unload)
+
+    def plugable_manifest_rule(
+        self,
+        rule_type: Union[TTP, str],
+        rule_name: Union[str, List[str]],
+        parsed_format: Type[PF],
+        handler: DIPHandler,
+        *,
+        source_format: Optional[SF] = None,
+        inline_reference_documentation: Optional[ParserDocumentation] = None,
+    ) -> None:
+        self._restricted_api()
+        feature_set = self._feature_set
+        if isinstance(rule_type, str):
+            if rule_type not in feature_set.dispatchable_object_parsers:
+                types = ", ".join(sorted(feature_set.dispatchable_object_parsers))
+                raise ValueError(
+                    f"The rule_type was not a supported type. It must be one of {types}"
+                )
+            dispatching_parser = feature_set.dispatchable_object_parsers[rule_type]
+        else:
+            if rule_type not in feature_set.dispatchable_table_parsers:
+                types = ", ".join(
+                    sorted(x.__name__ for x in feature_set.dispatchable_table_parsers)
+                )
+                raise ValueError(
+                    f"The rule_type was not a supported type. It must be one of {types}"
+                )
+            dispatching_parser = feature_set.dispatchable_table_parsers[rule_type]
+
+        parser = feature_set.manifest_parser_generator.parser_from_typed_dict(
+            parsed_format,
+            source_content=source_format,
+            inline_reference_documentation=inline_reference_documentation,
+        )
+        dispatching_parser.register_parser(
+            rule_name,
+            parser,
+            handler,
+            self._plugin_metadata,
+        )
+
+        def _unload() -> None:
+            raise PluginInitializationError(
+                "Cannot unload plugable_manifest_rule (not implemented)"
+            )
+
+        self._unloaders.append(_unload)
+
+    def known_packaging_files(
+        self,
+        packaging_file_details: KnownPackagingFileInfo,
+    ) -> None:
+        known_packaging_files = self._feature_set.known_packaging_files
+        detection_method = packaging_file_details.get(
+            "detection_method", cast("Literal['path']", "path")
+        )
+        path = packaging_file_details.get("path")
+        dhpkgfile = packaging_file_details.get("pkgfile")
+
+        packaging_file_details: KnownPackagingFileInfo = packaging_file_details.copy()
+
+        if detection_method == "path":
+            if dhpkgfile is not None:
+                raise ValueError(
+                    'The "pkgfile" attribute cannot be used when detection-method is "path" (or omitted)'
+                )
+            if path != _normalize_path(path, with_prefix=False):
+                raise ValueError(
+                    f"The path for known packaging files must be normalized. Please replace"
+                    f' "{path}" with "{_normalize_path(path, with_prefix=False)}"'
+                )
+            detection_value = path
+        else:
+            assert detection_method == "dh.pkgfile"
+            if path is not None:
+                raise ValueError(
+                    'The "path" attribute cannot be used when detection-method is "dh.pkgfile"'
+                )
+            if "/" in dhpkgfile:
+                raise ValueError(
+                    'The "pkgfile" attribute ḿust be a name stem such as "install" (no "/" are allowed)'
+                )
+            detection_value = dhpkgfile
+        key = f"{detection_method}::{detection_value}"
+        existing = known_packaging_files.get(key)
+        if existing is not None:
+            if existing.plugin_metadata.plugin_name != self._plugin_name:
+                message = (
+                    f'The key "{key}" is registered twice for known packaging files.'
+                    f" Once by {existing.plugin_metadata.plugin_name} and once by {self._plugin_name}"
+                )
+            else:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' key "{key}" twice for known packaging files.'
+                )
+            raise PluginConflictError(
+                message, existing.plugin_metadata, self._plugin_metadata
+            )
+        _validate_known_packaging_file_dh_compat_rules(
+            packaging_file_details.get("dh_compat_rules")
+        )
+        known_packaging_files[key] = PluginProvidedKnownPackagingFile(
+            packaging_file_details,
+            detection_method,
+            detection_value,
+            self._plugin_metadata,
+        )
+
+        def _unload() -> None:
+            del known_packaging_files[key]
+
+        self._unloaders.append(_unload)
+
+    def register_mapped_type(
+        self,
+        type_mapping: TypeMapping,
+        *,
+        reference_documentation: Optional[TypeMappingDocumentation] = None,
+    ) -> None:
+        self._restricted_api()
+        target_type = type_mapping.target_type
+        mapped_types = self._feature_set.mapped_types
+        existing = mapped_types.get(target_type)
+        if existing is not None:
+            if existing.plugin_metadata.plugin_name != self._plugin_name:
+                message = (
+                    f'The key "{target_type.__name__}" is registered twice for known packaging files.'
+                    f" Once by {existing.plugin_metadata.plugin_name} and once by {self._plugin_name}"
+                )
+            else:
+                message = (
+                    f"Bug in the plugin {self._plugin_name}: It tried to register the"
+                    f' key "{target_type.__name__}" twice for known packaging files.'
+                )
+            raise PluginConflictError(
+                message, existing.plugin_metadata, self._plugin_metadata
+            )
+        parser_generator = self._feature_set.manifest_parser_generator
+        mapped_types[target_type] = PluginProvidedTypeMapping(
+            type_mapping, reference_documentation, self._plugin_metadata
+        )
+        parser_generator.register_mapped_type(type_mapping)
+
+    def _restricted_api(
+        self,
+        *,
+        allowed_plugins: Union[Set[str], FrozenSet[str]] = frozenset(),
+    ) -> None:
+        if self._plugin_name != "debputy" and self._plugin_name not in allowed_plugins:
+            raise PluginAPIViolationError(
+                f"Plugin {self._plugin_name} attempted to access a debputy-only API."
+                " If you are the maintainer of this plugin and want access to this"
+                " API, please file a feature request to make this public."
+                " (The API is currently private as it is unstable.)"
+            )
+
+
+class MaintscriptAccessorProviderBase(MaintscriptAccessor, ABC):
+    __slots__ = ()
+
+    def _append_script(
+        self,
+        caller_name: str,
+        maintscript: Maintscript,
+        full_script: str,
+        /,
+        perform_substitution: bool = True,
+    ) -> None:
+        raise NotImplementedError
+
+    @classmethod
+    def _apply_condition_to_script(
+        cls,
+        condition: str,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+    ) -> str:
+        if indent is None:
+            # We auto-determine this based on heredocs currently
+            indent = "<<" not in run_snippet
+
+        if indent:
+            run_snippet = "".join("  " + x for x in run_snippet.splitlines(True))
+        if not run_snippet.endswith("\n"):
+            run_snippet += "\n"
+        condition_line = f"if {condition}; then\n"
+        end_line = "fi\n"
+        return "".join((condition_line, run_snippet, end_line))
+
+    def on_configure(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+        skip_on_rollback: bool = False,
+    ) -> None:
+        condition = POSTINST_DEFAULT_CONDITION
+        if skip_on_rollback:
+            condition = '[ "$1" = "configure" ]'
+        return self._append_script(
+            "on_configure",
+            "postinst",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_initial_install(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "configure" -a -z "$2" ]'
+        return self._append_script(
+            "on_initial_install",
+            "postinst",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_upgrade(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "configure" -a -n "$2" ]'
+        return self._append_script(
+            "on_upgrade",
+            "postinst",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_upgrade_from(
+        self,
+        version: str,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "configure" ] && dpkg --compare-versions le-nl "$2"'
+        return self._append_script(
+            "on_upgrade_from",
+            "postinst",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_before_removal(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "remove" ]'
+        return self._append_script(
+            "on_before_removal",
+            "prerm",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_removed(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "remove" ]'
+        return self._append_script(
+            "on_removed",
+            "postrm",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def on_purge(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        condition = '[ "$1" = "purge" ]'
+        return self._append_script(
+            "on_purge",
+            "postrm",
+            self._apply_condition_to_script(condition, run_snippet, indent=indent),
+            perform_substitution=perform_substitution,
+        )
+
+    def unconditionally_in_script(
+        self,
+        maintscript: Maintscript,
+        run_snippet: str,
+        /,
+        perform_substitution: bool = True,
+    ) -> None:
+        if maintscript not in STD_CONTROL_SCRIPTS:
+            raise ValueError(
+                f'Unknown script "{maintscript}". Should have been one of:'
+                f' {", ".join(sorted(STD_CONTROL_SCRIPTS))}'
+            )
+        return self._append_script(
+            "unconditionally_in_script",
+            maintscript,
+            run_snippet,
+            perform_substitution=perform_substitution,
+        )
+
+
+class MaintscriptAccessorProvider(MaintscriptAccessorProviderBase):
+    __slots__ = (
+        "_plugin_metadata",
+        "_maintscript_snippets",
+        "_plugin_source_id",
+        "_package_substitution",
+    )
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+        maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+        package_substitution: Substitution,
+    ):
+        self._plugin_metadata = plugin_metadata
+        self._plugin_source_id = plugin_source_id
+        self._maintscript_snippets = maintscript_snippets
+        self._package_substitution = package_substitution
+
+    def _append_script(
+        self,
+        caller_name: str,
+        maintscript: Maintscript,
+        full_script: str,
+        /,
+        perform_substitution: bool = True,
+    ) -> None:
+        def_source = f"{self._plugin_metadata.plugin_name} ({self._plugin_source_id})"
+        if perform_substitution:
+            full_script = self._package_substitution.substitute(full_script, def_source)
+
+        snippet = MaintscriptSnippet(snippet=full_script, definition_source=def_source)
+        self._maintscript_snippets[maintscript].append(snippet)
+
+
+class BinaryCtrlAccessorProviderBase(BinaryCtrlAccessor):
+    __slots__ = (
+        "_plugin_metadata",
+        "_plugin_source_id",
+        "_package_metadata_context",
+        "_triggers",
+        "_substvars",
+        "_maintscript",
+        "_shlibs_details",
+    )
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+        package_metadata_context: PackageProcessingContext,
+        triggers: Dict[Tuple[DpkgTriggerType, str], PluginProvidedTrigger],
+        substvars: FlushableSubstvars,
+        shlibs_details: Tuple[Optional[str], Optional[List[str]]],
+    ) -> None:
+        self._plugin_metadata = plugin_metadata
+        self._plugin_source_id = plugin_source_id
+        self._package_metadata_context = package_metadata_context
+        self._triggers = triggers
+        self._substvars = substvars
+        self._maintscript: Optional[MaintscriptAccessor] = None
+        self._shlibs_details = shlibs_details
+
+    def _create_maintscript_accessor(self) -> MaintscriptAccessor:
+        raise NotImplementedError
+
+    def dpkg_trigger(self, trigger_type: DpkgTriggerType, trigger_target: str) -> None:
+        """Register a declarative dpkg level trigger
+
+        The provided trigger will be added to the package's metadata (the triggers file of the control.tar).
+
+        If the trigger has already been added previously, a second call with the same trigger data will be ignored.
+        """
+        key = (trigger_type, trigger_target)
+        if key in self._triggers:
+            return
+        self._triggers[key] = PluginProvidedTrigger(
+            dpkg_trigger_type=trigger_type,
+            dpkg_trigger_target=trigger_target,
+            provider=self._plugin_metadata,
+            provider_source_id=self._plugin_source_id,
+        )
+
+    @property
+    def maintscript(self) -> MaintscriptAccessor:
+        maintscript = self._maintscript
+        if maintscript is None:
+            maintscript = self._create_maintscript_accessor()
+            self._maintscript = maintscript
+        return maintscript
+
+    @property
+    def substvars(self) -> FlushableSubstvars:
+        return self._substvars
+
+    def dpkg_shlibdeps(self, paths: Sequence[VirtualPath]) -> None:
+        binary_package = self._package_metadata_context.binary_package
+        with self.substvars.flush() as substvars_file:
+            dpkg_cmd = ["dpkg-shlibdeps", f"-T{substvars_file}"]
+            if binary_package.is_udeb:
+                dpkg_cmd.append("-tudeb")
+            if binary_package.is_essential:
+                dpkg_cmd.append("-dPre-Depends")
+            shlibs_local, shlib_dirs = self._shlibs_details
+            if shlibs_local is not None:
+                dpkg_cmd.append(f"-L{shlibs_local}")
+            if shlib_dirs:
+                dpkg_cmd.extend(f"-l{sd}" for sd in shlib_dirs)
+            dpkg_cmd.extend(p.fs_path for p in paths)
+            print_command(*dpkg_cmd)
+            try:
+                subprocess.check_call(dpkg_cmd)
+            except subprocess.CalledProcessError:
+                _error(
+                    f"Attempting to auto-detect dependencies via dpkg-shlibdeps for {binary_package.name} failed. Please"
+                    " review the output from dpkg-shlibdeps above to understand what went wrong."
+                )
+
+
+class BinaryCtrlAccessorProvider(BinaryCtrlAccessorProviderBase):
+    __slots__ = (
+        "_maintscript",
+        "_maintscript_snippets",
+        "_package_substitution",
+    )
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+        package_metadata_context: PackageProcessingContext,
+        triggers: Dict[Tuple[DpkgTriggerType, str], PluginProvidedTrigger],
+        substvars: FlushableSubstvars,
+        maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+        package_substitution: Substitution,
+        shlibs_details: Tuple[Optional[str], Optional[List[str]]],
+    ) -> None:
+        super().__init__(
+            plugin_metadata,
+            plugin_source_id,
+            package_metadata_context,
+            triggers,
+            substvars,
+            shlibs_details,
+        )
+        self._maintscript_snippets = maintscript_snippets
+        self._package_substitution = package_substitution
+        self._maintscript = MaintscriptAccessorProvider(
+            plugin_metadata,
+            plugin_source_id,
+            maintscript_snippets,
+            package_substitution,
+        )
+
+    def _create_maintscript_accessor(self) -> MaintscriptAccessor:
+        return MaintscriptAccessorProvider(
+            self._plugin_metadata,
+            self._plugin_source_id,
+            self._maintscript_snippets,
+            self._package_substitution,
+        )
+
+
+class BinaryCtrlAccessorProviderCreator:
+    def __init__(
+        self,
+        package_metadata_context: PackageProcessingContext,
+        substvars: FlushableSubstvars,
+        maintscript_snippets: Dict[str, MaintscriptSnippetContainer],
+        substitution: Substitution,
+    ) -> None:
+        self._package_metadata_context = package_metadata_context
+        self._substvars = substvars
+        self._maintscript_snippets = maintscript_snippets
+        self._substitution = substitution
+        self._triggers: Dict[Tuple[DpkgTriggerType, str], PluginProvidedTrigger] = {}
+        self.shlibs_details: Tuple[Optional[str], Optional[List[str]]] = None, None
+
+    def for_plugin(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+    ) -> BinaryCtrlAccessor:
+        return BinaryCtrlAccessorProvider(
+            plugin_metadata,
+            plugin_source_id,
+            self._package_metadata_context,
+            self._triggers,
+            self._substvars,
+            self._maintscript_snippets,
+            self._substitution,
+            self.shlibs_details,
+        )
+
+    def generated_triggers(self) -> Iterable[PluginProvidedTrigger]:
+        return self._triggers.values()
+
+
+def plugin_metadata_for_debputys_own_plugin(
+    loader: Optional[PluginInitializationEntryPoint] = None,
+) -> DebputyPluginMetadata:
+    if loader is None:
+        from debputy.plugin.debputy.debputy_plugin import initialize_debputy_features
+
+        loader = initialize_debputy_features
+    return DebputyPluginMetadata(
+        plugin_name="debputy",
+        api_compat_version=1,
+        plugin_initializer=loader,
+        plugin_loader=None,
+        plugin_path="<bundled>",
+    )
+
+
+def load_plugin_features(
+    plugin_search_dirs: Sequence[str],
+    substitution: Substitution,
+    requested_plugins_only: Optional[Sequence[str]] = None,
+    required_plugins: Optional[Set[str]] = None,
+    plugin_feature_set: Optional[PluginProvidedFeatureSet] = None,
+    debug_mode: bool = False,
+) -> PluginProvidedFeatureSet:
+    if plugin_feature_set is None:
+        plugin_feature_set = PluginProvidedFeatureSet()
+    plugins = [plugin_metadata_for_debputys_own_plugin()]
+    unloadable_plugins = set()
+    if required_plugins:
+        plugins.extend(
+            find_json_plugins(
+                plugin_search_dirs,
+                required_plugins,
+            )
+        )
+    if requested_plugins_only is not None:
+        plugins.extend(
+            find_json_plugins(
+                plugin_search_dirs,
+                requested_plugins_only,
+            )
+        )
+    else:
+        auto_loaded = _find_all_json_plugins(
+            plugin_search_dirs,
+            required_plugins if required_plugins is not None else frozenset(),
+            debug_mode=debug_mode,
+        )
+        for plugin_metadata in auto_loaded:
+            plugins.append(plugin_metadata)
+            unloadable_plugins.add(plugin_metadata.plugin_name)
+
+    for plugin_metadata in plugins:
+        api = DebputyPluginInitializerProvider(
+            plugin_metadata, plugin_feature_set, substitution
+        )
+        try:
+            api.load_plugin()
+        except PluginBaseError as e:
+            if plugin_metadata.plugin_name not in unloadable_plugins:
+                raise
+            if debug_mode:
+                raise
+            try:
+                api.unload_plugin()
+            except Exception:
+                _warn(
+                    f"Failed to load optional {plugin_metadata.plugin_name} and an error was raised when trying to"
+                    " clean up after the half-initialized plugin. Re-raising load error as the partially loaded"
+                    " module might have tainted the feature set."
+                )
+                raise e from None
+            else:
+                if debug_mode:
+                    _warn(
+                        f"The optional plugin {plugin_metadata.plugin_name} failed during load. Re-raising due"
+                        f" to --debug/-d."
+                    )
+                _warn(
+                    f"The optional plugin {plugin_metadata.plugin_name} failed during load. The plugin was"
+                    f" deactivated. Use debug mode (--debug) to show the stacktrace (the warning will become an error)"
+                )
+
+    return plugin_feature_set
+
+
+def find_json_plugin(
+    search_dirs: Sequence[str],
+    requested_plugin: str,
+) -> DebputyPluginMetadata:
+    r = list(find_json_plugins(search_dirs, [requested_plugin]))
+    assert len(r) == 1
+    return r[0]
+
+
+def find_related_implementation_files_for_plugin(
+    plugin_metadata: DebputyPluginMetadata,
+) -> List[str]:
+    plugin_path = plugin_metadata.plugin_path
+    if not os.path.isfile(plugin_path):
+        plugin_name = plugin_metadata.plugin_name
+        _error(
+            f"Cannot run find related files for {plugin_name}: The plugin seems to be bundled"
+            " or loaded via a mechanism that does not support detecting its tests."
+        )
+    files = []
+    module_name, module_file = _find_plugin_implementation_file(
+        plugin_metadata.plugin_name,
+        plugin_metadata.plugin_path,
+    )
+    if os.path.isfile(module_file):
+        files.append(module_file)
+    else:
+        if not plugin_metadata.is_loaded:
+            plugin_metadata.load_plugin()
+        if module_name in sys.modules:
+            _error(
+                f'The plugin {plugin_metadata.plugin_name} uses the "module"" key in its'
+                f" JSON metadata file ({plugin_metadata.plugin_path}) and cannot be "
+                f" installed via this method. The related Python would not be installed"
+                f" (which would result in a plugin that would fail to load)"
+            )
+
+    return files
+
+
+def find_tests_for_plugin(
+    plugin_metadata: DebputyPluginMetadata,
+) -> List[str]:
+    plugin_name = plugin_metadata.plugin_name
+    plugin_path = plugin_metadata.plugin_path
+
+    if not os.path.isfile(plugin_path):
+        _error(
+            f"Cannot run tests for {plugin_name}: The plugin seems to be bundled or loaded via a"
+            " mechanism that does not support detecting its tests."
+        )
+
+    plugin_dir = os.path.dirname(plugin_path)
+    test_basename_prefix = plugin_metadata.plugin_name.replace("-", "_")
+    tests = []
+    with os.scandir(plugin_dir) as dir_iter:
+        for p in dir_iter:
+            if (
+                p.is_file()
+                and p.name.startswith(test_basename_prefix)
+                and PLUGIN_TEST_SUFFIX.search(p.name)
+            ):
+                tests.append(p.path)
+    return tests
+
+
+def find_json_plugins(
+    search_dirs: Sequence[str],
+    requested_plugins: Iterable[str],
+) -> Iterable[DebputyPluginMetadata]:
+    for plugin_name_or_path in requested_plugins:
+        found = False
+        if "/" in plugin_name_or_path:
+            if not os.path.isfile(plugin_name_or_path):
+                raise PluginNotFoundError(
+                    f"Unable to load the plugin {plugin_name_or_path}: The path is not a file."
+                    ' (Because the plugin name contains "/", it is assumed to be a path and search path'
+                    " is not used."
+                )
+            yield parse_json_plugin_desc(plugin_name_or_path)
+            return
+        for search_dir in search_dirs:
+            path = os.path.join(
+                search_dir, "debputy", "plugins", f"{plugin_name_or_path}.json"
+            )
+            if not os.path.isfile(path):
+                continue
+            found = True
+            yield parse_json_plugin_desc(path)
+        if not found:
+            search_dir_str = ":".join(search_dirs)
+            raise PluginNotFoundError(
+                f"Unable to load the plugin {plugin_name_or_path}: Could not find {plugin_name_or_path}.json in the"
+                f" debputy/plugins subdir of any of the search dirs ({search_dir_str})"
+            )
+
+
+def _find_all_json_plugins(
+    search_dirs: Sequence[str],
+    required_plugins: AbstractSet[str],
+    debug_mode: bool = False,
+) -> Iterable[DebputyPluginMetadata]:
+    seen = set(required_plugins)
+    error_seen = False
+    for search_dir in search_dirs:
+        try:
+            dir_fd = os.scandir(os.path.join(search_dir, "debputy", "plugins"))
+        except FileNotFoundError:
+            continue
+        with dir_fd:
+            for entry in dir_fd:
+                if (
+                    not entry.is_file(follow_symlinks=True)
+                    or not entry.name.endswith(".json")
+                    or entry.name in seen
+                ):
+                    continue
+                try:
+                    plugin_metadata = parse_json_plugin_desc(entry.path)
+                except PluginBaseError as e:
+                    if debug_mode:
+                        raise
+                    if not error_seen:
+                        error_seen = True
+                        _warn(
+                            f"Failed to load the plugin in {entry.path} due to the following error: {e.message}"
+                        )
+                    else:
+                        _warn(
+                            f"Failed to load plugin in {entry.path} due to errors (not shown)."
+                        )
+                else:
+                    yield plugin_metadata
+
+
+def _find_plugin_implementation_file(
+    plugin_name: str,
+    json_file_path: str,
+) -> Tuple[str, str]:
+    guessed_module_basename = plugin_name.replace("-", "_")
+    module_name = f"debputy.plugin.{guessed_module_basename}"
+    module_fs_path = os.path.join(
+        os.path.dirname(json_file_path), f"{guessed_module_basename}.py"
+    )
+    return module_name, module_fs_path
+
+
+def _resolve_module_initializer(
+    plugin_name: str,
+    plugin_initializer_name: str,
+    module_name: Optional[str],
+    json_file_path: str,
+) -> PluginInitializationEntryPoint:
+    module = None
+    module_fs_path = None
+    if module_name is None:
+        module_name, module_fs_path = _find_plugin_implementation_file(
+            plugin_name, json_file_path
+        )
+        if os.path.isfile(module_fs_path):
+            spec = importlib.util.spec_from_file_location(module_name, module_fs_path)
+            if spec is None:
+                raise PluginInitializationError(
+                    f"Failed to load {plugin_name} (path: {module_fs_path})."
+                    " The spec_from_file_location function returned None."
+                )
+            mod = importlib.util.module_from_spec(spec)
+            loader = spec.loader
+            if loader is None:
+                raise PluginInitializationError(
+                    f"Failed to load {plugin_name} (path: {module_fs_path})."
+                    " Python could not find a suitable loader (spec.loader was None)"
+                )
+            sys.modules[module_name] = mod
+            try:
+                loader.exec_module(mod)
+            except (Exception, GeneratorExit) as e:
+                raise PluginInitializationError(
+                    f"Failed to load {plugin_name} (path: {module_fs_path})."
+                    " The module threw an exception while being loaded."
+                ) from e
+            module = mod
+
+    if module is None:
+        try:
+            module = importlib.import_module(module_name)
+        except ModuleNotFoundError as e:
+            if module_fs_path is None:
+                raise PluginMetadataError(
+                    f'The plugin defined in "{json_file_path}" wanted to load the module "{module_name}", but'
+                    " this module is not available in the python search path"
+                ) from e
+            raise PluginInitializationError(
+                f"Failed to load {plugin_name}. Tried loading it from"
+                f' "{module_fs_path}" (which did not exist) and PYTHONPATH as'
+                f" {module_name} (where it was not found either). Please ensure"
+                " the module code is installed in the correct spot or provide an"
+                f' explicit "module" definition in {json_file_path}.'
+            ) from e
+
+    plugin_initializer = getattr(module, plugin_initializer_name)
+
+    if plugin_initializer is None:
+        raise PluginMetadataError(
+            f'The plugin defined in {json_file_path} claimed that module "{module_name}" would have an'
+            f" attribute called {plugin_initializer}. However, it does not. Please correct the plugin"
+            f" metadata or initializer name in the Python module."
+        )
+    return cast("PluginInitializationEntryPoint", plugin_initializer)
+
+
+def _json_plugin_loader(
+    plugin_name: str,
+    plugin_json_metadata: PluginJsonMetadata,
+    json_file_path: str,
+    attribute_path: AttributePath,
+) -> Callable[["DebputyPluginInitializer"], None]:
+    api_compat = plugin_json_metadata["api_compat_version"]
+    module_name = plugin_json_metadata.get("module")
+    plugin_initializer_name = plugin_json_metadata.get("plugin_initializer")
+    packager_provided_files_raw = plugin_json_metadata.get(
+        "packager_provided_files", []
+    )
+    manifest_variables_raw = plugin_json_metadata.get("manifest_variables")
+    known_packaging_files_raw = plugin_json_metadata.get("known_packaging_files")
+    if api_compat != 1:
+        raise PluginMetadataError(
+            f'The plugin defined in "{json_file_path}" requires API compat level {api_compat}, but this'
+            f" version of debputy only supports API compat version of 1"
+        )
+    if plugin_initializer_name is not None and "." in plugin_initializer_name:
+        p = attribute_path["plugin_initializer"]
+        raise PluginMetadataError(
+            f'The "{p}" must not contain ".". Problematic file is "{json_file_path}".'
+        )
+
+    plugin_initializers = []
+
+    if plugin_initializer_name is not None:
+        plugin_initializer = _resolve_module_initializer(
+            plugin_name,
+            plugin_initializer_name,
+            module_name,
+            json_file_path,
+        )
+        plugin_initializers.append(plugin_initializer)
+
+    if known_packaging_files_raw:
+        kpf_root_path = attribute_path["known_packaging_files"]
+        known_packaging_files = []
+        for k, v in enumerate(known_packaging_files_raw):
+            kpf_path = kpf_root_path[k]
+            p = v.get("path")
+            if isinstance(p, str):
+                kpf_path.path_hint = p
+            if plugin_name.startswith("debputy-") and isinstance(v, dict):
+                docs = v.get("documentation-uris")
+                if docs is not None and isinstance(docs, list):
+                    docs = [
+                        (
+                            d.replace("@DEBPUTY_DOC_ROOT_DIR@", DEBPUTY_DOC_ROOT_DIR)
+                            if isinstance(d, str)
+                            else d
+                        )
+                        for d in docs
+                    ]
+                    v["documentation-uris"] = docs
+            known_packaging_file: KnownPackagingFileInfo = (
+                PLUGIN_KNOWN_PACKAGING_FILES_PARSER.parse_input(
+                    v,
+                    kpf_path,
+                )
+            )
+            known_packaging_files.append((kpf_path, known_packaging_file))
+
+        def _initialize_json_provided_known_packaging_files(
+            api: DebputyPluginInitializerProvider,
+        ) -> None:
+            for p, details in known_packaging_files:
+                try:
+                    api.known_packaging_files(details)
+                except ValueError as ex:
+                    raise PluginMetadataError(
+                        f"Error while processing {p.path} defined in {json_file_path}: {ex.args[0]}"
+                    )
+
+        plugin_initializers.append(_initialize_json_provided_known_packaging_files)
+
+    if manifest_variables_raw:
+        manifest_var_path = attribute_path["manifest_variables"]
+        manifest_variables = [
+            PLUGIN_MANIFEST_VARS_PARSER.parse_input(p, manifest_var_path[i])
+            for i, p in enumerate(manifest_variables_raw)
+        ]
+
+        def _initialize_json_provided_manifest_vars(
+            api: DebputyPluginInitializer,
+        ) -> None:
+            for idx, manifest_variable in enumerate(manifest_variables):
+                name = manifest_variable["name"]
+                value = manifest_variable["value"]
+                doc = manifest_variable.get("reference_documentation")
+                try:
+                    api.manifest_variable(
+                        name, value, variable_reference_documentation=doc
+                    )
+                except ValueError as ex:
+                    var_path = manifest_var_path[idx]
+                    raise PluginMetadataError(
+                        f"Error while processing {var_path.path} defined in {json_file_path}: {ex.args[0]}"
+                    )
+
+        plugin_initializers.append(_initialize_json_provided_manifest_vars)
+
+    if packager_provided_files_raw:
+        ppf_path = attribute_path["packager_provided_files"]
+        ppfs = [
+            PLUGIN_PPF_PARSER.parse_input(p, ppf_path[i])
+            for i, p in enumerate(packager_provided_files_raw)
+        ]
+
+        def _initialize_json_provided_ppfs(api: DebputyPluginInitializer) -> None:
+            ppf: PackagerProvidedFileJsonDescription
+            for idx, ppf in enumerate(ppfs):
+                c = dict(ppf)
+                stem = ppf["stem"]
+                installed_path = ppf["installed_path"]
+                default_mode = ppf.get("default_mode")
+                ref_doc_dict = ppf.get("reference_documentation")
+                if default_mode is not None:
+                    c["default_mode"] = default_mode.octal_mode
+
+                if ref_doc_dict is not None:
+                    ref_doc = packager_provided_file_reference_documentation(
+                        **ref_doc_dict
+                    )
+                else:
+                    ref_doc = None
+
+                for k in [
+                    "stem",
+                    "installed_path",
+                    "reference_documentation",
+                ]:
+                    try:
+                        del c[k]
+                    except KeyError:
+                        pass
+
+                try:
+                    api.packager_provided_file(stem, installed_path, reference_documentation=ref_doc, **c)  # type: ignore
+                except ValueError as ex:
+                    p_path = ppf_path[idx]
+                    raise PluginMetadataError(
+                        f"Error while processing {p_path.path} defined in {json_file_path}: {ex.args[0]}"
+                    )
+
+        plugin_initializers.append(_initialize_json_provided_ppfs)
+
+    if not plugin_initializers:
+        raise PluginMetadataError(
+            f"The plugin defined in {json_file_path} does not seem to provide features, "
+            f" such as module + plugin-initializer or packager-provided-files."
+        )
+
+    if len(plugin_initializers) == 1:
+        return plugin_initializers[0]
+
+    def _chain_loader(api: DebputyPluginInitializer) -> None:
+        for initializer in plugin_initializers:
+            initializer(api)
+
+    return _chain_loader
+
+
+@contextlib.contextmanager
+def _open(path: str, fd: Optional[IO[bytes]] = None) -> Iterator[IO[bytes]]:
+    if fd is not None:
+        yield fd
+    else:
+        with open(path, "rb") as fd:
+            yield fd
+
+
+def parse_json_plugin_desc(
+    path: str, *, fd: Optional[IO[bytes]] = None
+) -> DebputyPluginMetadata:
+    with _open(path, fd=fd) as rfd:
+        try:
+            raw = json.load(rfd)
+        except JSONDecodeError as e:
+            raise PluginMetadataError(
+                f'The plugin defined in "{path}" could not be parsed as valid JSON: {e.args[0]}'
+            ) from e
+    plugin_name = os.path.basename(path)
+    if plugin_name.endswith(".json"):
+        plugin_name = plugin_name[:-5]
+    elif plugin_name.endswith(".json.in"):
+        plugin_name = plugin_name[:-8]
+
+    if plugin_name == "debputy":
+        # Provide a better error message than "The plugin has already loaded!?"
+        raise PluginMetadataError(
+            f'The plugin named {plugin_name} must be bundled with `debputy`. Please rename "{path}" so it does not'
+            f" clash with the bundled plugin of same name."
+        )
+
+    attribute_path = AttributePath.root_path()
+
+    try:
+        plugin_json_metadata = PLUGIN_METADATA_PARSER.parse_input(
+            raw,
+            attribute_path,
+        )
+    except ManifestParseException as e:
+        raise PluginMetadataError(
+            f'The plugin defined in "{path}" was valid JSON but could not be parsed: {e.message}'
+        ) from e
+    api_compat = plugin_json_metadata["api_compat_version"]
+
+    return DebputyPluginMetadata(
+        plugin_name=plugin_name,
+        plugin_loader=lambda: _json_plugin_loader(
+            plugin_name,
+            plugin_json_metadata,
+            path,
+            attribute_path,
+        ),
+        api_compat_version=api_compat,
+        plugin_initializer=None,
+        plugin_path=path,
+    )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ServiceDefinitionImpl(ServiceDefinition[DSD]):
+    name: str
+    names: Sequence[str]
+    path: VirtualPath
+    type_of_service: str
+    service_scope: str
+    auto_enable_on_install: bool
+    auto_start_in_install: bool
+    on_upgrade: ServiceUpgradeRule
+    definition_source: str
+    is_plugin_provided_definition: bool
+    service_context: Optional[DSD]
+
+
+class ServiceRegistryImpl(ServiceRegistry[DSD]):
+    __slots__ = ("_service_manager_details", "_service_definitions")
+
+    def __init__(self, service_manager_details: ServiceManagerDetails) -> None:
+        self._service_manager_details = service_manager_details
+        self._service_definitions: List[ServiceDefinition[DSD]] = []
+
+    @property
+    def detected_services(self) -> Sequence[ServiceDefinition[DSD]]:
+        return self._service_definitions
+
+    def register_service(
+        self,
+        path: VirtualPath,
+        name: Union[str, List[str]],
+        *,
+        type_of_service: str = "service",  # "timer", etc.
+        service_scope: str = "system",
+        enable_by_default: bool = True,
+        start_by_default: bool = True,
+        default_upgrade_rule: ServiceUpgradeRule = "restart",
+        service_context: Optional[DSD] = None,
+    ) -> None:
+        names = name if isinstance(name, list) else [name]
+        if len(names) < 1:
+            raise ValueError(
+                f"The service must have at least one name - {path.absolute} did not have any"
+            )
+        # TODO: We cannot create a service definition immediate once the manifest is involved
+        self._service_definitions.append(
+            ServiceDefinitionImpl(
+                names[0],
+                names,
+                path,
+                type_of_service,
+                service_scope,
+                enable_by_default,
+                start_by_default,
+                default_upgrade_rule,
+                f"Auto-detected by plugin {self._service_manager_details.plugin_metadata.plugin_name}",
+                True,
+                service_context,
+            )
+        )
diff --git a/src/debputy/plugin/api/impl_types.py b/src/debputy/plugin/api/impl_types.py
new file mode 100644
index 0000000..f32b008
--- /dev/null
+++ b/src/debputy/plugin/api/impl_types.py
@@ -0,0 +1,1161 @@
+import dataclasses
+import os.path
+import textwrap
+from typing import (
+    Optional,
+    Callable,
+    FrozenSet,
+    Dict,
+    List,
+    Tuple,
+    Generic,
+    TYPE_CHECKING,
+    TypeVar,
+    cast,
+    Any,
+    Sequence,
+    Union,
+    Type,
+    TypedDict,
+    Iterable,
+    Mapping,
+    NotRequired,
+    Literal,
+    Set,
+    Iterator,
+)
+from weakref import ref
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy.exceptions import (
+    DebputyFSIsROError,
+    PluginAPIViolationError,
+    PluginConflictError,
+    UnhandledOrUnexpectedErrorFromPluginError,
+)
+from debputy.filesystem_scan import as_path_def
+from debputy.installations import InstallRule
+from debputy.maintscript_snippet import DpkgMaintscriptHelperCommand
+from debputy.manifest_conditions import ManifestCondition
+from debputy.manifest_parser.base_types import DebputyParsedContent, TypeMapping
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import (
+    VirtualPath,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.plugin.api.spec import (
+    DebputyPluginInitializer,
+    MetadataAutoDetector,
+    DpkgTriggerType,
+    ParserDocumentation,
+    PackageProcessor,
+    PathDef,
+    ParserAttributeDocumentation,
+    undocumented_attr,
+    documented_attr,
+    reference_documentation,
+    PackagerProvidedFileReferenceDocumentation,
+    TypeMappingDocumentation,
+)
+from debputy.substitution import VariableContext
+from debputy.transformation_rules import TransformationRule
+from debputy.util import _normalize_path, package_cross_check_precheck
+
+if TYPE_CHECKING:
+    from debputy.plugin.api.spec import (
+        ServiceDetector,
+        ServiceIntegrator,
+        PackageTypeSelector,
+    )
+    from debputy.manifest_parser.parser_data import ParserContextData
+    from debputy.highlevel_manifest import (
+        HighLevelManifest,
+        PackageTransformationDefinition,
+        BinaryPackageData,
+    )
+
+
+_PACKAGE_TYPE_DEB_ONLY = frozenset(["deb"])
+_ALL_PACKAGE_TYPES = frozenset(["deb", "udeb"])
+
+
+TD = TypeVar("TD", bound="DebputyParsedContent")
+PF = TypeVar("PF")
+SF = TypeVar("SF")
+TP = TypeVar("TP")
+TTP = Type[TP]
+
+DIPKWHandler = Callable[[str, AttributePath, "ParserContextData"], TP]
+DIPHandler = Callable[[str, PF, AttributePath, "ParserContextData"], TP]
+
+
+def resolve_package_type_selectors(
+    package_type: "PackageTypeSelector",
+) -> FrozenSet[str]:
+    if package_type is _ALL_PACKAGE_TYPES or package_type is _PACKAGE_TYPE_DEB_ONLY:
+        return cast("FrozenSet[str]", package_type)
+    if isinstance(package_type, str):
+        return (
+            _PACKAGE_TYPE_DEB_ONLY
+            if package_type == "deb"
+            else frozenset([package_type])
+        )
+    else:
+        return frozenset(package_type)
+
+
+@dataclasses.dataclass(slots=True)
+class DebputyPluginMetadata:
+    plugin_name: str
+    api_compat_version: int
+    plugin_loader: Optional[Callable[[], Callable[["DebputyPluginInitializer"], None]]]
+    plugin_initializer: Optional[Callable[["DebputyPluginInitializer"], None]]
+    plugin_path: str
+    _is_initialized: bool = False
+
+    @property
+    def is_loaded(self) -> bool:
+        return self.plugin_initializer is not None
+
+    @property
+    def is_initialized(self) -> bool:
+        return self._is_initialized
+
+    def initialize_plugin(self, api: "DebputyPluginInitializer") -> None:
+        if self.is_initialized:
+            raise RuntimeError("Cannot load plugins twice")
+        if not self.is_loaded:
+            self.load_plugin()
+        plugin_initializer = self.plugin_initializer
+        assert plugin_initializer is not None
+        plugin_initializer(api)
+        self._is_initialized = True
+
+    def load_plugin(self) -> None:
+        plugin_loader = self.plugin_loader
+        assert plugin_loader is not None
+        self.plugin_initializer = plugin_loader()
+        assert self.plugin_initializer is not None
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PluginProvidedParser(Generic[PF, TP]):
+    parser: "DeclarativeInputParser[PF]"
+    handler: Callable[[str, PF, "AttributePath", "ParserContextData"], TP]
+    plugin_metadata: DebputyPluginMetadata
+
+    def parse(
+        self,
+        name: str,
+        value: object,
+        attribute_path: "AttributePath",
+        *,
+        parser_context: "ParserContextData",
+    ) -> TP:
+        parsed_value = self.parser.parse_input(
+            value, attribute_path, parser_context=parser_context
+        )
+        return self.handler(name, parsed_value, attribute_path, parser_context)
+
+
+class PPFFormatParam(TypedDict):
+    priority: Optional[int]
+    name: str
+    owning_package: str
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PackagerProvidedFileClassSpec:
+    debputy_plugin_metadata: DebputyPluginMetadata
+    stem: str
+    installed_as_format: str
+    default_mode: int
+    default_priority: Optional[int]
+    allow_name_segment: bool
+    allow_architecture_segment: bool
+    post_formatting_rewrite: Optional[Callable[[str], str]]
+    packageless_is_fallback_for_all_packages: bool
+    reservation_only: bool
+    formatting_callback: Optional[Callable[[str, PPFFormatParam, VirtualPath], str]] = (
+        None
+    )
+    reference_documentation: Optional[PackagerProvidedFileReferenceDocumentation] = None
+    bug_950723: bool = False
+
+    @property
+    def supports_priority(self) -> bool:
+        return self.default_priority is not None
+
+    def compute_dest(
+        self,
+        assigned_name: str,
+        # Note this method is currently used 1:1 inside plugin tests.
+        *,
+        owning_package: Optional[str] = None,
+        assigned_priority: Optional[int] = None,
+        path: Optional[VirtualPath] = None,
+    ) -> Tuple[str, str]:
+        if assigned_priority is not None and not self.supports_priority:
+            raise ValueError(
+                f"Cannot assign priority to packager provided files with stem"
+                f' "{self.stem}" (e.g., "debian/foo.{self.stem}"). They'
+                " do not use priority at all."
+            )
+
+        path_format = self.installed_as_format
+        if self.supports_priority and assigned_priority is None:
+            assigned_priority = self.default_priority
+
+        if owning_package is None:
+            owning_package = assigned_name
+
+        params: PPFFormatParam = {
+            "priority": assigned_priority,
+            "name": assigned_name,
+            "owning_package": owning_package,
+        }
+
+        if self.formatting_callback is not None:
+            if path is None:
+                raise ValueError(
+                    "The path parameter is required for PPFs with formatting_callback"
+                )
+            dest_path = self.formatting_callback(path_format, params, path)
+        else:
+            dest_path = path_format.format(**params)
+
+        dirname, basename = os.path.split(dest_path)
+        dirname = _normalize_path(dirname)
+
+        if self.post_formatting_rewrite:
+            basename = self.post_formatting_rewrite(basename)
+        return dirname, basename
+
+
+@dataclasses.dataclass(slots=True)
+class MetadataOrMaintscriptDetector:
+    plugin_metadata: DebputyPluginMetadata
+    detector_id: str
+    detector: MetadataAutoDetector
+    applies_to_package_types: FrozenSet[str]
+    enabled: bool = True
+
+    def applies_to(self, binary_package: BinaryPackage) -> bool:
+        return binary_package.package_type in self.applies_to_package_types
+
+    def run_detector(
+        self,
+        fs_root: "VirtualPath",
+        ctrl: "BinaryCtrlAccessor",
+        context: "PackageProcessingContext",
+    ) -> None:
+        try:
+            self.detector(fs_root, ctrl, context)
+        except DebputyFSIsROError as e:
+            nv = self.plugin_metadata.plugin_name
+            raise PluginAPIViolationError(
+                f'The plugin {nv} violated the API contract for "metadata detectors"'
+                " by attempting to mutate the provided file system in its metadata detector"
+                f" with id {self.detector_id}.  File system mutation is *not* supported at"
+                " this stage (file system layout is committed and the attempted changes"
+                " would be lost)."
+            ) from e
+        except (ChildProcessError, RuntimeError, AttributeError) as e:
+            nv = f"{self.plugin_metadata.plugin_name}"
+            raise UnhandledOrUnexpectedErrorFromPluginError(
+                f"The plugin {nv} threw an unhandled or unexpected exception from its metadata"
+                f" detector with id {self.detector_id}."
+            ) from e
+
+
+class DeclarativeInputParser(Generic[TD]):
+    @property
+    def inline_reference_documentation(self) -> Optional[ParserDocumentation]:
+        return None
+
+    @property
+    def reference_documentation_url(self) -> Optional[str]:
+        doc = self.inline_reference_documentation
+        return doc.documentation_reference_url if doc is not None else None
+
+    def parse_input(
+        self,
+        value: object,
+        path: "AttributePath",
+        *,
+        parser_context: Optional["ParserContextData"] = None,
+    ) -> TD:
+        raise NotImplementedError
+
+
+class DispatchingParserBase(Generic[TP]):
+    def __init__(self, manifest_attribute_path_template: str) -> None:
+        self.manifest_attribute_path_template = manifest_attribute_path_template
+        self._parsers: Dict[str, PluginProvidedParser[Any, TP]] = {}
+
+    def is_known_keyword(self, keyword: str) -> bool:
+        return keyword in self._parsers
+
+    def registered_keywords(self) -> Iterable[str]:
+        yield from self._parsers
+
+    def parser_for(self, keyword: str) -> PluginProvidedParser[Any, TP]:
+        return self._parsers[keyword]
+
+    def register_keyword(
+        self,
+        keyword: Union[str, Sequence[str]],
+        handler: DIPKWHandler,
+        plugin_metadata: DebputyPluginMetadata,
+        *,
+        inline_reference_documentation: Optional[ParserDocumentation] = None,
+    ) -> None:
+        reference_documentation_url = None
+        if inline_reference_documentation:
+            if inline_reference_documentation.attribute_doc:
+                raise ValueError(
+                    "Cannot provide per-attribute documentation for a value-less keyword!"
+                )
+            if inline_reference_documentation.alt_parser_description:
+                raise ValueError(
+                    "Cannot provide non-mapping-format documentation for a value-less keyword!"
+                )
+            reference_documentation_url = (
+                inline_reference_documentation.documentation_reference_url
+            )
+        parser = DeclarativeValuelessKeywordInputParser(
+            inline_reference_documentation,
+            documentation_reference=reference_documentation_url,
+        )
+
+        def _combined_handler(
+            name: str,
+            _ignored: Any,
+            attr_path: AttributePath,
+            context: "ParserContextData",
+        ) -> TP:
+            return handler(name, attr_path, context)
+
+        p = PluginProvidedParser(
+            parser,
+            _combined_handler,
+            plugin_metadata,
+        )
+
+        self._add_parser(keyword, p)
+
+    def register_parser(
+        self,
+        keyword: Union[str, List[str]],
+        parser: "DeclarativeInputParser[PF]",
+        handler: Callable[[str, PF, "AttributePath", "ParserContextData"], TP],
+        plugin_metadata: DebputyPluginMetadata,
+    ) -> None:
+        p = PluginProvidedParser(
+            parser,
+            handler,
+            plugin_metadata,
+        )
+        self._add_parser(keyword, p)
+
+    def _add_parser(
+        self,
+        keyword: Union[str, List[str]],
+        ppp: "PluginProvidedParser[PF, TP]",
+    ) -> None:
+        ks = [keyword] if isinstance(keyword, str) else keyword
+        for k in ks:
+            existing_parser = self._parsers.get(k)
+            if existing_parser is not None:
+                message = (
+                    f'The rule name "{k}" is already taken by the plugin'
+                    f" {existing_parser.plugin_metadata.plugin_name}. This conflict was triggered"
+                    f" when plugin {ppp.plugin_metadata.plugin_name} attempted to register its parser."
+                )
+                raise PluginConflictError(
+                    message,
+                    existing_parser.plugin_metadata,
+                    ppp.plugin_metadata,
+                )
+            self._new_parser(k, ppp)
+
+    def _new_parser(self, keyword: str, ppp: "PluginProvidedParser[PF, TP]") -> None:
+        self._parsers[keyword] = ppp
+
+    def parse(
+        self,
+        orig_value: object,
+        attribute_path: "AttributePath",
+        *,
+        parser_context: "ParserContextData",
+    ) -> TP:
+        raise NotImplementedError
+
+
+class DispatchingObjectParser(
+    DispatchingParserBase[Mapping[str, Any]],
+    DeclarativeInputParser[Mapping[str, Any]],
+):
+    def __init__(
+        self,
+        manifest_attribute_path_template: str,
+        *,
+        parser_documentation: Optional[ParserDocumentation] = None,
+    ) -> None:
+        super().__init__(manifest_attribute_path_template)
+        self._attribute_documentation: List[ParserAttributeDocumentation] = []
+        if parser_documentation is None:
+            parser_documentation = reference_documentation()
+        self._parser_documentation = parser_documentation
+
+    @property
+    def reference_documentation_url(self) -> Optional[str]:
+        return self._parser_documentation.documentation_reference_url
+
+    @property
+    def inline_reference_documentation(self) -> Optional[ParserDocumentation]:
+        ref_doc = self._parser_documentation
+        return reference_documentation(
+            title=ref_doc.title,
+            description=ref_doc.description,
+            attributes=self._attribute_documentation,
+            reference_documentation_url=self.reference_documentation_url,
+        )
+
+    def _new_parser(self, keyword: str, ppp: "PluginProvidedParser[PF, TP]") -> None:
+        super()._new_parser(keyword, ppp)
+        doc = ppp.parser.inline_reference_documentation
+        if doc is None or doc.description is None:
+            self._attribute_documentation.append(undocumented_attr(keyword))
+        else:
+            self._attribute_documentation.append(
+                documented_attr(keyword, doc.description)
+            )
+
+    def register_child_parser(
+        self,
+        keyword: str,
+        parser: "DispatchingObjectParser",
+        plugin_metadata: DebputyPluginMetadata,
+        *,
+        on_end_parse_step: Optional[
+            Callable[
+                [str, Optional[Mapping[str, Any]], AttributePath, "ParserContextData"],
+                None,
+            ]
+        ] = None,
+    ) -> None:
+        def _handler(
+            name: str,
+            value: Mapping[str, Any],
+            path: AttributePath,
+            parser_context: "ParserContextData",
+        ) -> Mapping[str, Any]:
+            on_end_parse_step(name, value, path, parser_context)
+            return value
+
+        p = PluginProvidedParser(
+            parser,
+            _handler,
+            plugin_metadata,
+        )
+        self._add_parser(keyword, p)
+
+    # FIXME: Agree on naming (parse vs. parse_input)
+    def parse_input(
+        self,
+        value: object,
+        path: "AttributePath",
+        *,
+        parser_context: Optional["ParserContextData"] = None,
+    ) -> TD:
+        return self.parse(value, path, parser_context=parser_context)
+
+    def parse(
+        self,
+        orig_value: object,
+        attribute_path: "AttributePath",
+        *,
+        parser_context: "ParserContextData",
+    ) -> TP:
+        doc_ref = ""
+        if self.reference_documentation_url is not None:
+            doc_ref = (
+                f" Please see {self.reference_documentation_url} for the documentation."
+            )
+        if not isinstance(orig_value, dict):
+            raise ManifestParseException(
+                f"The attribute {attribute_path.path} must be a non-empty mapping.{doc_ref}"
+            )
+        if not orig_value:
+            raise ManifestParseException(
+                f"The attribute {attribute_path.path} must be a non-empty mapping.{doc_ref}"
+            )
+        result = {}
+        unknown_keys = orig_value.keys() - self._parsers.keys()
+        if unknown_keys:
+            first_key = next(iter(unknown_keys))
+            remaining_valid_attributes = self._parsers.keys() - orig_value.keys()
+            if not remaining_valid_attributes:
+                raise ManifestParseException(
+                    f'The attribute "{first_key}" is not applicable at {attribute_path.path} (with the'
+                    f" current set of plugins).{doc_ref}"
+                )
+            remaining_valid_attribute_names = ", ".join(remaining_valid_attributes)
+            raise ManifestParseException(
+                f'The attribute "{first_key}" is not applicable at {attribute_path.path}(with the current set'
+                " of plugins). Possible attributes available (and not already used) are:"
+                f" {remaining_valid_attribute_names}.{doc_ref}"
+            )
+        # Parse order is important for the root level (currently we use rule registration order)
+        for key, provided_parser in self._parsers.items():
+            value = orig_value.get(key)
+            if value is None:
+                if isinstance(provided_parser.parser, DispatchingObjectParser):
+                    provided_parser.handler(
+                        key, {}, attribute_path[key], parser_context
+                    )
+                continue
+            value_path = attribute_path[key]
+            if provided_parser is None:
+                valid_keys = ", ".join(sorted(self._parsers.keys()))
+                raise ManifestParseException(
+                    f'Unknown or unsupported option "{key}" at {value_path.path}.'
+                    " Valid options at this location are:"
+                    f" {valid_keys}\n{doc_ref}"
+                )
+            parsed_value = provided_parser.parse(
+                key, value, value_path, parser_context=parser_context
+            )
+            result[key] = parsed_value
+        return result
+
+
+class DispatchingTableParser(DispatchingParserBase[TP]):
+    def __init__(self, base_type: TTP, manifest_attribute_path_template: str) -> None:
+        super().__init__(manifest_attribute_path_template)
+        self.base_type = base_type
+
+    def parse(
+        self,
+        orig_value: object,
+        attribute_path: "AttributePath",
+        *,
+        parser_context: "ParserContextData",
+    ) -> TP:
+        if isinstance(orig_value, str):
+            key = orig_value
+            value = None
+            value_path = attribute_path
+        elif isinstance(orig_value, dict):
+            if len(orig_value) != 1:
+                valid_keys = ", ".join(sorted(self._parsers.keys()))
+                raise ManifestParseException(
+                    f'The mapping "{attribute_path.path}" had two keys, but it should only have one top level key.'
+                    " Maybe you are missing a list marker behind the second key or some indentation.  The"
+                    f" possible keys are: {valid_keys}"
+                )
+            key, value = next(iter(orig_value.items()))
+            value_path = attribute_path[key]
+        else:
+            raise ManifestParseException(
+                f"The attribute {attribute_path.path} must be a string or a mapping."
+            )
+        provided_parser = self._parsers.get(key)
+        if provided_parser is None:
+            valid_keys = ", ".join(sorted(self._parsers.keys()))
+            raise ManifestParseException(
+                f'Unknown or unsupported action "{key}" at {value_path.path}.'
+                " Valid actions at this location are:"
+                f" {valid_keys}"
+            )
+        return provided_parser.parse(
+            key, value, value_path, parser_context=parser_context
+        )
+
+
+@dataclasses.dataclass(slots=True)
+class DeclarativeValuelessKeywordInputParser(DeclarativeInputParser[None]):
+    inline_reference_documentation: Optional[ParserDocumentation] = None
+    documentation_reference: Optional[str] = None
+
+    def parse_input(
+        self,
+        value: object,
+        path: "AttributePath",
+        *,
+        parser_context: Optional["ParserContextData"] = None,
+    ) -> TD:
+        if value is None:
+            return cast("TD", value)
+        if self.documentation_reference is not None:
+            doc_ref = f" (Documentation: {self.documentation_reference})"
+        else:
+            doc_ref = ""
+        raise ManifestParseException(
+            f"Expected attribute {path.path} to be a string.{doc_ref}"
+        )
+
+
+SUPPORTED_DISPATCHABLE_TABLE_PARSERS = {
+    InstallRule: "installations",
+    TransformationRule: "packages.{{PACKAGE}}.transformations",
+    DpkgMaintscriptHelperCommand: "packages.{{PACKAGE}}.conffile-management",
+    ManifestCondition: "*.when",
+}
+
+OPARSER_MANIFEST_ROOT = "<ROOT>"
+OPARSER_PACKAGES = "packages.{{PACKAGE}}"
+OPARSER_MANIFEST_DEFINITIONS = "definitions"
+
+SUPPORTED_DISPATCHABLE_OBJECT_PARSERS = {
+    OPARSER_MANIFEST_ROOT: reference_documentation(
+        reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md",
+    ),
+    OPARSER_MANIFEST_DEFINITIONS: reference_documentation(
+        title="Packager provided definitions",
+        description="Reusable packager provided definitions such as manifest variables.",
+        reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#packager-provided-definitions",
+    ),
+    OPARSER_PACKAGES: reference_documentation(
+        title="Binary package rules",
+        description=textwrap.dedent(
+            """\
+            Inside the manifest, the `packages` mapping can be used to define requests for the binary packages
+            you want `debputy` to produce.  Each key inside `packages` must be the name of a binary package
+            defined in `debian/control`.  The value is a dictionary defining which features that `debputy`
+            should apply to that binary package.  An example could be:
+
+                packages:
+                    foo:
+                        transformations:
+                            - create-symlink:
+                                  path: usr/share/foo/my-first-symlink
+                                  target: /usr/share/bar/symlink-target
+                            - create-symlink:
+                                  path: usr/lib/{{DEB_HOST_MULTIARCH}}/my-second-symlink
+                                  target: /usr/lib/{{DEB_HOST_MULTIARCH}}/baz/symlink-target
+                    bar:
+                        transformations:
+                        - create-directories:
+                           - some/empty/directory.d
+                           - another/empty/integration-point.d
+                        - create-directories:
+                             path: a/third-empty/directory.d
+                             owner: www-data
+                             group: www-data
+
+            In this case, `debputy` will create some symlinks inside the `foo` package and some directories for
+            the `bar` package.  The following subsections define the keys you can use under each binary package.
+        """
+        ),
+        reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#binary-package-rules",
+    ),
+}
+
+
+@dataclasses.dataclass(slots=True)
+class PluginProvidedManifestVariable:
+    plugin_metadata: DebputyPluginMetadata
+    variable_name: str
+    variable_value: Optional[Union[str, Callable[[VariableContext], str]]]
+    is_context_specific_variable: bool
+    variable_reference_documentation: Optional[str] = None
+    is_documentation_placeholder: bool = False
+    is_for_special_case: bool = False
+
+    @property
+    def is_internal(self) -> bool:
+        return self.variable_name.startswith("_") or ":_" in self.variable_name
+
+    @property
+    def is_token(self) -> bool:
+        return self.variable_name.startswith("token:")
+
+    def resolve(self, variable_context: VariableContext) -> str:
+        value_resolver = self.variable_value
+        if isinstance(value_resolver, str):
+            res = value_resolver
+        else:
+            res = value_resolver(variable_context)
+        return res
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class AutomaticDiscardRuleExample:
+    content: Sequence[Tuple[PathDef, bool]]
+    description: Optional[str] = None
+
+
+def automatic_discard_rule_example(
+    *content: Union[str, PathDef, Tuple[Union[str, PathDef], bool]],
+    example_description: Optional[str] = None,
+) -> AutomaticDiscardRuleExample:
+    """Provide an example for an automatic discard rule
+
+    The return value of this method should be passed to the `examples` parameter of
+    `automatic_discard_rule` method - either directly for a single example or as a
+    part of a sequence of examples.
+
+    >>> # Possible example for an exclude rule for ".la" files
+    >>> # Example shows two files; The ".la" file that will be removed and another file that
+    >>> # will be kept.
+    >>> automatic_discard_rule_example(   # doctest: +ELLIPSIS
+    ...     "usr/lib/libfoo.la",
+    ...     ("usr/lib/libfoo.so.1.0.0", False),
+    ... )
+    AutomaticDiscardRuleExample(...)
+
+    Keep in mind that you have to explicitly include directories that are relevant for the test
+    if you want them shown. Also, if a directory is excluded, all path beneath it will be
+    automatically excluded in the example as well. Your example data must account for that.
+
+    >>> # Possible example for python cache file discard rule
+    >>> # In this example, we explicitly list the __pycache__ directory itself because we
+    >>> # want it shown in the output (otherwise, we could have omitted it)
+    >>> automatic_discard_rule_example(   # doctest: +ELLIPSIS
+    ...     (".../foo.py", False),
+    ...     ".../__pycache__/",
+    ...     ".../__pycache__/...",
+    ...     ".../foo.pyc",
+    ...     ".../foo.pyo",
+    ... )
+    AutomaticDiscardRuleExample(...)
+
+    Note: Even if `__pycache__` had been implicit, the result would have been the same. However,
+    the rendered example would not have shown the directory on its own.  The use of `...` as
+    path names is useful for denoting "anywhere" or "anything". Though, there is nothing "magic"
+    about this name - it happens to be allowed as a path name (unlike `.` or `..`).
+
+    These examples can be seen via `debputy plugin show automatic-discard-rules <name-here>`.
+
+    :param content: The content of the example.  Each element can be either a path definition or
+      a tuple of a path definition followed by a verdict (boolean). Each provided path definition
+      describes the paths to be presented in the example. Implicit paths such as parent
+      directories will be created but not shown in the example.  Therefore, if a directory is
+      relevant to the example, be sure to explicitly list it.
+
+      The verdict associated with a path determines whether the path should be discarded (when
+      True) or kept (when False). When a path is not explicitly associated with a verdict, the
+      verdict is assumed to be discarded (True).
+    :param example_description: An optional description displayed together with the example.
+    :return: An opaque data structure containing the example.
+    """
+    example = []
+    for d in content:
+        if not isinstance(d, tuple):
+            pd = d
+            verdict = True
+        else:
+            pd, verdict = d
+
+        path_def = as_path_def(pd)
+        example.append((path_def, verdict))
+
+    if not example:
+        raise ValueError("At least one path must be given for an example")
+
+    return AutomaticDiscardRuleExample(
+        tuple(example),
+        description=example_description,
+    )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PluginProvidedPackageProcessor:
+    processor_id: str
+    applies_to_package_types: FrozenSet[str]
+    package_processor: PackageProcessor
+    dependencies: FrozenSet[Tuple[str, str]]
+    plugin_metadata: DebputyPluginMetadata
+
+    def applies_to(self, binary_package: BinaryPackage) -> bool:
+        return binary_package.package_type in self.applies_to_package_types
+
+    @property
+    def dependency_id(self) -> Tuple[str, str]:
+        return self.plugin_metadata.plugin_name, self.processor_id
+
+    def run_package_processor(
+        self,
+        fs_root: "VirtualPath",
+        unused: None,
+        context: "PackageProcessingContext",
+    ) -> None:
+        self.package_processor(fs_root, unused, context)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PluginProvidedDiscardRule:
+    name: str
+    plugin_metadata: DebputyPluginMetadata
+    discard_check: Callable[[VirtualPath], bool]
+    reference_documentation: Optional[str]
+    examples: Sequence[AutomaticDiscardRuleExample] = tuple()
+
+    def should_discard(self, path: VirtualPath) -> bool:
+        return self.discard_check(path)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ServiceManagerDetails:
+    service_manager: str
+    service_detector: "ServiceDetector"
+    service_integrator: "ServiceIntegrator"
+    plugin_metadata: DebputyPluginMetadata
+
+
+ReferenceValue = TypedDict(
+    "ReferenceValue",
+    {
+        "description": str,
+    },
+)
+
+
+def _reference_data_value(
+    *,
+    description: str,
+) -> ReferenceValue:
+    return {
+        "description": description,
+    }
+
+
+KnownPackagingFileCategories = Literal[
+    "generated",
+    "generic-template",
+    "ppf-file",
+    "ppf-control-file",
+    "maint-config",
+    "pkg-metadata",
+    "pkg-helper-config",
+    "testing",
+    "lint-config",
+]
+KNOWN_PACKAGING_FILE_CATEGORY_DESCRIPTIONS: Mapping[
+    KnownPackagingFileCategories, ReferenceValue
+] = {
+    "generated": _reference_data_value(
+        description="The file is (likely) generated from another file"
+    ),
+    "generic-template": _reference_data_value(
+        description="The file is (likely) a generic template that generates a known packaging file. While the"
+        " file is annotated as if it was the target file, the file might uses a custom template"
+        " language inside it."
+    ),
+    "ppf-file": _reference_data_value(
+        description="Packager provided file to be installed on the file system - usually as-is."
+        " When `install-pattern` or `install-path` are provided, this is where the file is installed."
+    ),
+    "ppf-control-file": _reference_data_value(
+        description="Packager provided file that becomes a control file - possible after processing. "
+        " If `install-pattern` or `install-path` are provided, they denote where the is placed"
+        " (generally, this will be of the form `DEBIAN/<name>`)"
+    ),
+    "maint-config": _reference_data_value(
+        description="Maintenance configuration for a specific tool that the maintainer uses (tool / style preferences)"
+    ),
+    "pkg-metadata": _reference_data_value(
+        description="The file is related to standard package metadata (usually documented in Debian Policy)"
+    ),
+    "pkg-helper-config": _reference_data_value(
+        description="The file is packaging helper configuration or instruction file"
+    ),
+    "testing": _reference_data_value(
+        description="The file is related to automated testing (autopkgtests, salsa/gitlab CI)."
+    ),
+    "lint-config": _reference_data_value(
+        description="The file is related to a linter (such as overrides for false-positives or style preferences)"
+    ),
+}
+
+KnownPackagingConfigFeature = Literal[
+    "dh-filearray",
+    "dh-filedoublearray",
+    "dh-hash-subst",
+    "dh-dollar-subst",
+    "dh-glob",
+    "dh-partial-glob",
+    "dh-late-glob",
+    "dh-glob-after-execute",
+    "dh-executable-config",
+    "dh-custom-format",
+    "dh-file-list",
+    "dh-install-list",
+    "dh-install-list-dest-dir-like-dh_install",
+    "dh-install-list-fixed-dest-dir",
+    "dh-fixed-dest-dir",
+    "dh-exec-rename",
+    "dh-docs-only",
+]
+
+KNOWN_PACKAGING_FILE_CONFIG_FEATURE_DESCRIPTION: Mapping[
+    KnownPackagingConfigFeature, ReferenceValue
+] = {
+    "dh-filearray": _reference_data_value(
+        description="The file will be read as a list of space/newline separated tokens",
+    ),
+    "dh-filedoublearray": _reference_data_value(
+        description="Each line in the file will be read as a list of space-separated tokens",
+    ),
+    "dh-hash-subst": _reference_data_value(
+        description="Supports debhelper #PACKAGE# style substitutions (udebs often excluded)",
+    ),
+    "dh-dollar-subst": _reference_data_value(
+        description="Supports debhelper ${PACKAGE} style substitutions (usually requires compat 13+)",
+    ),
+    "dh-glob": _reference_data_value(
+        description="Supports standard debhelper globing",
+    ),
+    "dh-partial-glob": _reference_data_value(
+        description="Supports standard debhelper globing but only to a subset of the values (implies dh-late-glob)",
+    ),
+    "dh-late-glob": _reference_data_value(
+        description="Globbing is done separately instead of using the built-in function",
+    ),
+    "dh-glob-after-execute": _reference_data_value(
+        description="When the dh config file is executable, the generated output will be subject to globbing",
+    ),
+    "dh-executable-config": _reference_data_value(
+        description="If marked executable, debhelper will execute the file and read its output",
+    ),
+    "dh-custom-format": _reference_data_value(
+        description="The dh tool will or may have a custom parser for this file",
+    ),
+    "dh-file-list": _reference_data_value(
+        description="The dh file contains a list of paths to be processed",
+    ),
+    "dh-install-list": _reference_data_value(
+        description="The dh file contains a list of paths/globs to be installed but the tool specific knowledge"
+        " required to understand the file cannot be conveyed via this interface.",
+    ),
+    "dh-install-list-dest-dir-like-dh_install": _reference_data_value(
+        description="The dh file is processed similar to dh_install (notably dest-dir handling derived"
+        " from the path or the last token on the line)",
+    ),
+    "dh-install-list-fixed-dest-dir": _reference_data_value(
+        description="The dh file is an install list and the dest-dir is always the same for all patterns"
+        " (when `install-pattern` or `install-path` are provided, they identify the directory - not the file location)",
+    ),
+    "dh-exec-rename": _reference_data_value(
+        description="When `dh-exec` is the interpreter of this dh config file, its renaming (=>) feature can be"
+        " requested/used",
+    ),
+    "dh-docs-only": _reference_data_value(
+        description="The dh config file is used for documentation only. Implicit <!nodocs> Build-Profiles support",
+    ),
+}
+
+CONFIG_FEATURE_ALIASES: Dict[
+    KnownPackagingConfigFeature, List[Tuple[KnownPackagingConfigFeature, int]]
+] = {
+    "dh-filearray": [
+        ("dh-filearray", 0),
+        ("dh-executable-config", 9),
+        ("dh-dollar-subst", 13),
+    ],
+    "dh-filedoublearray": [
+        ("dh-filedoublearray", 0),
+        ("dh-executable-config", 9),
+        ("dh-dollar-subst", 13),
+    ],
+}
+
+
+def _implies(
+    features: List[KnownPackagingConfigFeature],
+    seen: Set[KnownPackagingConfigFeature],
+    implying: Sequence[KnownPackagingConfigFeature],
+    implied: KnownPackagingConfigFeature,
+) -> None:
+    if implied in seen:
+        return
+    if all(f in seen for f in implying):
+        seen.add(implied)
+        features.append(implied)
+
+
+def expand_known_packaging_config_features(
+    compat_level: int,
+    features: List[KnownPackagingConfigFeature],
+) -> List[KnownPackagingConfigFeature]:
+    final_features: List[KnownPackagingConfigFeature] = []
+    seen = set()
+    for feature in features:
+        expanded = CONFIG_FEATURE_ALIASES.get(feature)
+        if not expanded:
+            expanded = [(feature, 0)]
+        for v, c in expanded:
+            if compat_level < c or v in seen:
+                continue
+            seen.add(v)
+            final_features.append(v)
+    if "dh-glob" in seen and "dh-late-glob" in seen:
+        final_features.remove("dh-glob")
+
+    _implies(final_features, seen, ["dh-partial-glob"], "dh-late-glob")
+    _implies(
+        final_features,
+        seen,
+        ["dh-late-glob", "dh-executable-config"],
+        "dh-glob-after-execute",
+    )
+    return sorted(final_features)
+
+
+class InstallPatternDHCompatRule(DebputyParsedContent):
+    install_pattern: NotRequired[str]
+    add_config_features: NotRequired[List[KnownPackagingConfigFeature]]
+    starting_with_compat_level: NotRequired[int]
+
+
+class KnownPackagingFileInfo(DebputyParsedContent):
+    # Exposed directly in the JSON plugin parsing; be careful with changes
+    path: NotRequired[str]
+    pkgfile: NotRequired[str]
+    detection_method: NotRequired[Literal["path", "dh.pkgfile"]]
+    file_categories: NotRequired[List[KnownPackagingFileCategories]]
+    documentation_uris: NotRequired[List[str]]
+    debputy_cmd_templates: NotRequired[List[List[str]]]
+    debhelper_commands: NotRequired[List[str]]
+    config_features: NotRequired[List[KnownPackagingConfigFeature]]
+    install_pattern: NotRequired[str]
+    dh_compat_rules: NotRequired[List[InstallPatternDHCompatRule]]
+    default_priority: NotRequired[int]
+    post_formatting_rewrite: NotRequired[Literal["period-to-underscore"]]
+    packageless_is_fallback_for_all_packages: NotRequired[bool]
+
+
+@dataclasses.dataclass(slots=True)
+class PluginProvidedKnownPackagingFile:
+    info: KnownPackagingFileInfo
+    detection_method: Literal["path", "dh.pkgfile"]
+    detection_value: str
+    plugin_metadata: DebputyPluginMetadata
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PluginProvidedTypeMapping:
+    mapped_type: TypeMapping[Any, Any]
+    reference_documentation: Optional[TypeMappingDocumentation]
+    plugin_metadata: DebputyPluginMetadata
+
+
+class PackageDataTable:
+    def __init__(self, package_data_table: Mapping[str, "BinaryPackageData"]) -> None:
+        self._package_data_table = package_data_table
+        # This is enabled for metadata-detectors. But it is deliberate not enabled for package processors,
+        # because it is not clear how it should interact with dependencies. For metadata-detectors, things
+        # read-only and there are no dependencies, so we cannot "get them wrong".
+        self.enable_cross_package_checks = False
+
+    def __iter__(self) -> Iterator["BinaryPackageData"]:
+        return iter(self._package_data_table.values())
+
+    def __getitem__(self, item: str) -> "BinaryPackageData":
+        return self._package_data_table[item]
+
+    def __contains__(self, item: str) -> bool:
+        return item in self._package_data_table
+
+
+class PackageProcessingContextProvider(PackageProcessingContext):
+    __slots__ = (
+        "_manifest",
+        "_binary_package",
+        "_related_udeb_package",
+        "_package_data_table",
+        "_cross_check_cache",
+    )
+
+    def __init__(
+        self,
+        manifest: "HighLevelManifest",
+        binary_package: BinaryPackage,
+        related_udeb_package: Optional[BinaryPackage],
+        package_data_table: PackageDataTable,
+    ) -> None:
+        self._manifest = manifest
+        self._binary_package = binary_package
+        self._related_udeb_package = related_udeb_package
+        self._package_data_table = ref(package_data_table)
+        self._cross_check_cache: Optional[
+            Sequence[Tuple[BinaryPackage, "VirtualPath"]]
+        ] = None
+
+    def _package_state_for(
+        self,
+        package: BinaryPackage,
+    ) -> "PackageTransformationDefinition":
+        return self._manifest.package_state_for(package.name)
+
+    def _package_version_for(
+        self,
+        package: BinaryPackage,
+    ) -> str:
+        package_state = self._package_state_for(package)
+        version = package_state.binary_version
+        if version is not None:
+            return version
+        return self._manifest.source_version(
+            include_binnmu_version=not package.is_arch_all
+        )
+
+    @property
+    def binary_package(self) -> BinaryPackage:
+        return self._binary_package
+
+    @property
+    def related_udeb_package(self) -> Optional[BinaryPackage]:
+        return self._related_udeb_package
+
+    @property
+    def binary_package_version(self) -> str:
+        return self._package_version_for(self._binary_package)
+
+    @property
+    def related_udeb_package_version(self) -> Optional[str]:
+        udeb = self._related_udeb_package
+        if udeb is None:
+            return None
+        return self._package_version_for(udeb)
+
+    def accessible_package_roots(self) -> Iterable[Tuple[BinaryPackage, "VirtualPath"]]:
+        package_table = self._package_data_table()
+        if package_table is None:
+            raise ReferenceError(
+                "Internal error: package_table was garbage collected too early"
+            )
+        if not package_table.enable_cross_package_checks:
+            raise PluginAPIViolationError(
+                "Cross package content checks are not available at this time."
+            )
+        cache = self._cross_check_cache
+        if cache is None:
+            matches = []
+            pkg = self.binary_package
+            for pkg_data in package_table:
+                if pkg_data.binary_package.name == pkg.name:
+                    continue
+                res = package_cross_check_precheck(pkg, pkg_data.binary_package)
+                if not res[0]:
+                    continue
+                matches.append((pkg_data.binary_package, pkg_data.fs_root))
+            cache = tuple(matches) if matches else tuple()
+            self._cross_check_cache = cache
+        return cache
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PluginProvidedTrigger:
+    dpkg_trigger_type: DpkgTriggerType
+    dpkg_trigger_target: str
+    provider: DebputyPluginMetadata
+    provider_source_id: str
+
+    def serialized_format(self) -> str:
+        return f"{self.dpkg_trigger_type} {self.dpkg_trigger_target}"
diff --git a/src/debputy/plugin/api/plugin_parser.py b/src/debputy/plugin/api/plugin_parser.py
new file mode 100644
index 0000000..ad2489f
--- /dev/null
+++ b/src/debputy/plugin/api/plugin_parser.py
@@ -0,0 +1,66 @@
+from typing import NotRequired, List, Any, TypedDict
+
+from debputy.manifest_parser.base_types import (
+    DebputyParsedContent,
+    OctalMode,
+    TypeMapping,
+)
+from debputy.manifest_parser.declarative_parser import ParserGenerator
+from debputy.plugin.api.impl_types import KnownPackagingFileInfo
+
+
+class PPFReferenceDocumentation(TypedDict):
+    description: NotRequired[str]
+    format_documentation_uris: NotRequired[List[str]]
+
+
+class PackagerProvidedFileJsonDescription(DebputyParsedContent):
+    stem: str
+    installed_path: str
+    default_mode: NotRequired[OctalMode]
+    default_priority: NotRequired[int]
+    allow_name_segment: NotRequired[bool]
+    allow_architecture_segment: NotRequired[bool]
+    reference_documentation: NotRequired[PPFReferenceDocumentation]
+
+
+class ManifestVariableJsonDescription(DebputyParsedContent):
+    name: str
+    value: str
+    reference_documentation: NotRequired[str]
+
+
+class PluginJsonMetadata(DebputyParsedContent):
+    api_compat_version: int
+    module: NotRequired[str]
+    plugin_initializer: NotRequired[str]
+    packager_provided_files: NotRequired[List[Any]]
+    manifest_variables: NotRequired[List[Any]]
+    known_packaging_files: NotRequired[List[Any]]
+
+
+def _initialize_plugin_metadata_parser_generator() -> ParserGenerator:
+    pc = ParserGenerator()
+    pc.register_mapped_type(
+        TypeMapping(
+            OctalMode,
+            str,
+            lambda v, ap, _: OctalMode.parse_filesystem_mode(v, ap),
+        )
+    )
+    return pc
+
+
+PLUGIN_METADATA_PARSER_GENERATOR = _initialize_plugin_metadata_parser_generator()
+PLUGIN_METADATA_PARSER = PLUGIN_METADATA_PARSER_GENERATOR.parser_from_typed_dict(
+    PluginJsonMetadata
+)
+PLUGIN_PPF_PARSER = PLUGIN_METADATA_PARSER_GENERATOR.parser_from_typed_dict(
+    PackagerProvidedFileJsonDescription
+)
+PLUGIN_MANIFEST_VARS_PARSER = PLUGIN_METADATA_PARSER_GENERATOR.parser_from_typed_dict(
+    ManifestVariableJsonDescription
+)
+PLUGIN_KNOWN_PACKAGING_FILES_PARSER = (
+    PLUGIN_METADATA_PARSER_GENERATOR.parser_from_typed_dict(KnownPackagingFileInfo)
+)
diff --git a/src/debputy/plugin/api/spec.py b/src/debputy/plugin/api/spec.py
new file mode 100644
index 0000000..d034a28
--- /dev/null
+++ b/src/debputy/plugin/api/spec.py
@@ -0,0 +1,1743 @@
+import contextlib
+import dataclasses
+import os
+import tempfile
+import textwrap
+from typing import (
+    Iterable,
+    Optional,
+    Callable,
+    Literal,
+    Union,
+    Iterator,
+    overload,
+    FrozenSet,
+    Sequence,
+    TypeVar,
+    Any,
+    TYPE_CHECKING,
+    TextIO,
+    BinaryIO,
+    Generic,
+    ContextManager,
+    List,
+    Type,
+    Tuple,
+)
+
+from debian.substvars import Substvars
+
+from debputy import util
+from debputy.exceptions import TestPathWithNonExistentFSPathError, PureVirtualPathError
+from debputy.interpreter import Interpreter, extract_shebang_interpreter_from_file
+from debputy.manifest_parser.util import parse_symbolic_mode
+from debputy.packages import BinaryPackage
+from debputy.types import S
+
+if TYPE_CHECKING:
+    from debputy.manifest_parser.base_types import (
+        StaticFileSystemOwner,
+        StaticFileSystemGroup,
+    )
+
+
+PluginInitializationEntryPoint = Callable[["DebputyPluginInitializer"], None]
+MetadataAutoDetector = Callable[
+    ["VirtualPath", "BinaryCtrlAccessor", "PackageProcessingContext"], None
+]
+PackageProcessor = Callable[["VirtualPath", None, "PackageProcessingContext"], None]
+DpkgTriggerType = Literal[
+    "activate",
+    "activate-await",
+    "activate-noawait",
+    "interest",
+    "interest-await",
+    "interest-noawait",
+]
+Maintscript = Literal["postinst", "preinst", "prerm", "postrm"]
+PackageTypeSelector = Union[Literal["deb", "udeb"], Iterable[Literal["deb", "udeb"]]]
+ServiceUpgradeRule = Literal[
+    "do-nothing",
+    "reload",
+    "restart",
+    "stop-then-start",
+]
+
+DSD = TypeVar("DSD")
+ServiceDetector = Callable[
+    ["VirtualPath", "ServiceRegistry[DSD]", "PackageProcessingContext"],
+    None,
+]
+ServiceIntegrator = Callable[
+    [
+        Sequence["ServiceDefinition[DSD]"],
+        "BinaryCtrlAccessor",
+        "PackageProcessingContext",
+    ],
+    None,
+]
+
+PMT = TypeVar("PMT")
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class PackagerProvidedFileReferenceDocumentation:
+    description: Optional[str] = None
+    format_documentation_uris: Sequence[str] = tuple()
+
+    def replace(self, **changes: Any) -> "PackagerProvidedFileReferenceDocumentation":
+        return dataclasses.replace(self, **changes)
+
+
+def packager_provided_file_reference_documentation(
+    *,
+    description: Optional[str] = None,
+    format_documentation_uris: Optional[Sequence[str]] = tuple(),
+) -> PackagerProvidedFileReferenceDocumentation:
+    """Provide documentation for a given packager provided file.
+
+    :param description: Textual description presented to the user.
+    :param format_documentation_uris: A sequence of URIs to documentation that describes
+      the format of the file. Most relevant first.
+    :return:
+    """
+    uris = tuple(format_documentation_uris) if format_documentation_uris else tuple()
+    return PackagerProvidedFileReferenceDocumentation(
+        description=description,
+        format_documentation_uris=uris,
+    )
+
+
+class PathMetadataReference(Generic[PMT]):
+    """An accessor to plugin provided metadata
+
+    This is a *short-lived* reference to a piece of metadata.  It should *not* be stored beyond
+    the boundaries of the current plugin execution context as it can be become invalid (as an
+    example, if the path associated with this path is removed, then this reference become invalid)
+    """
+
+    @property
+    def is_present(self) -> bool:
+        """Determine whether the value has been set
+
+        If the current plugin cannot access the value, then this method unconditionally returns
+        `False` regardless of whether the value is there.
+
+        :return: `True` if the value has been set to a not None value (and not been deleted).
+          Otherwise, this property is `False`.
+        """
+        raise NotImplementedError
+
+    @property
+    def can_read(self) -> bool:
+        """Test whether it is possible to read the metadata
+
+        Note: That the metadata being readable does *not* imply that the metadata is present.
+
+        :return: True if it is possible to read the metadata. This is always True for the
+          owning plugin.
+        """
+        raise NotImplementedError
+
+    @property
+    def can_write(self) -> bool:
+        """Test whether it is possible to update the metadata
+
+        :return: True if it is possible to update the metadata.
+        """
+        raise NotImplementedError
+
+    @property
+    def value(self) -> Optional[PMT]:
+        """Fetch the currently stored value if present.
+
+        :return: The value previously stored if any. Returns `None` if the value was never
+          stored, explicitly set to `None` or was deleted.
+        """
+        raise NotImplementedError
+
+    @value.setter
+    def value(self, value: Optional[PMT]) -> None:
+        """Replace any current value with the provided value
+
+        This operation is only possible if the path is writable *and* the caller is from
+        the owning plugin OR the owning plugin made the reference read-write.
+        """
+        raise NotImplementedError
+
+    @value.deleter
+    def value(self) -> None:
+        """Delete any current value.
+
+        This has the same effect as setting the value to `None`.  It has the same restrictions
+        as the value setter.
+        """
+        self.value = None
+
+
+@dataclasses.dataclass(slots=True)
+class PathDef:
+    path_name: str
+    mode: Optional[int] = None
+    mtime: Optional[int] = None
+    has_fs_path: Optional[bool] = None
+    fs_path: Optional[str] = None
+    link_target: Optional[str] = None
+    content: Optional[str] = None
+    materialized_content: Optional[str] = None
+
+
+def virtual_path_def(
+    path_name: str,
+    /,
+    mode: Optional[int] = None,
+    mtime: Optional[int] = None,
+    fs_path: Optional[str] = None,
+    link_target: Optional[str] = None,
+    content: Optional[str] = None,
+    materialized_content: Optional[str] = None,
+) -> PathDef:
+    """Define a virtual path for use with examples or, in tests, `build_virtual_file_system`
+
+    :param path_name: The full path. Must start with "./".  If it ends with "/", the path will be interpreted
+      as a directory (the `is_dir` attribute will be True).  Otherwise, it will be a symlink or file depending
+      on whether a `link_target` is provided.
+    :param mode: The mode to use for this path.  Defaults to 0644 for files and 0755 for directories. The mode
+      should be None for symlinks.
+    :param mtime: Define the last modified time for this path. If not provided, debputy will provide a default
+      if the mtime attribute is accessed.
+    :param fs_path: Define a file system path for this path.  This causes `has_fs_path` to return True and the
+      `fs_path` attribute will return this value.  The test is required to make this path available to the extent
+      required. Note that the virtual file system will *not* examine the provided path in any way nor attempt
+      to resolve defaults from the path.
+    :param link_target: A target for the symlink. Providing a not None value for this parameter will make the
+      path a symlink.
+    :param content: The content of the path (if opened).  The path must be a file.
+    :param materialized_content: Same as `content` except `debputy` will put the contents into a physical file
+      as needed. Cannot be used with `content` or `fs_path`.
+    :return: An *opaque* object to be passed to `build_virtual_file_system`. While the exact type is provided
+      to aid with typing, the type name and its behaviour is not part of the API.
+    """
+
+    is_dir = path_name.endswith("/")
+    is_symlink = link_target is not None
+
+    if is_symlink:
+        if mode is not None:
+            raise ValueError(
+                f'Please do not provide mode for symlinks. Triggered by "{path_name}"'
+            )
+        if is_dir:
+            raise ValueError(
+                "Path name looks like a directory, but a symlink target was also provided."
+                f' Please remove the trailing slash OR the symlink_target. Triggered by "{path_name}"'
+            )
+
+    if content and (is_dir or is_symlink):
+        raise ValueError(
+            "Content was defined however, the path appears to be a directory a or a symlink"
+            f' Please remove the content, the trailing slash OR the symlink_target. Triggered by "{path_name}"'
+        )
+
+    if materialized_content is not None:
+        if content is not None:
+            raise ValueError(
+                "The materialized_content keyword is mutually exclusive with the content keyword."
+                f' Triggered by "{path_name}"'
+            )
+        if fs_path is not None:
+            raise ValueError(
+                "The materialized_content keyword is mutually exclusive with the fs_path keyword."
+                f' Triggered by "{path_name}"'
+            )
+    return PathDef(
+        path_name,
+        mode=mode,
+        mtime=mtime,
+        has_fs_path=bool(fs_path) or materialized_content is not None,
+        fs_path=fs_path,
+        link_target=link_target,
+        content=content,
+        materialized_content=materialized_content,
+    )
+
+
+class PackageProcessingContext:
+    """Context for auto-detectors of metadata and package processors (no instantiation)
+
+    This object holds some context related data for the metadata detector or/and package
+    processors.  It may receive new attributes in the future.
+    """
+
+    __slots__ = ()
+
+    @property
+    def binary_package(self) -> BinaryPackage:
+        """The binary package stanza from `debian/control`"""
+        raise NotImplementedError
+
+    @property
+    def binary_package_version(self) -> str:
+        """The version of the binary package
+
+        Note this never includes the binNMU version for arch:all packages, but it may for arch:any.
+        """
+        raise NotImplementedError
+
+    @property
+    def related_udeb_package(self) -> Optional[BinaryPackage]:
+        """An udeb related to this binary package (if any)"""
+        raise NotImplementedError
+
+    @property
+    def related_udeb_package_version(self) -> Optional[str]:
+        """The version of the related udeb package (if present)
+
+        Note this never includes the binNMU version for arch:all packages, but it may for arch:any.
+        """
+        raise NotImplementedError
+
+    def accessible_package_roots(self) -> Iterable[Tuple[BinaryPackage, "VirtualPath"]]:
+        raise NotImplementedError
+
+    # """The source package stanza from `debian/control`"""
+    # source_package: SourcePackage
+
+
+class DebputyPluginInitializer:
+    __slots__ = ()
+
+    def packager_provided_file(
+        self,
+        stem: str,
+        installed_path: str,
+        *,
+        default_mode: int = 0o0644,
+        default_priority: Optional[int] = None,
+        allow_name_segment: bool = True,
+        allow_architecture_segment: bool = False,
+        post_formatting_rewrite: Optional[Callable[[str], str]] = None,
+        packageless_is_fallback_for_all_packages: bool = False,
+        reservation_only: bool = False,
+        reference_documentation: Optional[
+            PackagerProvidedFileReferenceDocumentation
+        ] = None,
+    ) -> None:
+        """Register a packager provided file (debian/<pkg>.foo)
+
+        Register a packager provided file that debputy should automatically detect and install for the
+        packager (example `debian/foo.tmpfiles` -> `debian/foo/usr/lib/tmpfiles.d/foo.conf`).  A packager
+        provided file typically identified by a package prefix and a "stem" and by convention placed
+        in the `debian/` directory.
+
+        Like debhelper, debputy also supports the `foo.bar.tmpfiles` variant where the file is to be
+        installed into the `foo` package but be named after the `bar` segment rather than the package name.
+        This feature can be controlled via the `allow_name_segment` parameter.
+
+        :param stem: The "stem" of the file. This would be the `tmpfiles` part of `debian/foo.tmpfiles`.
+          Note that this value must be unique across all registered packager provided files.
+        :param installed_path: A format string describing where the file should be installed. Would be
+          `/usr/lib/tmpfiles.d/{name}.conf` from the example above.
+
+          The caller should provide a string with one or more of the placeholders listed below (usually `{name}`
+          should be one of them). The format affect the entire path.
+
+          The following placeholders are supported:
+            * `{name}` - The name in the name segment (defaulting the package name if no name segment is given)
+            * `{priority}` / `{priority:02}` - The priority of the file. Only provided priorities are used (that
+               is, default_priority is not None).  The latter variant ensuring that the priority takes at least
+               two characters and the `0` character is left-padded for priorities that takes less than two
+               characters.
+            * `{owning_package}` - The name of the package.  Should only be used when `{name}` alone is insufficient.
+              If you do not want the "name" segment in the first place, use `allow_name_segment=False` instead.
+
+          The path is always interpreted as relative to the binary package root.
+
+        :param default_mode: The mode the installed file should have by default. Common options are 0o0644 (the default)
+          or 0o0755 (for files that must be executable).
+        :param allow_architecture_segment: If True, the file may have an optional "architecture" segment at the end
+           (`foo.tmpfiles.amd64`), which marks it architecture specific. When False, debputy will detect the
+           "architecture" segment and report the use as an error.  Note the architecture segment is only allowed for
+           arch:any packages. If a file targeting an arch:all package uses an architecture specific file it will
+           always result in an error.
+        :param allow_name_segment: If True, the file may have an optional "name" segment after the package name prefix.
+           (`foo.<name-here>.tmpfiles`). When False, debputy will detect the "name" segment and report the use as an
+           error.
+        :param default_priority: Special-case option for packager files that are installed into directories that have
+          "parse ordering" or "priority".  These files will generally be installed as something like `20-foo.conf`
+          where the `20-` denotes their "priority".  If the plugin is registering such a file type, then it should
+          provide a default priority.
+
+          The following placeholders are supported:
+            * `{name}` - The name in the name segment (defaulting the package name if no name segment is given)
+            * `{priority}` - The priority of the file. Only provided priorities are used (that is, default_priority
+               is not None)
+            * `{owning_package}` - The name of the package.  Should only be used when `{name}` alone is insufficient.
+              If you do not want the "name" segment in the first place, use `allow_name_segment=False` instead.
+        :param post_formatting_rewrite: An optional "name correcting" callback. It receives the formatted name and can
+          do any transformation required. The primary use-case for this is to replace "forbidden" characters. The most
+          common case for debputy itself is to replace "." with "_" for tools that refuse to work with files containing
+          "." (`lambda x: x.replace(".", "_")`).  The callback operates on basename of formatted version of the
+          `installed_path` and the callback should return the basename.
+        :param packageless_is_fallback_for_all_packages: If True, the packageless variant (such as, `debian/changelog`)
+          is a fallback for every package.
+        :param reference_documentation: Reference documentation for the packager provided file. Use the
+           packager_provided_file_reference_documentation function to provide the value for this parameter.
+        :param reservation_only: When True, tell debputy that the plugin reserves this packager provided file, but that
+          debputy should not actually install it automatically.  This is useful in the cases, where the plugin
+          needs to process the file before installing it.  The file will be marked as provided by this plugin. This
+          enables introspection and detects conflicts if other plugins attempts to claim the file.
+        """
+        raise NotImplementedError
+
+    def metadata_or_maintscript_detector(
+        self,
+        auto_detector_id: str,
+        auto_detector: MetadataAutoDetector,
+        *,
+        package_type: PackageTypeSelector = "deb",
+    ) -> None:
+        """Provide a pre-assembly hook that can affect the metadata/maintscript of binary ("deb") packages
+
+        The provided hook will be run once per binary package to be assembled, and it can see all the content
+        ("data.tar") planned to be included in the deb. The hook may do any *read-only* analysis of this content
+        and provide metadata, alter substvars or inject maintscript snippets.  However, the hook must *not*
+        change the content ("data.tar") part of the deb.
+
+        The hook will be run unconditionally for all binary packages built. When the hook does not apply to all
+        packages, it must provide its own (internal) logic for detecting whether it is relevant and reduced itself
+        to a no-op if it should not apply to the current package.
+
+        Hooks are run in "some implementation defined order" and should not rely on being run before or after
+        any other hook.
+
+        The hooks are only applied to packages defined in `debian/control`. Notably, the metadata detector will
+        not apply to auto-generated `-dbgsym` packages (as those are not listed explicitly in `debian/control`).
+
+        :param auto_detector_id: A plugin-wide unique ID for this detector. Packagers may use this ID for disabling
+          the detector and accordingly the ID is part of the plugin's API toward the packager.
+        :param auto_detector: The code to be called that will be run at the metadata generation state (once for each
+          binary package).
+        :param package_type: Which kind of packages this metadata detector applies to.  The package type is generally
+          defined by `Package-Type` field in the binary package. The default is to only run for regular `deb` packages
+          and ignore `udeb` packages.
+        """
+        raise NotImplementedError
+
+    def manifest_variable(
+        self,
+        variable_name: str,
+        value: str,
+        variable_reference_documentation: Optional[str] = None,
+    ) -> None:
+        """Provide a variable that can be used in the package manifest
+
+            >>> # Enable users to use "{{path:BASH_COMPLETION_DIR}}/foo" in their manifest.
+            >>> api.manifest_variable(  # doctest: +SKIP
+            ...     "path:BASH_COMPLETION_DIR",
+            ...     "/usr/share/bash-completion/completions",
+            ...     variable_reference_documentation="Directory to install bash completions into",
+            ... )
+
+        :param variable_name: The variable name.
+        :param value: The value the variable should resolve to.
+        :param variable_reference_documentation: A short snippet of reference documentation that explains
+          the purpose of the variable.
+        """
+        raise NotImplementedError
+
+
+class MaintscriptAccessor:
+    __slots__ = ()
+
+    def on_configure(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+        skip_on_rollback: bool = False,
+    ) -> None:
+        """Provide a snippet to be run when the package is about to be "configured"
+
+        This condition is the most common "post install" condition and covers the two
+        common cases:
+          * On initial install, OR
+          * On upgrade
+
+        In dpkg maintscript terms, this method roughly corresponds to postinst containing
+             `if [ "$1" = configure ]; then <snippet>; fi`
+
+        Additionally, the condition will by default also include rollback/abort scenarios such as "above-remove",
+        which is normally what you want but most people forget about.
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param skip_on_rollback: By default, this condition will also cover common rollback scenarios. This
+          is normally what you want (or benign in most cases due to the idempotence requirement for maintscripts).
+          However, you can disable the rollback cases, leaving only "On initial install OR On upgrade".
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_initial_install(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package is about to be "configured" for the first time
+
+        The snippet will only be run on the first time the package is installed (ever or since last purge).
+        Note that "first" does not mean "exactly once" as dpkg does *not* provide such semantics. There are two
+        common cases where this can snippet can be run multiple times for the same system (and why the snippet
+        must still be idempotent):
+
+          1) The package is installed (1), then purged and then installed again (2).  This can partly be mitigated
+             by having an `on_purge` script to do clean up.
+
+          2) As the package is installed, the `postinst` script terminates prematurely (Disk full, power loss, etc.).
+             The user resolves the problem and runs `dpkg --configure <pkg>`, which in turn restarts the script
+             from the beginning.  This is why scripts must be idempotent in general.
+
+        In dpkg maintscript terms, this method roughly corresponds to postinst containing
+             `if [ "$1" = configure ] && [ -z "$2" ]; then <snippet>; fi`
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_upgrade(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package is about to be "configured" after an upgrade
+
+        The snippet will only be run on any upgrade (that is, it will be skipped on the initial install).
+
+        In dpkg maintscript terms, this method roughly corresponds to postinst containing
+             `if [ "$1" = configure ] && [ -n "$2" ]; then <snippet>; fi`
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_upgrade_from(
+        self,
+        version: str,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package is about to be "configured" after an upgrade from a given version
+
+        The snippet will only be run on any upgrade (that is, it will be skipped on the initial install).
+
+        In dpkg maintscript terms, this method roughly corresponds to postinst containing
+             `if [ "$1" = configure ] && dpkg --compare-versions le-nl "$2" ; then <snippet>; fi`
+
+        :param version: The version to upgrade from
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_before_removal(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package is about to be removed
+
+        The snippet will be run before dpkg removes any files.
+
+        In dpkg maintscript terms, this method roughly corresponds to prerm containing
+             `if [ "$1" = remove ] ; then <snippet>; fi`
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_removed(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package has been removed
+
+        The snippet will be run after dpkg removes the package content from the file system.
+
+        **WARNING**: The snippet *cannot* rely on dependencies and must rely on `Essential: yes` packages.
+
+        In dpkg maintscript terms, this method roughly corresponds to postrm containing
+             `if [ "$1" = remove ] ; then <snippet>; fi`
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def on_purge(
+        self,
+        run_snippet: str,
+        /,
+        indent: Optional[bool] = None,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run when the package is being purged.
+
+        The snippet will when the package is purged from the system.
+
+        **WARNING**: The snippet *cannot* rely on dependencies and must rely on `Essential: yes` packages.
+
+        In dpkg maintscript terms, this method roughly corresponds to postrm containing
+             `if [ "$1" = purge ] ; then <snippet>; fi`
+
+        :param run_snippet: The actual shell snippet to be run in the given condition.  The snippet must be idempotent.
+          The snippet may contain newlines as necessary, which will make the result more readable.  Additionally, the
+          snippet may contain '{{FOO}}' substitutions by default.
+        :param indent: If True, the provided snippet will be indented to fit the condition provided by debputy.
+          In most cases, this is safe to do and provides more readable scripts. However, it may cause issues
+          with some special shell syntax (such as "Heredocs"). When False, the snippet will *not* be re-indented.
+          You are recommended to do 4 spaces of indentation when indent is False for readability.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def unconditionally_in_script(
+        self,
+        maintscript: Maintscript,
+        run_snippet: str,
+        /,
+        perform_substitution: bool = True,
+    ) -> None:
+        """Provide a snippet to be run in a given script
+
+        Run a given snippet unconditionally from a given script.  The snippet must contain its own conditional
+        for when it should be run.
+
+        :param maintscript: The maintscript to insert the snippet into.
+        :param run_snippet: The actual shell snippet to be run.  The snippet will be run unconditionally and should
+          contain its own conditions as necessary. The snippet must be idempotent. The snippet may contain newlines
+          as necessary, which will make the result more readable.  Additionally, the snippet may contain '{{FOO}}'
+          substitutions by default.
+        :param perform_substitution: When True, `{{FOO}}` will be substituted in the snippet. When False, no
+          substitution is provided.
+        """
+        raise NotImplementedError
+
+    def escape_shell_words(self, *args: str) -> str:
+        """Provide sh-shell escape of strings
+
+          `assert escape_shell("foo", "fu bar", "baz") == 'foo "fu bar" baz'`
+
+        This is useful for ensuring file names and other "input" are considered one parameter even when they
+        contain spaces or shell meta-characters.
+
+        :param args: The string(s) to be escaped.
+        :return: Each argument escaped such that each argument becomes a single "word" and then all these words are
+          joined by a single space.
+        """
+        return util.escape_shell(*args)
+
+
+class BinaryCtrlAccessor:
+    __slots__ = ()
+
+    def dpkg_trigger(self, trigger_type: DpkgTriggerType, trigger_target: str) -> None:
+        """Register a declarative dpkg level trigger
+
+        The provided trigger will be added to the package's metadata (the triggers file of the control.tar).
+
+        If the trigger has already been added previously, a second call with the same trigger data will be ignored.
+        """
+        raise NotImplementedError
+
+    @property
+    def maintscript(self) -> MaintscriptAccessor:
+        """Attribute for manipulating maintscripts"""
+        raise NotImplementedError
+
+    @property
+    def substvars(self) -> "FlushableSubstvars":
+        """Attribute for manipulating dpkg substvars (deb-substvars)"""
+        raise NotImplementedError
+
+
+class VirtualPath:
+    __slots__ = ()
+
+    @property
+    def name(self) -> str:
+        """Basename of the path a.k.a. last segment of the path
+
+        In a path "usr/share/doc/pkg/changelog.gz" the basename is "changelog.gz".
+
+        For a directory, the basename *never* ends with a `/`.
+        """
+        raise NotImplementedError
+
+    @property
+    def iterdir(self) -> Iterable["VirtualPath"]:
+        """Returns an iterable that iterates over all children of this path
+
+        For directories, this returns an iterable of all children. For non-directories,
+        the iterable is always empty.
+        """
+        raise NotImplementedError
+
+    def lookup(self, path: str) -> Optional["VirtualPath"]:
+        """Perform a path lookup relative to this path
+
+        As an example `doc_dir = fs_root.lookup('./usr/share/doc')`
+
+        If the provided path starts with `/`, then the lookup is performed relative to the
+        file system root.  That is, you can assume the following to always be True:
+
+            `fs_root.lookup("usr") == any_path_beneath_fs_root.lookup('/usr')`
+
+        Note: This method requires the path to be attached (see `is_detached`) regardless of
+        whether the lookup is relative or absolute.
+
+        If the path traverse a symlink, the symlink will be resolved.
+
+        :param path: The path to look. Can contain "." and ".." segments.  If starting with `/`,
+          look up is performed relative to the file system root, otherwise the lookup is relative
+          to this path.
+        :return: The path object for the desired path if it can be found. Otherwise, None.
+        """
+        raise NotImplementedError
+
+    def all_paths(self) -> Iterable["VirtualPath"]:
+        """Iterate over this path and all of its descendants (if any)
+
+        If used on the root path, then every path in the package is returned.
+
+        The iterable is ordered, so using the order in output will be produce
+        bit-for-bit reproducible output. Additionally, a directory will always
+        be seen before its descendants. Otherwise, the order is implementation
+        defined.
+
+        The iteration is lazy and as a side effect do account for some obvious
+        mutation. Like if the current path is removed, then none of its children
+        will be returned (provided mutation happens before the lazy iteration
+        was required to resolve it). Likewise, mutation of the directory will
+        also work (again, provided mutation happens before the lazy iteration order).
+
+        :return: An ordered iterable of this path followed by its descendants.
+        """
+        raise NotImplementedError
+
+    @property
+    def is_detached(self) -> bool:
+        """Returns True if this path is detached
+
+        Paths that are detached from the file system will not be present in the package and
+        most operations are unsafe on them. This usually only happens if the path or one of
+        its parent directories are unlinked (rm'ed) from the file system tree.
+
+        All paths are attached by default and will only become detached as a result of
+        an action to mutate the virtual file system.  Note that the file system may not
+        always be manipulated.
+
+        :return: True if the entry is detached. Detached entries should be discarded, so they
+        can be garbage collected.
+        """
+        raise NotImplementedError
+
+    # The __getitem__ behaves like __getitem__ from Dict but __iter__ would ideally work like a Sequence.
+    # However, that does not feel compatible, so lets force people to use .children instead for the Sequence
+    # behaviour to avoid surprises for now.
+    # (Maybe it is a non-issue, but it is easier to add the API later than to remove it once we have committed
+    # to using it)
+    __iter__ = None
+
+    def __getitem__(self, key: object) -> "VirtualPath":
+        """Lookup a (direct) child by name
+
+        Ignoring the possible `KeyError`, then the following are the same:
+            `fs_root["usr"] == fs_root.lookup('usr')`
+
+        Note that unlike `.lookup` this can only locate direct children.
+        """
+        raise NotImplementedError
+
+    def __delitem__(self, key) -> None:
+        """Remove a child from this node if it exists
+
+        If that child is a directory, then the entire tree is removed (like `rm -fr`).
+        """
+        raise NotImplementedError
+
+    def get(self, key: str) -> "Optional[VirtualPath]":
+        """Lookup a (direct) child by name
+
+        The following are the same:
+            `fs_root.get("usr") == fs_root.lookup('usr')`
+
+        Note that unlike `.lookup` this can only locate direct children.
+        """
+        try:
+            return self[key]
+        except KeyError:
+            return None
+
+    def __contains__(self, item: object) -> bool:
+        """Determine if this path includes a given child (either by object or string)
+
+        Examples:
+
+            if 'foo' in dir: ...
+        """
+        if isinstance(item, VirtualPath):
+            return item.parent_dir is self
+        if not isinstance(item, str):
+            return False
+        m = self.get(item)
+        return m is not None
+
+    @property
+    def path(self) -> str:
+        """Returns the "full" path for this file system entry
+
+        This is the path that debputy uses to refer to this file system entry. It is always
+        normalized. Use the `absolute` attribute for how the path looks
+        when the package is installed. Alternatively, there is also `fs_path`, which is the
+        path to the underlying file system object (assuming there is one). That is the one
+        you need if you want to read the file.
+
+        This is attribute is mostly useful for debugging or for looking up the path relative
+        to the "root" of the virtual file system that debputy maintains.
+
+        If the path is detached (see `is_detached`), then this method returns the path as it
+        was known prior to being detached.
+        """
+        raise NotImplementedError
+
+    @property
+    def absolute(self) -> str:
+        """Returns the absolute version of this path
+
+        This is how to refer to this path when the package is installed.
+
+        If the path is detached (see `is_detached`), then this method returns the last known location
+        of installation (prior to being detached).
+
+        :return: The absolute path of this file as it would be on the installed system.
+        """
+        p = self.path.lstrip(".")
+        if not p.startswith("/"):
+            return f"/{p}"
+        return p
+
+    @property
+    def parent_dir(self) -> Optional["VirtualPath"]:
+        """The parent directory of this path
+
+        Note this operation requires the path is "attached" (see `is_detached`).  All paths are attached
+        by default but unlinking paths will cause them to become detached.
+
+        :return: The parent path or None for the root.
+        """
+        raise NotImplementedError
+
+    def stat(self) -> os.stat_result:
+        """Attempt to do stat of the underlying path (if it exists)
+
+        *Avoid* using `stat()` whenever possible where a more specialized attribute exist.  The
+        `stat()` call returns the data from the file system and often, `debputy` does *not* track
+        its state in the file system.  As an example, if you want to know the file system mode of
+        a path, please use the `mode` attribute instead.
+
+        This never follow symlinks (it behaves like `os.lstat`). It will raise an error
+        if the path is not backed by a file system object (that is, `has_fs_path` is False).
+
+        :return: The stat result or an error.
+        """
+        raise NotImplementedError()
+
+    @property
+    def size(self) -> int:
+        """Resolve the file size (`st_size`)
+
+        This may be using `stat()` and therefore `fs_path`.
+
+        :return: The size of the file in bytes
+        """
+        return self.stat().st_size
+
+    @property
+    def mode(self) -> int:
+        """Determine the mode bits of this path object
+
+        Note that:
+         * like with `stat` above, this never follows symlinks.
+         * the mode returned by this method is not always a 1:1 with the mode in the
+           physical file system. As an optimization, `debputy` skips unnecessary writes
+           to the underlying file system in many cases.
+
+
+        :return: The mode bits for the path.
+        """
+        raise NotImplementedError
+
+    @mode.setter
+    def mode(self, new_mode: int) -> None:
+        """Set the octal file mode of this path
+
+        Note that:
+         * this operation will fail if `path.is_read_write` returns False.
+         * this operation is generally *not* synced to the physical file system (as
+           an optimization).
+
+        :param new_mode: The new octal mode for this path.  Note that `debputy` insists
+          that all paths have the `user read bit` and, for directories also, the
+          `user execute bit`.  The absence of these minimal mode bits causes hard to
+          debug errors.
+        """
+        raise NotImplementedError
+
+    @property
+    def is_executable(self) -> bool:
+        """Determine whether a path is considered executable
+
+        Generally, this means that at least one executable bit is set. This will
+        basically always be true for directories as directories need the execute
+        parameter to be traversable.
+
+        :return: True if the path is considered executable with its current mode
+        """
+        return bool(self.mode & 0o0111)
+
+    def chmod(self, new_mode: Union[int, str]) -> None:
+        """Set the file mode of this path
+
+        This is similar to setting the `mode` attribute. However, this method accepts
+        a string argument, which will be parsed as a symbolic mode (example: `u+rX,go=rX`).
+
+        Note that:
+         * this operation will fail if `path.is_read_write` returns False.
+         * this operation is generally *not* synced to the physical file system (as
+           an optimization).
+
+        :param new_mode: The new mode for this path.
+          Note that `debputy` insists that all paths have the `user read bit` and, for
+          directories also, the `user execute bit`.  The absence of these minimal mode
+          bits causes hard to debug errors.
+        """
+        if isinstance(new_mode, str):
+            segments = parse_symbolic_mode(new_mode, None)
+            final_mode = self.mode
+            is_dir = self.is_dir
+            for segment in segments:
+                final_mode = segment.apply(final_mode, is_dir)
+            self.mode = final_mode
+        else:
+            self.mode = new_mode
+
+    def chown(
+        self,
+        owner: Optional["StaticFileSystemOwner"],
+        group: Optional["StaticFileSystemGroup"],
+    ) -> None:
+        """Change the owner/group of this path
+
+        :param owner: The desired owner definition for this path. If None, then no change of owner is performed.
+        :param group: The desired  group definition for this path. If None, then no change of group is performed.
+        """
+        raise NotImplementedError
+
+    @property
+    def mtime(self) -> float:
+        """Determine the mtime of this path object
+
+        Note that:
+         * like with `stat` above, this never follows symlinks.
+         * the mtime returned has *not* been clamped against ´SOURCE_DATE_EPOCH`. Timestamp
+           normalization is handled later by `debputy`.
+         * the mtime returned by this method is not always a 1:1 with the mtime in the
+           physical file system. As an optimization, `debputy` skips unnecessary writes
+           to the underlying file system in many cases.
+
+        :return: The mtime for the path.
+        """
+        raise NotImplementedError
+
+    @mtime.setter
+    def mtime(self, new_mtime: float) -> None:
+        """Set the mtime of this path
+
+        Note that:
+         * this operation will fail if `path.is_read_write` returns False.
+         * this operation is generally *not* synced to the physical file system (as
+           an optimization).
+
+        :param new_mtime: The new mtime of this path. Note that the caller does not need to
+          account for `SOURCE_DATE_EPOCH`. Timestamp normalization is handled later.
+        """
+        raise NotImplementedError
+
+    def readlink(self) -> str:
+        """Determine the link target of this path assuming it is a symlink
+
+        For paths where `is_symlink` is True, this already returns a link target even when
+        `has_fs_path` is False.
+
+        :return: The link target of the path or an error is this is not a symlink
+        """
+        raise NotImplementedError()
+
+    @overload
+    def open(
+        self,
+        *,
+        byte_io: Literal[False] = False,
+        buffering: Optional[int] = ...,
+    ) -> TextIO: ...
+
+    @overload
+    def open(
+        self,
+        *,
+        byte_io: Literal[True],
+        buffering: Optional[int] = ...,
+    ) -> BinaryIO: ...
+
+    @overload
+    def open(
+        self,
+        *,
+        byte_io: bool,
+        buffering: Optional[int] = ...,
+    ) -> Union[TextIO, BinaryIO]: ...
+
+    def open(
+        self,
+        *,
+        byte_io: bool = False,
+        buffering: int = -1,
+    ) -> Union[TextIO, BinaryIO]:
+        """Open the file for reading.  Usually used with a context manager
+
+        By default, the file is opened in text mode (utf-8). Binary mode can be requested
+        via the `byte_io` parameter.  This operation is only valid for files (`is_file` returns
+        `True`). Usage on symlinks and directories will raise exceptions.
+
+        This method *often* requires the `fs_path` to be present.  However, tests as a notable
+        case can inject content without having the `fs_path` point to a real file. (To be clear,
+        such tests are generally expected to ensure `has_fs_path` returns `True`).
+
+
+        :param byte_io: If True, open the file in binary mode (like `rb` for `open`)
+        :param buffering: Same as open(..., buffering=...) where supported. Notably during
+          testing, the content may be purely in memory and use a BytesIO/StringIO
+          (which does not accept that parameter, but then is buffered in a different way)
+        :return: The file handle.
+        """
+
+        if not self.is_file:
+            raise TypeError(f"Cannot open {self.path} for reading: It is not a file")
+
+        if byte_io:
+            return open(self.fs_path, "rb", buffering=buffering)
+        return open(self.fs_path, "rt", encoding="utf-8", buffering=buffering)
+
+    @property
+    def fs_path(self) -> str:
+        """Request the underling fs_path of this path
+
+        Only available when `has_fs_path` is True.  Generally this should only be used for files to read
+        the contents of the file and do some action based on the parsed result.
+
+        The path should only be used for read-only purposes as debputy may assume that it is safe to have
+        multiple paths pointing to the same file system path.
+
+        Note that:
+          * This is often *not* available for directories and symlinks.
+          * The debputy in-memory file system overrules the physical file system. Attempting to "fix" things
+            by using `os.chmod` or `os.unlink`'ing files, etc. will generally not do as you expect. Best case,
+            your actions are ignored and worst case it will cause the build to fail as it violates debputy's
+            internal invariants.
+
+        :return: The path to the underlying file system object on the build system or an error if no such
+        file exist (see `has_fs_path`).
+        """
+        raise NotImplementedError()
+
+    @property
+    def is_dir(self) -> bool:
+        """Determine if this path is a directory
+
+        Never follows symlinks.
+
+        :return: True if this path is a directory. False otherwise.
+        """
+        raise NotImplementedError()
+
+    @property
+    def is_file(self) -> bool:
+        """Determine if this path is a directory
+
+        Never follows symlinks.
+
+        :return: True if this path is a regular file. False otherwise.
+        """
+        raise NotImplementedError()
+
+    @property
+    def is_symlink(self) -> bool:
+        """Determine if this path is a symlink
+
+        :return: True if this path is a symlink. False otherwise.
+        """
+        raise NotImplementedError()
+
+    @property
+    def has_fs_path(self) -> bool:
+        """Determine whether this path is backed by a file system path
+
+        :return: True if this path is backed by a file system object on the build system.
+        """
+        raise NotImplementedError()
+
+    @property
+    def is_read_write(self) -> bool:
+        """When true, the file system entry may be mutated
+
+        Read-write rules are:
+
+        +--------------------------+-------------------+------------------------+
+        | File system              | From / Inside     | Read-Only / Read-Write |
+        +--------------------------+-------------------+------------------------+
+        | Source directory         | Any context       | Read-Only              |
+        | Binary staging directory | Package Processor | Read-Write             |
+        | Binary staging directory | Metadata Detector | Read-Only              |
+        +--------------------------+-------------------+------------------------+
+
+        These rules apply to the virtual file system (`debputy` cannot enforce
+        these rules in the underlying file system). The `debputy` code relies
+        on these rules for its logic in multiple places to catch bugs and for
+        optimizations.
+
+        As an example, the reason why the file system is read-only when Metadata
+        Detectors are run is based the contents of the file system has already
+        been committed. New files will not be included, removals of existing
+        files will trigger a hard error when the package is assembled, etc.
+        To avoid people spending hours debugging why their code does not work
+        as intended, `debputy` instead throws a hard error if you try to mutate
+        the file system when it is read-only mode to "fail fast".
+
+        :return: Whether file system mutations are permitted.
+        """
+        return False
+
+    def mkdir(self, name: str) -> "VirtualPath":
+        """Create a new subdirectory of the current path
+
+        :param name: Basename of the new directory. The directory must not contain a path
+          with this basename.
+        :return: The new subdirectory
+        """
+        raise NotImplementedError
+
+    def mkdirs(self, path: str) -> "VirtualPath":
+        """Ensure a given path exists and is a directory.
+
+        :param path: Path to the directory to create. Any parent directories will be
+          created as needed. If the path already exists and is a directory, then it
+          is returned.  If any part of the path exists and that is not a directory,
+          then the `mkdirs` call will raise an error.
+        :return: The directory denoted by the given path
+        """
+        raise NotImplementedError
+
+    def add_file(
+        self,
+        name: str,
+        *,
+        unlink_if_exists: bool = True,
+        use_fs_path_mode: bool = False,
+        mode: int = 0o0644,
+        mtime: Optional[float] = None,
+    ) -> ContextManager["VirtualPath"]:
+        """Add a new regular file as a child of this path
+
+        This method will insert a new file into the virtual file system as a child
+        of the current path (which must be a directory).  The caller must use the
+        return value as a context manager (see example).  During the life-cycle of
+        the managed context, the caller can fill out the contents of the file
+        from the new path's `fs_path` attribute. The `fs_path` will exist as an
+        empty file when the context manager is entered.
+
+        Once the context manager exits, mutation of the `fs_path` is no longer permitted.
+
+          >>> import subprocess
+          >>> path = ...                                                                 # doctest: +SKIP
+          >>> with path.add_file("foo") as new_file, open(new_file.fs_path, "w") as fd:  # doctest: +SKIP
+          ...     fd.writelines(["Some", "Content", "Here"])
+
+        The caller can replace the provided `fs_path` entirely provided at the end result
+        (when the context manager exits) is a regular file with no hard links.
+
+        Note that this operation will fail if `path.is_read_write` returns False.
+
+        :param name: Basename of the new file
+        :param unlink_if_exists: If the name was already in use, then either an exception is thrown
+           (when `unlink_if_exists` is False) or the path will be removed via ´unlink(recursive=False)`
+           (when `unlink_if_exists` is True)
+        :param use_fs_path_mode: When True, the file created will have this mode in the physical file
+          system. When the context manager exists, `debputy` will refresh its mode to match the mode
+          in the physical file system.  This is primarily useful if the caller uses a subprocess to
+          mutate the path and the file mode is relevant for this tool (either as input or output).
+          When the parameter is false, the new file is guaranteed to be readable and writable for
+          the current user. However, no other guarantees are given (not even that it matches the
+          `mode` parameter and any changes to the mode in the physical file system will be ignored.
+        :param mode: This is the initial file mode. Note the `use_fs_path_mode` parameter for how
+          this interacts with the physical file system.
+        :param mtime: If the caller has a more accurate mtime than the mtime of the generated file,
+          then it can be provided here. Note that all mtimes will later be clamped based on
+          `SOURCE_DATE_EPOCH`. This parameter is only for when the conceptual mtime of this path
+          should be earlier than `SOURCE_DATE_EPOCH`.
+        :return: A Context manager that upon entering provides a `VirtualPath` instance for the
+                 new file. The instance remains valid after the context manager exits (assuming it exits
+                 successfully), but the file denoted by `fs_path` must not be changed after the context
+                 manager exits
+        """
+        raise NotImplementedError
+
+    def replace_fs_path_content(
+        self,
+        *,
+        use_fs_path_mode: bool = False,
+    ) -> ContextManager[str]:
+        """Replace the contents of this file via inline manipulation
+
+        Used as a context manager to provide the fs path for manipulation.
+
+        Example:
+            >>> import subprocess
+            >>> path = ...                                       # doctest: +SKIP
+            >>> with path.replace_fs_path_content() as fs_path:  # doctest: +SKIP
+            ...    subprocess.check_call(['strip', fs_path])     # doctest: +SKIP
+
+        The provided file system path should be manipulated inline. The debputy framework may
+        copy it first as necessary and therefore the provided fs_path may be different from
+        `path.fs_path` prior to entering the context manager.
+
+        Note that this operation will fail if `path.is_read_write` returns False.
+
+        If the mutation causes the returned `fs_path` to be a non-file or a hard-linked file
+        when the context manager exits, `debputy` will raise an error at that point. To preserve
+        the internal invariants of `debputy`, the path will be unlinked as `debputy` cannot
+        reliably restore the path.
+
+        :param use_fs_path_mode: If True, any changes to the mode on the physical FS path will be
+          recorded as the desired mode of the file when the contextmanager ends.  The provided FS path
+          with start with the current mode when `use_fs_path_mode` is True. Otherwise, `debputy` will
+          ignore the mode of the file system entry and re-use its own current mode
+          definition.
+        :return: A Context manager that upon entering provides the path to a muable (copy) of
+                 this path's `fs_path` attribute. The file on the underlying path may be mutated however
+                 the caller wishes until the context manager exits.
+        """
+        raise NotImplementedError
+
+    def add_symlink(self, link_name: str, link_target: str) -> "VirtualPath":
+        """Add a new regular file as a child of this path
+
+        This will create a new symlink inside the current path. If the path already exists,
+        the existing path will be unlinked via `unlink(recursive=False)`.
+
+        Note that this operation will fail if `path.is_read_write` returns False.
+
+        :param link_name: The basename of the link file entry.
+        :param link_target: The target of the link.  Link target normalization will
+          be handled by `debputy`, so the caller can use relative or absolute paths.
+          (At the time of writing, symlink target normalization happens late)
+        :return: The newly created symlink.
+        """
+        raise NotImplementedError
+
+    def unlink(self, *, recursive: bool = False) -> None:
+        """Unlink a file or a directory
+
+        This operation will remove the path from the file system (causing `is_detached` to return True).
+
+        When the path is a:
+
+         * symlink, then the symlink itself is removed. The target (if present) is not affected.
+         * *non-empty* directory, then the `recursive` parameter decides the outcome. An empty
+           directory will be removed regardless of the value of `recursive`.
+
+        Note that:
+          * the root directory cannot be deleted.
+          * this operation will fail if `path.is_read_write` returns False.
+
+        :param recursive: If True, then non-empty directories will be unlinked as well removing everything inside them
+          as well.  When False, an error is raised if the path is a non-empty directory
+        """
+        raise NotImplementedError
+
+    def interpreter(self) -> Optional[Interpreter]:
+        """Determine the interpreter of the file (`#!`-line details)
+
+        Note: this method is only applicable for files (`is_file` is True).
+
+        :return: The detected interpreter if present or None if no interpreter can be detected.
+        """
+        if not self.is_file:
+            raise TypeError("Only files can have interpreters")
+        try:
+            with self.open(byte_io=True, buffering=4096) as fd:
+                return extract_shebang_interpreter_from_file(fd)
+        except (PureVirtualPathError, TestPathWithNonExistentFSPathError):
+            return None
+
+    def metadata(
+        self,
+        metadata_type: Type[PMT],
+    ) -> PathMetadataReference[PMT]:
+        """Fetch the path metadata reference to access the underlying metadata
+
+        Calling this method returns a reference to an arbitrary piece of metadata associated
+        with this path. Plugins can store any arbitrary data associated with a given path.
+        Keep in mind that the metadata is stored in memory, so keep the size in moderation.
+
+        To store / update the metadata, the path must be in read-write mode. However,
+        already stored metadata remains accessible even if the path becomes read-only.
+
+        Note this method is not applicable if the path is detached
+
+        :param metadata_type: Type of the metadata being stored.
+        :return: A reference to the metadata.
+        """
+        raise NotImplementedError
+
+
+class FlushableSubstvars(Substvars):
+    __slots__ = ()
+
+    @contextlib.contextmanager
+    def flush(self) -> Iterator[str]:
+        """Temporarily write the substvars to a file and then re-read it again
+
+        >>> s = FlushableSubstvars()
+        >>> 'Test:Var' in s
+        False
+        >>> with s.flush() as name, open(name, 'wt', encoding='utf-8') as fobj:
+        ...     _ = fobj.write('Test:Var=bar\\n')  # "_ = " is to ignore the return value of write
+        >>> 'Test:Var' in s
+        True
+
+        Used as a context manager to define when the file is flushed and can be
+        accessed via the file system. If the context terminates successfully, the
+        file is read and its content replaces the current substvars.
+
+        This is mostly useful if the plugin needs to interface with a third-party
+        tool that requires a file as interprocess communication (IPC) for sharing
+        the substvars.
+
+        The file may be truncated or completed replaced (change inode) as long as
+        the provided path points to a regular file when the context manager
+        terminates successfully.
+
+        Note that any manipulation of the substvars via the `Substvars` API while
+        the file is flushed will silently be discarded if the context manager completes
+        successfully.
+        """
+        with tempfile.NamedTemporaryFile(mode="w+t", encoding="utf-8") as tmp:
+            self.write_substvars(tmp)
+            tmp.flush()  # Temping to use close, but then we have to manually delete the file.
+            yield tmp.name
+            # Re-open; seek did not work when I last tried (if I did it work, feel free to
+            # convert back to seek - as long as it works!)
+            with open(tmp.name, "rt", encoding="utf-8") as fd:
+                self.read_substvars(fd)
+
+    def save(self) -> None:
+        # Promote the debputy extension over `save()` for the plugins.
+        if self._substvars_path is None:
+            raise TypeError(
+                "Please use `flush()` extension to temporarily write the substvars to the file system"
+            )
+        super().save()
+
+
+class ServiceRegistry(Generic[DSD]):
+    __slots__ = ()
+
+    def register_service(
+        self,
+        path: VirtualPath,
+        name: Union[str, List[str]],
+        *,
+        type_of_service: str = "service",  # "timer", etc.
+        service_scope: str = "system",
+        enable_by_default: bool = True,
+        start_by_default: bool = True,
+        default_upgrade_rule: ServiceUpgradeRule = "restart",
+        service_context: Optional[DSD] = None,
+    ) -> None:
+        """Register a service detected in the package
+
+        All the details will either be provided as-is or used as default when the plugin provided
+        integration code is called.
+
+        Two services from different service managers are considered related when:
+
+         1) They are of the same type (`type_of_service`) and has the same scope (`service_scope`), AND
+         2) Their plugin provided names has an overlap
+
+        Related services can be covered by the same service definition in the manifest.
+
+        :param path: The path defining this service.
+        :param name: The name of the service. Multiple ones can be provided if the service has aliases.
+          Note that when providing multiple names, `debputy` will use the first name in the list as the
+          default name if it has to choose. Any alternative name provided can be used by the packager
+          to identify this service.
+        :param type_of_service: The type of service. By default, this is "service", but plugins can
+          provide other types (such as "timer" for the systemd timer unit).
+        :param service_scope: The scope for this service. By default, this is "system" meaning the
+          service is a system-wide service. Service managers can define their own scopes such as
+          "user" (which is used by systemd for "per-user" services).
+        :param enable_by_default: Whether the service should be enabled by default, assuming the
+          packager does not explicitly override this setting.
+        :param start_by_default: Whether the service should be started by default on install, assuming
+          the packager does not explicitly override this setting.
+        :param default_upgrade_rule: The default value for how the service should be processed during
+          upgrades. Options are:
+              * `do-nothing`: The plugin should not interact with the running service (if any)
+                (maintenance of the enabled start, start on install, etc. are still applicable)
+              * `reload`: The plugin should attempt to reload the running service (if any).
+                 Note: In combination with `auto_start_in_install == False`, be careful to not
+                 start the service if not is not already running.
+              * `restart`: The plugin should attempt to restart the running service (if any).
+                 Note: In combination with `auto_start_in_install == False`, be careful to not
+                 start the service if not is not already running.
+              * `stop-then-start`: The plugin should stop the service during `prerm upgrade`
+                 and start it against in the `postinst` script.
+
+        :param service_context: Any custom data that the detector want to pass along to the
+          integrator for this service.
+        """
+        raise NotImplementedError
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ParserAttributeDocumentation:
+    attributes: FrozenSet[str]
+    description: Optional[str]
+
+
+def undocumented_attr(attr: str) -> ParserAttributeDocumentation:
+    """Describe an attribute as undocumented
+
+    If you for some reason do not want to document a particular attribute, you can mark it as
+    undocumented. This is required if you are only documenting a subset of the attributes,
+    because `debputy` assumes any omission to be a mistake.
+    """
+    return ParserAttributeDocumentation(
+        frozenset({attr}),
+        None,
+    )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ParserDocumentation:
+    title: Optional[str] = None
+    description: Optional[str] = None
+    attribute_doc: Optional[Sequence[ParserAttributeDocumentation]] = None
+    alt_parser_description: Optional[str] = None
+    documentation_reference_url: Optional[str] = None
+
+    def replace(self, **changes: Any) -> "ParserDocumentation":
+        return dataclasses.replace(self, **changes)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class TypeMappingExample(Generic[S]):
+    source_input: S
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class TypeMappingDocumentation(Generic[S]):
+    description: Optional[str] = None
+    examples: Sequence[TypeMappingExample[S]] = tuple()
+
+
+def type_mapping_example(source_input: S) -> TypeMappingExample[S]:
+    return TypeMappingExample(source_input)
+
+
+def type_mapping_reference_documentation(
+    *,
+    description: Optional[str] = None,
+    examples: Union[TypeMappingExample[S], Iterable[TypeMappingExample[S]]] = tuple(),
+) -> TypeMappingDocumentation[S]:
+    e = (
+        tuple([examples])
+        if isinstance(examples, TypeMappingExample)
+        else tuple(examples)
+    )
+    return TypeMappingDocumentation(
+        description=description,
+        examples=e,
+    )
+
+
+def documented_attr(
+    attr: Union[str, Iterable[str]],
+    description: str,
+) -> ParserAttributeDocumentation:
+    """Describe an attribute or a group of attributes
+
+    :param attr: A single attribute or a sequence of attributes. The attribute must be the
+      attribute name as used in the source format version of the TypedDict.
+
+      If multiple attributes are provided, they will be documented together. This is often
+      useful if these attributes are strongly related (such as different names for the same
+      target attribute).
+    :param description: The description the user should see for this attribute / these
+       attributes. This parameter can be a Python format string with variables listed in
+       the description of `reference_documentation`.
+    :return: An opaque representation of the documentation,
+    """
+    attributes = [attr] if isinstance(attr, str) else attr
+    return ParserAttributeDocumentation(
+        frozenset(attributes),
+        description,
+    )
+
+
+def reference_documentation(
+    title: str = "Auto-generated reference documentation for {RULE_NAME}",
+    description: Optional[str] = textwrap.dedent(
+        """\
+            This is an automatically generated reference documentation for {RULE_NAME}. It is generated
+            from input provided by {PLUGIN_NAME} via the debputy API.
+
+            (If you are the provider of the {PLUGIN_NAME} plugin, you can replace this text with
+             your own documentation by providing the `inline_reference_documentation` when registering
+             the manifest rule.)
+            """
+    ),
+    attributes: Optional[Sequence[ParserAttributeDocumentation]] = None,
+    non_mapping_description: Optional[str] = None,
+    reference_documentation_url: Optional[str] = None,
+) -> ParserDocumentation:
+    """Provide inline reference documentation for the manifest snippet
+
+    For parameters that mention that they are a Python format, the following format variables
+    are available:
+
+     * RULE_NAME: Name of the rule. If manifest snippet has aliases, this will be the name of
+       the alias provided by the user.
+     * MANIFEST_FORMAT_DOC: Path OR URL to the "MANIFEST-FORMAT" reference documentation from
+       `debputy`. By using the MANIFEST_FORMAT_DOC variable, you ensure that you point to the
+       file that matches the version of `debputy` itself.
+     * PLUGIN_NAME: Name of the plugin providing this rule.
+
+    :param title: The text you want the user to see as for your rule. A placeholder is provided by default.
+      This parameter can be a Python format string with the above listed variables.
+    :param description: The text you want the user to see as a description for the rule. An auto-generated
+      placeholder is provided by default saying that no human written documentation was provided.
+      This parameter can be a Python format string with the above listed variables.
+    :param attributes: A sequence of attribute-related documentation. Each element of the sequence should
+      be the result of `documented_attr` or `undocumented_attr`. The sequence must cover all source
+      attributes exactly once.
+    :param non_mapping_description: The text you want the user to see as the description for your rule when
+      `debputy` describes its non-mapping format. Must not be provided for rules that do not have an
+      (optional) non-mapping format as source format.  This parameter can be a Python format string with
+      the above listed variables.
+    :param reference_documentation_url: A URL to the reference documentation.
+    :return: An opaque representation of the documentation,
+    """
+    return ParserDocumentation(
+        title,
+        description,
+        attributes,
+        non_mapping_description,
+        reference_documentation_url,
+    )
+
+
+class ServiceDefinition(Generic[DSD]):
+    __slots__ = ()
+
+    @property
+    def name(self) -> str:
+        """Name of the service registered by the plugin
+
+        This is always a plugin provided name for this service (that is, `x.name in x.names`
+        will always be `True`).  Where possible, this will be the same as the one that the
+        packager provided when they provided any configuration related to this service.
+        When not possible, this will be the first name provided by the plugin (`x.names[0]`).
+
+        If all the aliases are equal, then using this attribute will provide traceability
+        between the manifest and the generated maintscript snippets. When the exact name
+        used is important, the plugin should ignore this attribute and pick the name that
+        is needed.
+        """
+        raise NotImplementedError
+
+    @property
+    def names(self) -> Sequence[str]:
+        """All *plugin provided* names and aliases of the service
+
+        This is the name/sequence of names that the plugin provided when it registered
+        the service earlier.
+        """
+        raise NotImplementedError
+
+    @property
+    def path(self) -> VirtualPath:
+        """The registered path for this service
+
+        :return: The path that was associated with this service when it was registered
+          earlier.
+        """
+        raise NotImplementedError
+
+    @property
+    def type_of_service(self) -> str:
+        """Type of the service such as "service" (daemon), "timer", etc.
+
+        :return: The type of service scope. It is the same value as the one as the plugin provided
+           when registering the service (if not explicitly provided, it defaults to "service").
+        """
+        raise NotImplementedError
+
+    @property
+    def service_scope(self) -> str:
+        """Service scope such as "system" or "user"
+
+        :return: The service scope. It is the same value as the one as the plugin provided
+           when registering the service (if not explicitly provided, it defaults to "system")
+        """
+        raise NotImplementedError
+
+    @property
+    def auto_enable_on_install(self) -> bool:
+        """Whether the service should be auto-enabled on install
+
+        :return: True if the service should be enabled automatically, false if not.
+        """
+        raise NotImplementedError
+
+    @property
+    def auto_start_in_install(self) -> bool:
+        """Whether the service should be auto-started on install
+
+        :return: True if the service should be started automatically, false if not.
+        """
+        raise NotImplementedError
+
+    @property
+    def on_upgrade(self) -> ServiceUpgradeRule:
+        """How to handle the service during an upgrade
+
+        Options are:
+          * `do-nothing`: The plugin should not interact with the running service (if any)
+            (maintenance of the enabled start, start on install, etc. are still applicable)
+          * `reload`: The plugin should attempt to reload the running service (if any).
+             Note: In combination with `auto_start_in_install == False`, be careful to not
+             start the service if not is not already running.
+          * `restart`: The plugin should attempt to restart the running service (if any).
+             Note: In combination with `auto_start_in_install == False`, be careful to not
+             start the service if not is not already running.
+          * `stop-then-start`: The plugin should stop the service during `prerm upgrade`
+             and start it against in the `postinst` script.
+
+        Note: In all cases, the plugin should still consider what to do in
+        `prerm remove`, which is the last point in time where the plugin can rely on the
+        service definitions in the file systems to stop the services when the package is
+        being uninstalled.
+
+        :return: The service restart rule
+        """
+        raise NotImplementedError
+
+    @property
+    def definition_source(self) -> str:
+        """Describes where this definition came from
+
+        If the definition is provided by the packager, then this will reference the part
+        of the manifest that made this definition. Otherwise, this will be a reference
+        to the plugin providing this definition.
+
+        :return: The source of this definition
+        """
+        raise NotImplementedError
+
+    @property
+    def is_plugin_provided_definition(self) -> bool:
+        """Whether the definition source points to the plugin or a package provided definition
+
+        :return: True if definition is from the plugin. False if the definition is defined
+          in another place (usually, the manifest)
+        """
+        raise NotImplementedError
+
+    @property
+    def service_context(self) -> Optional[DSD]:
+        """Custom service context (if any) provided by the detector code of the plugin
+
+        :return: If the detection code provided a custom data when registering the
+          service, this attribute will reference that data.  If nothing was provided,
+          then this attribute will be None.
+        """
+        raise NotImplementedError
diff --git a/src/debputy/plugin/api/test_api/__init__.py b/src/debputy/plugin/api/test_api/__init__.py
new file mode 100644
index 0000000..414e6c1
--- /dev/null
+++ b/src/debputy/plugin/api/test_api/__init__.py
@@ -0,0 +1,21 @@
+from debputy.plugin.api.test_api.test_impl import (
+    package_metadata_context,
+    initialize_plugin_under_test,
+    manifest_variable_resolution_context,
+)
+from debputy.plugin.api.test_api.test_spec import (
+    RegisteredPackagerProvidedFile,
+    build_virtual_file_system,
+    InitializedPluginUnderTest,
+    DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS,
+)
+
+__all__ = [
+    "initialize_plugin_under_test",
+    "RegisteredPackagerProvidedFile",
+    "build_virtual_file_system",
+    "InitializedPluginUnderTest",
+    "package_metadata_context",
+    "manifest_variable_resolution_context",
+    "DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS",
+]
diff --git a/src/debputy/plugin/api/test_api/test_impl.py b/src/debputy/plugin/api/test_api/test_impl.py
new file mode 100644
index 0000000..46f054c
--- /dev/null
+++ b/src/debputy/plugin/api/test_api/test_impl.py
@@ -0,0 +1,803 @@
+import contextlib
+import dataclasses
+import inspect
+import os.path
+from io import BytesIO
+from typing import (
+    Mapping,
+    Dict,
+    Optional,
+    Tuple,
+    List,
+    cast,
+    FrozenSet,
+    Sequence,
+    Union,
+    Type,
+    Iterator,
+    Set,
+    KeysView,
+    Callable,
+)
+
+from debian.deb822 import Deb822
+from debian.substvars import Substvars
+
+from debputy import DEBPUTY_PLUGIN_ROOT_DIR
+from debputy.architecture_support import faked_arch_table
+from debputy.filesystem_scan import FSROOverlay, FSRootDir
+from debputy.packages import BinaryPackage
+from debputy.plugin.api import (
+    PluginInitializationEntryPoint,
+    VirtualPath,
+    PackageProcessingContext,
+    DpkgTriggerType,
+    Maintscript,
+)
+from debputy.plugin.api.example_processing import process_discard_rule_example
+from debputy.plugin.api.impl import (
+    plugin_metadata_for_debputys_own_plugin,
+    DebputyPluginInitializerProvider,
+    parse_json_plugin_desc,
+    MaintscriptAccessorProviderBase,
+    BinaryCtrlAccessorProviderBase,
+    PLUGIN_TEST_SUFFIX,
+    find_json_plugin,
+    ServiceDefinitionImpl,
+)
+from debputy.plugin.api.impl_types import (
+    PackagerProvidedFileClassSpec,
+    DebputyPluginMetadata,
+    PluginProvidedTrigger,
+    ServiceManagerDetails,
+)
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.plugin.api.spec import (
+    MaintscriptAccessor,
+    FlushableSubstvars,
+    ServiceRegistry,
+    DSD,
+    ServiceUpgradeRule,
+)
+from debputy.plugin.api.test_api.test_spec import (
+    InitializedPluginUnderTest,
+    RegisteredPackagerProvidedFile,
+    RegisteredTrigger,
+    RegisteredMaintscript,
+    DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS,
+    ADRExampleIssue,
+    DetectedService,
+    RegisteredMetadata,
+)
+from debputy.plugin.debputy.debputy_plugin import initialize_debputy_features
+from debputy.substitution import SubstitutionImpl, VariableContext, Substitution
+from debputy.util import package_cross_check_precheck
+
+RegisteredPackagerProvidedFile.register(PackagerProvidedFileClassSpec)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PackageProcessingContextTestProvider(PackageProcessingContext):
+    binary_package: BinaryPackage
+    binary_package_version: str
+    related_udeb_package: Optional[BinaryPackage]
+    related_udeb_package_version: Optional[str]
+    accessible_package_roots: Callable[[], Sequence[Tuple[BinaryPackage, VirtualPath]]]
+
+
+def _initialize_plugin_under_test(
+    plugin_metadata: DebputyPluginMetadata,
+    load_debputy_plugin: bool = True,
+) -> "InitializedPluginUnderTest":
+    feature_set = PluginProvidedFeatureSet()
+    substitution = SubstitutionImpl(
+        unresolvable_substitutions=frozenset(["SOURCE_DATE_EPOCH", "PACKAGE"]),
+        variable_context=VariableContext(
+            FSROOverlay.create_root_dir("debian", "debian"),
+        ),
+        plugin_feature_set=feature_set,
+    )
+
+    if load_debputy_plugin:
+        debputy_plugin_metadata = plugin_metadata_for_debputys_own_plugin(
+            initialize_debputy_features
+        )
+        # Load debputy's own plugin first, so conflicts with debputy's plugin are detected early
+        debputy_provider = DebputyPluginInitializerProvider(
+            debputy_plugin_metadata,
+            feature_set,
+            substitution,
+        )
+        debputy_provider.load_plugin()
+
+    plugin_under_test_provider = DebputyPluginInitializerProvider(
+        plugin_metadata,
+        feature_set,
+        substitution,
+    )
+    plugin_under_test_provider.load_plugin()
+
+    return InitializedPluginUnderTestImpl(
+        plugin_metadata.plugin_name,
+        feature_set,
+        substitution,
+    )
+
+
+def _auto_load_plugin_from_filename(
+    py_test_filename: str,
+) -> "InitializedPluginUnderTest":
+    dirname, basename = os.path.split(py_test_filename)
+    plugin_name = PLUGIN_TEST_SUFFIX.sub("", basename).replace("_", "-")
+
+    test_location = os.environ.get("DEBPUTY_TEST_PLUGIN_LOCATION", "uninstalled")
+    if test_location == "uninstalled":
+        json_basename = f"{plugin_name}.json"
+        json_desc_file = os.path.join(dirname, json_basename)
+        if "/" not in json_desc_file:
+            json_desc_file = f"./{json_desc_file}"
+
+        if os.path.isfile(json_desc_file):
+            return _initialize_plugin_from_desc(json_desc_file)
+
+        json_desc_file_in = f"{json_desc_file}.in"
+        if os.path.isfile(json_desc_file_in):
+            return _initialize_plugin_from_desc(json_desc_file)
+        raise FileNotFoundError(
+            f"Cannot determine the plugin JSON metadata descriptor: Expected it to be"
+            f" {json_desc_file} or {json_desc_file_in}"
+        )
+
+    if test_location == "installed":
+        plugin_metadata = find_json_plugin([str(DEBPUTY_PLUGIN_ROOT_DIR)], plugin_name)
+        return _initialize_plugin_under_test(plugin_metadata, load_debputy_plugin=True)
+
+    raise ValueError(
+        'Invalid or unsupported "DEBPUTY_TEST_PLUGIN_LOCATION" environment variable. It must be either'
+        ' unset OR one of "installed", "uninstalled".'
+    )
+
+
+def initialize_plugin_under_test(
+    *,
+    plugin_desc_file: Optional[str] = None,
+) -> "InitializedPluginUnderTest":
+    """Load and initialize a plugin for testing it
+
+    This method will load the plugin via plugin description, which is the method that `debputy` does at
+     run-time (in contrast to `initialize_plugin_under_test_preloaded`, which bypasses this concrete part
+     of the flow).
+
+    :param plugin_desc_file: The plugin description file (`.json`) that describes how to load the plugin.
+      If omitted, `debputy` will attempt to attempt the plugin description file based on the test itself.
+      This works for "single-file" plugins, where the description file and the test are right next to
+      each other.
+
+      Note that the description file is *not* required to a valid version at this stage (e.g., "N/A" or
+      "@PLACEHOLDER@") is fine. So you still use this method if you substitute in the version during
+      build after running the tests. To support this flow, the file name can also end with `.json.in`
+      (instead of `.json`).
+    :return: The loaded plugin for testing
+    """
+    if plugin_desc_file is None:
+        caller_file = inspect.stack()[1].filename
+        return _auto_load_plugin_from_filename(caller_file)
+    if DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS:
+        raise RuntimeError(
+            "Running the test against an installed plugin does not work when"
+            " plugin_desc_file is provided. Please skip this test. You can "
+            " import DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS and use that as"
+            " conditional for this purpose."
+        )
+    return _initialize_plugin_from_desc(plugin_desc_file)
+
+
+def _initialize_plugin_from_desc(
+    desc_file: str,
+) -> "InitializedPluginUnderTest":
+    if not desc_file.endswith((".json", ".json.in")):
+        raise ValueError("The plugin file must end with .json or .json.in")
+
+    plugin_metadata = parse_json_plugin_desc(desc_file)
+
+    return _initialize_plugin_under_test(plugin_metadata, load_debputy_plugin=True)
+
+
+def initialize_plugin_under_test_from_inline_json(
+    plugin_name: str,
+    json_content: str,
+) -> "InitializedPluginUnderTest":
+    with BytesIO(json_content.encode("utf-8")) as fd:
+        plugin_metadata = parse_json_plugin_desc(plugin_name, fd=fd)
+
+    return _initialize_plugin_under_test(plugin_metadata, load_debputy_plugin=True)
+
+
+def initialize_plugin_under_test_preloaded(
+    api_compat_version: int,
+    plugin_initializer: PluginInitializationEntryPoint,
+    /,
+    plugin_name: str = "plugin-under-test",
+    load_debputy_plugin: bool = True,
+) -> "InitializedPluginUnderTest":
+    """Internal API: Initialize a plugin for testing without loading it from a file
+
+    This method by-passes the standard loading mechanism, meaning you will not test that your plugin
+    description file is correct. Notably, any feature provided via the JSON description file will
+    **NOT** be visible for the test.
+
+    This API is mostly useful for testing parts of debputy itself.
+
+    :param api_compat_version: The API version the plugin was written for. Use the same version as the
+      version from the entry point (The `v1` part of `debputy.plugins.v1.initialize` translate into `1`).
+    :param plugin_initializer: The entry point of the plugin
+    :param plugin_name: Normally, debputy would derive this from the entry point. In the test, it will
+      use a test name and version. However, you can explicitly set if you want the real name/version.
+    :param load_debputy_plugin: Whether to load debputy's own plugin first. Doing so provides a more
+      realistic test and enables the test to detect conflicts with debputy's own plugins (de facto making
+      the plugin unloadable in practice if such a conflict is present).  This option is mostly provided
+      to enable debputy to use this method for self testing.
+    :return: The loaded plugin for testing
+    """
+
+    if DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS:
+        raise RuntimeError(
+            "Running the test against an installed plugin does not work when"
+            " the plugin is preload. Please skip this test. You can "
+            " import DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS and use that as"
+            " conditional for this purpose."
+        )
+
+    plugin_metadata = DebputyPluginMetadata(
+        plugin_name=plugin_name,
+        api_compat_version=api_compat_version,
+        plugin_initializer=plugin_initializer,
+        plugin_loader=None,
+        plugin_path="<loaded-via-test>",
+    )
+
+    return _initialize_plugin_under_test(
+        plugin_metadata,
+        load_debputy_plugin=load_debputy_plugin,
+    )
+
+
+class _MockArchTable:
+    @staticmethod
+    def matches_architecture(_a: str, _b: str) -> bool:
+        return True
+
+
+FAKE_DPKG_QUERY_TABLE = cast("DpkgArchTable", _MockArchTable())
+del _MockArchTable
+
+
+def package_metadata_context(
+    *,
+    host_arch: str = "amd64",
+    package_fields: Optional[Dict[str, str]] = None,
+    related_udeb_package_fields: Optional[Dict[str, str]] = None,
+    binary_package_version: str = "1.0-1",
+    related_udeb_package_version: Optional[str] = None,
+    should_be_acted_on: bool = True,
+    related_udeb_fs_root: Optional[VirtualPath] = None,
+    accessible_package_roots: Sequence[Tuple[Mapping[str, str], VirtualPath]] = tuple(),
+) -> PackageProcessingContext:
+    process_table = faked_arch_table(host_arch)
+    f = {
+        "Package": "foo",
+        "Architecture": "any",
+    }
+    if package_fields is not None:
+        f.update(package_fields)
+
+    bin_package = BinaryPackage(
+        Deb822(f),
+        process_table,
+        FAKE_DPKG_QUERY_TABLE,
+        is_main_package=True,
+        should_be_acted_on=should_be_acted_on,
+    )
+    udeb_package = None
+    if related_udeb_package_fields is not None:
+        uf = dict(related_udeb_package_fields)
+        uf.setdefault("Package", f'{f["Package"]}-udeb')
+        uf.setdefault("Architecture", f["Architecture"])
+        uf.setdefault("Package-Type", "udeb")
+        udeb_package = BinaryPackage(
+            Deb822(uf),
+            process_table,
+            FAKE_DPKG_QUERY_TABLE,
+            is_main_package=False,
+            should_be_acted_on=True,
+        )
+        if related_udeb_package_version is None:
+            related_udeb_package_version = binary_package_version
+    if accessible_package_roots:
+        apr = []
+        for fields, apr_fs_root in accessible_package_roots:
+            apr_fields = Deb822(dict(fields))
+            if "Package" not in apr_fields:
+                raise ValueError(
+                    "Missing mandatory Package field in member of accessible_package_roots"
+                )
+            if "Architecture" not in apr_fields:
+                raise ValueError(
+                    "Missing mandatory Architecture field in member of accessible_package_roots"
+                )
+            apr_package = BinaryPackage(
+                apr_fields,
+                process_table,
+                FAKE_DPKG_QUERY_TABLE,
+                is_main_package=False,
+                should_be_acted_on=True,
+            )
+            r = package_cross_check_precheck(bin_package, apr_package)
+            if not r[0]:
+                raise ValueError(
+                    f"{apr_package.name} would not be accessible for {bin_package.name}"
+                )
+            apr.append((apr_package, apr_fs_root))
+
+        if related_udeb_fs_root is not None:
+            if udeb_package is None:
+                raise ValueError(
+                    "related_udeb_package_fields must be given when related_udeb_fs_root is given"
+                )
+            r = package_cross_check_precheck(bin_package, udeb_package)
+            if not r[0]:
+                raise ValueError(
+                    f"{udeb_package.name} would not be accessible for {bin_package.name}, so providing"
+                    " related_udeb_fs_root is irrelevant"
+                )
+            apr.append(udeb_package)
+        apr = tuple(apr)
+    else:
+        apr = tuple()
+
+    return PackageProcessingContextTestProvider(
+        binary_package=bin_package,
+        related_udeb_package=udeb_package,
+        binary_package_version=binary_package_version,
+        related_udeb_package_version=related_udeb_package_version,
+        accessible_package_roots=lambda: apr,
+    )
+
+
+def manifest_variable_resolution_context(
+    *,
+    debian_dir: Optional[VirtualPath] = None,
+) -> VariableContext:
+    if debian_dir is None:
+        debian_dir = FSRootDir()
+
+    return VariableContext(debian_dir)
+
+
+class MaintscriptAccessorTestProvider(MaintscriptAccessorProviderBase):
+    __slots__ = ("_plugin_metadata", "_plugin_source_id", "_maintscript_container")
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+        maintscript_container: Dict[str, List[RegisteredMaintscript]],
+    ):
+        self._plugin_metadata = plugin_metadata
+        self._plugin_source_id = plugin_source_id
+        self._maintscript_container = maintscript_container
+
+    @classmethod
+    def _apply_condition_to_script(
+        cls, condition: str, run_snippet: str, /, indent: Optional[bool] = None
+    ) -> str:
+        return run_snippet
+
+    def _append_script(
+        self,
+        caller_name: str,
+        maintscript: Maintscript,
+        full_script: str,
+        /,
+        perform_substitution: bool = True,
+    ) -> None:
+        if self._plugin_source_id not in self._maintscript_container:
+            self._maintscript_container[self._plugin_source_id] = []
+        self._maintscript_container[self._plugin_source_id].append(
+            RegisteredMaintscript(
+                maintscript,
+                caller_name,
+                full_script,
+                perform_substitution,
+            )
+        )
+
+
+class RegisteredMetadataImpl(RegisteredMetadata):
+    __slots__ = (
+        "_substvars",
+        "_triggers",
+        "_maintscripts",
+    )
+
+    def __init__(
+        self,
+        substvars: Substvars,
+        triggers: List[RegisteredTrigger],
+        maintscripts: List[RegisteredMaintscript],
+    ) -> None:
+        self._substvars = substvars
+        self._triggers = triggers
+        self._maintscripts = maintscripts
+
+    @property
+    def substvars(self) -> Substvars:
+        return self._substvars
+
+    @property
+    def triggers(self) -> List[RegisteredTrigger]:
+        return self._triggers
+
+    def maintscripts(
+        self,
+        *,
+        maintscript: Optional[Maintscript] = None,
+    ) -> List[RegisteredMaintscript]:
+        if maintscript is None:
+            return self._maintscripts
+        return [m for m in self._maintscripts if m.maintscript == maintscript]
+
+
+class BinaryCtrlAccessorTestProvider(BinaryCtrlAccessorProviderBase):
+    __slots__ = ("_maintscript_container",)
+
+    def __init__(
+        self,
+        plugin_metadata: DebputyPluginMetadata,
+        plugin_source_id: str,
+        context: PackageProcessingContext,
+    ) -> None:
+        super().__init__(
+            plugin_metadata,
+            plugin_source_id,
+            context,
+            {},
+            FlushableSubstvars(),
+            (None, None),
+        )
+        self._maintscript_container: Dict[str, List[RegisteredMaintscript]] = {}
+
+    def _create_maintscript_accessor(self) -> MaintscriptAccessor:
+        return MaintscriptAccessorTestProvider(
+            self._plugin_metadata,
+            self._plugin_source_id,
+            self._maintscript_container,
+        )
+
+    def registered_metadata(self) -> RegisteredMetadata:
+        return RegisteredMetadataImpl(
+            self._substvars,
+            [
+                RegisteredTrigger.from_plugin_provided_trigger(t)
+                for t in self._triggers.values()
+                if t.provider_source_id == self._plugin_source_id
+            ],
+            self._maintscript_container.get(self._plugin_source_id, []),
+        )
+
+
+class ServiceRegistryTestImpl(ServiceRegistry[DSD]):
+    __slots__ = ("_service_manager_details", "_service_definitions")
+
+    def __init__(
+        self,
+        service_manager_details: ServiceManagerDetails,
+        detected_services: List[DetectedService[DSD]],
+    ) -> None:
+        self._service_manager_details = service_manager_details
+        self._service_definitions = detected_services
+
+    def register_service(
+        self,
+        path: VirtualPath,
+        name: Union[str, List[str]],
+        *,
+        type_of_service: str = "service",  # "timer", etc.
+        service_scope: str = "system",
+        enable_by_default: bool = True,
+        start_by_default: bool = True,
+        default_upgrade_rule: ServiceUpgradeRule = "restart",
+        service_context: Optional[DSD] = None,
+    ) -> None:
+        names = name if isinstance(name, list) else [name]
+        if len(names) < 1:
+            raise ValueError(
+                f"The service must have at least one name - {path.absolute} did not have any"
+            )
+        self._service_definitions.append(
+            DetectedService(
+                path,
+                names,
+                type_of_service,
+                service_scope,
+                enable_by_default,
+                start_by_default,
+                default_upgrade_rule,
+                service_context,
+            )
+        )
+
+
+@contextlib.contextmanager
+def _read_only_fs_root(fs_root: VirtualPath) -> Iterator[VirtualPath]:
+    if fs_root.is_read_write:
+        assert isinstance(fs_root, FSRootDir)
+        fs_root.is_read_write = False
+        yield fs_root
+        fs_root.is_read_write = True
+    else:
+        yield fs_root
+
+
+class InitializedPluginUnderTestImpl(InitializedPluginUnderTest):
+    def __init__(
+        self,
+        plugin_name: str,
+        feature_set: PluginProvidedFeatureSet,
+        substitution: SubstitutionImpl,
+    ) -> None:
+        self._feature_set = feature_set
+        self._plugin_name = plugin_name
+        self._packager_provided_files: Optional[
+            Dict[str, RegisteredPackagerProvidedFile]
+        ] = None
+        self._triggers: Dict[Tuple[DpkgTriggerType, str], PluginProvidedTrigger] = {}
+        self._maintscript_container: Dict[str, List[RegisteredMaintscript]] = {}
+        self._substitution = substitution
+        assert plugin_name in self._feature_set.plugin_data
+
+    @property
+    def _plugin_metadata(self) -> DebputyPluginMetadata:
+        return self._feature_set.plugin_data[self._plugin_name]
+
+    def packager_provided_files_by_stem(
+        self,
+    ) -> Mapping[str, RegisteredPackagerProvidedFile]:
+        ppf = self._packager_provided_files
+        if ppf is None:
+            result: Dict[str, RegisteredPackagerProvidedFile] = {}
+            for spec in self._feature_set.packager_provided_files.values():
+                if spec.debputy_plugin_metadata.plugin_name != self._plugin_name:
+                    continue
+                # Registered as a virtual subclass, so this should always be True
+                assert isinstance(spec, RegisteredPackagerProvidedFile)
+                result[spec.stem] = spec
+            self._packager_provided_files = result
+            ppf = result
+        return ppf
+
+    def run_metadata_detector(
+        self,
+        metadata_detector_id: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+    ) -> RegisteredMetadata:
+        if fs_root.parent_dir is not None:
+            raise ValueError("Provided path must be the file system root.")
+        detectors = self._feature_set.metadata_maintscript_detectors[self._plugin_name]
+        matching_detectors = [
+            d for d in detectors if d.detector_id == metadata_detector_id
+        ]
+        if len(matching_detectors) != 1:
+            assert not matching_detectors
+            raise ValueError(
+                f"The plugin {self._plugin_name} did not provide a metadata detector with ID"
+                f' "{metadata_detector_id}"'
+            )
+        if context is None:
+            context = package_metadata_context()
+        detector = matching_detectors[0]
+        if not detector.applies_to(context.binary_package):
+            raise ValueError(
+                f'The detector "{metadata_detector_id}" from {self._plugin_name} does not apply to the'
+                " given package. Consider using `package_metadata_context()` to emulate a binary package"
+                " with the correct specification. As an example: "
+                '`package_metadata_context(package_fields={"Package-Type": "udeb"})` would emulate a udeb'
+                " package."
+            )
+
+        ctrl = BinaryCtrlAccessorTestProvider(
+            self._plugin_metadata,
+            metadata_detector_id,
+            context,
+        )
+        with _read_only_fs_root(fs_root) as ro_root:
+            detector.run_detector(
+                ro_root,
+                ctrl,
+                context,
+            )
+        return ctrl.registered_metadata()
+
+    def run_package_processor(
+        self,
+        package_processor_id: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+    ) -> None:
+        if fs_root.parent_dir is not None:
+            raise ValueError("Provided path must be the file system root.")
+        pp_key = (self._plugin_name, package_processor_id)
+        package_processor = self._feature_set.all_package_processors.get(pp_key)
+        if package_processor is None:
+            raise ValueError(
+                f"The plugin {self._plugin_name} did not provide a package processor with ID"
+                f' "{package_processor_id}"'
+            )
+        if context is None:
+            context = package_metadata_context()
+        if not fs_root.is_read_write:
+            raise ValueError(
+                "The provided fs_root is read-only and it must be read-write for package processor"
+            )
+        if not package_processor.applies_to(context.binary_package):
+            raise ValueError(
+                f'The package processor "{package_processor_id}" from {self._plugin_name} does not apply'
+                " to the given package. Consider using `package_metadata_context()` to emulate a binary"
+                " package with the correct specification. As an example: "
+                '`package_metadata_context(package_fields={"Package-Type": "udeb"})` would emulate a udeb'
+                " package."
+            )
+        package_processor.run_package_processor(
+            fs_root,
+            None,
+            context,
+        )
+
+    @property
+    def declared_manifest_variables(self) -> FrozenSet[str]:
+        return frozenset(
+            {
+                k
+                for k, v in self._feature_set.manifest_variables.items()
+                if v.plugin_metadata.plugin_name == self._plugin_name
+            }
+        )
+
+    def automatic_discard_rules_examples_with_issues(self) -> Sequence[ADRExampleIssue]:
+        issues = []
+        for adr in self._feature_set.auto_discard_rules.values():
+            if adr.plugin_metadata.plugin_name != self._plugin_name:
+                continue
+            for idx, example in enumerate(adr.examples):
+                result = process_discard_rule_example(
+                    adr,
+                    example,
+                )
+                if result.inconsistent_paths:
+                    issues.append(
+                        ADRExampleIssue(
+                            adr.name,
+                            idx,
+                            [
+                                x.absolute + ("/" if x.is_dir else "")
+                                for x in result.inconsistent_paths
+                            ],
+                        )
+                    )
+        return issues
+
+    def run_service_detection_and_integrations(
+        self,
+        service_manager: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+        *,
+        service_context_type_hint: Optional[Type[DSD]] = None,
+    ) -> Tuple[List[DetectedService[DSD]], RegisteredMetadata]:
+        if fs_root.parent_dir is not None:
+            raise ValueError("Provided path must be the file system root.")
+        try:
+            service_manager_details = self._feature_set.service_managers[
+                service_manager
+            ]
+            if service_manager_details.plugin_metadata.plugin_name != self._plugin_name:
+                raise KeyError(service_manager)
+        except KeyError:
+            raise ValueError(
+                f"The plugin {self._plugin_name} does not provide a"
+                f" service manager called {service_manager}"
+            ) from None
+
+        if context is None:
+            context = package_metadata_context()
+        detected_services: List[DetectedService[DSD]] = []
+        registry = ServiceRegistryTestImpl(service_manager_details, detected_services)
+        service_manager_details.service_detector(
+            fs_root,
+            registry,
+            context,
+        )
+        ctrl = BinaryCtrlAccessorTestProvider(
+            self._plugin_metadata,
+            service_manager_details.service_manager,
+            context,
+        )
+        if detected_services:
+            service_definitions = [
+                ServiceDefinitionImpl(
+                    ds.names[0],
+                    ds.names,
+                    ds.path,
+                    ds.type_of_service,
+                    ds.service_scope,
+                    ds.enable_by_default,
+                    ds.start_by_default,
+                    ds.default_upgrade_rule,
+                    self._plugin_name,
+                    True,
+                    ds.service_context,
+                )
+                for ds in detected_services
+            ]
+            service_manager_details.service_integrator(
+                service_definitions,
+                ctrl,
+                context,
+            )
+        return detected_services, ctrl.registered_metadata()
+
+    def manifest_variables(
+        self,
+        *,
+        resolution_context: Optional[VariableContext] = None,
+        mocked_variables: Optional[Mapping[str, str]] = None,
+    ) -> Mapping[str, str]:
+        valid_manifest_variables = frozenset(
+            {
+                n
+                for n, v in self._feature_set.manifest_variables.items()
+                if v.plugin_metadata.plugin_name == self._plugin_name
+            }
+        )
+        if resolution_context is None:
+            resolution_context = manifest_variable_resolution_context()
+        substitution = self._substitution.copy_for_subst_test(
+            self._feature_set,
+            resolution_context,
+            extra_substitutions=mocked_variables,
+        )
+        return SubstitutionTable(
+            valid_manifest_variables,
+            substitution,
+        )
+
+
+class SubstitutionTable(Mapping[str, str]):
+    def __init__(
+        self, valid_manifest_variables: FrozenSet[str], substitution: Substitution
+    ) -> None:
+        self._valid_manifest_variables = valid_manifest_variables
+        self._resolved: Set[str] = set()
+        self._substitution = substitution
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._valid_manifest_variables
+
+    def __getitem__(self, key: str) -> str:
+        if key not in self._valid_manifest_variables:
+            raise KeyError(key)
+        v = self._substitution.substitute(
+            "{{" + key + "}}", f"test of manifest variable `{key}`"
+        )
+        self._resolved.add(key)
+        return v
+
+    def __len__(self) -> int:
+        return len(self._valid_manifest_variables)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._valid_manifest_variables)
+
+    def keys(self) -> KeysView[str]:
+        return cast("KeysView[str]", self._valid_manifest_variables)
diff --git a/src/debputy/plugin/api/test_api/test_spec.py b/src/debputy/plugin/api/test_api/test_spec.py
new file mode 100644
index 0000000..b05f7ed
--- /dev/null
+++ b/src/debputy/plugin/api/test_api/test_spec.py
@@ -0,0 +1,364 @@
+import dataclasses
+import os
+from abc import ABCMeta
+from typing import (
+    Iterable,
+    Mapping,
+    Callable,
+    Optional,
+    Union,
+    List,
+    Tuple,
+    Set,
+    Sequence,
+    Generic,
+    Type,
+    Self,
+    FrozenSet,
+)
+
+from debian.substvars import Substvars
+
+from debputy import filesystem_scan
+from debputy.plugin.api import (
+    VirtualPath,
+    PackageProcessingContext,
+    DpkgTriggerType,
+    Maintscript,
+)
+from debputy.plugin.api.impl_types import PluginProvidedTrigger
+from debputy.plugin.api.spec import DSD, ServiceUpgradeRule, PathDef
+from debputy.substitution import VariableContext
+
+DEBPUTY_TEST_AGAINST_INSTALLED_PLUGINS = (
+    os.environ.get("DEBPUTY_TEST_PLUGIN_LOCATION", "uninstalled") == "installed"
+)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class ADRExampleIssue:
+    name: str
+    example_index: int
+    inconsistent_paths: Sequence[str]
+
+
+def build_virtual_file_system(
+    paths: Iterable[Union[str, PathDef]],
+    read_write_fs: bool = True,
+) -> VirtualPath:
+    """Create a pure-virtual file system for use with metadata detectors
+
+    This method will generate a virtual file system a list of path names or virtual path definitions.  It will
+    also insert any implicit path required to make the file system connected.  As an example:
+
+        >>> fs_root = build_virtual_file_system(['./usr/share/doc/package/copyright'])
+        >>> # The file we explicitly requested is obviously there
+        >>> fs_root.lookup('./usr/share/doc/package/copyright') is not None
+        True
+        >>> # but so is every directory up to that point
+        >>> all(fs_root.lookup(d).is_dir
+        ...     for d in ['./usr', './usr/share', './usr/share/doc', './usr/share/doc/package']
+        ... )
+        True
+
+    Any string provided will be pased to `virtual_path` using all defaults for other parameters, making `str`
+    arguments a nice easy shorthand if you just want a path to exist, but do not really care about it otherwise
+    (or `virtual_path_def` defaults happens to work for you).
+
+    Here is a very small example of how to create some basic file system objects to get you started:
+
+        >>> from debputy.plugin.api import virtual_path_def
+        >>> path_defs = [
+        ...    './usr/share/doc/',                                       # Create a directory
+        ...    virtual_path_def("./bin/zcat", link_target="/bin/gzip"),  # Create a symlink
+        ...    virtual_path_def("./bin/gzip", mode=0o755),               # Create a file (with a custom mode)
+        ... ]
+        >>> fs_root = build_virtual_file_system(path_defs)
+        >>> fs_root.lookup('./usr/share/doc').is_dir
+        True
+        >>> fs_root.lookup('./bin/zcat').is_symlink
+        True
+        >>> fs_root.lookup('./bin/zcat').readlink() == '/bin/gzip'
+        True
+        >>> fs_root.lookup('./bin/gzip').is_file
+        True
+        >>> fs_root.lookup('./bin/gzip').mode == 0o755
+        True
+
+    :param paths: An iterable any mix of path names (str) and virtual_path_def definitions
+        (results from `virtual_path_def`).
+    :param read_write_fs: Whether the file system is read-write (True) or read-only (False).
+        Note that this is the default permission; the plugin test API may temporarily turn a
+        read-write to read-only temporarily (when running a metadata detector, etc.).
+    :return: The root of the generated file system
+    """
+    return filesystem_scan.build_virtual_fs(paths, read_write_fs=read_write_fs)
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class RegisteredTrigger:
+    dpkg_trigger_type: DpkgTriggerType
+    dpkg_trigger_target: str
+
+    def serialized_format(self) -> str:
+        """The semantic contents of the DEBIAN/triggers file"""
+        return f"{self.dpkg_trigger_type} {self.dpkg_trigger_target}"
+
+    @classmethod
+    def from_plugin_provided_trigger(
+        cls,
+        plugin_provided_trigger: PluginProvidedTrigger,
+    ) -> "Self":
+        return cls(
+            plugin_provided_trigger.dpkg_trigger_type,
+            plugin_provided_trigger.dpkg_trigger_target,
+        )
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class RegisteredMaintscript:
+    """Details about a maintscript registered by a plugin"""
+
+    """Which maintscript is applies to (e.g., "postinst")"""
+    maintscript: Maintscript
+    """Which method was used to trigger the script (e.g., "on_configure")"""
+    registration_method: str
+    """The snippet provided by the plugin as it was provided
+
+    That is, no indentation/conditions/substitutions have been applied to this text
+    """
+    plugin_provided_script: str
+    """Whether substitutions would have been applied in a production run"""
+    requested_substitution: bool
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class DetectedService(Generic[DSD]):
+    path: VirtualPath
+    names: Sequence[str]
+    type_of_service: str
+    service_scope: str
+    enable_by_default: bool
+    start_by_default: bool
+    default_upgrade_rule: ServiceUpgradeRule
+    service_context: Optional[DSD]
+
+
+class RegisteredPackagerProvidedFile(metaclass=ABCMeta):
+    """Record of a registered packager provided file - No instantiation
+
+    New "mandatory" attributes may be added in minor versions, which means instantiation will break tests.
+    Plugin providers should therefore not create instances of this dataclass.  It is visible only to aid
+    test writing by providing type-safety / auto-completion.
+    """
+
+    """The name stem used for generating the file"""
+    stem: str
+    """The recorded directory these file should be installed into"""
+    installed_path: str
+    """The mode that debputy will give these files when installed (unless overridden)"""
+    default_mode: int
+    """The default priority assigned to files unless overriden (if priories are assigned at all)"""
+    default_priority: Optional[int]
+    """The filename format to be used"""
+    filename_format: Optional[str]
+    """The formatting correcting callback"""
+    post_formatting_rewrite: Optional[Callable[[str], str]]
+
+    def compute_dest(
+        self,
+        assigned_name: str,
+        *,
+        assigned_priority: Optional[int] = None,
+        owning_package: Optional[str] = None,
+        path: Optional[VirtualPath] = None,
+    ) -> Tuple[str, str]:
+        """Determine the basename of this packager provided file
+
+        This method is useful for verifying that the `installed_path` and `post_formatting_rewrite` works
+        as intended. As example, some programs do not support "." in their configuration files, so you might
+        have a post_formatting_rewrite à la `lambda x: x.replace(".", "_")`.  Then you can test it by
+        calling `assert rppf.compute_dest("python3.11")[1] == "python3_11"` to verify that if a package like
+        `python3.11` were to use this packager provided file, it would still generate a supported file name.
+
+        For the `assigned_name` parameter, then this is normally derived from the filename. Examples for
+        how to derive it:
+
+          * `debian/my-pkg.stem` => `my-pkg`
+          * `debian/my-pkg.my-custom-name.stem` => `my-custom-name`
+
+        Note that all parts (`my-pkg`, `my-custom-name` and `stem`) can contain periods (".") despite
+        also being a delimiter. Additionally, `my-custom-name` is not restricted to being a valid package
+        name, so it can have any file-system valid character in it.
+
+        For the 0.01% case, where the plugin is using *both* `{name}` *and* `{owning_package}` in the
+        installed_path, then you can separately *also* set the `owning_package` attribute.  However, by
+        default the `assigned_named` is used for both when `owning_package` is not provided.
+
+        :param assigned_name: The name assigned.  Usually this is the name of the package containing the file.
+        :param assigned_priority: Optionally a priority override for the file (if priority is supported). Must be
+          omitted/None if priorities are not supported.
+        :param owning_package: Optionally the name of the owning package.  It is only needed for those exceedingly
+          rare cases where the `installed_path` contains both `{owning_package}` (usually in addition to `{name}`).
+        :param path: Special-case param, only needed for when testing a special `debputy` PPF..
+        :return: A tuple of the directory name and the basename (in that order) that combined makes up that path
+          that debputy would use.
+        """
+        raise NotImplementedError
+
+
+class RegisteredMetadata:
+    __slots__ = ()
+
+    @property
+    def substvars(self) -> Substvars:
+        """Returns the Substvars
+
+        :return: The substvars in their current state.
+        """
+        raise NotImplementedError
+
+    @property
+    def triggers(self) -> List[RegisteredTrigger]:
+        raise NotImplementedError
+
+    def maintscripts(
+        self,
+        *,
+        maintscript: Optional[Maintscript] = None,
+    ) -> List[RegisteredMaintscript]:
+        """Extract the maintscript provided by the given metadata detector
+
+        :param maintscript: If provided, only snippet registered for the given maintscript is returned. Can be
+          used to say "Give me all the 'postinst' snippets by this metadata detector", which can simplify
+          verification in some cases.
+        :return: A list of all matching maintscript registered by the metadata detector. If the detector has
+          not been run, then the list will be empty.  If the metadata detector has been run multiple times,
+          then this is the aggregation of all the runs.
+        """
+        raise NotImplementedError
+
+
+class InitializedPluginUnderTest:
+    def packager_provided_files(self) -> Iterable[RegisteredPackagerProvidedFile]:
+        """An iterable of all packager provided files registered by the plugin under test
+
+        If you want a particular order, please sort the result.
+        """
+        return self.packager_provided_files_by_stem().values()
+
+    def packager_provided_files_by_stem(
+        self,
+    ) -> Mapping[str, RegisteredPackagerProvidedFile]:
+        """All packager provided files registered by the plugin under test grouped by name stem"""
+        raise NotImplementedError
+
+    def run_metadata_detector(
+        self,
+        metadata_detector_id: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+    ) -> RegisteredMetadata:
+        """Run a metadata detector (by its ID) against a given file system
+
+        :param metadata_detector_id: The ID of the metadata detector to run
+        :param fs_root: The file system the metadata detector should see (must be the root of the file system)
+        :param context: The context the metadata detector should see. If not provided, one will be mock will be
+          provided to the extent possible.
+        :return: The metadata registered by the metadata detector
+        """
+        raise NotImplementedError
+
+    def run_package_processor(
+        self,
+        package_processor_id: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+    ) -> None:
+        """Run a package processor (by its ID) against a given file system
+
+        Note: Dependency processors are *not* run first.
+
+        :param package_processor_id: The ID of the package processor to run
+        :param fs_root: The file system the package processor should see (must be the root of the file system)
+        :param context: The context the package processor should see. If not provided, one will be mock will be
+          provided to the extent possible.
+        """
+        raise NotImplementedError
+
+    @property
+    def declared_manifest_variables(self) -> Union[Set[str], FrozenSet[str]]:
+        """Extract the manifest variables declared by the plugin
+
+        :return: All manifest variables declared by the plugin
+        """
+        raise NotImplementedError
+
+    def automatic_discard_rules_examples_with_issues(self) -> Sequence[ADRExampleIssue]:
+        """Validate examples of the automatic discard rules
+
+        For any failed example, use `debputy plugin show automatic-discard-rules <name>` to see
+        the failed example in full.
+
+        :return: If any examples have issues, this will return a non-empty sequence with an
+          entry with each issue.
+        """
+        raise NotImplementedError
+
+    def run_service_detection_and_integrations(
+        self,
+        service_manager: str,
+        fs_root: VirtualPath,
+        context: Optional[PackageProcessingContext] = None,
+        *,
+        service_context_type_hint: Optional[Type[DSD]] = None,
+    ) -> Tuple[List[DetectedService[DSD]], RegisteredMetadata]:
+        """Run the service manager's detection logic and return the results
+
+        This method can be used to validate the service detection and integration logic of a plugin
+        for a given service manager.
+
+        First the service detector is run and if it finds any services, the integrator code is then
+        run on those services with their default values.
+
+        :param service_manager: The name of the service manager as provided during the initialization
+        :param fs_root: The file system the system detector should see (must be the root of
+           the file system)
+        :param context: The context the service detector should see. If not provided, one will be mock
+          will be provided to the extent possible.
+        :param service_context_type_hint: Unused; but can be used as a type hint for `mypy` (etc.)
+          to align the return type.
+        :return: A tuple of the list of all detected services in the provided file system and the
+          metadata generated by the integrator (if any services were detected).
+        """
+        raise NotImplementedError
+
+    def manifest_variables(
+        self,
+        *,
+        resolution_context: Optional[VariableContext] = None,
+        mocked_variables: Optional[Mapping[str, str]] = None,
+    ) -> Mapping[str, str]:
+        """Provide a table of the manifest variables registered by the plugin
+
+        Each key is a manifest variable and the value of said key is the value of the manifest
+        variable.  Lazy loaded variables are resolved when accessed for the first time and may
+        raise exceptions if the preconditions are not correct.
+
+        Note this method can be called multiple times with different parameters to provide
+        different contexts. Lazy loaded variables are resolved at most once per context.
+
+        :param resolution_context: An optional context for lazy loaded manifest variables.
+          Create an instance of it via `manifest_variable_resolution_context`.
+        :param mocked_variables: An optional mapping that provides values for certain manifest
+          variables. This can be used if you want a certain variable to have a certain value
+          for the test to be stable (or because the manifest variable you are mocking is from
+          another plugin, and you do not want to deal with the implementation details of how
+          it is set). Any variable that depends on the mocked variable will use the mocked
+          variable in the given context.
+        :return: A table of the manifest variables provided by the plugin.  Note this table
+          only contains manifest variables registered by the plugin. Attempting to resolve
+          other variables (directly), such as mocked variables or from other plugins, will
+          trigger a `KeyError`.
+        """
+        raise NotImplementedError
diff --git a/src/debputy/plugin/debputy/__init__.py b/src/debputy/plugin/debputy/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/src/debputy/plugin/debputy/__init__.py
diff --git a/src/debputy/plugin/debputy/binary_package_rules.py b/src/debputy/plugin/debputy/binary_package_rules.py
new file mode 100644
index 0000000..04a0fa1
--- /dev/null
+++ b/src/debputy/plugin/debputy/binary_package_rules.py
@@ -0,0 +1,491 @@
+import os
+import textwrap
+from typing import (
+    Any,
+    List,
+    NotRequired,
+    Union,
+    Literal,
+    TypedDict,
+    Annotated,
+    Optional,
+)
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy.maintscript_snippet import DpkgMaintscriptHelperCommand, MaintscriptSnippet
+from debputy.manifest_parser.base_types import (
+    DebputyParsedContent,
+    FileSystemExactMatchRule,
+)
+from debputy.manifest_parser.declarative_parser import (
+    DebputyParseHint,
+    ParserGenerator,
+)
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.path_matcher import MatchRule, MATCH_ANYTHING, ExactFileSystemPath
+from debputy.plugin.api import reference_documentation
+from debputy.plugin.api.impl import DebputyPluginInitializerProvider
+from debputy.plugin.api.impl_types import OPARSER_PACKAGES
+from debputy.transformation_rules import TransformationRule
+
+
+ACCEPTABLE_CLEAN_ON_REMOVAL_FOR_GLOBS_AND_EXACT_MATCHES = frozenset(
+    [
+        "./var/log",
+    ]
+)
+
+
+ACCEPTABLE_CLEAN_ON_REMOVAL_IF_EXACT_MATCH_OR_SUBDIR_OF = frozenset(
+    [
+        "./etc",
+        "./run",
+        "./var/lib",
+        "./var/cache",
+        "./var/backups",
+        "./var/spool",
+        # linux-image uses these paths with some `rm -f`
+        "./usr/lib/modules",
+        "./lib/modules",
+        # udev special case
+        "./lib/udev",
+        "./usr/lib/udev",
+        # pciutils deletes /usr/share/misc/pci.ids.<ext>
+        "./usr/share/misc",
+    ]
+)
+
+
+def register_binary_package_rules(api: DebputyPluginInitializerProvider) -> None:
+    api.plugable_manifest_rule(
+        OPARSER_PACKAGES,
+        "binary-version",
+        BinaryVersionParsedFormat,
+        _parse_binary_version,
+        source_format=str,
+        inline_reference_documentation=reference_documentation(
+            title="Custom binary version (`binary-version`)",
+            description=textwrap.dedent(
+                """\
+                In the *rare* case that you need a binary package to have a custom version, you can use
+                the `binary-version:` key to describe the desired package version.  An example being:
+
+                    packages:
+                        foo:
+                            # The foo package needs a different epoch because we took it over from a different
+                            # source package with higher epoch version
+                            binary-version: '1:{{DEB_VERSION_UPSTREAM_REVISION}}'
+
+                Use this feature sparingly as it is generally not possible to undo as each version must be
+                monotonously higher than the previous one. This feature translates into `-v` option for
+                `dpkg-gencontrol`.
+
+                The value for the `binary-version` key is a string that defines the binary version.  Generally,
+                you will want it to contain one of the versioned related substitution variables such as 
+                `{{DEB_VERSION_UPSTREAM_REVISION}}`.  Otherwise, you will have to remember to bump the version
+                manually with each upload as versions cannot be reused and the package would not support binNMUs
+                either.
+            """
+            ),
+            reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#custom-binary-version-binary-version",
+        ),
+    )
+
+    api.plugable_manifest_rule(
+        OPARSER_PACKAGES,
+        "transformations",
+        ListOfTransformationRulesFormat,
+        _unpack_list,
+        source_format=List[TransformationRule],
+        inline_reference_documentation=reference_documentation(
+            title="Transformations (`packages.{{PACKAGE}}.transformations`)",
+            description=textwrap.dedent(
+                """\
+                You can define a `transformations` under the package definition, which is a list a transformation
+                rules.  An example:
+
+                    packages:
+                        foo:
+                            transformations:
+                              - remove: 'usr/share/doc/{{PACKAGE}}/INSTALL.md'
+                              - move:
+                                    source: bar/*
+                                    target: foo/
+
+
+                Transformations are ordered and are applied in the listed order.  A path can be matched by multiple
+                transformations; how that plays out depends on which transformations are applied and in which order.
+                A quick summary:
+
+                 - Transformations that modify the file system layout affect how path matches in later transformations.
+                   As an example, `move` and `remove` transformations affects what globs and path matches expand to in
+                   later transformation rules.
+
+                 - For other transformations generally the latter transformation overrules the earlier one, when they
+                   overlap or conflict.
+            """
+            ),
+            reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#transformations-packagespackagetransformations",
+        ),
+    )
+
+    api.plugable_manifest_rule(
+        OPARSER_PACKAGES,
+        "conffile-management",
+        ListOfDpkgMaintscriptHelperCommandFormat,
+        _unpack_list,
+        source_format=List[DpkgMaintscriptHelperCommand],
+    )
+
+    api.plugable_manifest_rule(
+        OPARSER_PACKAGES,
+        "clean-after-removal",
+        ListParsedFormat,
+        _parse_clean_after_removal,
+        source_format=List[Any],
+        # FIXME: debputy won't see the attributes for this one :'(
+        inline_reference_documentation=reference_documentation(
+            title="Remove runtime created paths on purge or post removal (`clean-after-removal`)",
+            description=textwrap.dedent(
+                """\
+        For some packages, it is necessary to clean up some run-time created paths. Typical use cases are
+        deleting log files, cache files, or persistent state. This can be done via the `clean-after-removal`.
+        An example being:
+
+            packages:
+                foo:
+                    clean-after-removal:
+                    - /var/log/foo/*.log
+                    - /var/log/foo/*.log.gz
+                    - path: /var/log/foo/
+                      ignore-non-empty-dir: true
+                    - /etc/non-conffile-configuration.conf
+                    - path: /var/cache/foo
+                      recursive: true
+
+        The `clean-after-removal` key accepts a list, where each element is either a mapping, a string or a list
+        of strings. When an element is a mapping, then the following key/value pairs are applicable:
+
+         * `path` or `paths` (required): A path match (`path`) or a list of path matches (`paths`) defining the
+           path(s) that should be removed after clean. The path match(es) can use globs and manifest variables.
+           Every path matched will by default be removed via `rm -f` or `rmdir` depending on whether the path
+           provided ends with a *literal* `/`. Special-rules for matches:
+            - Glob is interpreted by the shell, so shell (`/bin/sh`) rules apply to globs rather than
+              `debputy`'s glob rules.  As an example, `foo/*` will **not** match `foo/.hidden-file`.
+            - `debputy` cannot evaluate whether these paths/globs will match the desired paths (or anything at
+              all). Be sure to test the resulting package.
+            - When a symlink is matched, it is not followed.
+            - Directory handling depends on the `recursive` attribute and whether the pattern ends with a literal
+              "/".
+            - `debputy` has restrictions on the globs being used to prevent rules that could cause massive damage
+              to the system.
+
+         * `recursive` (optional): When `true`, the removal rule will use `rm -fr` rather than `rm -f` or `rmdir`
+            meaning any directory matched will be deleted along with all of its contents.
+
+         * `ignore-non-empty-dir` (optional): When `true`, each path must be or match a directory (and as a
+           consequence each path must with a literal `/`). The affected directories will be deleted only if they
+           are empty. Non-empty directories will be skipped. This option is mutually exclusive with `recursive`.
+
+         * `delete-on` (optional, defaults to `purge`): This attribute defines when the removal happens. It can
+           be set to one of the following values:
+           - `purge`: The removal happens with the package is being purged. This is the default. At a technical
+             level, the removal occurs at `postrm purge`.
+           - `removal`: The removal happens immediately after the package has been removed. At a technical level,
+             the removal occurs at `postrm remove`.
+
+        This feature resembles the concept of `rpm`'s `%ghost` files.
+            """
+            ),
+            reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#remove-runtime-created-paths-on-purge-or-post-removal-clean-after-removal",
+        ),
+    )
+
+    api.plugable_manifest_rule(
+        OPARSER_PACKAGES,
+        "installation-search-dirs",
+        InstallationSearchDirsParsedFormat,
+        _parse_installation_search_dirs,
+        source_format=List[FileSystemExactMatchRule],
+        inline_reference_documentation=reference_documentation(
+            title="Custom installation time search directories (`installation-search-dirs`)",
+            description=textwrap.dedent(
+                """\
+        For source packages that does multiple build, it can be an advantage to provide a custom list of
+        installation-time search directories. This can be done via the `installation-search-dirs` key. A common
+        example is building  the source twice with different optimization and feature settings where the second
+        build is for the `debian-installer` (in the form of a `udeb` package). A sample manifest snippet could
+        look something like:
+
+            installations:
+            - install:
+                # Because of the search order (see below), `foo` installs `debian/tmp/usr/bin/tool`,
+                # while `foo-udeb` installs `debian/tmp-udeb/usr/bin/tool` (assuming both paths are
+                # available). Note the rule can be split into two with the same effect if that aids
+                # readability or understanding.
+                source: usr/bin/tool
+                into:
+                  - foo
+                  - foo-udeb
+            packages:
+                foo-udeb:
+                    installation-search-dirs:
+                    - debian/tmp-udeb
+
+
+        The `installation-search-dirs` key accepts a list, where each element is a path (str) relative from the
+        source root to the directory that should be used as a search directory (absolute paths are still interpreted
+        as relative to the source root).  This list should contain all search directories that should be applicable
+        for this package (except the source root itself, which is always appended after the provided list). If the
+        key is omitted, then `debputy` will provide a default  search order (In the `dh` integration, the default
+        is the directory `debian/tmp`).
+
+        If a non-existing or non-directory path is listed, then it will be skipped (info-level note). If the path
+        exists and is a directory, it will also be checked for "not-installed" paths.
+            """
+            ),
+            reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#custom-installation-time-search-directories-installation-search-dirs",
+        ),
+    )
+
+
+class BinaryVersionParsedFormat(DebputyParsedContent):
+    binary_version: str
+
+
+class ListParsedFormat(DebputyParsedContent):
+    elements: List[Any]
+
+
+class ListOfTransformationRulesFormat(DebputyParsedContent):
+    elements: List[TransformationRule]
+
+
+class ListOfDpkgMaintscriptHelperCommandFormat(DebputyParsedContent):
+    elements: List[DpkgMaintscriptHelperCommand]
+
+
+class InstallationSearchDirsParsedFormat(DebputyParsedContent):
+    installation_search_dirs: List[FileSystemExactMatchRule]
+
+
+def _parse_binary_version(
+    _name: str,
+    parsed_data: BinaryVersionParsedFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> str:
+    return parsed_data["binary_version"]
+
+
+def _parse_installation_search_dirs(
+    _name: str,
+    parsed_data: InstallationSearchDirsParsedFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> List[FileSystemExactMatchRule]:
+    return parsed_data["installation_search_dirs"]
+
+
+def _unpack_list(
+    _name: str,
+    parsed_data: ListParsedFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> List[Any]:
+    return parsed_data["elements"]
+
+
+class CleanAfterRemovalRuleSourceFormat(TypedDict):
+    path: NotRequired[Annotated[str, DebputyParseHint.target_attribute("paths")]]
+    paths: NotRequired[List[str]]
+    delete_on: NotRequired[Literal["purge", "removal"]]
+    recursive: NotRequired[bool]
+    ignore_non_empty_dir: NotRequired[bool]
+
+
+class CleanAfterRemovalRule(DebputyParsedContent):
+    paths: List[str]
+    delete_on: NotRequired[Literal["purge", "removal"]]
+    recursive: NotRequired[bool]
+    ignore_non_empty_dir: NotRequired[bool]
+
+
+# FIXME: Not optimal that we are doing an initialization of ParserGenerator here. But the rule is not depending on any
+#  complex types that is regiersted by plugins, so it will work for now.
+_CLEAN_AFTER_REMOVAL_RULE_PARSER = ParserGenerator().parser_from_typed_dict(
+    CleanAfterRemovalRule,
+    source_content=Union[CleanAfterRemovalRuleSourceFormat, str, List[str]],
+    inline_reference_documentation=reference_documentation(
+        reference_documentation_url=f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#remove-runtime-created-paths-on-purge-or-post-removal-clean-after-removal",
+    ),
+)
+
+
+# Order between clean_on_removal and conffile_management is
+# important. We want the dpkg conffile management rules to happen before the
+# clean clean_on_removal rules.  Since the latter only affects `postrm`
+# and the order is reversed for `postrm` scripts (among other), we need do
+# clean_on_removal first to account for the reversing of order.
+#
+# FIXME: All of this is currently not really possible todo, but it should be.
+# (I think it is the correct order by "mistake" rather than by "design", which is
+# what this note is about)
+def _parse_clean_after_removal(
+    _name: str,
+    parsed_data: ListParsedFormat,
+    attribute_path: AttributePath,
+    parser_context: ParserContextData,
+) -> None:  # TODO: Return and pass to a maintscript helper
+    raw_clean_after_removal = parsed_data["elements"]
+    package_state = parser_context.current_binary_package_state
+
+    for no, raw_transformation in enumerate(raw_clean_after_removal):
+        definition_source = attribute_path[no]
+        clean_after_removal_rules = _CLEAN_AFTER_REMOVAL_RULE_PARSER.parse_input(
+            raw_transformation,
+            definition_source,
+            parser_context=parser_context,
+        )
+        patterns = clean_after_removal_rules["paths"]
+        if patterns:
+            definition_source.path_hint = patterns[0]
+        delete_on = clean_after_removal_rules.get("delete_on") or "purge"
+        recurse = clean_after_removal_rules.get("recursive") or False
+        ignore_non_empty_dir = (
+            clean_after_removal_rules.get("ignore_non_empty_dir") or False
+        )
+        if delete_on == "purge":
+            condition = '[ "$1" = "purge" ]'
+        else:
+            condition = '[ "$1" = "remove" ]'
+
+        if ignore_non_empty_dir:
+            if recurse:
+                raise ManifestParseException(
+                    'The "recursive" and "ignore-non-empty-dir" options are mutually exclusive.'
+                    f" Both were enabled at the same time in at {definition_source.path}"
+                )
+            for pattern in patterns:
+                if not pattern.endswith("/"):
+                    raise ManifestParseException(
+                        'When ignore-non-empty-dir is True, then all patterns must end with a literal "/"'
+                        f' to ensure they only apply to directories. The pattern "{pattern}" at'
+                        f" {definition_source.path} did not."
+                    )
+
+        substitution = parser_context.substitution
+        match_rules = [
+            MatchRule.from_path_or_glob(
+                p, definition_source.path, substitution=substitution
+            )
+            for p in patterns
+        ]
+        content_lines = [
+            f"if {condition}; then\n",
+        ]
+        for idx, match_rule in enumerate(match_rules):
+            original_pattern = patterns[idx]
+            if match_rule is MATCH_ANYTHING:
+                raise ManifestParseException(
+                    f'Using "{original_pattern}" in a clean rule would trash the system.'
+                    f" Please restrict this pattern at {definition_source.path} considerably."
+                )
+            is_subdir_match = False
+            matched_directory: Optional[str]
+            if isinstance(match_rule, ExactFileSystemPath):
+                matched_directory = (
+                    os.path.dirname(match_rule.path)
+                    if match_rule.path not in ("/", ".", "./")
+                    else match_rule.path
+                )
+                is_subdir_match = True
+            else:
+                matched_directory = getattr(match_rule, "directory", None)
+
+            if matched_directory is None:
+                raise ManifestParseException(
+                    f'The pattern "{original_pattern}" defined at {definition_source.path} is not'
+                    f" trivially anchored in a specific directory. Cowardly refusing to use it"
+                    f" in a clean rule as it may trash the system if the pattern is overreaching."
+                    f" Please avoid glob characters in the top level directories."
+                )
+            assert matched_directory.startswith("./") or matched_directory in (
+                ".",
+                "./",
+                "",
+            )
+            acceptable_directory = False
+            would_have_allowed_direct_match = False
+            while matched_directory not in (".", "./", ""):
+                # Our acceptable paths set includes "/var/lib" or "/etc".  We require that the
+                # pattern is either an exact match, in which case it may match directly inside
+                # the acceptable directory OR it is a pattern against a subdirectory of the
+                # acceptable path. As an example:
+                #
+                # /etc/inputrc <-- OK, exact match
+                # /etc/foo/*   <-- OK, subdir match
+                # /etc/*       <-- ERROR, glob directly in the accepted directory.
+                if is_subdir_match and (
+                    matched_directory
+                    in ACCEPTABLE_CLEAN_ON_REMOVAL_IF_EXACT_MATCH_OR_SUBDIR_OF
+                ):
+                    acceptable_directory = True
+                    break
+                if (
+                    matched_directory
+                    in ACCEPTABLE_CLEAN_ON_REMOVAL_FOR_GLOBS_AND_EXACT_MATCHES
+                ):
+                    # Special-case: In some directories (such as /var/log), we allow globs directly.
+                    # Notably, X11's log files are /var/log/Xorg.*.log
+                    acceptable_directory = True
+                    break
+                if (
+                    matched_directory
+                    in ACCEPTABLE_CLEAN_ON_REMOVAL_IF_EXACT_MATCH_OR_SUBDIR_OF
+                ):
+                    would_have_allowed_direct_match = True
+                    break
+                matched_directory = os.path.dirname(matched_directory)
+                is_subdir_match = True
+
+            if would_have_allowed_direct_match and not acceptable_directory:
+                raise ManifestParseException(
+                    f'The pattern "{original_pattern}" defined at {definition_source.path} seems to'
+                    " be overreaching. If it has been a path (and not use a glob), the rule would"
+                    " have been permitted."
+                )
+            elif not acceptable_directory:
+                raise ManifestParseException(
+                    f'The pattern or path "{original_pattern}" defined at {definition_source.path} seems to'
+                    f' be overreaching or not limited to the set of "known acceptable" directories.'
+                )
+
+            try:
+                shell_escaped_pattern = match_rule.shell_escape_pattern()
+            except TypeError:
+                raise ManifestParseException(
+                    f'Sorry, the pattern "{original_pattern}" defined at {definition_source.path}'
+                    f" is unfortunately not supported by `debputy` for clean-after-removal rules."
+                    f" If you can rewrite the rule to something like `/var/log/foo/*.log` or"
+                    f' similar "trivial" patterns. You may have to rewrite the pattern the rule '
+                    f" into multiple patterns to achieve this.  This restriction is to enable "
+                    f' `debputy` to ensure the pattern is correctly executed plus catch "obvious'
+                    f' system trashing" patterns. Apologies for the inconvenience.'
+                )
+
+            if ignore_non_empty_dir:
+                cmd = f'    rmdir --ignore-fail-on-non-empty "${{DPKG_ROOT}}"{shell_escaped_pattern}\n'
+            elif recurse:
+                cmd = f'    rm -fr "${{DPKG_ROOT}}"{shell_escaped_pattern}\n'
+            elif original_pattern.endswith("/"):
+                cmd = f'    rmdir "${{DPKG_ROOT}}"{shell_escaped_pattern}\n'
+            else:
+                cmd = f'    rm -f "${{DPKG_ROOT}}"{shell_escaped_pattern}\n'
+            content_lines.append(cmd)
+        content_lines.append("fi\n")
+
+        snippet = MaintscriptSnippet(definition_source.path, "".join(content_lines))
+        package_state.maintscript_snippets["postrm"].append(snippet)
diff --git a/src/debputy/plugin/debputy/debputy_plugin.py b/src/debputy/plugin/debputy/debputy_plugin.py
new file mode 100644
index 0000000..7a8f6da
--- /dev/null
+++ b/src/debputy/plugin/debputy/debputy_plugin.py
@@ -0,0 +1,400 @@
+import textwrap
+
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    packager_provided_file_reference_documentation,
+)
+from debputy.plugin.debputy.metadata_detectors import (
+    detect_systemd_tmpfiles,
+    detect_kernel_modules,
+    detect_icons,
+    detect_gsettings_dependencies,
+    detect_xfonts,
+    detect_initramfs_hooks,
+    detect_systemd_sysusers,
+    detect_pycompile_files,
+    translate_capabilities,
+    pam_auth_update,
+    auto_depends_arch_any_solink,
+)
+from debputy.plugin.debputy.paths import (
+    SYSTEMD_TMPFILES_DIR,
+    INITRAMFS_HOOK_DIR,
+    GSETTINGS_SCHEMA_DIR,
+    SYSTEMD_SYSUSERS_DIR,
+)
+from debputy.plugin.debputy.private_api import initialize_via_private_api
+
+
+def initialize_debputy_features(api: DebputyPluginInitializer) -> None:
+    initialize_via_private_api(api)
+    declare_manifest_variables(api)
+    register_packager_provided_files(api)
+    register_package_metadata_detectors(api)
+
+
+def declare_manifest_variables(api: DebputyPluginInitializer) -> None:
+    api.manifest_variable(
+        "path:BASH_COMPLETION_DIR",
+        "/usr/share/bash-completion/completions",
+        variable_reference_documentation="Directory to install bash completions into",
+    )
+    api.manifest_variable(
+        "path:GNU_INFO_DIR",
+        "/usr/share/info",
+        variable_reference_documentation="Directory to install GNU INFO files into",
+    )
+
+    api.manifest_variable(
+        "token:NL",
+        "\n",
+        variable_reference_documentation="Literal newline (linefeed) character",
+    )
+    api.manifest_variable(
+        "token:NEWLINE",
+        "\n",
+        variable_reference_documentation="Literal newline (linefeed) character",
+    )
+    api.manifest_variable(
+        "token:TAB",
+        "\t",
+        variable_reference_documentation="Literal tab character",
+    )
+    api.manifest_variable(
+        "token:OPEN_CURLY_BRACE",
+        "{",
+        variable_reference_documentation='Literal "{" character',
+    )
+    api.manifest_variable(
+        "token:CLOSE_CURLY_BRACE",
+        "}",
+        variable_reference_documentation='Literal "}" character',
+    )
+    api.manifest_variable(
+        "token:DOUBLE_OPEN_CURLY_BRACE",
+        "{{",
+        variable_reference_documentation='Literal "{{" character - useful to avoid triggering a substitution',
+    )
+    api.manifest_variable(
+        "token:DOUBLE_CLOSE_CURLY_BRACE",
+        "}}",
+        variable_reference_documentation='Literal "}}" string - useful to avoid triggering a substitution',
+    )
+
+
+def register_package_metadata_detectors(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector("systemd-tmpfiles", detect_systemd_tmpfiles)
+    api.metadata_or_maintscript_detector("systemd-sysusers", detect_systemd_sysusers)
+    api.metadata_or_maintscript_detector("kernel-modules", detect_kernel_modules)
+    api.metadata_or_maintscript_detector("icon-cache", detect_icons)
+    api.metadata_or_maintscript_detector(
+        "gsettings-dependencies",
+        detect_gsettings_dependencies,
+    )
+    api.metadata_or_maintscript_detector("xfonts", detect_xfonts)
+    api.metadata_or_maintscript_detector("initramfs-hooks", detect_initramfs_hooks)
+    api.metadata_or_maintscript_detector("pycompile-files", detect_pycompile_files)
+    api.metadata_or_maintscript_detector(
+        "translate-capabilities",
+        translate_capabilities,
+    )
+    api.metadata_or_maintscript_detector("pam-auth-update", pam_auth_update)
+    api.metadata_or_maintscript_detector(
+        "auto-depends-arch-any-solink",
+        auto_depends_arch_any_solink,
+    )
+
+
+def register_packager_provided_files(api: DebputyPluginInitializer) -> None:
+    api.packager_provided_file(
+        "tmpfiles",
+        f"{SYSTEMD_TMPFILES_DIR}/{{name}}.conf",
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=["man:tmpfiles.d(5)"]
+        ),
+    )
+    api.packager_provided_file(
+        "sysusers",
+        f"{SYSTEMD_SYSUSERS_DIR}/{{name}}.conf",
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=["man:sysusers.d(5)"]
+        ),
+    )
+    api.packager_provided_file(
+        "bash-completion", "/usr/share/bash-completion/completions/{name}"
+    )
+    api.packager_provided_file(
+        "bug-script",
+        "./usr/share/bug/{name}/script",
+        default_mode=0o0755,
+        allow_name_segment=False,
+    )
+    api.packager_provided_file(
+        "bug-control",
+        "/usr/share/bug/{name}/control",
+        allow_name_segment=False,
+    )
+
+    api.packager_provided_file(
+        "bug-presubj",
+        "/usr/share/bug/{name}/presubj",
+        allow_name_segment=False,
+    )
+
+    api.packager_provided_file("pam", "/usr/lib/pam.d/{name}")
+    api.packager_provided_file(
+        "ppp.ip-up",
+        "/etc/ppp/ip-up.d/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "ppp.ip-down",
+        "/etc/ppp/ip-down.d/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "lintian-overrides",
+        "/usr/share/lintian/overrides/{name}",
+        allow_name_segment=False,
+    )
+    api.packager_provided_file("logrotate", "/etc/logrotate.d/{name}")
+    api.packager_provided_file(
+        "logcheck.cracking",
+        "/etc/logcheck/cracking.d/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+    api.packager_provided_file(
+        "logcheck.violations",
+        "/etc/logcheck/violations.d/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+    api.packager_provided_file(
+        "logcheck.violations.ignore",
+        "/etc/logcheck/violations.ignore.d/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+    api.packager_provided_file(
+        "logcheck.ignore.workstation",
+        "/etc/logcheck/ignore.d.workstation/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+    api.packager_provided_file(
+        "logcheck.ignore.server",
+        "/etc/logcheck/ignore.d.server/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+    api.packager_provided_file(
+        "logcheck.ignore.paranoid",
+        "/etc/logcheck/ignore.d.paranoid/{name}",
+        post_formatting_rewrite=_replace_dot_with_underscore,
+    )
+
+    api.packager_provided_file("mime", "/usr/lib/mime/packages/{name}")
+    api.packager_provided_file("sharedmimeinfo", "/usr/share/mime/packages/{name}.xml")
+
+    api.packager_provided_file(
+        "if-pre-up",
+        "/etc/network/if-pre-up.d/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "if-up",
+        "/etc/network/if-up.d/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "if-down",
+        "/etc/network/if-down.d/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "if-post-down",
+        "/etc/network/if-post-down.d/{name}",
+        default_mode=0o0755,
+    )
+
+    api.packager_provided_file(
+        "cron.hourly",
+        "/etc/cron.hourly/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "cron.daily",
+        "/etc/cron.daily/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "cron.weekly",
+        "/etc/cron.weekly/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "cron.monthly",
+        "./etc/cron.monthly/{name}",
+        default_mode=0o0755,
+    )
+    api.packager_provided_file(
+        "cron.yearly",
+        "/etc/cron.yearly/{name}",
+        default_mode=0o0755,
+    )
+    # cron.d uses 0644 unlike the others
+    api.packager_provided_file(
+        "cron.d",
+        "/etc/cron.d/{name}",
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=["man:crontab(5)"]
+        ),
+    )
+
+    api.packager_provided_file(
+        "initramfs-hook", f"{INITRAMFS_HOOK_DIR}/{{name}}", default_mode=0o0755
+    )
+
+    api.packager_provided_file("modprobe", "/etc/modprobe.d/{name}.conf")
+
+    api.packager_provided_file(
+        "init",
+        "/etc/init.d/{name}",
+        default_mode=0o755,
+    )
+    api.packager_provided_file("default", "/etc/default/{name}")
+
+    for stem in [
+        "mount",
+        "path",
+        "service",
+        "socket",
+        "target",
+        "timer",
+    ]:
+        api.packager_provided_file(
+            stem,
+            f"/usr/lib/systemd/system/{{name}}.{stem}",
+            reference_documentation=packager_provided_file_reference_documentation(
+                format_documentation_uris=[f"man:systemd.{stem}(5)"]
+            ),
+        )
+
+    for stem in [
+        "path",
+        "service",
+        "socket",
+        "target",
+        "timer",
+    ]:
+        api.packager_provided_file(
+            f"@{stem}", f"/usr/lib/systemd/system/{{name}}@.{stem}"
+        )
+
+    # api.packager_provided_file(
+    #     "udev",
+    #     "./lib/udev/rules.d/{priority:02}-{name}.rules",
+    #     default_priority=60,
+    # )
+
+    api.packager_provided_file(
+        "gsettings-override",
+        f"{GSETTINGS_SCHEMA_DIR}/{{priority:02}}_{{name}}.gschema.override",
+        default_priority=10,
+    )
+
+    # Special-cases that will probably not be a good example for other plugins
+    api.packager_provided_file(
+        "changelog",
+        # The "changelog.Debian" gets renamed to "changelog" for native packages elsewhere.
+        # Also, the changelog trimming is also done elsewhere.
+        "/usr/share/doc/{name}/changelog.Debian",
+        allow_name_segment=False,
+        packageless_is_fallback_for_all_packages=True,
+        reference_documentation=packager_provided_file_reference_documentation(
+            description=textwrap.dedent(
+                """\
+                This file is the changelog of the package and is mandatory.
+
+                The changelog contains the version of the source package and is mandatory for all
+                packages.
+
+                Use `dch --create` to create the changelog.
+
+                In theory, the binary package can have a different changelog than the source
+                package (by having `debian/binary-package.changelog`). However, it is generally
+                not useful and leads to double administration. It has not been used in practice.
+            """
+            ),
+            format_documentation_uris=[
+                "man:deb-changelog(5)",
+                "https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog",
+                "man:dch(1)",
+            ],
+        ),
+    )
+    api.packager_provided_file(
+        "copyright",
+        "/usr/share/doc/{name}/copyright",
+        allow_name_segment=False,
+        packageless_is_fallback_for_all_packages=True,
+        reference_documentation=packager_provided_file_reference_documentation(
+            description=textwrap.dedent(
+                """\
+                This file documents the license and copyright information of the binary package.
+                Packages aimed at the Debian archive (and must derivatives thereof) must have this file.
+
+                For packages not aimed at Debian, the file can still be useful to convey the license
+                terms of the package (which is often a requirement in many licenses). However, it is
+                not a strict *technical* requirement. Whether it is a legal requirement depends on
+                license.
+
+                Often, the same file can be used for all packages. In the extremely rare case where
+                one binary package has a "vastly different" license than the other packages, you can
+                provide a package specific version for that package.
+            """
+            ),
+            format_documentation_uris=[
+                "https://www.debian.org/doc/debian-policy/ch-source.html#copyright-debian-copyright",
+                "https://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightfile",
+                "https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/",
+            ],
+        ),
+    )
+    api.packager_provided_file(
+        "NEWS",
+        "/usr/share/doc/{name}/NEWS.Debian",
+        allow_name_segment=False,
+        packageless_is_fallback_for_all_packages=True,
+        reference_documentation=packager_provided_file_reference_documentation(
+            description=textwrap.dedent(
+                """\
+            Important news that should be shown to the user/admin when upgrading. If a system has
+            apt-listchanges installed, then contents of this file will be shown prior to upgrading
+            the package.
+
+            Uses a similar format to that of debian/changelog (create with `dch --news --create`).
+            """
+            ),
+            format_documentation_uris=[
+                "https://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.en.html#supplementing-changelogs-with-news-debian-files",
+                "man:dch(1)",
+            ],
+        ),
+    )
+    api.packager_provided_file(
+        "README.Debian",
+        "/usr/share/doc/{name}/README.Debian",
+        allow_name_segment=False,
+    )
+    api.packager_provided_file(
+        "TODO",
+        "/usr/share/doc/{name}/TODO.Debian",
+        allow_name_segment=False,
+    )
+    # From dh-python / dh_python3
+    # api.packager_provided_file(
+    #     "bcep",
+    #     "/usr/share/python3/bcep/{name}",
+    #     allow_name_segment=False,
+    # )
+
+
+def _replace_dot_with_underscore(x: str) -> str:
+    return x.replace(".", "_")
diff --git a/src/debputy/plugin/debputy/discard_rules.py b/src/debputy/plugin/debputy/discard_rules.py
new file mode 100644
index 0000000..689761e
--- /dev/null
+++ b/src/debputy/plugin/debputy/discard_rules.py
@@ -0,0 +1,97 @@
+import re
+
+from debputy.plugin.api import VirtualPath
+
+_VCS_PATHS = {
+    ".arch-inventory",
+    ".arch-ids",
+    ".be",
+    ".bzrbackup",
+    ".bzrignore",
+    ".bzrtags",
+    ".cvsignore",
+    ".hg",
+    ".hgignore",
+    ".hgtags",
+    ".hgsigs",
+    ".git",
+    ".gitignore",
+    ".gitattributes",
+    ".gitmodules",
+    ".gitreview",
+    ".mailmap",
+    ".mtn-ignore",
+    ".svn",
+    "{arch}",
+    "CVS",
+    "RCS",
+    "_MTN",
+    "_darcs",
+}
+
+_BACKUP_FILES_RE = re.compile(
+    "|".join(
+        [
+            # Common backup files
+            r".*~",
+            r".*[.](?:bak|orig|rej)",
+            # Editor backup/swap files
+            r"[.]#.*",
+            r"[.].*[.]sw.",
+            # Other known stuff
+            r"[.]shelf",
+            r",,.*",  # "baz-style junk" (according to dpkg (Dpkg::Source::Package)
+            r"DEADJOE",  # Joe's one line of immortality that just gets cargo cult'ed around ... just in case.
+        ]
+    )
+)
+
+_DOXYGEN_DIR_TEST_FILES = ["doxygen.css", "doxygen.svg", "index.html"]
+
+
+def _debputy_discard_pyc_files(path: "VirtualPath") -> bool:
+    if path.name == "__pycache__" and path.is_dir:
+        return True
+    return path.name.endswith((".pyc", ".pyo")) and path.is_file
+
+
+def _debputy_prune_la_files(path: "VirtualPath") -> bool:
+    return (
+        path.name.endswith(".la")
+        and path.is_file
+        and path.absolute.startswith("/usr/lib")
+    )
+
+
+def _debputy_prune_backup_files(path: VirtualPath) -> bool:
+    return bool(_BACKUP_FILES_RE.match(path.name))
+
+
+def _debputy_prune_vcs_paths(path: VirtualPath) -> bool:
+    return path.name in _VCS_PATHS
+
+
+def _debputy_prune_info_dir_file(path: VirtualPath) -> bool:
+    return path.absolute == "/usr/share/info/dir"
+
+
+def _debputy_prune_binary_debian_dir(path: VirtualPath) -> bool:
+    return path.absolute == "/DEBIAN"
+
+
+def _debputy_prune_doxygen_cruft(path: VirtualPath) -> bool:
+    if not path.name.endswith((".md5", ".map")) or not path.is_file:
+        return False
+    parent_dir = path.parent_dir
+    while parent_dir:
+        is_doxygen_dir = True
+        for name in _DOXYGEN_DIR_TEST_FILES:
+            test_file = parent_dir.get(name)
+            if test_file is None or not test_file.is_file:
+                is_doxygen_dir = False
+                break
+
+        if is_doxygen_dir:
+            return True
+        parent_dir = parent_dir.parent_dir
+    return False
diff --git a/src/debputy/plugin/debputy/manifest_root_rules.py b/src/debputy/plugin/debputy/manifest_root_rules.py
new file mode 100644
index 0000000..cc2b1d4
--- /dev/null
+++ b/src/debputy/plugin/debputy/manifest_root_rules.py
@@ -0,0 +1,254 @@
+import textwrap
+from typing import List, Any, Dict, Tuple, TYPE_CHECKING, cast
+
+from debputy._manifest_constants import (
+    ManifestVersion,
+    MK_MANIFEST_VERSION,
+    MK_INSTALLATIONS,
+    SUPPORTED_MANIFEST_VERSIONS,
+    MK_MANIFEST_DEFINITIONS,
+    MK_PACKAGES,
+    MK_MANIFEST_VARIABLES,
+)
+from debputy.exceptions import DebputySubstitutionError
+from debputy.installations import InstallRule
+from debputy.manifest_parser.base_types import DebputyParsedContent
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.plugin.api import reference_documentation
+from debputy.plugin.api.impl import DebputyPluginInitializerProvider
+from debputy.plugin.api.impl_types import (
+    OPARSER_MANIFEST_ROOT,
+    OPARSER_MANIFEST_DEFINITIONS,
+    SUPPORTED_DISPATCHABLE_OBJECT_PARSERS,
+    OPARSER_PACKAGES,
+)
+from debputy.substitution import VariableNameState, SUBST_VAR_RE
+
+if TYPE_CHECKING:
+    from debputy.highlevel_manifest_parser import YAMLManifestParser
+
+
+def register_manifest_root_rules(api: DebputyPluginInitializerProvider) -> None:
+    # Registration order matters. Notably, definitions must come before anything that can
+    # use definitions (variables), which is why it is second only to the manifest version.
+    api.plugable_manifest_rule(
+        OPARSER_MANIFEST_ROOT,
+        MK_MANIFEST_VERSION,
+        ManifestVersionFormat,
+        _handle_version,
+        source_format=ManifestVersion,
+        inline_reference_documentation=reference_documentation(
+            title="Manifest version",
+            description=textwrap.dedent(
+                """\
+                All `debputy` manifests must include a `debputy` manifest version, which will enable the
+                format to change over time.  For now, there is only one version (`"0.1"`) and you have
+                to include the line:
+
+                    manifest-version: "0.1"
+
+                On its own, the manifest containing only `manifest-version: "..."` will not do anything.  So if you
+                end up only having the `manifest-version` key in the manifest, you can just remove the manifest and
+                rely entirely on the built-in rules.
+            """
+            ),
+        ),
+    )
+    api.plugable_object_parser(
+        OPARSER_MANIFEST_ROOT,
+        MK_MANIFEST_DEFINITIONS,
+        object_parser_key=OPARSER_MANIFEST_DEFINITIONS,
+        on_end_parse_step=lambda _a, _b, _c, mp: mp._ensure_package_states_is_initialized(),
+    )
+    api.plugable_manifest_rule(
+        OPARSER_MANIFEST_DEFINITIONS,
+        MK_MANIFEST_VARIABLES,
+        ManifestVariablesParsedFormat,
+        _handle_manifest_variables,
+        source_format=Dict[str, str],
+        inline_reference_documentation=reference_documentation(
+            title="Manifest Variables (`variables`)",
+            description=textwrap.dedent(
+                """\
+                It is possible to provide custom manifest variables via the `variables` attribute.  An example:
+
+                    manifest-version: '0.1'
+                    definitions:
+                      variables:
+                        LIBPATH: "/usr/lib/{{DEB_HOST_MULTIARCH}}"
+                        SONAME: "1"
+                    installations:
+                      - install:
+                           source: build/libfoo.so.{{SONAME}}*
+                           # The quotes here is for the YAML parser's sake.
+                           dest-dir: "{{LIBPATH}}"
+                           into: libfoo{{SONAME}}
+
+                The value of the `variables` key must be a mapping, where each key is a new variable name and
+                the related value is the value of said key. The keys must be valid variable name and not shadow
+                existing variables (that is, variables such as `PACKAGE` and `DEB_HOST_MULTIARCH` *cannot* be
+                redefined). The value for each variable *can* refer to *existing* variables as seen in the
+                example above.
+
+                As usual, `debputy` will insist that all declared variables must be used.
+
+                Limitations:
+                 * When declaring variables that depends on another variable declared in the manifest, the
+                   order is important. The variables are resolved from top to bottom.
+                 * When a manifest variable depends on another manifest variable, the existing variable is
+                   currently always resolved in source context. As a consequence, some variables such as
+                   `{{PACKAGE}}` cannot be used when defining a variable. This restriction may be
+                   lifted in the future.
+            """
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        OPARSER_MANIFEST_ROOT,
+        MK_INSTALLATIONS,
+        ListOfInstallRulesFormat,
+        _handle_installation_rules,
+        source_format=List[InstallRule],
+        inline_reference_documentation=reference_documentation(
+            title="Installations",
+            description=textwrap.dedent(
+                """\
+        For source packages building a single binary, the `dh_auto_install` from debhelper will default to
+        providing everything from upstream's install in the binary package.  The `debputy` tool matches this
+        behaviour and accordingly, the `installations` feature is only relevant in this case when you need to
+        manually specify something upstream's install did not cover.
+
+        For sources, that build multiple binaries, where `dh_auto_install` does not detect anything to install,
+        or when `dh_auto_install --destdir debian/tmp` is used, the `installations` section of the manifest is
+        used to declare what goes into which binary package. An example:
+
+            installations:
+              - install:
+                    sources: "usr/bin/foo"
+                    into: foo
+              - install:
+                    sources: "usr/*"
+                    into: foo-extra
+
+        All installation rules are processed in order (top to bottom).  Once a path has been matched, it can
+        no longer be matched by future rules.  In the above example, then `usr/bin/foo` would be in the `foo`
+        package while everything in `usr` *except* `usr/bin/foo` would be in `foo-extra`.  If these had been
+        ordered in reverse, the `usr/bin/foo` rule would not have matched anything and caused `debputy`
+        to reject the input as an error on that basis.  This behaviour is similar to "DEP-5" copyright files,
+        except the order is reversed ("DEP-5" uses "last match wins", where here we are doing "first match wins")
+
+        In the rare case that some path need to be installed into two packages at the same time, then this is
+        generally done by changing `into` into a list of packages.
+
+        All installations are currently run in *source* package context.  This implies that:
+
+          1) No package specific substitutions are available. Notably `{{PACKAGE}}` cannot be resolved.
+          2) All conditions are evaluated in source context.  For 99.9% of users, this makes no difference,
+             but there is a cross-build feature that changes the "per package" architecture which is affected.
+
+        This is a limitation that should be fixed in `debputy`.
+
+        **Attention debhelper users**: Note the difference between `dh_install` (etc.) vs. `debputy` on
+        overlapping matches for installation.
+            """
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        OPARSER_MANIFEST_ROOT,
+        MK_PACKAGES,
+        DictFormat,
+        _handle_opaque_dict,
+        source_format=Dict[str, Any],
+        inline_reference_documentation=SUPPORTED_DISPATCHABLE_OBJECT_PARSERS[
+            OPARSER_PACKAGES
+        ],
+    )
+
+
+class ManifestVersionFormat(DebputyParsedContent):
+    manifest_version: ManifestVersion
+
+
+class ListOfInstallRulesFormat(DebputyParsedContent):
+    elements: List[InstallRule]
+
+
+class DictFormat(DebputyParsedContent):
+    mapping: Dict[str, Any]
+
+
+class ManifestVariablesParsedFormat(DebputyParsedContent):
+    variables: Dict[str, str]
+
+
+def _handle_version(
+    _name: str,
+    parsed_data: ManifestVersionFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> str:
+    manifest_version = parsed_data["manifest_version"]
+    if manifest_version not in SUPPORTED_MANIFEST_VERSIONS:
+        raise ManifestParseException(
+            "Unsupported manifest-version.  This implementation supports the following versions:"
+            f' {", ".join(repr(v) for v in SUPPORTED_MANIFEST_VERSIONS)}"'
+        )
+    return manifest_version
+
+
+def _handle_manifest_variables(
+    _name: str,
+    parsed_data: ManifestVariablesParsedFormat,
+    variables_path: AttributePath,
+    parser_context: ParserContextData,
+) -> None:
+    variables = parsed_data.get("variables", {})
+    resolved_vars: Dict[str, Tuple[str, AttributePath]] = {}
+    manifest_parser: "YAMLManifestParser" = cast("YAMLManifestParser", parser_context)
+    substitution = manifest_parser.substitution
+    for key, value_raw in variables.items():
+        key_path = variables_path[key]
+        if not SUBST_VAR_RE.match("{{" + key + "}}"):
+            raise ManifestParseException(
+                f"The variable at {key_path.path} has an invalid name and therefore cannot"
+                " be used."
+            )
+        if substitution.variable_state(key) != VariableNameState.UNDEFINED:
+            raise ManifestParseException(
+                f'The variable "{key}" is already reserved/defined. Error triggered by'
+                f" {key_path.path}."
+            )
+        try:
+            value = substitution.substitute(value_raw, key_path.path)
+        except DebputySubstitutionError:
+            if not resolved_vars:
+                raise
+            # See if flushing the variables work
+            substitution = manifest_parser.add_extra_substitution_variables(
+                **resolved_vars
+            )
+            resolved_vars = {}
+            value = substitution.substitute(value_raw, key_path.path)
+        resolved_vars[key] = (value, key_path)
+        substitution = manifest_parser.add_extra_substitution_variables(**resolved_vars)
+
+
+def _handle_installation_rules(
+    _name: str,
+    parsed_data: ListOfInstallRulesFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> List[Any]:
+    return parsed_data["elements"]
+
+
+def _handle_opaque_dict(
+    _name: str,
+    parsed_data: DictFormat,
+    _attribute_path: AttributePath,
+    _parser_context: ParserContextData,
+) -> Dict[str, Any]:
+    return parsed_data["mapping"]
diff --git a/src/debputy/plugin/debputy/metadata_detectors.py b/src/debputy/plugin/debputy/metadata_detectors.py
new file mode 100644
index 0000000..4338087
--- /dev/null
+++ b/src/debputy/plugin/debputy/metadata_detectors.py
@@ -0,0 +1,550 @@
+import itertools
+import os
+import re
+import textwrap
+from typing import Iterable, Iterator
+
+from debputy.plugin.api import (
+    VirtualPath,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+from debputy.plugin.debputy.paths import (
+    INITRAMFS_HOOK_DIR,
+    SYSTEMD_TMPFILES_DIR,
+    GSETTINGS_SCHEMA_DIR,
+    SYSTEMD_SYSUSERS_DIR,
+)
+from debputy.plugin.debputy.types import DebputyCapability
+from debputy.util import assume_not_none, _warn
+
+DPKG_ROOT = '"${DPKG_ROOT}"'
+DPKG_ROOT_UNQUOTED = "${DPKG_ROOT}"
+
+KERNEL_MODULE_EXTENSIONS = tuple(
+    f"{ext}{comp_ext}"
+    for ext, comp_ext in itertools.product(
+        (".o", ".ko"),
+        ("", ".gz", ".bz2", ".xz"),
+    )
+)
+
+
+def detect_initramfs_hooks(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    hook_dir = fs_root.lookup(INITRAMFS_HOOK_DIR)
+    if not hook_dir:
+        return
+    for _ in hook_dir.iterdir:
+        # Only add the trigger if the directory is non-empty. It is unlikely to matter a lot,
+        # but we do this to match debhelper.
+        break
+    else:
+        return
+
+    ctrl.dpkg_trigger("activate-noawait", "update-initramfs")
+
+
+def _all_tmpfiles_conf(fs_root: VirtualPath) -> Iterable[VirtualPath]:
+    seen_tmpfiles = set()
+    tmpfiles_dirs = [
+        SYSTEMD_TMPFILES_DIR,
+        "./etc/tmpfiles.d",
+    ]
+    for tmpfiles_dir_path in tmpfiles_dirs:
+        tmpfiles_dir = fs_root.lookup(tmpfiles_dir_path)
+        if not tmpfiles_dir:
+            continue
+        for path in tmpfiles_dir.iterdir:
+            if (
+                not path.is_file
+                or not path.name.endswith(".conf")
+                or path.name in seen_tmpfiles
+            ):
+                continue
+            seen_tmpfiles.add(path.name)
+            yield path
+
+
+def detect_systemd_tmpfiles(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    tmpfiles_confs = [
+        x.name for x in sorted(_all_tmpfiles_conf(fs_root), key=lambda x: x.name)
+    ]
+    if not tmpfiles_confs:
+        return
+
+    tmpfiles_escaped = ctrl.maintscript.escape_shell_words(*tmpfiles_confs)
+
+    snippet = textwrap.dedent(
+        f"""\
+            if [ -x "$(command -v systemd-tmpfiles)" ]; then
+                systemd-tmpfiles ${{DPKG_ROOT:+--root="$DPKG_ROOT"}} --create {tmpfiles_escaped} || true
+            fi
+    """
+    )
+
+    ctrl.maintscript.on_configure(snippet)
+
+
+def _all_sysusers_conf(fs_root: VirtualPath) -> Iterable[VirtualPath]:
+    sysusers_dir = fs_root.lookup(SYSTEMD_SYSUSERS_DIR)
+    if not sysusers_dir:
+        return
+    for child in sysusers_dir.iterdir:
+        if not child.name.endswith(".conf"):
+            continue
+        yield child
+
+
+def detect_systemd_sysusers(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    sysusers_confs = [p.name for p in _all_sysusers_conf(fs_root)]
+    if not sysusers_confs:
+        return
+
+    sysusers_escaped = ctrl.maintscript.escape_shell_words(*sysusers_confs)
+
+    snippet = textwrap.dedent(
+        f"""\
+            systemd-sysusers ${{DPKG_ROOT:+--root="$DPKG_ROOT"}} --create {sysusers_escaped} || true
+    """
+    )
+
+    ctrl.substvars.add_dependency(
+        "misc:Depends", "systemd | systemd-standalone-sysusers | systemd-sysusers"
+    )
+    ctrl.maintscript.on_configure(snippet)
+
+
+def detect_icons(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    icons_root_dir = fs_root.lookup("./usr/share/icons")
+    if not icons_root_dir:
+        return
+    icon_dirs = []
+    for subdir in icons_root_dir.iterdir:
+        if subdir.name in ("gnome", "hicolor"):
+            # dh_icons skips this for some reason.
+            continue
+        for p in subdir.all_paths():
+            if p.is_file and p.name.endswith((".png", ".svg", ".xpm", ".icon")):
+                icon_dirs.append(subdir.absolute)
+                break
+    if not icon_dirs:
+        return
+
+    icon_dir_list_escaped = ctrl.maintscript.escape_shell_words(*icon_dirs)
+
+    postinst_snippet = textwrap.dedent(
+        f"""\
+        if command -v update-icon-caches >/dev/null; then
+            update-icon-caches {icon_dir_list_escaped}
+        fi
+    """
+    )
+
+    postrm_snippet = textwrap.dedent(
+        f"""\
+        if command -v update-icon-caches >/dev/null; then
+            update-icon-caches {icon_dir_list_escaped}
+        fi
+    """
+    )
+
+    ctrl.maintscript.on_configure(postinst_snippet)
+    ctrl.maintscript.unconditionally_in_script("postrm", postrm_snippet)
+
+
+def detect_gsettings_dependencies(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    gsettings_schema_dir = fs_root.lookup(GSETTINGS_SCHEMA_DIR)
+    if not gsettings_schema_dir:
+        return
+
+    for path in gsettings_schema_dir.all_paths():
+        if path.is_file and path.name.endswith((".xml", ".override")):
+            ctrl.substvars.add_dependency(
+                "misc:Depends", "dconf-gsettings-backend | gsettings-backend"
+            )
+            break
+
+
+def detect_kernel_modules(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _unused: PackageProcessingContext,
+) -> None:
+    for prefix in [".", "./usr"]:
+        module_root_dir = fs_root.lookup(f"{prefix}/lib/modules")
+
+        if not module_root_dir:
+            continue
+
+        module_version_dirs = []
+
+        for module_version_dir in module_root_dir.iterdir:
+            if not module_version_dir.is_dir:
+                continue
+
+            for fs_path in module_version_dir.all_paths():
+                if fs_path.name.endswith(KERNEL_MODULE_EXTENSIONS):
+                    module_version_dirs.append(module_version_dir.name)
+                    break
+
+        for module_version in module_version_dirs:
+            module_version_escaped = ctrl.maintscript.escape_shell_words(module_version)
+            postinst_snippet = textwrap.dedent(
+                f"""\
+                    if [ -e /boot/System.map-{module_version_escaped} ]; then
+                        depmod -a -F /boot/System.map-{module_version_escaped} {module_version_escaped} || true
+                    fi
+            """
+            )
+
+            postrm_snippet = textwrap.dedent(
+                f"""\
+                if [ -e /boot/System.map-{module_version_escaped} ]; then
+                    depmod -a -F /boot/System.map-{module_version_escaped} {module_version_escaped} || true
+                fi
+            """
+            )
+
+            ctrl.maintscript.on_configure(postinst_snippet)
+            # TODO: This should probably be on removal. However, this is what debhelper did and we should
+            # do the same until we are sure (not that it matters a lot).
+            ctrl.maintscript.unconditionally_in_script("postrm", postrm_snippet)
+
+
+def detect_xfonts(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    xfonts_root_dir = fs_root.lookup("./usr/share/fonts/X11/")
+    if not xfonts_root_dir:
+        return
+
+    cmds = []
+    cmds_postinst = []
+    cmds_postrm = []
+    escape_shell_words = ctrl.maintscript.escape_shell_words
+    package_name = context.binary_package.name
+
+    for xfonts_dir in xfonts_root_dir.iterdir:
+        xfonts_dirname = xfonts_dir.name
+        if not xfonts_dir.is_dir or xfonts_dirname.startswith("."):
+            continue
+        if fs_root.lookup(f"./etc/X11/xfonts/{xfonts_dirname}/{package_name}.scale"):
+            cmds.append(escape_shell_words("update-fonts-scale", xfonts_dirname))
+        cmds.append(
+            escape_shell_words("update-fonts-dir", "--x11r7-layout", xfonts_dirname)
+        )
+        alias_file = fs_root.lookup(
+            f"./etc/X11/xfonts/{xfonts_dirname}/{package_name}.alias"
+        )
+        if alias_file:
+            cmds_postinst.append(
+                escape_shell_words(
+                    "update-fonts-alias",
+                    "--include",
+                    alias_file.absolute,
+                    xfonts_dirname,
+                )
+            )
+            cmds_postrm.append(
+                escape_shell_words(
+                    "update-fonts-alias",
+                    "--exclude",
+                    alias_file.absolute,
+                    xfonts_dirname,
+                )
+            )
+
+    if not cmds:
+        return
+
+    postinst_snippet = textwrap.dedent(
+        f"""\
+        if command -v update-fonts-dir >/dev/null; then
+            {';'.join(itertools.chain(cmds, cmds_postinst))}
+        fi
+    """
+    )
+
+    postrm_snippet = textwrap.dedent(
+        f"""\
+        if [ -x "`command -v update-fonts-dir`" ]; then
+            {';'.join(itertools.chain(cmds, cmds_postrm))}
+        fi
+    """
+    )
+
+    ctrl.maintscript.unconditionally_in_script("postinst", postinst_snippet)
+    ctrl.maintscript.unconditionally_in_script("postrm", postrm_snippet)
+    ctrl.substvars.add_dependency("misc:Depends", "xfonts-utils")
+
+
+# debputy does not support python2, so we do not list python / python2.
+_PYTHON_PUBLIC_DIST_DIR_NAMES = re.compile(r"(?:pypy|python)3(?:[.]\d+)?")
+
+
+def _public_python_dist_dirs(fs_root: VirtualPath) -> Iterator[VirtualPath]:
+    usr_lib = fs_root.lookup("./usr/lib")
+    root_dirs = []
+    if usr_lib:
+        root_dirs.append(usr_lib)
+
+    dbg_root = fs_root.lookup("./usr/lib/debug/usr/lib")
+    if dbg_root:
+        root_dirs.append(dbg_root)
+
+    for root_dir in root_dirs:
+        python_dirs = (
+            path
+            for path in root_dir.iterdir
+            if path.is_dir and _PYTHON_PUBLIC_DIST_DIR_NAMES.match(path.name)
+        )
+        for python_dir in python_dirs:
+            dist_packages = python_dir.get("dist-packages")
+            if not dist_packages:
+                continue
+            yield dist_packages
+
+
+def _has_py_file_in_dir(d: VirtualPath) -> bool:
+    return any(f.is_file and f.name.endswith(".py") for f in d.all_paths())
+
+
+def detect_pycompile_files(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    package = context.binary_package.name
+    # TODO: Support configurable list of private dirs
+    private_search_dirs = [
+        fs_root.lookup(os.path.join(d, package))
+        for d in [
+            "./usr/share",
+            "./usr/share/games",
+            "./usr/lib",
+            f"./usr/lib/{context.binary_package.deb_multiarch}",
+            "./usr/lib/games",
+        ]
+    ]
+    private_search_dirs_with_py_files = [
+        p for p in private_search_dirs if p is not None and _has_py_file_in_dir(p)
+    ]
+    public_search_dirs_has_py_files = any(
+        p is not None and _has_py_file_in_dir(p)
+        for p in _public_python_dist_dirs(fs_root)
+    )
+
+    if not public_search_dirs_has_py_files and not private_search_dirs_with_py_files:
+        return
+
+    # The dh_python3 helper also supports -V and -X.  We do not use them. They can be
+    # replaced by bcep support instead, which is how we will be supporting this kind
+    # of configuration down the line.
+    ctrl.maintscript.unconditionally_in_script(
+        "prerm",
+        textwrap.dedent(
+            f"""\
+        if command -v py3clean >/dev/null 2>&1; then
+            py3clean -p {package}
+        else
+            dpkg -L {package} | sed -En -e '/^(.*)\\/(.+)\\.py$/s,,rm "\\1/__pycache__/\\2".*,e'
+            find /usr/lib/python3/dist-packages/ -type d -name __pycache__ -empty -print0 | xargs --null --no-run-if-empty rmdir
+        fi
+        """
+        ),
+    )
+    if public_search_dirs_has_py_files:
+        ctrl.maintscript.on_configure(
+            textwrap.dedent(
+                f"""\
+            if command -v py3compile >/dev/null 2>&1; then
+                py3compile -p {package}
+            fi
+            if command -v pypy3compile >/dev/null 2>&1; then
+                pypy3compile -p {package} || true
+            fi
+            """
+            )
+        )
+    for private_dir in private_search_dirs_with_py_files:
+        escaped_dir = ctrl.maintscript.escape_shell_words(private_dir.absolute)
+        ctrl.maintscript.on_configure(
+            textwrap.dedent(
+                f"""\
+            if command -v py3compile >/dev/null 2>&1; then
+                py3compile -p {package} {escaped_dir}
+            fi
+            if command -v pypy3compile >/dev/null 2>&1; then
+                pypy3compile -p {package} {escaped_dir} || true
+            fi
+            """
+            )
+        )
+
+
+def translate_capabilities(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    caps = []
+    maintscript = ctrl.maintscript
+    for p in fs_root.all_paths():
+        if not p.is_file:
+            continue
+        metadata_ref = p.metadata(DebputyCapability)
+        capability = metadata_ref.value
+        if capability is None:
+            continue
+
+        abs_path = maintscript.escape_shell_words(p.absolute)
+
+        cap_script = "".join(
+            [
+                "    # Triggered by: {DEFINITION_SOURCE}\n"
+                "    _TPATH=$(dpkg-divert --truename {ABS_PATH})\n",
+                '    if setcap {CAP} "{DPKG_ROOT_UNQUOTED}${{_TPATH}}"; then\n',
+                '        chmod {MODE} "{DPKG_ROOT_UNQUOTED}${{_TPATH}}"\n',
+                '        echo "Successfully applied capabilities {CAP} on ${{_TPATH}}"\n',
+                "    else\n",
+                # We do not reset the mode here; generally a re-install or upgrade would re-store both mode,
+                # and remove the capabilities.
+                '        echo "The setcap failed to processes {CAP} on ${{_TPATH}}; falling back to no capability support" >&2\n',
+                "    fi\n",
+            ]
+        ).format(
+            CAP=maintscript.escape_shell_words(capability.capabilities).replace(
+                "\\+", "+"
+            ),
+            DPKG_ROOT_UNQUOTED=DPKG_ROOT_UNQUOTED,
+            ABS_PATH=abs_path,
+            MODE=maintscript.escape_shell_words(str(capability.capability_mode)),
+            DEFINITION_SOURCE=capability.definition_source.replace("\n", "\\n"),
+        )
+        assert cap_script.endswith("\n")
+        caps.append(cap_script)
+
+    if not caps:
+        return
+
+    maintscript.on_configure(
+        textwrap.dedent(
+            """\
+        if command -v setcap > /dev/null; then
+        {SET_CAP_COMMANDS}
+            unset _TPATH
+        else
+            echo "The setcap utility is not installed available; falling back to no capability support" >&2
+        fi
+        """
+        ).format(
+            SET_CAP_COMMANDS="".join(caps).rstrip("\n"),
+        )
+    )
+
+
+def pam_auth_update(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    pam_configs = fs_root.lookup("/usr/share/pam-configs")
+    if not pam_configs:
+        return
+    maintscript = ctrl.maintscript
+    for pam_config in pam_configs.iterdir:
+        if not pam_config.is_file:
+            continue
+        maintscript.on_configure("pam-auth-update --package\n")
+        maintscript.on_before_removal(
+            textwrap.dedent(
+                f"""\
+                if [ "${{DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT:-1}}" = 1 ]; then
+                    pam-auth-update --package --remove {maintscript.escape_shell_words(pam_config.name)}
+                fi
+                """
+            )
+        )
+
+
+def auto_depends_arch_any_solink(
+    fs_foot: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    context: PackageProcessingContext,
+) -> None:
+    package = context.binary_package
+    if package.is_arch_all:
+        return
+    libbasedir = fs_foot.lookup("usr/lib")
+    if not libbasedir:
+        return
+    libmadir = libbasedir.get(package.deb_multiarch)
+    if libmadir:
+        libdirs = [libmadir, libbasedir]
+    else:
+        libdirs = [libbasedir]
+    targets = []
+    for libdir in libdirs:
+        for path in libdir.iterdir:
+            if not path.is_symlink or not path.name.endswith(".so"):
+                continue
+            target = path.readlink()
+            resolved = assume_not_none(path.parent_dir).lookup(target)
+            if resolved is not None:
+                continue
+            targets.append((libdir.path, target))
+
+    roots = list(context.accessible_package_roots())
+    if not roots:
+        return
+
+    for libdir, target in targets:
+        final_path = os.path.join(libdir, target)
+        matches = []
+        for opkg, ofs_root in roots:
+            m = ofs_root.lookup(final_path)
+            if not m:
+                continue
+            matches.append(opkg)
+        if not matches or len(matches) > 1:
+            if matches:
+                all_matches = ", ".join(p.name for p in matches)
+                _warn(
+                    f"auto-depends-solink: The {final_path} was found in multiple packages ({all_matches}):"
+                    f" Not generating a dependency."
+                )
+            else:
+                _warn(
+                    f"auto-depends-solink: The {final_path} was NOT found in any accessible package:"
+                    " Not generating a dependency. This detection only works when both packages are arch:any"
+                    " and they have the same build-profiles."
+                )
+            continue
+        pkg_dep = matches[0]
+        # The debputy API should not allow this constraint to fail
+        assert pkg_dep.is_arch_all == package.is_arch_all
+        # If both packages are arch:all or both are arch:any, we can generate a tight dependency
+        relation = f"{pkg_dep.name} (= ${{binary:Version}})"
+        ctrl.substvars.add_dependency("misc:Depends", relation)
diff --git a/src/debputy/plugin/debputy/package_processors.py b/src/debputy/plugin/debputy/package_processors.py
new file mode 100644
index 0000000..3747755
--- /dev/null
+++ b/src/debputy/plugin/debputy/package_processors.py
@@ -0,0 +1,317 @@
+import contextlib
+import functools
+import gzip
+import os
+import re
+import subprocess
+from contextlib import ExitStack
+from typing import Optional, Iterator, IO, Any, List, Dict, Callable, Union
+
+from debputy.plugin.api import VirtualPath
+from debputy.util import _error, xargs, escape_shell, _info, assume_not_none
+
+
+@contextlib.contextmanager
+def _open_maybe_gzip(path: VirtualPath) -> Iterator[Union[IO[bytes], gzip.GzipFile]]:
+    if path.name.endswith(".gz"):
+        with gzip.GzipFile(path.fs_path, "rb") as fd:
+            yield fd
+    else:
+        with path.open(byte_io=True) as fd:
+            yield fd
+
+
+_SO_LINK_RE = re.compile(rb"[.]so\s+(.*)\s*")
+_LA_DEP_LIB_RE = re.compile(rb"'.+'")
+
+
+def _detect_so_link(path: VirtualPath) -> Optional[str]:
+    so_link_re = _SO_LINK_RE
+    with _open_maybe_gzip(path) as fd:
+        for line in fd:
+            m = so_link_re.search(line)
+            if m:
+                return m.group(1).decode("utf-8")
+    return None
+
+
+def _replace_with_symlink(path: VirtualPath, so_link_target: str) -> None:
+    adjusted_target = so_link_target
+    parent_dir = path.parent_dir
+    assert parent_dir is not None  # For the type checking
+    if parent_dir.name == os.path.dirname(adjusted_target):
+        # Avoid man8/../man8/foo links
+        adjusted_target = os.path.basename(adjusted_target)
+    elif "/" in so_link_target:
+        # symlinks and so links have a different base directory when the link has a "/".
+        # Adjust with an extra "../" to align the result
+        adjusted_target = "../" + adjusted_target
+
+    path.unlink()
+    parent_dir.add_symlink(path.name, adjusted_target)
+
+
+@functools.lru_cache(1)
+def _has_man_recode() -> bool:
+    # Ideally, we would just use shutil.which or something like that.
+    # Unfortunately, in debhelper, we experienced problems with which
+    # returning "yes" for a man tool that actually could not be run
+    # on salsa CI.
+    #
+    # Therefore, we adopt the logic of dh_installman to run the tool
+    # with --help to confirm it is not broken, because no one could
+    # figure out what happened in the salsa CI and my life is still
+    # too short to figure it out.
+    try:
+        subprocess.check_call(
+            ["man-recode", "--help"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            restore_signals=True,
+        )
+    except subprocess.CalledProcessError:
+        return False
+    return True
+
+
+def process_manpages(fs_root: VirtualPath, _unused1: Any, _unused2: Any) -> None:
+    man_dir = fs_root.lookup("./usr/share/man")
+    if not man_dir:
+        return
+
+    re_encode = []
+    for path in (p for p in man_dir.all_paths() if p.is_file and p.has_fs_path):
+        size = path.size
+        if size == 0:
+            continue
+        so_link_target = None
+        if size <= 1024:
+            # debhelper has a 1024 byte guard on the basis that ".so file tend to be small".
+            # That guard worked well for debhelper, so lets keep it for now on that basis alone.
+            so_link_target = _detect_so_link(path)
+        if so_link_target:
+            _replace_with_symlink(path, so_link_target)
+        else:
+            re_encode.append(path)
+
+    if not re_encode or not _has_man_recode():
+        return
+
+    with ExitStack() as manager:
+        manpages = [
+            manager.enter_context(p.replace_fs_path_content()) for p in re_encode
+        ]
+        static_cmd = ["man-recode", "--to-code", "UTF-8", "--suffix", ".encoded"]
+        for cmd in xargs(static_cmd, manpages):
+            _info(f"Ensuring manpages have utf-8 encoding via: {escape_shell(*cmd)}")
+            try:
+                subprocess.check_call(
+                    cmd,
+                    stdin=subprocess.DEVNULL,
+                    restore_signals=True,
+                )
+            except subprocess.CalledProcessError:
+                _error(
+                    "The man-recode process failed. Please review the output of `man-recode` to understand"
+                    " what went wrong."
+                )
+        for manpage in manpages:
+            os.rename(f"{manpage}.encoded", manpage)
+
+
+def _filter_compress_paths() -> Callable[[VirtualPath], Iterator[VirtualPath]]:
+    ignore_dir_basenames = {
+        "_sources",
+    }
+    ignore_basenames = {
+        ".htaccess",
+        "index.sgml",
+        "objects.inv",
+        "search_index.json",
+        "copyright",
+    }
+    ignore_extensions = {
+        ".htm",
+        ".html",
+        ".xhtml",
+        ".gif",
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gz",
+        ".taz",
+        ".tgz",
+        ".z",
+        ".bz2",
+        ".epub",
+        ".jar",
+        ".zip",
+        ".odg",
+        ".odp",
+        ".odt",
+        ".css",
+        ".xz",
+        ".lz",
+        ".lzma",
+        ".haddock",
+        ".hs",
+        ".woff",
+        ".woff2",
+        ".svg",
+        ".svgz",
+        ".js",
+        ".devhelp2",
+        ".map",  # Technically, dh_compress has this one case-sensitive
+    }
+    ignore_special_cases = ("-gz", "-z", "_z")
+
+    def _filtered_walk(path: VirtualPath) -> Iterator[VirtualPath]:
+        for path, children in path.walk():
+            if path.name in ignore_dir_basenames:
+                children.clear()
+                continue
+            if path.is_dir and path.name == "examples":
+                # Ignore anything beneath /usr/share/doc/*/examples
+                parent = path.parent_dir
+                grand_parent = parent.parent_dir if parent else None
+                if grand_parent and grand_parent.absolute == "/usr/share/doc":
+                    children.clear()
+                    continue
+            name = path.name
+            if (
+                path.is_symlink
+                or not path.is_file
+                or name in ignore_basenames
+                or not path.has_fs_path
+            ):
+                continue
+
+            name_lc = name.lower()
+            _, ext = os.path.splitext(name_lc)
+
+            if ext in ignore_extensions or name_lc.endswith(ignore_special_cases):
+                continue
+            yield path
+
+    return _filtered_walk
+
+
+def _find_compressable_paths(fs_root: VirtualPath) -> Iterator[VirtualPath]:
+    path_filter = _filter_compress_paths()
+
+    for p, compress_size_threshold in (
+        ("./usr/share/info", 0),
+        ("./usr/share/man", 0),
+        ("./usr/share/doc", 4096),
+    ):
+        path = fs_root.lookup(p)
+        if path is None:
+            continue
+        paths = path_filter(path)
+        if compress_size_threshold:
+            # The special-case for changelog and NEWS is from dh_compress. Generally these files
+            # have always been compressed regardless of their size.
+            paths = (
+                p
+                for p in paths
+                if p.size > compress_size_threshold
+                or p.name.startswith(("changelog", "NEWS"))
+            )
+        yield from paths
+    x11_path = fs_root.lookup("./usr/share/fonts/X11")
+    if x11_path:
+        yield from (
+            p for p in x11_path.all_paths() if p.is_file and p.name.endswith(".pcf")
+        )
+
+
+def apply_compression(fs_root: VirtualPath, _unused1: Any, _unused2: Any) -> None:
+    # TODO: Support hardlinks
+    compressed_files: Dict[str, str] = {}
+    for path in _find_compressable_paths(fs_root):
+        parent_dir = assume_not_none(path.parent_dir)
+        with parent_dir.add_file(f"{path.name}.gz", mtime=path.mtime) as new_file, open(
+            new_file.fs_path, "wb"
+        ) as fd:
+            try:
+                subprocess.check_call(["gzip", "-9nc", path.fs_path], stdout=fd)
+            except subprocess.CalledProcessError:
+                full_command = f"gzip -9nc {escape_shell(path.fs_path)} > {escape_shell(new_file.fs_path)}"
+                _error(
+                    f"The compression of {path.path} failed. Please review the error message from gzip to"
+                    f" understand what went wrong.  Full command was: {full_command}"
+                )
+            compressed_files[path.path] = new_file.path
+        del parent_dir[path.name]
+
+    all_remaining_symlinks = {p.path: p for p in fs_root.all_paths() if p.is_symlink}
+    changed = True
+    while changed:
+        changed = False
+        remaining: List[VirtualPath] = list(all_remaining_symlinks.values())
+        for symlink in remaining:
+            target = symlink.readlink()
+            dir_target, basename_target = os.path.split(target)
+            new_basename_target = f"{basename_target}.gz"
+            symlink_parent_dir = assume_not_none(symlink.parent_dir)
+            dir_path = symlink_parent_dir
+            if dir_target != "":
+                dir_path = dir_path.lookup(dir_target)
+            if (
+                not dir_path
+                or basename_target in dir_path
+                or new_basename_target not in dir_path
+            ):
+                continue
+            del all_remaining_symlinks[symlink.path]
+            changed = True
+
+            new_link_name = (
+                f"{symlink.name}.gz"
+                if not symlink.name.endswith(".gz")
+                else symlink.name
+            )
+            symlink_parent_dir.add_symlink(
+                new_link_name, os.path.join(dir_target, new_basename_target)
+            )
+            symlink.unlink()
+
+
+def _la_files(fs_root: VirtualPath) -> Iterator[VirtualPath]:
+    lib_dir = fs_root.lookup("/usr/lib")
+    if not lib_dir:
+        return
+    # Original code only iterators directly in /usr/lib. To be a faithful conversion, we do the same
+    # here.
+    # Eagerly resolve the list as the replacement can trigger a runtime error otherwise
+    paths = list(lib_dir.iterdir)
+    yield from (p for p in paths if p.is_file and p.name.endswith(".la"))
+
+
+# Conceptually, the same feature that dh_gnome provides.
+# The clean_la_files function based on the dh_gnome version written by Luca Falavigna in 2010,
+# who in turn references a Makefile version of the feature.
+# https://salsa.debian.org/gnome-team/gnome-pkg-tools/-/commit/2868e1e41ea45443b0fb340bf4c71c4de87d4a5b
+def clean_la_files(
+    fs_root: VirtualPath,
+    _unused1: Any,
+    _unused2: Any,
+) -> None:
+    for path in _la_files(fs_root):
+        buffer = []
+        with path.open(byte_io=True) as fd:
+            replace_file = False
+            for line in fd:
+                if line.startswith(b"dependency_libs"):
+                    replacement = _LA_DEP_LIB_RE.sub(b"''", line)
+                    if replacement != line:
+                        replace_file = True
+                        line = replacement
+                buffer.append(line)
+
+            if not replace_file:
+                continue
+            _info(f"Clearing the dependency_libs line in {path.path}")
+            with path.replace_fs_path_content() as fs_path, open(fs_path, "wb") as wfd:
+                wfd.writelines(buffer)
diff --git a/src/debputy/plugin/debputy/paths.py b/src/debputy/plugin/debputy/paths.py
new file mode 100644
index 0000000..5e512d1
--- /dev/null
+++ b/src/debputy/plugin/debputy/paths.py
@@ -0,0 +1,4 @@
+GSETTINGS_SCHEMA_DIR = "/usr/share/glib-2.0/schemas"
+INITRAMFS_HOOK_DIR = "/usr/share/initramfs-tools/hooks"
+SYSTEMD_TMPFILES_DIR = "/usr/lib/tmpfiles.d"
+SYSTEMD_SYSUSERS_DIR = "/usr/lib/sysusers.d"
diff --git a/src/debputy/plugin/debputy/private_api.py b/src/debputy/plugin/debputy/private_api.py
new file mode 100644
index 0000000..2db2b56
--- /dev/null
+++ b/src/debputy/plugin/debputy/private_api.py
@@ -0,0 +1,2931 @@
+import ctypes
+import ctypes.util
+import functools
+import itertools
+import textwrap
+import time
+from datetime import datetime
+from typing import (
+    cast,
+    NotRequired,
+    Optional,
+    Tuple,
+    Union,
+    Type,
+    TypedDict,
+    List,
+    Annotated,
+    Any,
+    Dict,
+    Callable,
+)
+
+from debian.changelog import Changelog
+from debian.deb822 import Deb822
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy._manifest_constants import (
+    MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE,
+    MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION,
+    MK_INSTALLATIONS_INSTALL_EXAMPLES,
+    MK_INSTALLATIONS_INSTALL,
+    MK_INSTALLATIONS_INSTALL_DOCS,
+    MK_INSTALLATIONS_INSTALL_MAN,
+    MK_INSTALLATIONS_DISCARD,
+    MK_INSTALLATIONS_MULTI_DEST_INSTALL,
+)
+from debputy.exceptions import DebputyManifestVariableRequiresDebianDirError
+from debputy.installations import InstallRule
+from debputy.maintscript_snippet import DpkgMaintscriptHelperCommand
+from debputy.manifest_conditions import (
+    ManifestCondition,
+    BinaryPackageContextArchMatchManifestCondition,
+    BuildProfileMatch,
+    SourceContextArchMatchManifestCondition,
+)
+from debputy.manifest_parser.base_types import (
+    DebputyParsedContent,
+    DebputyParsedContentStandardConditional,
+    FileSystemMode,
+    StaticFileSystemOwner,
+    StaticFileSystemGroup,
+    SymlinkTarget,
+    FileSystemExactMatchRule,
+    FileSystemMatchRule,
+    SymbolicMode,
+    TypeMapping,
+    OctalMode,
+    FileSystemExactNonDirMatchRule,
+)
+from debputy.manifest_parser.declarative_parser import DebputyParseHint
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.manifest_parser.mapper_code import type_mapper_str2package
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.path_matcher import ExactFileSystemPath
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    documented_attr,
+    reference_documentation,
+    VirtualPath,
+    packager_provided_file_reference_documentation,
+)
+from debputy.plugin.api.impl import DebputyPluginInitializerProvider
+from debputy.plugin.api.impl_types import automatic_discard_rule_example, PPFFormatParam
+from debputy.plugin.api.spec import (
+    type_mapping_reference_documentation,
+    type_mapping_example,
+)
+from debputy.plugin.debputy.binary_package_rules import register_binary_package_rules
+from debputy.plugin.debputy.discard_rules import (
+    _debputy_discard_pyc_files,
+    _debputy_prune_la_files,
+    _debputy_prune_doxygen_cruft,
+    _debputy_prune_binary_debian_dir,
+    _debputy_prune_info_dir_file,
+    _debputy_prune_backup_files,
+    _debputy_prune_vcs_paths,
+)
+from debputy.plugin.debputy.manifest_root_rules import register_manifest_root_rules
+from debputy.plugin.debputy.package_processors import (
+    process_manpages,
+    apply_compression,
+    clean_la_files,
+)
+from debputy.plugin.debputy.service_management import (
+    detect_systemd_service_files,
+    generate_snippets_for_systemd_units,
+    detect_sysv_init_service_files,
+    generate_snippets_for_init_scripts,
+)
+from debputy.plugin.debputy.shlib_metadata_detectors import detect_shlibdeps
+from debputy.plugin.debputy.strip_non_determinism import strip_non_determinism
+from debputy.substitution import VariableContext
+from debputy.transformation_rules import (
+    CreateSymlinkReplacementRule,
+    TransformationRule,
+    CreateDirectoryTransformationRule,
+    RemoveTransformationRule,
+    MoveTransformationRule,
+    PathMetadataTransformationRule,
+    CreateSymlinkPathTransformationRule,
+)
+from debputy.util import (
+    _normalize_path,
+    PKGNAME_REGEX,
+    PKGVERSION_REGEX,
+    debian_policy_normalize_symlink_target,
+    active_profiles_match,
+    _error,
+    _warn,
+    _info,
+    assume_not_none,
+)
+
+_DOCUMENTED_DPKG_ARCH_TYPES = {
+    "HOST": (
+        "installed on",
+        "The package will be **installed** on this type of machine / system",
+    ),
+    "BUILD": (
+        "compiled on",
+        "The compilation of this package will be performed **on** this kind of machine / system",
+    ),
+    "TARGET": (
+        "cross-compiler output",
+        "When building a cross-compiler, it will produce output for this kind of machine/system",
+    ),
+}
+
+_DOCUMENTED_DPKG_ARCH_VARS = {
+    "ARCH": "Debian's name for the architecture",
+    "ARCH_ABI": "Debian's name for the architecture ABI",
+    "ARCH_BITS": "Number of bits in the pointer size",
+    "ARCH_CPU": "Debian's name for the CPU type",
+    "ARCH_ENDIAN": "Endianness of the architecture (little/big)",
+    "ARCH_LIBC": "Debian's name for the libc implementation",
+    "ARCH_OS": "Debian name for the OS/kernel",
+    "GNU_CPU": "GNU's name for the CPU",
+    "GNU_SYSTEM": "GNU's name for the system",
+    "GNU_TYPE": "GNU system type (GNU_CPU and GNU_SYSTEM combined)",
+    "MULTIARCH": "Multi-arch tuple",
+}
+
+
+def _manifest_format_doc(anchor: str) -> str:
+    return f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md#{anchor}"
+
+
+@functools.lru_cache
+def load_libcap() -> Tuple[bool, Optional[str], Callable[[str], bool]]:
+    cap_library_path = ctypes.util.find_library("cap.so")
+    has_libcap = False
+    libcap = None
+    if cap_library_path:
+        try:
+            libcap = ctypes.cdll.LoadLibrary(cap_library_path)
+            has_libcap = True
+        except OSError:
+            pass
+
+    if libcap is None:
+        warned = False
+
+        def _is_valid_cap(cap: str) -> bool:
+            nonlocal warned
+            if not warned:
+                _info(
+                    "Could not load libcap.so; will not validate capabilities. Use `apt install libcap2` to provide"
+                    " checking of capabilities."
+                )
+                warned = True
+            return True
+
+    else:
+        # cap_t cap_from_text(const char *path_p)
+        libcap.cap_from_text.argtypes = [ctypes.c_char_p]
+        libcap.cap_from_text.restype = ctypes.c_char_p
+
+        libcap.cap_free.argtypes = [ctypes.c_void_p]
+        libcap.cap_free.restype = None
+
+        def _is_valid_cap(cap: str) -> bool:
+            cap_t = libcap.cap_from_text(cap.encode("utf-8"))
+            ok = cap_t is not None
+            libcap.cap_free(cap_t)
+            return ok
+
+    return has_libcap, cap_library_path, _is_valid_cap
+
+
+def check_cap_checker() -> Callable[[str, str], None]:
+    _, libcap_path, is_valid_cap = load_libcap()
+
+    seen_cap = set()
+
+    def _check_cap(cap: str, definition_source: str) -> None:
+        if cap not in seen_cap and not is_valid_cap(cap):
+            seen_cap.add(cap)
+            cap_path = f" ({libcap_path})" if libcap_path is not None else ""
+            _warn(
+                f'The capabilities "{cap}" provided in {definition_source} were not understood by'
+                f" libcap.so{cap_path}. Please verify you provided the correct capabilities."
+                f" Note: This warning can be a false-positive if you are targeting a newer libcap.so"
+                f" than the one installed on this system."
+            )
+
+    return _check_cap
+
+
+def load_source_variables(variable_context: VariableContext) -> Dict[str, str]:
+    try:
+        changelog = variable_context.debian_dir.lookup("changelog")
+        if changelog is None:
+            raise DebputyManifestVariableRequiresDebianDirError(
+                "The changelog was not present"
+            )
+        with changelog.open() as fd:
+            dch = Changelog(fd, max_blocks=2)
+    except FileNotFoundError as e:
+        raise DebputyManifestVariableRequiresDebianDirError(
+            "The changelog was not present"
+        ) from e
+    first_entry = dch[0]
+    first_non_binnmu_entry = dch[0]
+    if first_non_binnmu_entry.other_pairs.get("binary-only", "no") == "yes":
+        first_non_binnmu_entry = dch[1]
+        assert first_non_binnmu_entry.other_pairs.get("binary-only", "no") == "no"
+    source_version = first_entry.version
+    epoch = source_version.epoch
+    upstream_version = source_version.upstream_version
+    debian_revision = source_version.debian_revision
+    epoch_upstream = upstream_version
+    upstream_debian_revision = upstream_version
+    if epoch is not None and epoch != "":
+        epoch_upstream = f"{epoch}:{upstream_version}"
+    if debian_revision is not None and debian_revision != "":
+        upstream_debian_revision = f"{upstream_version}-{debian_revision}"
+
+    package = first_entry.package
+    if package is None:
+        _error("Cannot determine the source package name from debian/changelog.")
+
+    date = first_entry.date
+    if date is not None:
+        local_time = datetime.strptime(date, "%a, %d %b %Y %H:%M:%S %z")
+        source_date_epoch = str(int(local_time.timestamp()))
+    else:
+        _warn(
+            "The latest changelog entry does not have a (parsable) date, using current time"
+            " for SOURCE_DATE_EPOCH"
+        )
+        source_date_epoch = str(int(time.time()))
+
+    if first_non_binnmu_entry is not first_entry:
+        non_binnmu_date = first_non_binnmu_entry.date
+        if non_binnmu_date is not None:
+            local_time = datetime.strptime(non_binnmu_date, "%a, %d %b %Y %H:%M:%S %z")
+            snd_source_date_epoch = str(int(local_time.timestamp()))
+        else:
+            _warn(
+                "The latest (non-binNMU) changelog entry does not have a (parsable) date, using current time"
+                " for SOURCE_DATE_EPOCH (for strip-nondeterminism)"
+            )
+            snd_source_date_epoch = source_date_epoch = str(int(time.time()))
+    else:
+        snd_source_date_epoch = source_date_epoch
+    return {
+        "DEB_SOURCE": package,
+        "DEB_VERSION": source_version.full_version,
+        "DEB_VERSION_EPOCH_UPSTREAM": epoch_upstream,
+        "DEB_VERSION_UPSTREAM_REVISION": upstream_debian_revision,
+        "DEB_VERSION_UPSTREAM": upstream_version,
+        "SOURCE_DATE_EPOCH": source_date_epoch,
+        "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE": str(first_non_binnmu_entry.version),
+        "_DEBPUTY_SND_SOURCE_DATE_EPOCH": snd_source_date_epoch,
+    }
+
+
+def initialize_via_private_api(public_api: DebputyPluginInitializer) -> None:
+    api = cast("DebputyPluginInitializerProvider", public_api)
+
+    api.metadata_or_maintscript_detector(
+        "dpkg-shlibdeps",
+        # Private because detect_shlibdeps expects private API (hench this cast)
+        cast("MetadataAutoDetector", detect_shlibdeps),
+        package_type={"deb", "udeb"},
+    )
+    register_type_mappings(api)
+    register_variables_via_private_api(api)
+    document_builtin_variables(api)
+    register_automatic_discard_rules(api)
+    register_special_ppfs(api)
+    register_install_rules(api)
+    register_transformation_rules(api)
+    register_manifest_condition_rules(api)
+    register_dpkg_conffile_rules(api)
+    register_processing_steps(api)
+    register_service_managers(api)
+    register_manifest_root_rules(api)
+    register_binary_package_rules(api)
+
+
+def register_type_mappings(api: DebputyPluginInitializerProvider) -> None:
+    api.register_mapped_type(
+        TypeMapping(
+            FileSystemMatchRule,
+            str,
+            FileSystemMatchRule.parse_path_match,
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                """\
+                A generic file system path match with globs.
+
+                Manifest variable substitution will be applied and glob expansion will be performed.
+
+                The match will be read as one of the following cases:
+
+                  - Exact path match if there is no globs characters like `usr/bin/debputy`
+                  - A basename glob like `*.txt` or `**/foo`
+                  - A generic path glob otherwise like `usr/lib/*.so*`
+
+                Except for basename globs, all matches are always relative to the root directory of
+                the match, which is typically the package root directory or a search directory.
+
+                For basename globs, any path matching that basename beneath the package root directory
+                or relevant search directories will match.
+
+                Please keep in mind that:
+
+                  * glob patterns often have to be quoted as YAML interpret the glob metacharacter as
+                    an anchor reference.
+
+                  * Directories can be matched via this type. Whether the rule using this type
+                    recurse into the directory depends on the usage and not this type. Related, if
+                    value for this rule ends with a literal "/", then the definition can *only* match
+                    directories (similar to the shell).
+
+                  * path matches involving glob expansion are often subject to different rules than
+                    path matches without them. As an example, automatic discard rules does not apply
+                    to exact path matches, but they will filter out glob matches.
+            """,
+            ),
+            examples=[
+                type_mapping_example("usr/bin/debputy"),
+                type_mapping_example("*.txt"),
+                type_mapping_example("**/foo"),
+                type_mapping_example("usr/lib/*.so*"),
+                type_mapping_example("usr/share/foo/data-*/"),
+            ],
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            FileSystemExactMatchRule,
+            str,
+            FileSystemExactMatchRule.parse_path_match,
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                """\
+                A file system match that does **not** expand globs.
+
+                Manifest variable substitution will be applied. However, globs will not be expanded.
+                Any glob metacharacters will be interpreted as a literal part of path.
+
+                Note that a directory can be matched via this type. Whether the rule using this type
+                recurse into the directory depends on the usage and is not defined by this type.
+                Related, if value for this rule ends with a literal "/", then the definition can
+                *only* match directories (similar to the shell).
+            """,
+            ),
+            examples=[
+                type_mapping_example("usr/bin/dpkg"),
+                type_mapping_example("usr/share/foo/"),
+                type_mapping_example("usr/share/foo/data.txt"),
+            ],
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            FileSystemExactNonDirMatchRule,
+            str,
+            FileSystemExactNonDirMatchRule.parse_path_match,
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                f"""\
+                A file system match that does **not** expand globs and must not match a directory.
+
+                Manifest variable substitution will be applied. However, globs will not be expanded.
+                Any glob metacharacters will be interpreted as a literal part of path.
+
+                This is like {FileSystemExactMatchRule.__name__} except that the match will fail if the
+                provided path matches a directory. Since a directory cannot be matched, it is an error
+                for any input to end with a "/" as only directories can be matched if the path ends
+                with a "/".
+            """,
+            ),
+            examples=[
+                type_mapping_example("usr/bin/dh_debputy"),
+                type_mapping_example("usr/share/foo/data.txt"),
+            ],
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            SymlinkTarget,
+            str,
+            lambda v, ap, pc: SymlinkTarget.parse_symlink_target(
+                v, ap, assume_not_none(pc).substitution
+            ),
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                """\
+                A symlink target.
+
+                Manifest variable substitution will be applied. This is distinct from an exact file
+                system match in that a symlink target is not relative to the package root by default
+                (explicitly prefix for "/" for absolute path targets)
+
+                Note that `debputy` will policy normalize symlinks when assembling the deb, so
+                use of relative or absolute symlinks comes down to preference.
+            """,
+            ),
+            examples=[
+                type_mapping_example("../foo"),
+                type_mapping_example("/usr/share/doc/bar"),
+            ],
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            StaticFileSystemOwner,
+            Union[int, str],
+            lambda v, ap, _: StaticFileSystemOwner.from_manifest_value(v, ap),
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                """\
+            File system owner reference that is part of the passwd base data (such as "root").
+
+            The group can be provided in either of the following three forms:
+
+             * A name (recommended), such as "root"
+             * The UID in the form of an integer (that is, no quoting), such as 0 (for "root")
+             * The name and the UID separated by colon such as "root:0" (for "root").
+
+            Note in the last case, the `debputy` will validate that the name and the UID match.
+
+            Some owners (such as "nobody") are deliberately disallowed.
+            """
+            ),
+            examples=[
+                type_mapping_example("root"),
+                type_mapping_example(0),
+                type_mapping_example("root:0"),
+                type_mapping_example("bin"),
+            ],
+        ),
+    )
+    api.register_mapped_type(
+        TypeMapping(
+            StaticFileSystemGroup,
+            Union[int, str],
+            lambda v, ap, _: StaticFileSystemGroup.from_manifest_value(v, ap),
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description=textwrap.dedent(
+                """\
+            File system group reference that is part of the passwd base data (such as "root").
+
+            The group can be provided in either of the following three forms:
+
+             * A name (recommended), such as "root"
+             * The GID in the form of an integer (that is, no quoting), such as 0 (for "root")
+             * The name and the GID separated by colon such as "root:0" (for "root").
+
+            Note in the last case, the `debputy` will validate that the name and the GID match.
+
+            Some owners (such as "nobody") are deliberately disallowed.
+            """
+            ),
+            examples=[
+                type_mapping_example("root"),
+                type_mapping_example(0),
+                type_mapping_example("root:0"),
+                type_mapping_example("tty"),
+            ],
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            BinaryPackage,
+            str,
+            type_mapper_str2package,
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description="Name of a package in debian/control",
+        ),
+    )
+
+    api.register_mapped_type(
+        TypeMapping(
+            FileSystemMode,
+            str,
+            lambda v, ap, _: FileSystemMode.parse_filesystem_mode(v, ap),
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description="Either an octal mode or symbolic mode",
+            examples=[
+                type_mapping_example("a+x"),
+                type_mapping_example("u=rwX,go=rX"),
+                type_mapping_example("0755"),
+            ],
+        ),
+    )
+    api.register_mapped_type(
+        TypeMapping(
+            OctalMode,
+            str,
+            lambda v, ap, _: OctalMode.parse_filesystem_mode(v, ap),
+        ),
+        reference_documentation=type_mapping_reference_documentation(
+            description="An octal mode. Must always be a string.",
+            examples=[
+                type_mapping_example("0644"),
+                type_mapping_example("0755"),
+            ],
+        ),
+    )
+
+
+def register_service_managers(
+    api: DebputyPluginInitializerProvider,
+) -> None:
+    api.service_provider(
+        "systemd",
+        detect_systemd_service_files,
+        generate_snippets_for_systemd_units,
+    )
+    api.service_provider(
+        "sysvinit",
+        detect_sysv_init_service_files,
+        generate_snippets_for_init_scripts,
+    )
+
+
+def register_automatic_discard_rules(
+    api: DebputyPluginInitializerProvider,
+) -> None:
+    api.automatic_discard_rule(
+        "python-cache-files",
+        _debputy_discard_pyc_files,
+        rule_reference_documentation="Discards any *.pyc, *.pyo files and any __pycache__ directories",
+        examples=automatic_discard_rule_example(
+            (".../foo.py", False),
+            ".../__pycache__/",
+            ".../__pycache__/...",
+            ".../foo.pyc",
+            ".../foo.pyo",
+        ),
+    )
+    api.automatic_discard_rule(
+        "la-files",
+        _debputy_prune_la_files,
+        rule_reference_documentation="Discards any file with the extension .la beneath the directory /usr/lib",
+        examples=automatic_discard_rule_example(
+            "usr/lib/libfoo.la",
+            ("usr/lib/libfoo.so.1.0.0", False),
+        ),
+    )
+    api.automatic_discard_rule(
+        "backup-files",
+        _debputy_prune_backup_files,
+        rule_reference_documentation="Discards common back up files such as foo~, foo.bak or foo.orig",
+        examples=(
+            automatic_discard_rule_example(
+                ".../foo~",
+                ".../foo.orig",
+                ".../foo.rej",
+                ".../DEADJOE",
+                ".../.foo.sw.",
+            ),
+        ),
+    )
+    api.automatic_discard_rule(
+        "version-control-paths",
+        _debputy_prune_vcs_paths,
+        rule_reference_documentation="Discards common version control paths such as .git, .gitignore, CVS, etc.",
+        examples=automatic_discard_rule_example(
+            ("tools/foo", False),
+            ".../CVS/",
+            ".../CVS/...",
+            ".../.gitignore",
+            ".../.gitattributes",
+            ".../.git/",
+            ".../.git/...",
+        ),
+    )
+    api.automatic_discard_rule(
+        "gnu-info-dir-file",
+        _debputy_prune_info_dir_file,
+        rule_reference_documentation="Discards the /usr/share/info/dir file (causes package file conflicts)",
+        examples=automatic_discard_rule_example(
+            "usr/share/info/dir",
+            ("usr/share/info/foo.info", False),
+            ("usr/share/info/dir.info", False),
+            ("usr/share/random/case/dir", False),
+        ),
+    )
+    api.automatic_discard_rule(
+        "debian-dir",
+        _debputy_prune_binary_debian_dir,
+        rule_reference_documentation="(Implementation detail) Discards any DEBIAN directory to avoid it from appearing"
+        " literally in the file listing",
+        examples=(
+            automatic_discard_rule_example(
+                "DEBIAN/",
+                "DEBIAN/control",
+                ("usr/bin/foo", False),
+                ("usr/share/DEBIAN/foo", False),
+            ),
+        ),
+    )
+    api.automatic_discard_rule(
+        "doxygen-cruft-files",
+        _debputy_prune_doxygen_cruft,
+        rule_reference_documentation="Discards cruft files generated by doxygen",
+        examples=automatic_discard_rule_example(
+            ("usr/share/doc/foo/api/doxygen.css", False),
+            ("usr/share/doc/foo/api/doxygen.svg", False),
+            ("usr/share/doc/foo/api/index.html", False),
+            "usr/share/doc/foo/api/.../cruft.map",
+            "usr/share/doc/foo/api/.../cruft.md5",
+        ),
+    )
+
+
+def register_processing_steps(api: DebputyPluginInitializerProvider) -> None:
+    api.package_processor("manpages", process_manpages)
+    api.package_processor("clean-la-files", clean_la_files)
+    # strip-non-determinism makes assumptions about the PackageProcessingContext implementation
+    api.package_processor(
+        "strip-nondeterminism",
+        cast("Any", strip_non_determinism),
+        depends_on_processor=["manpages"],
+    )
+    api.package_processor(
+        "compression",
+        apply_compression,
+        depends_on_processor=["manpages", "strip-nondeterminism"],
+    )
+
+
+def register_variables_via_private_api(api: DebputyPluginInitializerProvider) -> None:
+    api.manifest_variable_provider(
+        load_source_variables,
+        {
+            "DEB_SOURCE": "Name of the source package (`dpkg-parsechangelog -SSource`)",
+            "DEB_VERSION": "Version from the top most changelog entry (`dpkg-parsechangelog -SVersion`)",
+            "DEB_VERSION_EPOCH_UPSTREAM": "Version from the top most changelog entry *without* the Debian revision",
+            "DEB_VERSION_UPSTREAM_REVISION": "Version from the top most changelog entry *without* the epoch",
+            "DEB_VERSION_UPSTREAM": "Upstream version from the top most changelog entry (that is, *without* epoch and Debian revision)",
+            "SOURCE_DATE_EPOCH": textwrap.dedent(
+                """\
+            Timestamp from the top most changelog entry (`dpkg-parsechangelog -STimestamp`)
+            Please see https://reproducible-builds.org/docs/source-date-epoch/ for the full definition of
+            this variable.
+            """
+            ),
+            "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE": None,
+            "_DEBPUTY_SND_SOURCE_DATE_EPOCH": None,
+        },
+    )
+
+
+def document_builtin_variables(api: DebputyPluginInitializerProvider) -> None:
+    api.document_builtin_variable(
+        "PACKAGE",
+        "Name of the binary package (only available in binary context)",
+        is_context_specific=True,
+    )
+
+    arch_types = _DOCUMENTED_DPKG_ARCH_TYPES
+
+    for arch_type, (arch_type_tag, arch_type_doc) in arch_types.items():
+        for arch_var, arch_var_doc in _DOCUMENTED_DPKG_ARCH_VARS.items():
+            full_var = f"DEB_{arch_type}_{arch_var}"
+            documentation = textwrap.dedent(
+                f"""\
+            {arch_var_doc} ({arch_type_tag})
+            This variable describes machine information used when the package is compiled and assembled.
+             * Machine type: {arch_type_doc}
+             * Value description: {arch_var_doc}
+
+            The value is the output of: `dpkg-architecture -q{full_var}`
+            """
+            )
+            api.document_builtin_variable(
+                full_var,
+                documentation,
+                is_for_special_case=arch_type != "HOST",
+            )
+
+
+def _format_docbase_filename(
+    path_format: str,
+    format_param: PPFFormatParam,
+    docbase_file: VirtualPath,
+) -> str:
+    with docbase_file.open() as fd:
+        content = Deb822(fd)
+        proper_name = content["Document"]
+        if proper_name is not None:
+            format_param["name"] = proper_name
+        else:
+            _warn(
+                f"The docbase file {docbase_file.fs_path} is missing the Document field"
+            )
+    return path_format.format(**format_param)
+
+
+def register_special_ppfs(api: DebputyPluginInitializerProvider) -> None:
+    api.packager_provided_file(
+        "doc-base",
+        "/usr/share/doc-base/{owning_package}.{name}",
+        format_callback=_format_docbase_filename,
+    )
+
+    api.packager_provided_file(
+        "shlibs",
+        "DEBIAN/shlibs",
+        allow_name_segment=False,
+        reservation_only=True,
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=["man:deb-shlibs(5)"],
+        ),
+    )
+    api.packager_provided_file(
+        "symbols",
+        "DEBIAN/symbols",
+        allow_name_segment=False,
+        allow_architecture_segment=True,
+        reservation_only=True,
+        reference_documentation=packager_provided_file_reference_documentation(
+            format_documentation_uris=["man:deb-symbols(5)"],
+        ),
+    )
+    api.packager_provided_file(
+        "templates",
+        "DEBIAN/templates",
+        allow_name_segment=False,
+        allow_architecture_segment=False,
+        reservation_only=True,
+    )
+    api.packager_provided_file(
+        "alternatives",
+        "DEBIAN/alternatives",
+        allow_name_segment=False,
+        allow_architecture_segment=True,
+        reservation_only=True,
+    )
+
+
+def register_install_rules(api: DebputyPluginInitializerProvider) -> None:
+    api.plugable_manifest_rule(
+        InstallRule,
+        MK_INSTALLATIONS_INSTALL,
+        ParsedInstallRule,
+        _install_rule_handler,
+        source_format=_with_alt_form(ParsedInstallRuleSourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Generic install (`install`)",
+            description=textwrap.dedent(
+                """\
+                The generic `install` rule can be used to install arbitrary paths into packages
+                and is *similar* to how `dh_install` from debhelper works.  It is a two "primary" uses.
+
+                  1) The classic "install into directory" similar to the standard `dh_install`
+                  2) The "install as" similar to `dh-exec`'s `foo => bar` feature.
+
+                The `install` rule installs a path exactly once into each package it acts on. In
+                the rare case that you want to install the same source *multiple* times into the
+                *same* packages, please have a look at `{MULTI_DEST_INSTALL}`.
+            """.format(
+                    MULTI_DEST_INSTALL=MK_INSTALLATIONS_MULTI_DEST_INSTALL
+                )
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+                When the input is a string or a list of string, then that value is used as shorthand
+                for `source` or `sources` (respectively).  This form can only be used when `into` is
+                not required.
+            """
+            ),
+            attributes=[
+                documented_attr(
+                    ["source", "sources"],
+                    textwrap.dedent(
+                        """\
+                        A path match (`source`) or a list of path matches (`sources`) defining the
+                        source path(s) to be installed. The path match(es) can use globs.  Each match
+                        is tried against default search directories.
+                         - When a symlink is matched, then the symlink (not its target) is installed
+                           as-is.  When a directory is matched, then the directory is installed along
+                           with all the contents that have not already been installed somewhere.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "dest_dir",
+                    textwrap.dedent(
+                        """\
+                        A path defining the destination *directory*.  The value *cannot* use globs, but can
+                        use substitution.  If neither `as` nor `dest-dir` is given, then `dest-dir` defaults
+                        to the directory name of the `source`.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "into",
+                    textwrap.dedent(
+                        """\
+                    Either a package name or a list of package names for which these paths should be
+                    installed.  This key is conditional on whether there are multiple binary packages listed
+                    in `debian/control`.  When there is only one binary package, then that binary is the
+                    default for `into`. Otherwise, the key is required.
+                    """
+                    ),
+                ),
+                documented_attr(
+                    "install_as",
+                    textwrap.dedent(
+                        """\
+                                A path defining the path to install the source as. This is a full path.  This option
+                                is mutually exclusive with `dest-dir` and `sources` (but not `source`).  When `as` is
+                                given, then `source` must match exactly one "not yet matched" path.
+                            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                    A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc("generic-install-install"),
+        ),
+    )
+    api.plugable_manifest_rule(
+        InstallRule,
+        [
+            MK_INSTALLATIONS_INSTALL_DOCS,
+            "install-doc",
+        ],
+        ParsedInstallRule,
+        _install_docs_rule_handler,
+        source_format=_with_alt_form(ParsedInstallDocRuleSourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Install documentation (`install-docs`)",
+            description=textwrap.dedent(
+                """\
+            This install rule resemble that of `dh_installdocs`.  It is a shorthand over the generic
+            `install` rule with the following key features:
+
+             1) The default `dest-dir` is to use the package's documentation directory (usually something
+                like `/usr/share/doc/{{PACKAGE}}`, though it respects the "main documentation package"
+                recommendation from Debian Policy). The `dest-dir` or `as` can be set in case the
+                documentation in question goes into another directory or with a concrete path.  In this
+                case, it is still "better" than `install` due to the remaining benefits.
+             2) The rule comes with pre-defined conditional logic for skipping the rule under
+                `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself.
+             3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb`
+                package listed in `debian/control`.
+
+            With these two things in mind, it behaves just like the `install` rule.
+
+            Note: It is often worth considering to use a more specialized version of the `install-docs`
+            rule when one such is available. If you are looking to install an example or a manpage,
+            consider whether `install-examples` or `install-man` might be a better fit for your
+            use-case.
+        """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+            When the input is a string or a list of string, then that value is used as shorthand
+            for `source` or `sources` (respectively).  This form can only be used when `into` is
+            not required.
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["source", "sources"],
+                    textwrap.dedent(
+                        """\
+                    A path match (`source`) or a list of path matches (`sources`) defining the
+                    source path(s) to be installed. The path match(es) can use globs.  Each match
+                    is tried against default search directories.
+                     - When a symlink is matched, then the symlink (not its target) is installed
+                       as-is.  When a directory is matched, then the directory is installed along
+                       with all the contents that have not already been installed somewhere.
+
+                     - **CAVEAT**:  Specifying `source: examples` where `examples` resolves to a
+                       directory for `install-examples` will give you an `examples/examples`
+                       directory in the package, which is rarely what you want. Often, you
+                       can solve this by using `examples/*` instead. Similar for `install-docs`
+                       and a `doc` or `docs` directory.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "dest_dir",
+                    textwrap.dedent(
+                        """\
+                        A path defining the destination *directory*.  The value *cannot* use globs, but can
+                        use substitution.  If neither `as` nor `dest-dir` is given, then `dest-dir` defaults
+                        to the relevant package documentation directory (a la `/usr/share/doc/{{PACKAGE}}`).
+                """
+                    ),
+                ),
+                documented_attr(
+                    "into",
+                    textwrap.dedent(
+                        """\
+                    Either a package name or a list of package names for which these paths should be
+                    installed as documentation.  This key is conditional on whether there are multiple
+                    (non-`udeb`) binary packages listed in `debian/control`.  When there is only one
+                    (non-`udeb`) binary package, then that binary is the default for `into`. Otherwise,
+                    the key is required.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "install_as",
+                    textwrap.dedent(
+                        """\
+                                A path defining the path to install the source as. This is a full path.  This option
+                                is mutually exclusive with `dest-dir` and `sources` (but not `source`).  When `as` is
+                                given, then `source` must match exactly one "not yet matched" path.
+                            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                This condition will be combined with the built-in condition provided by these rules
+                (rather than replacing it).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "install-documentation-install-docs"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        InstallRule,
+        [
+            MK_INSTALLATIONS_INSTALL_EXAMPLES,
+            "install-example",
+        ],
+        ParsedInstallExamplesRule,
+        _install_examples_rule_handler,
+        source_format=_with_alt_form(ParsedInstallExamplesRuleSourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Install examples (`install-examples`)",
+            description=textwrap.dedent(
+                """\
+            This install rule resemble that of `dh_installexamples`.  It is a shorthand over the generic `
+            install` rule with the following key features:
+
+             1) It pre-defines the `dest-dir` that respects the "main documentation package" recommendation from
+                Debian Policy. The `install-examples` will use the `examples` subdir for the package documentation
+                dir.
+             2) The rule comes with pre-defined conditional logic for skipping the rule under
+                `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself.
+             3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb`
+                package listed in `debian/control`.
+
+            With these two things in mind, it behaves just like the `install` rule.
+        """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+            When the input is a string or a list of string, then that value is used as shorthand
+            for `source` or `sources` (respectively).  This form can only be used when `into` is
+            not required.
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["source", "sources"],
+                    textwrap.dedent(
+                        """\
+                    A path match (`source`) or a list of path matches (`sources`) defining the
+                    source path(s) to be installed. The path match(es) can use globs.  Each match
+                    is tried against default search directories.
+                     - When a symlink is matched, then the symlink (not its target) is installed
+                       as-is.  When a directory is matched, then the directory is installed along
+                       with all the contents that have not already been installed somewhere.
+
+                     - **CAVEAT**:  Specifying `source: examples` where `examples` resolves to a
+                       directory for `install-examples` will give you an `examples/examples`
+                       directory in the package, which is rarely what you want. Often, you
+                       can solve this by using `examples/*` instead. Similar for `install-docs`
+                       and a `doc` or `docs` directory.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "into",
+                    textwrap.dedent(
+                        """\
+                    Either a package name or a list of package names for which these paths should be
+                    installed as examples.  This key is conditional on whether there are (non-`udeb`)
+                    multiple binary packages listed in `debian/control`.  When there is only one
+                    (non-`udeb`) binary package, then that binary is the default for `into`.
+                    Otherwise, the key is required.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                This condition will be combined with the built-in condition provided by these rules
+                (rather than replacing it).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "install-examples-install-examples"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        InstallRule,
+        MK_INSTALLATIONS_INSTALL_MAN,
+        ParsedInstallManpageRule,
+        _install_man_rule_handler,
+        source_format=_with_alt_form(ParsedInstallManpageRuleSourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Install manpages (`install-man`)",
+            description=textwrap.dedent(
+                """\
+                Install rule for installing manpages similar to `dh_installman`. It is a shorthand
+                over the generic `install` rule with the following key features:
+
+                 1) The rule can only match files (notably, symlinks cannot be matched by this rule).
+                 2) The `dest-dir` is computed per source file based on the manpage's section and
+                    language.
+                 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb`
+                    package listed in `debian/control`.
+                 4) The rule comes with manpage specific attributes such as `language` and `section`
+                    for when the auto-detection is insufficient.
+                 5) The rule comes with pre-defined conditional logic for skipping the rule under
+                    `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself.
+
+                With these things in mind, the rule behaves similar to the `install` rule.
+            """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+                When the input is a string or a list of string, then that value is used as shorthand
+                for `source` or `sources` (respectively).  This form can only be used when `into` is
+                not required.
+            """
+            ),
+            attributes=[
+                documented_attr(
+                    ["source", "sources"],
+                    textwrap.dedent(
+                        """\
+                        A path match (`source`) or a list of path matches (`sources`) defining the
+                        source path(s) to be installed. The path match(es) can use globs.  Each match
+                        is tried against default search directories.
+                         - When a symlink is matched, then the symlink (not its target) is installed
+                           as-is.  When a directory is matched, then the directory is installed along
+                           with all the contents that have not already been installed somewhere.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "into",
+                    textwrap.dedent(
+                        """\
+                    Either a package name or a list of package names for which these paths should be
+                    installed as manpages.  This key is conditional on whether there are multiple (non-`udeb`)
+                    binary packages listed in `debian/control`.  When there is only one (non-`udeb`) binary
+                    package, then that binary is the default for `into`. Otherwise, the key is required.
+                    """
+                    ),
+                ),
+                documented_attr(
+                    "section",
+                    textwrap.dedent(
+                        """\
+                        If provided, it must be an integer between 1 and 9 (both inclusive), defining the
+                        section the manpages belong overriding any auto-detection that `debputy` would
+                        have performed.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "language",
+                    textwrap.dedent(
+                        """\
+                        If provided, it must be either a 2 letter language code (such as `de`), a 5 letter
+                        language + dialect code (such as `pt_BR`), or one of the special keywords `C`,
+                        `derive-from-path`, or `derive-from-basename`.  The default is `derive-from-path`.
+                           - When `language` is `C`, then the manpages are assumed to be "untranslated".
+                           - When `language` is a language code (with or without dialect), then all manpages
+                             matched will be assumed to be translated to that concrete language / dialect.
+                           - When `language` is `derive-from-path`, then `debputy` attempts to derive the
+                             language from the path (`man/<language>/man<section>`).  This matches the
+                             default of `dh_installman`. When no language can be found for a given source,
+                             `debputy` behaves like language was `C`.
+                           - When `language` is `derive-from-basename`, then `debputy` attempts to derive
+                             the language from the basename (`foo.<language>.1`) similar to `dh_installman`
+                             previous default.  When no language can be found for a given source, `debputy`
+                             behaves like language was `C`.  Note this is prone to false positives where
+                             `.pl`, `.so` or similar two-letter extensions gets mistaken for a language code
+                             (`.pl` can both be "Polish" or "Perl Script", `.so` can both be "Somali" and
+                             "Shared Object" documentation).  In this configuration, such extensions are
+                             always assumed to be a language.
+                            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                    A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "install-manpages-install-man"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        InstallRule,
+        MK_INSTALLATIONS_DISCARD,
+        ParsedInstallDiscardRule,
+        _install_discard_rule_handler,
+        source_format=_with_alt_form(ParsedInstallDiscardRuleSourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Discard (or exclude) upstream provided paths (`discard`)",
+            description=textwrap.dedent(
+                """\
+                    When installing paths from `debian/tmp` into packages, it might be useful to ignore
+                    some paths that you never need installed.  This can be done with the `discard` rule.
+
+                    Once a path is discarded, it cannot be matched by any other install rules.  A path
+                    that is discarded, is considered handled when `debputy` checks for paths you might
+                    have forgotten to install.  The `discard` feature is therefore *also* replaces the
+                    `debian/not-installed` file used by `debhelper` and `cdbs`.
+        """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+            When the input is a string or a list of string, then that value is used as shorthand
+            for `path` or `paths` (respectively).
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["path", "paths"],
+                    textwrap.dedent(
+                        """\
+                    A path match (`path`) or a list of path matches (`paths`) defining the source
+                    path(s) that should not be installed anywhere. The path match(es) can use globs.
+                    - When a symlink is matched, then the symlink (not its target) is discarded as-is.
+                      When a directory is matched, then the directory is discarded along with all the
+                      contents that have not already been installed somewhere.
+            """
+                    ),
+                ),
+                documented_attr(
+                    ["search_dir", "search_dirs"],
+                    textwrap.dedent(
+                        """\
+                         A path (`search-dir`) or a list to paths (`search-dirs`) that defines
+                         which search directories apply to. This attribute is primarily useful
+                         for source packages that uses "per package search dirs", and you want
+                         to restrict a discard rule to a subset of the relevant search dirs.
+                         Note all listed search directories must be either an explicit search
+                         requested by the packager or a search directory that `debputy`
+                         provided automatically (such as `debian/tmp`). Listing other paths
+                         will make `debputy` report an error.
+                         - Note that the `path` or `paths` must match at least one entry in 
+                           any of the search directories unless *none* of the search directories
+                           exist (or the condition in `required-when` evaluates to false). When
+                           none of the search directories exist, the discard rule is silently
+                           skipped. This special-case enables you to have discard rules only
+                           applicable to certain builds that are only performed conditionally.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "required_when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules](#conditional-rules). The discard
+                rule is always applied. When the conditional is present and evaluates to false,
+                the discard rule can silently match nothing.When the condition is absent, *or*
+                it evaluates to true, then each pattern provided must match at least one path.
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "discard-or-exclude-upstream-provided-paths-discard"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        InstallRule,
+        MK_INSTALLATIONS_MULTI_DEST_INSTALL,
+        ParsedMultiDestInstallRule,
+        _multi_dest_install_rule_handler,
+        source_format=ParsedMultiDestInstallRuleSourceFormat,
+        inline_reference_documentation=reference_documentation(
+            title=f"Multi destination install (`{MK_INSTALLATIONS_MULTI_DEST_INSTALL}`)",
+            description=textwrap.dedent(
+                """\
+                The `{RULE_NAME}` is a variant of the generic `install` rule that installs sources
+                into multiple destination paths. This is needed for the rare case where you want a
+                path to be installed *twice* (or more) into the *same* package. The rule is a two
+                "primary" uses.
+
+                  1) The classic "install into directory" similar to the standard `dh_install`,
+                     except you list 2+ destination directories.
+                  2) The "install as" similar to `dh-exec`'s `foo => bar` feature, except you list
+                     2+ `as` names.
+            """.format(
+                    RULE_NAME=MK_INSTALLATIONS_MULTI_DEST_INSTALL
+                )
+            ),
+            attributes=[
+                documented_attr(
+                    ["source", "sources"],
+                    textwrap.dedent(
+                        """\
+                        A path match (`source`) or a list of path matches (`sources`) defining the
+                        source path(s) to be installed. The path match(es) can use globs.  Each match
+                        is tried against default search directories.
+                         - When a symlink is matched, then the symlink (not its target) is installed
+                           as-is.  When a directory is matched, then the directory is installed along
+                           with all the contents that have not already been installed somewhere.
+                """
+                    ),
+                ),
+                documented_attr(
+                    "dest_dirs",
+                    textwrap.dedent(
+                        """\
+                        A list of paths defining the destination *directories*.  The value *cannot* use
+                        globs, but can use substitution. It is mutually exclusive with `as` but must be
+                        provided if `as` is not provided. The attribute must contain at least two paths
+                        (if you do not have two paths, you want `install`).
+                """
+                    ),
+                ),
+                documented_attr(
+                    "into",
+                    textwrap.dedent(
+                        """\
+                    Either a package name or a list of package names for which these paths should be
+                    installed.  This key is conditional on whether there are multiple binary packages listed
+                    in `debian/control`.  When there is only one binary package, then that binary is the
+                    default for `into`. Otherwise, the key is required.
+                    """
+                    ),
+                ),
+                documented_attr(
+                    "install_as",
+                    textwrap.dedent(
+                        """\
+                                A list of paths, which defines all the places the source will be installed.
+                                Each path must be a full path without globs (but can use substitution).
+                                This option is mutually exclusive with `dest-dirs` and `sources` (but not
+                                `source`).  When `as` is given, then `source` must match exactly one
+                                "not yet matched" path. The attribute must contain at least two paths
+                                (if you do not have two paths, you want `install`).
+                            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                    A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc("generic-install-install"),
+        ),
+    )
+
+
+def register_transformation_rules(api: DebputyPluginInitializerProvider) -> None:
+    api.plugable_manifest_rule(
+        TransformationRule,
+        "move",
+        TransformationMoveRuleSpec,
+        _transformation_move_handler,
+        inline_reference_documentation=reference_documentation(
+            title="Move transformation rule (`move`)",
+            description=textwrap.dedent(
+                """\
+                The move transformation rule is mostly only useful for single binary source packages,
+                where everything from upstream's build system is installed automatically into the package.
+                In those case, you might find yourself with some files that need to be renamed to match
+                Debian specific requirements.
+
+                This can be done with the `move` transformation rule, which is a rough emulation of the
+                `mv` command line tool.
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    "source",
+                    textwrap.dedent(
+                        """\
+                        A path match defining the source path(s) to be renamed.  The value can use globs
+                        and substitutions.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "target",
+                    textwrap.dedent(
+                        """\
+                        A path defining the target path.  The value *cannot* use globs, but can use
+                        substitution. If the target ends with a literal `/` (prior to substitution),
+                        the target will *always* be a directory.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "move-transformation-rule-move"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        TransformationRule,
+        "remove",
+        TransformationRemoveRuleSpec,
+        _transformation_remove_handler,
+        source_format=_with_alt_form(TransformationRemoveRuleInputFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Remove transformation rule (`remove`)",
+            description=textwrap.dedent(
+                """\
+                The remove transformation rule is mostly only useful for single binary source packages,
+                where everything from upstream's build system is installed automatically into the package.
+                In those case, you might find yourself with some files that are _not_ relevant for the
+                Debian package (but would be relevant for other distros or for non-distro local builds).
+                Common examples include `INSTALL` files or `LICENSE` files (when they are just a subset
+                of `debian/copyright`).
+
+                In the manifest, you can ask `debputy` to remove paths from the debian package by using
+                the `remove` transformation rule.
+
+                Note that `remove` removes paths from future glob matches and transformation rules.
+        """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+            When the input is a string or a list of string, then that value is used as shorthand
+            for `path` or `paths` (respectively).
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["path", "paths"],
+                    textwrap.dedent(
+                        """\
+                        A path match (`path`) or a list of path matches (`paths`) defining the
+                        path(s) inside the package that should be removed. The path match(es)
+                        can use globs.
+                        - When a symlink is matched, then the symlink (not its target) is removed
+                          as-is.  When a directory is matched, then the directory is removed
+                          along with all the contents.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "keep_empty_parent_dirs",
+                    textwrap.dedent(
+                        """\
+                        A boolean determining whether to prune parent directories that become
+                        empty as a consequence of this rule.  When provided and `true`, this
+                        rule will leave empty directories behind. Otherwise, if this rule
+                        causes a directory to become empty that directory will be removed.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+                This condition will be combined with the built-in condition provided by these rules
+                (rather than replacing it).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "remove-transformation-rule-remove"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        TransformationRule,
+        "create-symlink",
+        CreateSymlinkRule,
+        _transformation_create_symlink,
+        inline_reference_documentation=reference_documentation(
+            title="Create symlinks transformation rule (`create-symlink`)",
+            description=textwrap.dedent(
+                """\
+                Often, the upstream build system will provide the symlinks for you.  However,
+                in some cases, it is useful for the packager to define distribution specific
+                symlinks. This can be done via the `create-symlink` transformation rule.
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    "path",
+                    textwrap.dedent(
+                        """\
+                         The path that should be a symlink.  The path may contain substitution
+                         variables such as `{{DEB_HOST_MULTIARCH}}` but _cannot_ use globs.
+                         Parent directories are implicitly created as necessary.
+                         * Note that if `path` already exists, the behaviour of this
+                           transformation depends on the value of `replacement-rule`.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "target",
+                    textwrap.dedent(
+                        """\
+                        Where the symlink should point to. The target may contain substitution
+                        variables such as `{{DEB_HOST_MULTIARCH}}` but _cannot_ use globs.
+                        The link target is _not_ required to exist inside the package.
+                        * The `debputy` tool will normalize the target according to the rules
+                          of the Debian Policy.  Use absolute or relative target at your own
+                          preference.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "replacement_rule",
+                    textwrap.dedent(
+                        """\
+                        This attribute defines how to handle if `path` already exists. It can
+                        be set to one of the following values:
+                           - `error-if-exists`: When `path` already exists, `debputy` will
+                              stop with an error.  This is similar to `ln -s` semantics.
+                           - `error-if-directory`: When `path` already exists, **and** it is
+                              a directory, `debputy` will stop with an error. Otherwise,
+                              remove the `path` first and then create the symlink.  This is
+                              similar to `ln -sf` semantics.
+                           - `abort-on-non-empty-directory` (default): When `path` already
+                              exists, then it will be removed provided it is a non-directory
+                              **or** an *empty* directory and the symlink will then be
+                              created.  If the path is a *non-empty* directory, `debputy`
+                              will stop with an error.
+                           - `discard-existing`: When `path` already exists, it will be
+                              removed. If the `path` is a directory, all its contents will
+                              be removed recursively along with the directory. Finally,
+                              the symlink is created. This is similar to having an explicit
+                              `remove` rule just prior to the `create-symlink` that is
+                              conditional on `path` existing (plus the condition defined in
+                              `when` if any).
+
+                       Keep in mind, that `replacement-rule` only applies if `path` exists.
+                       If the symlink cannot be created, because a part of `path` exist and
+                       is *not* a directory, then `create-symlink` will fail regardless of
+                       the value in `replacement-rule`.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "create-symlinks-transformation-rule-create-symlink"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        TransformationRule,
+        "path-metadata",
+        PathManifestRule,
+        _transformation_path_metadata,
+        source_format=PathManifestSourceDictFormat,
+        inline_reference_documentation=reference_documentation(
+            title="Change path owner/group or mode (`path-metadata`)",
+            description=textwrap.dedent(
+                """\
+                The `debputy` command normalizes the path metadata (such as ownership and mode) similar
+                to `dh_fixperms`.  For most packages, the default is what you want.  However, in some
+                cases, the package has a special case or two that `debputy` does not cover.  In that
+                case, you can tell `debputy` to use the metadata you want by using the `path-metadata`
+                transformation.
+
+                Common use-cases include setuid/setgid binaries (such `usr/bin/sudo`) or/and static
+                ownership (such as /usr/bin/write).
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["path", "paths"],
+                    textwrap.dedent(
+                        """\
+                         A path match (`path`) or a list of path matches (`paths`) defining the path(s)
+                         inside the package that should be affected. The path match(es) can use globs
+                         and substitution variables. Special-rules for matches:
+                         - Symlinks are never followed and will never be matched by this rule.
+                         - Directory handling depends on the `recursive` attribute.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "owner",
+                    textwrap.dedent(
+                        """\
+                         Denotes the owner of the paths matched by `path` or `paths`. When omitted,
+                         no change of owner is done.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "group",
+                    textwrap.dedent(
+                        """\
+                         Denotes the group of the paths matched by `path` or `paths`. When omitted,
+                         no change of group is done.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "mode",
+                    textwrap.dedent(
+                        """\
+                         Denotes the mode of the paths matched by `path` or `paths`. When omitted,
+                         no change in mode is done. Note that numeric mode must always be given as
+                         a string (i.e., with quotes).  Symbolic mode can be used as well. If
+                         symbolic mode uses a relative definition (e.g., `o-rx`), then it is
+                         relative to the matched path's current mode.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "capabilities",
+                    textwrap.dedent(
+                        """\
+                         Denotes a Linux capability that should be applied to the path. When provided,
+                         `debputy` will cause the capability to be applied to all *files* denoted by
+                         the `path`/`paths` attribute on install (via `postinst configure`) provided
+                         that `setcap` is installed on the system when the `postinst configure` is
+                         run.
+                         - If any non-file paths are matched, the `capabilities` will *not* be applied
+                           to those paths.
+
+            """
+                    ),
+                ),
+                documented_attr(
+                    "capability_mode",
+                    textwrap.dedent(
+                        """\
+                        Denotes the mode to apply to the path *if* the Linux capability denoted in
+                       `capabilities` was successfully applied. If omitted, it defaults to `a-s` as
+                       generally capabilities are used to avoid "setuid"/"setgid" binaries. The
+                       `capability-mode` is relative to the *final* path mode (the mode of the path
+                       in the produced `.deb`). The `capability-mode` attribute cannot be used if
+                       `capabilities` is omitted.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "recursive",
+                    textwrap.dedent(
+                        """\
+                        When a directory is matched, then the metadata changes are applied to the
+                        directory itself. When `recursive` is `true`, then the transformation is
+                        *also* applied to all paths beneath the directory. The default value for
+                        this attribute is `false`.
+            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "change-path-ownergroup-or-mode-path-metadata"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        TransformationRule,
+        "create-directories",
+        EnsureDirectoryRule,
+        _transformation_mkdirs,
+        source_format=_with_alt_form(EnsureDirectorySourceFormat),
+        inline_reference_documentation=reference_documentation(
+            title="Create directories transformation rule (`create-directories`)",
+            description=textwrap.dedent(
+                """\
+                NOTE: This transformation is only really needed if you need to create an empty
+                directory somewhere in your package as an integration point.  All `debputy`
+                transformations will create directories as required.
+
+                In most cases, upstream build systems and `debputy` will create all the relevant
+                directories.  However, in some rare cases you may want to explicitly define a path
+                to be a directory.  Maybe to silence a linter that is warning you about a directory
+                being empty, or maybe you need an empty directory that nothing else is creating for
+                you. This can be done via the `create-directories` transformation rule.
+
+                Unless you have a specific need for the mapping form, you are recommended to use the
+                shorthand form of just listing the directories you want created.
+        """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+            When the input is a string or a list of string, then that value is used as shorthand
+            for `path` or `paths` (respectively).
+        """
+            ),
+            attributes=[
+                documented_attr(
+                    ["path", "paths"],
+                    textwrap.dedent(
+                        """\
+                        A path (`path`) or a list of path (`paths`) defining the path(s) inside the
+                        package that should be created as directories. The path(es) _cannot_ use globs
+                        but can use substitution variables.  Parent directories are implicitly created
+                        (with owner `root:root` and mode `0755` - only explicitly listed directories
+                        are affected by the owner/mode options)
+            """
+                    ),
+                ),
+                documented_attr(
+                    "owner",
+                    textwrap.dedent(
+                        """\
+                         Denotes the owner of the directory (but _not_ what is inside the directory).
+                         Default is "root".
+            """
+                    ),
+                ),
+                documented_attr(
+                    "group",
+                    textwrap.dedent(
+                        """\
+                        Denotes the group of the directory (but _not_ what is inside the directory).
+                        Default is "root".
+            """
+                    ),
+                ),
+                documented_attr(
+                    "mode",
+                    textwrap.dedent(
+                        """\
+                         Denotes the mode of the directory (but _not_ what is inside the directory).
+                         Note that numeric mode must always be given as a string (i.e., with quotes).
+                         Symbolic mode can be used as well. If symbolic mode uses a relative
+                         definition (e.g., `o-rx`), then it is relative to the directory's current mode
+                         (if it already exists) or `0755` if the directory is created by this
+                         transformation.  The default is "0755".
+            """
+                    ),
+                ),
+                documented_attr(
+                    "when",
+                    textwrap.dedent(
+                        """\
+                A condition as defined in [Conditional rules]({MANIFEST_FORMAT_DOC}#Conditional rules).
+            """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "create-directories-transformation-rule-directories"
+            ),
+        ),
+    )
+
+
+def register_manifest_condition_rules(api: DebputyPluginInitializerProvider) -> None:
+    api.provide_manifest_keyword(
+        ManifestCondition,
+        "cross-compiling",
+        lambda *_: ManifestCondition.is_cross_building(),
+        inline_reference_documentation=reference_documentation(
+            title="Cross-Compiling condition `cross-compiling`",
+            description=textwrap.dedent(
+                """\
+                The `cross-compiling` condition is used to determine if the current build is
+                performing a cross build (i.e., `DEB_BUILD_GNU_TYPE` != `DEB_HOST_GNU_TYPE`).
+                Often this has consequences for what is possible to do.
+
+                Note if you specifically want to know:
+
+                 * whether build-time tests should be run, then please use the
+                   `run-build-time-tests` condition.
+                 * whether compiled binaries can be run as if it was a native binary, please
+                   use the `can-execute-compiled-binaries` condition instead.  That condition
+                   accounts for cross-building in its evaluation.
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "cross-compiling-condition-cross-compiling-string"
+            ),
+        ),
+    )
+    api.provide_manifest_keyword(
+        ManifestCondition,
+        "can-execute-compiled-binaries",
+        lambda *_: ManifestCondition.can_execute_compiled_binaries(),
+        inline_reference_documentation=reference_documentation(
+            title="Can run produced binaries `can-execute-compiled-binaries`",
+            description=textwrap.dedent(
+                """\
+                The `can-execute-compiled-binaries` condition is used to assert the build
+                can assume that all compiled binaries can be run as-if they were native
+                binaries. For native builds, this condition always evaluates to `true`.
+                For cross builds, the condition is generally evaluates to `false`.  However,
+                there are special-cases where binaries can be run during cross-building.
+                Accordingly, this condition is subtly different from the `cross-compiling`
+                condition.
+
+                Note this condition should *not* be used when you know the binary has been
+                built for the build architecture (`DEB_BUILD_ARCH`) or for determining
+                whether build-time tests should be run (for build-time tests, please use
+                the `run-build-time-tests` condition instead). Some upstream build systems
+                are advanced enough to distinguish building a final product vs. building
+                a helper tool that needs to run during build.  The latter will often be
+                compiled by a separate compiler (often using `$(CC_FOR_BUILD)`,
+                `cc_for_build` or similar variable names in upstream build systems for
+                that compiler).
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "can-run-produced-binaries-can-execute-compiled-binaries-string"
+            ),
+        ),
+    )
+    api.provide_manifest_keyword(
+        ManifestCondition,
+        "run-build-time-tests",
+        lambda *_: ManifestCondition.run_build_time_tests(),
+        inline_reference_documentation=reference_documentation(
+            title="Whether build time tests should be run `run-build-time-tests`",
+            description=textwrap.dedent(
+                """\
+                The `run-build-time-tests` condition is used to determine whether (build
+                time) tests should be run for this build.  This condition roughly
+                translates into whether `nocheck` is present in `DEB_BUILD_OPTIONS`.
+
+                In general, the manifest *should not* prevent build time tests from being
+                run during cross-builds.
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "whether-build-time-tests-should-be-run-run-build-time-tests-string"
+            ),
+        ),
+    )
+
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        "not",
+        MCNot,
+        _mc_not,
+        inline_reference_documentation=reference_documentation(
+            title="Negated condition `not` (mapping)",
+            description=textwrap.dedent(
+                """\
+                    It is possible to negate a condition via the `not` condition.
+
+                    As an example:
+
+                        packages:
+                            util-linux:
+                                transformations:
+                                - create-symlink
+                                      path: sbin/getty
+                                      target: /sbin/agetty
+                                      when:
+                                          # On Hurd, the package "hurd" ships "sbin/getty".
+                                          # This example happens to also be alternative to `arch-marches: '!hurd-any`
+                                          not:
+                                              arch-matches: 'hurd-any'
+
+                    The `not` condition is specified as a mapping, where the key is `not` and the
+                    value is a nested condition.
+                """
+            ),
+            attributes=[
+                documented_attr(
+                    "negated_condition",
+                    textwrap.dedent(
+                        """\
+                        The condition to be negated.
+                        """
+                    ),
+                ),
+            ],
+            reference_documentation_url=_manifest_format_doc(
+                "whether-build-time-tests-should-be-run-run-build-time-tests-string"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        ["any-of", "all-of"],
+        MCAnyOfAllOf,
+        _mc_any_of,
+        source_format=List[ManifestCondition],
+        inline_reference_documentation=reference_documentation(
+            title="All or any of a list of conditions `all-of`/`any-of`",
+            description=textwrap.dedent(
+                """\
+                It is possible to aggregate conditions using the `all-of` or `any-of`
+                condition. This provide `X and Y` and `X or Y` semantics (respectively).
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "all-or-any-of-a-list-of-conditions-all-ofany-of-list"
+            ),
+        ),
+    )
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        "arch-matches",
+        MCArchMatches,
+        _mc_arch_matches,
+        source_format=str,
+        inline_reference_documentation=reference_documentation(
+            title="Architecture match condition `arch-matches`",
+            description=textwrap.dedent(
+                """\
+                Sometimes, a rule needs to be conditional on the architecture.
+                This can be done by using the `arch-matches` rule. In 99.99%
+                of the cases, `arch-matches` will be form you are looking for
+                and practically behaves like a comparison against
+                `dpkg-architecture -qDEB_HOST_ARCH`.
+
+                For the cross-compiling specialists or curious people: The
+                `arch-matches` rule behaves like a `package-context-arch-matches`
+                in the context of a binary package and like
+                `source-context-arch-matches` otherwise. The details of those
+                are covered in their own keywords.
+                """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+                The value must be a string in the form of a space separated list
+                architecture names or architecture wildcards (same syntax as the
+                architecture restriction in Build-Depends in debian/control except
+                there is no enclosing `[]` brackets). The names/wildcards can
+                optionally be prefixed by `!` to negate them.  However, either
+                *all* names / wildcards must have negation or *none* of them may
+                have it.
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "architecture-match-condition-arch-matches-mapping"
+            ),
+        ),
+    )
+
+    context_arch_doc = reference_documentation(
+        title="Explicit source or binary package context architecture match condition"
+        " `source-context-arch-matches`, `package-context-arch-matches` (mapping)",
+        description=textwrap.dedent(
+            """\
+            **These are special-case conditions**. Unless you know that you have a very special-case,
+            you should probably use `arch-matches` instead. These conditions are aimed at people with
+            corner-case special architecture needs. It also assumes the reader is familiar with the
+            `arch-matches` condition.
+
+            To understand these rules, here is a quick primer on `debputy`'s concept of "source context"
+            vs "(binary) package context" architecture.  For a native build, these two contexts are the
+            same except that in the package context an `Architecture: all` package always resolve to
+            `all` rather than `DEB_HOST_ARCH`. As a consequence, `debputy` forbids `arch-matches` and
+            `package-context-arch-matches` in the context of an `Architecture: all` package as a warning
+            to the packager that condition does not make sense.
+
+            In the very rare case that you need an architecture condition for an `Architecture: all` package,
+            you can use `source-context-arch-matches`. However, this means your `Architecture: all` package
+            is not reproducible between different build hosts (which has known to be relevant for some
+            very special cases).
+
+            Additionally, for the 0.0001% case you are building a cross-compiling compiler (that is,
+            `DEB_HOST_ARCH != DEB_TARGET_ARCH` and you are working with `gcc` or similar) `debputy` can be
+            instructed (opt-in) to use `DEB_TARGET_ARCH` rather than `DEB_HOST_ARCH` for certain packages when
+            evaluating an architecture condition in context of a binary package. This can be useful if the
+            compiler produces supporting libraries that need to be built for the `DEB_TARGET_ARCH` rather than
+            the `DEB_HOST_ARCH`.  This is where `arch-matches` or `package-context-arch-matches` can differ
+            subtly from `source-context-arch-matches` in how they evaluate the condition.  This opt-in currently
+            relies on setting `X-DH-Build-For-Type: target` for each of the relevant packages in
+            `debian/control`.  However, unless you are a cross-compiling specialist, you will probably never
+            need to care about nor use any of this.
+
+            Accordingly, the possible conditions are:
+
+             * `arch-matches`: This is the form recommended to laymen and as the default use-case. This
+               conditional acts `package-context-arch-matches` if the condition is used in the context
+               of a binary package. Otherwise, it acts as `source-context-arch-matches`.
+
+             * `source-context-arch-matches`: With this conditional, the provided architecture constraint is compared
+               against the build time provided host architecture (`dpkg-architecture -qDEB_HOST_ARCH`). This can
+               be useful when an `Architecture: all` package needs an architecture condition for some reason.
+
+             * `package-context-arch-matches`: With this conditional, the provided architecture constraint is compared
+               against the package's resolved architecture. This condition can only be used in the context of a binary
+               package (usually, under `packages.<name>.`).  If the package is an `Architecture: all` package, the
+               condition will fail with an error as the condition always have the same outcome. For all other
+               packages, the package's resolved architecture is the same as the build time provided host architecture
+               (`dpkg-architecture -qDEB_HOST_ARCH`).
+
+               - However, as noted above there is a special case for when compiling a cross-compiling compiler, where
+                 this behaves subtly different from `source-context-arch-matches`.
+
+            All conditions are used the same way as `arch-matches`. Simply replace `arch-matches` with the other
+            condition. See the `arch-matches` description for an example.
+            """
+        ),
+        non_mapping_description=textwrap.dedent(
+            """\
+            The value must be a string in the form of a space separated list
+            architecture names or architecture wildcards (same syntax as the
+            architecture restriction in Build-Depends in debian/control except
+            there is no enclosing `[]` brackets). The names/wildcards can
+            optionally be prefixed by `!` to negate them.  However, either
+            *all* names / wildcards must have negation or *none* of them may
+            have it.
+            """
+        ),
+    )
+
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        "source-context-arch-matches",
+        MCArchMatches,
+        _mc_source_context_arch_matches,
+        source_format=str,
+        inline_reference_documentation=context_arch_doc,
+    )
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        "package-context-arch-matches",
+        MCArchMatches,
+        _mc_arch_matches,
+        source_format=str,
+        inline_reference_documentation=context_arch_doc,
+    )
+    api.plugable_manifest_rule(
+        ManifestCondition,
+        "build-profiles-matches",
+        MCBuildProfileMatches,
+        _mc_build_profile_matches,
+        source_format=str,
+        inline_reference_documentation=reference_documentation(
+            title="Active build profile match condition `build-profiles-matches`",
+            description=textwrap.dedent(
+                """\
+                The `build-profiles-matches` condition is used to assert whether the
+                active build profiles (`DEB_BUILD_PROFILES` / `dpkg-buildpackage -P`)
+                matches a given build profile restriction.
+                """
+            ),
+            non_mapping_description=textwrap.dedent(
+                """\
+                The value is a string using the same syntax as the `Build-Profiles`
+                field from `debian/control` (i.e., a space separated list of
+                `<[!]profile ...>` groups).
+                """
+            ),
+            reference_documentation_url=_manifest_format_doc(
+                "active-build-profile-match-condition-build-profiles-matches-mapping"
+            ),
+        ),
+    )
+
+
+def register_dpkg_conffile_rules(api: DebputyPluginInitializerProvider) -> None:
+    api.plugable_manifest_rule(
+        DpkgMaintscriptHelperCommand,
+        "remove",
+        DpkgRemoveConffileRule,
+        _dpkg_conffile_remove,
+        inline_reference_documentation=None,  # TODO: write and add
+    )
+
+    api.plugable_manifest_rule(
+        DpkgMaintscriptHelperCommand,
+        "rename",
+        DpkgRenameConffileRule,
+        _dpkg_conffile_rename,
+        inline_reference_documentation=None,  # TODO: write and add
+    )
+
+
+class _ModeOwnerBase(DebputyParsedContentStandardConditional):
+    mode: NotRequired[FileSystemMode]
+    owner: NotRequired[StaticFileSystemOwner]
+    group: NotRequired[StaticFileSystemGroup]
+
+
+class PathManifestSourceDictFormat(_ModeOwnerBase):
+    path: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("paths")]
+    ]
+    paths: NotRequired[List[FileSystemMatchRule]]
+    recursive: NotRequired[bool]
+    capabilities: NotRequired[str]
+    capability_mode: NotRequired[FileSystemMode]
+
+
+class PathManifestRule(_ModeOwnerBase):
+    paths: List[FileSystemMatchRule]
+    recursive: NotRequired[bool]
+    capabilities: NotRequired[str]
+    capability_mode: NotRequired[FileSystemMode]
+
+
+class EnsureDirectorySourceFormat(_ModeOwnerBase):
+    path: NotRequired[
+        Annotated[FileSystemExactMatchRule, DebputyParseHint.target_attribute("paths")]
+    ]
+    paths: NotRequired[List[FileSystemExactMatchRule]]
+
+
+class EnsureDirectoryRule(_ModeOwnerBase):
+    paths: List[FileSystemExactMatchRule]
+
+
+class CreateSymlinkRule(DebputyParsedContentStandardConditional):
+    path: FileSystemExactMatchRule
+    target: Annotated[SymlinkTarget, DebputyParseHint.not_path_error_hint()]
+    replacement_rule: NotRequired[CreateSymlinkReplacementRule]
+
+
+class TransformationMoveRuleSpec(DebputyParsedContentStandardConditional):
+    source: FileSystemMatchRule
+    target: FileSystemExactMatchRule
+
+
+class TransformationRemoveRuleSpec(DebputyParsedContentStandardConditional):
+    paths: List[FileSystemMatchRule]
+    keep_empty_parent_dirs: NotRequired[bool]
+
+
+class TransformationRemoveRuleInputFormat(DebputyParsedContentStandardConditional):
+    path: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("paths")]
+    ]
+    paths: NotRequired[List[FileSystemMatchRule]]
+    keep_empty_parent_dirs: NotRequired[bool]
+
+
+class ParsedInstallRuleSourceFormat(DebputyParsedContentStandardConditional):
+    sources: NotRequired[List[FileSystemMatchRule]]
+    source: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("sources")]
+    ]
+    into: NotRequired[
+        Annotated[
+            Union[str, List[str]],
+            DebputyParseHint.required_when_multi_binary(),
+        ]
+    ]
+    dest_dir: NotRequired[
+        Annotated[FileSystemExactMatchRule, DebputyParseHint.not_path_error_hint()]
+    ]
+    install_as: NotRequired[
+        Annotated[
+            FileSystemExactMatchRule,
+            DebputyParseHint.conflicts_with_source_attributes("sources", "dest_dir"),
+            DebputyParseHint.manifest_attribute("as"),
+            DebputyParseHint.not_path_error_hint(),
+        ]
+    ]
+
+
+class ParsedInstallDocRuleSourceFormat(DebputyParsedContentStandardConditional):
+    sources: NotRequired[List[FileSystemMatchRule]]
+    source: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("sources")]
+    ]
+    into: NotRequired[
+        Annotated[
+            Union[str, List[str]],
+            DebputyParseHint.required_when_multi_binary(package_type="deb"),
+        ]
+    ]
+    dest_dir: NotRequired[
+        Annotated[FileSystemExactMatchRule, DebputyParseHint.not_path_error_hint()]
+    ]
+    install_as: NotRequired[
+        Annotated[
+            FileSystemExactMatchRule,
+            DebputyParseHint.conflicts_with_source_attributes("sources", "dest_dir"),
+            DebputyParseHint.manifest_attribute("as"),
+            DebputyParseHint.not_path_error_hint(),
+        ]
+    ]
+
+
+class ParsedInstallRule(DebputyParsedContentStandardConditional):
+    sources: List[FileSystemMatchRule]
+    into: NotRequired[List[BinaryPackage]]
+    dest_dir: NotRequired[FileSystemExactMatchRule]
+    install_as: NotRequired[FileSystemExactMatchRule]
+
+
+class ParsedMultiDestInstallRuleSourceFormat(DebputyParsedContentStandardConditional):
+    sources: NotRequired[List[FileSystemMatchRule]]
+    source: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("sources")]
+    ]
+    into: NotRequired[
+        Annotated[
+            Union[str, List[str]],
+            DebputyParseHint.required_when_multi_binary(),
+        ]
+    ]
+    dest_dirs: NotRequired[
+        Annotated[
+            List[FileSystemExactMatchRule], DebputyParseHint.not_path_error_hint()
+        ]
+    ]
+    install_as: NotRequired[
+        Annotated[
+            List[FileSystemExactMatchRule],
+            DebputyParseHint.conflicts_with_source_attributes("sources", "dest_dirs"),
+            DebputyParseHint.not_path_error_hint(),
+            DebputyParseHint.manifest_attribute("as"),
+        ]
+    ]
+
+
+class ParsedMultiDestInstallRule(DebputyParsedContentStandardConditional):
+    sources: List[FileSystemMatchRule]
+    into: NotRequired[List[BinaryPackage]]
+    dest_dirs: NotRequired[List[FileSystemExactMatchRule]]
+    install_as: NotRequired[List[FileSystemExactMatchRule]]
+
+
+class ParsedInstallExamplesRule(DebputyParsedContentStandardConditional):
+    sources: List[FileSystemMatchRule]
+    into: NotRequired[List[BinaryPackage]]
+
+
+class ParsedInstallExamplesRuleSourceFormat(DebputyParsedContentStandardConditional):
+    sources: NotRequired[List[FileSystemMatchRule]]
+    source: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("sources")]
+    ]
+    into: NotRequired[
+        Annotated[
+            Union[str, List[str]],
+            DebputyParseHint.required_when_multi_binary(package_type="deb"),
+        ]
+    ]
+
+
+class ParsedInstallManpageRule(DebputyParsedContentStandardConditional):
+    sources: List[FileSystemMatchRule]
+    language: NotRequired[str]
+    section: NotRequired[int]
+    into: NotRequired[List[BinaryPackage]]
+
+
+class ParsedInstallManpageRuleSourceFormat(DebputyParsedContentStandardConditional):
+    sources: NotRequired[List[FileSystemMatchRule]]
+    source: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("sources")]
+    ]
+    language: NotRequired[str]
+    section: NotRequired[int]
+    into: NotRequired[
+        Annotated[
+            Union[str, List[str]],
+            DebputyParseHint.required_when_multi_binary(package_type="deb"),
+        ]
+    ]
+
+
+class ParsedInstallDiscardRuleSourceFormat(DebputyParsedContent):
+    paths: NotRequired[List[FileSystemMatchRule]]
+    path: NotRequired[
+        Annotated[FileSystemMatchRule, DebputyParseHint.target_attribute("paths")]
+    ]
+    search_dir: NotRequired[
+        Annotated[
+            FileSystemExactMatchRule, DebputyParseHint.target_attribute("search_dirs")
+        ]
+    ]
+    search_dirs: NotRequired[List[FileSystemExactMatchRule]]
+    required_when: NotRequired[ManifestCondition]
+
+
+class ParsedInstallDiscardRule(DebputyParsedContent):
+    paths: List[FileSystemMatchRule]
+    search_dirs: NotRequired[List[FileSystemExactMatchRule]]
+    required_when: NotRequired[ManifestCondition]
+
+
+class DpkgConffileManagementRuleBase(DebputyParsedContent):
+    prior_to_version: NotRequired[str]
+    owning_package: NotRequired[str]
+
+
+class DpkgRenameConffileRule(DpkgConffileManagementRuleBase):
+    source: str
+    target: str
+
+
+class DpkgRemoveConffileRule(DpkgConffileManagementRuleBase):
+    path: str
+
+
+class MCAnyOfAllOf(DebputyParsedContent):
+    conditions: List[ManifestCondition]
+
+
+class MCNot(DebputyParsedContent):
+    negated_condition: Annotated[
+        ManifestCondition, DebputyParseHint.manifest_attribute("not")
+    ]
+
+
+class MCArchMatches(DebputyParsedContent):
+    arch_matches: str
+
+
+class MCBuildProfileMatches(DebputyParsedContent):
+    build_profile_matches: str
+
+
+def _parse_filename(
+    filename: str,
+    attribute_path: AttributePath,
+    *,
+    allow_directories: bool = True,
+) -> str:
+    try:
+        normalized_path = _normalize_path(filename, with_prefix=False)
+    except ValueError as e:
+        raise ManifestParseException(
+            f'Error parsing the path "{filename}" defined in {attribute_path.path}: {e.args[0]}'
+        ) from None
+    if not allow_directories and filename.endswith("/"):
+        raise ManifestParseException(
+            f'The path "{filename}" in {attribute_path.path} ends with "/" implying it is a directory,'
+            f" but this feature can only be used for files"
+        )
+    if normalized_path == ".":
+        raise ManifestParseException(
+            f'The path "{filename}" in {attribute_path.path} looks like the root directory,'
+            f" but this feature does not allow the root directory here."
+        )
+    return normalized_path
+
+
+def _with_alt_form(t: Type[TypedDict]):
+    return Union[
+        t,
+        List[str],
+        str,
+    ]
+
+
+def _dpkg_conffile_rename(
+    _name: str,
+    parsed_data: DpkgRenameConffileRule,
+    path: AttributePath,
+    _context: ParserContextData,
+) -> DpkgMaintscriptHelperCommand:
+    source_file = parsed_data["source"]
+    target_file = parsed_data["target"]
+    normalized_source = _parse_filename(
+        source_file,
+        path["source"],
+        allow_directories=False,
+    )
+    path.path_hint = source_file
+
+    normalized_target = _parse_filename(
+        target_file,
+        path["target"],
+        allow_directories=False,
+    )
+    normalized_source = "/" + normalized_source
+    normalized_target = "/" + normalized_target
+
+    if normalized_source == normalized_target:
+        raise ManifestParseException(
+            f"Invalid rename defined in {path.path}: The source and target path are the same!"
+        )
+
+    version, owning_package = _parse_conffile_prior_version_and_owning_package(
+        parsed_data, path
+    )
+    return DpkgMaintscriptHelperCommand.mv_conffile(
+        path,
+        normalized_source,
+        normalized_target,
+        version,
+        owning_package,
+    )
+
+
+def _dpkg_conffile_remove(
+    _name: str,
+    parsed_data: DpkgRemoveConffileRule,
+    path: AttributePath,
+    _context: ParserContextData,
+) -> DpkgMaintscriptHelperCommand:
+    source_file = parsed_data["path"]
+    normalized_source = _parse_filename(
+        source_file,
+        path["path"],
+        allow_directories=False,
+    )
+    path.path_hint = source_file
+
+    normalized_source = "/" + normalized_source
+
+    version, owning_package = _parse_conffile_prior_version_and_owning_package(
+        parsed_data, path
+    )
+    return DpkgMaintscriptHelperCommand.rm_conffile(
+        path,
+        normalized_source,
+        version,
+        owning_package,
+    )
+
+
+def _parse_conffile_prior_version_and_owning_package(
+    d: DpkgConffileManagementRuleBase,
+    attribute_path: AttributePath,
+) -> Tuple[Optional[str], Optional[str]]:
+    prior_version = d.get("prior_to_version")
+    owning_package = d.get("owning_package")
+
+    if prior_version is not None and not PKGVERSION_REGEX.match(prior_version):
+        p = attribute_path["prior_to_version"]
+        raise ManifestParseException(
+            f"The {MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION} parameter in {p.path} must be a"
+            r" valid package version (i.e., match (?:\d+:)?\d[0-9A-Za-z.+:~]*(?:-[0-9A-Za-z.+:~]+)*)."
+        )
+
+    if owning_package is not None and not PKGNAME_REGEX.match(owning_package):
+        p = attribute_path["owning_package"]
+        raise ManifestParseException(
+            f"The {MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE} parameter in {p.path} must be a valid"
+            f" package name (i.e., match {PKGNAME_REGEX.pattern})."
+        )
+
+    return prior_version, owning_package
+
+
+def _install_rule_handler(
+    _name: str,
+    parsed_data: ParsedInstallRule,
+    path: AttributePath,
+    context: ParserContextData,
+) -> InstallRule:
+    sources = parsed_data["sources"]
+    install_as = parsed_data.get("install_as")
+    into = parsed_data.get("into")
+    dest_dir = parsed_data.get("dest_dir")
+    condition = parsed_data.get("when")
+    if not into:
+        into = [context.single_binary_package(path, package_attribute="into")]
+    into = frozenset(into)
+    if install_as is not None:
+        assert len(sources) == 1
+        assert dest_dir is None
+        return InstallRule.install_as(
+            sources[0],
+            install_as.match_rule.path,
+            into,
+            path.path,
+            condition,
+        )
+    return InstallRule.install_dest(
+        sources,
+        dest_dir.match_rule.path if dest_dir is not None else None,
+        into,
+        path.path,
+        condition,
+    )
+
+
+def _multi_dest_install_rule_handler(
+    _name: str,
+    parsed_data: ParsedMultiDestInstallRule,
+    path: AttributePath,
+    context: ParserContextData,
+) -> InstallRule:
+    sources = parsed_data["sources"]
+    install_as = parsed_data.get("install_as")
+    into = parsed_data.get("into")
+    dest_dirs = parsed_data.get("dest_dirs")
+    condition = parsed_data.get("when")
+    if not into:
+        into = [context.single_binary_package(path, package_attribute="into")]
+    into = frozenset(into)
+    if install_as is not None:
+        assert len(sources) == 1
+        assert dest_dirs is None
+        if len(install_as) < 2:
+            raise ManifestParseException(
+                f"The {path['install_as'].path} attribute must contain at least two paths."
+            )
+        return InstallRule.install_multi_as(
+            sources[0],
+            [p.match_rule.path for p in install_as],
+            into,
+            path.path,
+            condition,
+        )
+    if dest_dirs is None:
+        raise ManifestParseException(
+            f"Either the `as` or the `dest-dirs` key must be provided at {path.path}"
+        )
+    if len(dest_dirs) < 2:
+        raise ManifestParseException(
+            f"The {path['dest_dirs'].path} attribute must contain at least two paths."
+        )
+    return InstallRule.install_multi_dest(
+        sources,
+        [dd.match_rule.path for dd in dest_dirs],
+        into,
+        path.path,
+        condition,
+    )
+
+
+def _install_docs_rule_handler(
+    _name: str,
+    parsed_data: ParsedInstallRule,
+    path: AttributePath,
+    context: ParserContextData,
+) -> InstallRule:
+    sources = parsed_data["sources"]
+    install_as = parsed_data.get("install_as")
+    into = parsed_data.get("into")
+    dest_dir = parsed_data.get("dest_dir")
+    condition = parsed_data.get("when")
+    if not into:
+        into = [
+            context.single_binary_package(
+                path, package_type="deb", package_attribute="into"
+            )
+        ]
+    into = frozenset(into)
+    if install_as is not None:
+        assert len(sources) == 1
+        assert dest_dir is None
+        return InstallRule.install_doc_as(
+            sources[0],
+            install_as.match_rule.path,
+            into,
+            path.path,
+            condition,
+        )
+    return InstallRule.install_doc(
+        sources,
+        dest_dir,
+        into,
+        path.path,
+        condition,
+    )
+
+
+def _install_examples_rule_handler(
+    _name: str,
+    parsed_data: ParsedInstallExamplesRule,
+    path: AttributePath,
+    context: ParserContextData,
+) -> InstallRule:
+    sources = parsed_data["sources"]
+    into = parsed_data.get("into")
+    if not into:
+        into = [
+            context.single_binary_package(
+                path, package_type="deb", package_attribute="into"
+            )
+        ]
+    condition = parsed_data.get("when")
+    into = frozenset(into)
+    return InstallRule.install_examples(
+        sources,
+        into,
+        path.path,
+        condition,
+    )
+
+
+def _install_man_rule_handler(
+    _name: str,
+    parsed_data: ParsedInstallManpageRule,
+    attribute_path: AttributePath,
+    context: ParserContextData,
+) -> InstallRule:
+    sources = parsed_data["sources"]
+    language = parsed_data.get("language")
+    section = parsed_data.get("section")
+
+    if language is not None:
+        is_lang_ok = language in (
+            "C",
+            "derive-from-basename",
+            "derive-from-path",
+        )
+
+        if not is_lang_ok and len(language) == 2 and language.islower():
+            is_lang_ok = True
+
+        if (
+            not is_lang_ok
+            and len(language) == 5
+            and language[2] == "_"
+            and language[:2].islower()
+            and language[3:].isupper()
+        ):
+            is_lang_ok = True
+
+        if not is_lang_ok:
+            raise ManifestParseException(
+                f'The language attribute must in a 2-letter language code ("de"), a 5-letter language + dialect'
+                f' code ("pt_BR"), "derive-from-basename", "derive-from-path", or omitted.  The problematic'
+                f' definition is {attribute_path["language"]}'
+            )
+
+    if section is not None and (section < 1 or section > 10):
+        raise ManifestParseException(
+            f"The section attribute must in the range [1-9] or omitted.  The problematic definition is"
+            f' {attribute_path["section"]}'
+        )
+    if section is None and any(s.raw_match_rule.endswith(".gz") for s in sources):
+        raise ManifestParseException(
+            "Sorry, compressed manpages are not supported without an explicit `section` definition at the moment."
+            " This limitation may be removed in the future.  Problematic definition from"
+            f' {attribute_path["sources"]}'
+        )
+    if any(s.raw_match_rule.endswith("/") for s in sources):
+        raise ManifestParseException(
+            'The install-man rule can only match non-directories.  Therefore, none of the sources can end with "/".'
+            " as that implies the source is for a directory.  Problematic definition from"
+            f' {attribute_path["sources"]}'
+        )
+    into = parsed_data.get("into")
+    if not into:
+        into = [
+            context.single_binary_package(
+                attribute_path, package_type="deb", package_attribute="into"
+            )
+        ]
+    condition = parsed_data.get("when")
+    into = frozenset(into)
+    return InstallRule.install_man(
+        sources,
+        into,
+        section,
+        language,
+        attribute_path.path,
+        condition,
+    )
+
+
+def _install_discard_rule_handler(
+    _name: str,
+    parsed_data: ParsedInstallDiscardRule,
+    path: AttributePath,
+    _context: ParserContextData,
+) -> InstallRule:
+    limit_to = parsed_data.get("search_dirs")
+    if limit_to is not None and not limit_to:
+        p = path["search_dirs"]
+        raise ManifestParseException(f"The {p.path} attribute must not be empty.")
+    condition = parsed_data.get("required_when")
+    return InstallRule.discard_paths(
+        parsed_data["paths"],
+        path.path,
+        condition,
+        limit_to=limit_to,
+    )
+
+
+def _transformation_move_handler(
+    _name: str,
+    parsed_data: TransformationMoveRuleSpec,
+    path: AttributePath,
+    _context: ParserContextData,
+) -> TransformationRule:
+    source_match = parsed_data["source"]
+    target_path = parsed_data["target"].match_rule.path
+    condition = parsed_data.get("when")
+
+    if (
+        isinstance(source_match, ExactFileSystemPath)
+        and source_match.path == target_path
+    ):
+        raise ManifestParseException(
+            f"The transformation rule {path.path} requests a move of {source_match} to"
+            f" {target_path}, which is the same path"
+        )
+    return MoveTransformationRule(
+        source_match.match_rule,
+        target_path,
+        target_path.endswith("/"),
+        path,
+        condition,
+    )
+
+
+def _transformation_remove_handler(
+    _name: str,
+    parsed_data: TransformationRemoveRuleSpec,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> TransformationRule:
+    paths = parsed_data["paths"]
+    keep_empty_parent_dirs = parsed_data.get("keep_empty_parent_dirs", False)
+
+    return RemoveTransformationRule(
+        [m.match_rule for m in paths],
+        keep_empty_parent_dirs,
+        attribute_path,
+    )
+
+
+def _transformation_create_symlink(
+    _name: str,
+    parsed_data: CreateSymlinkRule,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> TransformationRule:
+    link_dest = parsed_data["path"].match_rule.path
+    replacement_rule: CreateSymlinkReplacementRule = parsed_data.get(
+        "replacement_rule",
+        "abort-on-non-empty-directory",
+    )
+    try:
+        link_target = debian_policy_normalize_symlink_target(
+            link_dest,
+            parsed_data["target"].symlink_target,
+        )
+    except ValueError as e:  # pragma: no cover
+        raise AssertionError(
+            "Debian Policy normalization should not raise ValueError here"
+        ) from e
+
+    condition = parsed_data.get("when")
+
+    return CreateSymlinkPathTransformationRule(
+        link_target,
+        link_dest,
+        replacement_rule,
+        attribute_path,
+        condition,
+    )
+
+
+def _transformation_path_metadata(
+    _name: str,
+    parsed_data: PathManifestRule,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> TransformationRule:
+    match_rules = parsed_data["paths"]
+    owner = parsed_data.get("owner")
+    group = parsed_data.get("group")
+    mode = parsed_data.get("mode")
+    recursive = parsed_data.get("recursive", False)
+    capabilities = parsed_data.get("capabilities")
+    capability_mode = parsed_data.get("capability_mode")
+
+    if capabilities is not None:
+        if capability_mode is None:
+            capability_mode = SymbolicMode.parse_filesystem_mode(
+                "a-s",
+                attribute_path["capability-mode"],
+            )
+        validate_cap = check_cap_checker()
+        validate_cap(capabilities, attribute_path["capabilities"].path)
+    elif capability_mode is not None and capabilities is None:
+        raise ManifestParseException(
+            "The attribute capability-mode cannot be provided without capabilities"
+            f" in {attribute_path.path}"
+        )
+    if owner is None and group is None and mode is None and capabilities is None:
+        raise ManifestParseException(
+            "At least one of owner, group, mode, or capabilities must be provided"
+            f" in {attribute_path.path}"
+        )
+    condition = parsed_data.get("when")
+
+    return PathMetadataTransformationRule(
+        [m.match_rule for m in match_rules],
+        owner,
+        group,
+        mode,
+        recursive,
+        capabilities,
+        capability_mode,
+        attribute_path.path,
+        condition,
+    )
+
+
+def _transformation_mkdirs(
+    _name: str,
+    parsed_data: EnsureDirectoryRule,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> TransformationRule:
+    provided_paths = parsed_data["paths"]
+    owner = parsed_data.get("owner")
+    group = parsed_data.get("group")
+    mode = parsed_data.get("mode")
+
+    condition = parsed_data.get("when")
+
+    return CreateDirectoryTransformationRule(
+        [p.match_rule.path for p in provided_paths],
+        owner,
+        group,
+        mode,
+        attribute_path.path,
+        condition,
+    )
+
+
+def _at_least_two(
+    content: List[Any],
+    attribute_path: AttributePath,
+    attribute_name: str,
+) -> None:
+    if len(content) < 2:
+        raise ManifestParseException(
+            f"Must have at least two conditions in {attribute_path[attribute_name].path}"
+        )
+
+
+def _mc_any_of(
+    name: str,
+    parsed_data: MCAnyOfAllOf,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> ManifestCondition:
+    conditions = parsed_data["conditions"]
+    _at_least_two(conditions, attribute_path, "conditions")
+    if name == "any-of":
+        return ManifestCondition.any_of(conditions)
+    assert name == "all-of"
+    return ManifestCondition.all_of(conditions)
+
+
+def _mc_not(
+    _name: str,
+    parsed_data: MCNot,
+    _attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> ManifestCondition:
+    condition = parsed_data["negated_condition"]
+    return condition.negated()
+
+
+def _extract_arch_matches(
+    parsed_data: MCArchMatches,
+    attribute_path: AttributePath,
+) -> List[str]:
+    arch_matches_as_str = parsed_data["arch_matches"]
+    # Can we check arch list for typos? If we do, it must be tight in how close matches it does.
+    # Consider "arm" vs. "armel" (edit distance 2, but both are valid).  Likewise, names often
+    # include a bit indicator "foo", "foo32", "foo64" - all of these have an edit distance of 2
+    # of each other.
+    arch_matches_as_list = arch_matches_as_str.split()
+    attr_path = attribute_path["arch_matches"]
+    if not arch_matches_as_list:
+        raise ManifestParseException(
+            f"The condition at {attr_path.path} must not be empty"
+        )
+
+    if arch_matches_as_list[0].startswith("[") or arch_matches_as_list[-1].endswith(
+        "]"
+    ):
+        raise ManifestParseException(
+            f"The architecture match at {attr_path.path} must be defined without enclosing it with "
+            '"[" or/and "]" brackets'
+        )
+    return arch_matches_as_list
+
+
+def _mc_source_context_arch_matches(
+    _name: str,
+    parsed_data: MCArchMatches,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> ManifestCondition:
+    arch_matches = _extract_arch_matches(parsed_data, attribute_path)
+    return SourceContextArchMatchManifestCondition(arch_matches)
+
+
+def _mc_package_context_arch_matches(
+    name: str,
+    parsed_data: MCArchMatches,
+    attribute_path: AttributePath,
+    context: ParserContextData,
+) -> ManifestCondition:
+    arch_matches = _extract_arch_matches(parsed_data, attribute_path)
+
+    if not context.is_in_binary_package_state:
+        raise ManifestParseException(
+            f'The condition "{name}" at {attribute_path.path} can only be used in the context of a binary package.'
+        )
+
+    package_state = context.current_binary_package_state
+    if package_state.binary_package.is_arch_all:
+        result = context.dpkg_arch_query_table.architecture_is_concerned(
+            "all", arch_matches
+        )
+        attr_path = attribute_path["arch_matches"]
+        raise ManifestParseException(
+            f"The package architecture restriction at {attr_path.path} is applied to the"
+            f' "Architecture: all" package {package_state.binary_package.name}, which does not make sense'
+            f" as the condition will always resolves to `{str(result).lower()}`."
+            f" If you **really** need an architecture specific constraint for this rule, consider using"
+            f' "source-context-arch-matches" instead. However, this is a very rare use-case!'
+        )
+    return BinaryPackageContextArchMatchManifestCondition(arch_matches)
+
+
+def _mc_arch_matches(
+    name: str,
+    parsed_data: MCArchMatches,
+    attribute_path: AttributePath,
+    context: ParserContextData,
+) -> ManifestCondition:
+    if context.is_in_binary_package_state:
+        return _mc_package_context_arch_matches(
+            name, parsed_data, attribute_path, context
+        )
+    return _mc_source_context_arch_matches(name, parsed_data, attribute_path, context)
+
+
+def _mc_build_profile_matches(
+    _name: str,
+    parsed_data: MCBuildProfileMatches,
+    attribute_path: AttributePath,
+    _context: ParserContextData,
+) -> ManifestCondition:
+    build_profile_spec = parsed_data["build_profile_matches"].strip()
+    attr_path = attribute_path["build_profile_matches"]
+    if not build_profile_spec:
+        raise ManifestParseException(
+            f"The condition at {attr_path.path} must not be empty"
+        )
+    try:
+        active_profiles_match(build_profile_spec, frozenset())
+    except ValueError as e:
+        raise ManifestParseException(
+            f"Could not parse the build specification at {attr_path.path}: {e.args[0]}"
+        )
+    return BuildProfileMatch(build_profile_spec)
diff --git a/src/debputy/plugin/debputy/service_management.py b/src/debputy/plugin/debputy/service_management.py
new file mode 100644
index 0000000..1ec8c1b
--- /dev/null
+++ b/src/debputy/plugin/debputy/service_management.py
@@ -0,0 +1,452 @@
+import collections
+import dataclasses
+import os
+import textwrap
+from typing import Dict, List, Literal, Iterable, Sequence
+
+from debputy.packages import BinaryPackage
+from debputy.plugin.api.spec import (
+    ServiceRegistry,
+    VirtualPath,
+    PackageProcessingContext,
+    BinaryCtrlAccessor,
+    ServiceDefinition,
+)
+from debputy.util import _error, assume_not_none
+
+DPKG_ROOT = '"${DPKG_ROOT}"'
+EMPTY_DPKG_ROOT_CONDITION = '[ -z "${DPKG_ROOT}" ]'
+SERVICE_MANAGER_IS_SYSTEMD_CONDITION = "[ -d /run/systemd/system ]"
+
+
+@dataclasses.dataclass(slots=True)
+class SystemdServiceContext:
+    had_install_section: bool
+
+
+@dataclasses.dataclass(slots=True)
+class SystemdUnit:
+    path: VirtualPath
+    names: List[str]
+    type_of_service: str
+    service_scope: str
+    enable_by_default: bool
+    start_by_default: bool
+    had_install_section: bool
+
+
+def detect_systemd_service_files(
+    fs_root: VirtualPath,
+    service_registry: ServiceRegistry[SystemdServiceContext],
+    context: PackageProcessingContext,
+) -> None:
+    pkg = context.binary_package
+    systemd_units = _find_and_analyze_systemd_service_files(pkg, fs_root, "system")
+    for unit in systemd_units:
+        service_registry.register_service(
+            unit.path,
+            unit.names,
+            type_of_service=unit.type_of_service,
+            service_scope=unit.service_scope,
+            enable_by_default=unit.enable_by_default,
+            start_by_default=unit.start_by_default,
+            default_upgrade_rule="restart" if unit.start_by_default else "do-nothing",
+            service_context=SystemdServiceContext(
+                unit.had_install_section,
+            ),
+        )
+
+
+def generate_snippets_for_systemd_units(
+    services: Sequence[ServiceDefinition[SystemdServiceContext]],
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    stop_in_prerm: List[str] = []
+    stop_then_start_scripts = []
+    on_purge = []
+    start_on_install = []
+    action_on_upgrade = collections.defaultdict(list)
+    assert services
+
+    for service_def in services:
+        if service_def.auto_enable_on_install:
+            template = """\
+                if deb-systemd-helper debian-installed {UNITFILE}; then
+                    # The following line should be removed in trixie or trixie+1
+                    deb-systemd-helper unmask {UNITFILE} >/dev/null || true
+
+                    if deb-systemd-helper --quiet was-enabled {UNITFILE}; then
+                        # Create new symlinks, if any.
+                        deb-systemd-helper enable {UNITFILE} >/dev/null || true
+                    fi
+                fi
+
+                # Update the statefile to add new symlinks (if any), which need to be cleaned
+                # up on purge. Also remove old symlinks.
+                deb-systemd-helper update-state {UNITFILE} >/dev/null || true
+            """
+        else:
+            template = """\
+                # The following line should be removed in trixie or trixie+1
+                deb-systemd-helper unmask {UNITFILE} >/dev/null || true
+
+                # was-enabled defaults to true, so new installations run enable.
+                if deb-systemd-helper --quiet was-enabled {UNITFILE}; then
+                    # Enables the unit on first installation, creates new
+                    # symlinks on upgrades if the unit file has changed.
+                    deb-systemd-helper enable {UNITFILE} >/dev/null || true
+                else
+                    # Update the statefile to add new symlinks (if any), which need to be
+                    # cleaned up on purge. Also remove old symlinks.
+                    deb-systemd-helper update-state {UNITFILE} >/dev/null || true
+                fi
+            """
+        service_name = service_def.name
+
+        if assume_not_none(service_def.service_context).had_install_section:
+            ctrl.maintscript.on_configure(
+                template.format(
+                    UNITFILE=ctrl.maintscript.escape_shell_words(service_name),
+                )
+            )
+            on_purge.append(service_name)
+        elif service_def.auto_enable_on_install:
+            _error(
+                f'The service "{service_name}" cannot be enabled under "systemd" as'
+                f' it has no "[Install]" section. Please correct {service_def.definition_source}'
+                f' so that it does not enable the service or does not apply to "systemd"'
+            )
+
+        if service_def.auto_start_in_install:
+            start_on_install.append(service_name)
+        if service_def.on_upgrade == "stop-then-start":
+            stop_then_start_scripts.append(service_name)
+        elif service_def.on_upgrade in ("restart", "reload"):
+            action: str = service_def.on_upgrade
+            if not service_def.auto_start_in_install and action != "reload":
+                action = f"try-{action}"
+            action_on_upgrade[action].append(service_name)
+        elif service_def.on_upgrade != "do-nothing":
+            raise AssertionError(
+                f"Missing support for on_upgrade rule: {service_def.on_upgrade}"
+            )
+
+    if start_on_install or action_on_upgrade:
+        lines = [
+            "if {EMPTY_DPKG_ROOT_CONDITION} && {SERVICE_MANAGER_IS_SYSTEMD_CONDITION}; then".format(
+                EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                SERVICE_MANAGER_IS_SYSTEMD_CONDITION=SERVICE_MANAGER_IS_SYSTEMD_CONDITION,
+            ),
+            "    systemctl --system daemon-reload >/dev/null || true",
+        ]
+        if stop_then_start_scripts:
+            unit_files = ctrl.maintscript.escape_shell_words(*stop_then_start_scripts)
+            lines.append(
+                "        deb-systemd-invoke start {UNITFILES} >/dev/null || true".format(
+                    UNITFILES=unit_files,
+                )
+            )
+        if start_on_install:
+            lines.append('    if [ -z "$2" ]; then')
+            lines.append(
+                "        deb-systemd-invoke start {UNITFILES} >/dev/null || true".format(
+                    UNITFILES=ctrl.maintscript.escape_shell_words(*start_on_install),
+                )
+            )
+            lines.append("    fi")
+        if action_on_upgrade:
+            lines.append('    if [ -n "$2" ]; then')
+            for action, units in action_on_upgrade.items():
+                lines.append(
+                    "        deb-systemd-invoke {ACTION} {UNITFILES} >/dev/null || true".format(
+                        ACTION=action,
+                        UNITFILES=ctrl.maintscript.escape_shell_words(*units),
+                    )
+                )
+            lines.append("    fi")
+        lines.append("fi")
+        combined = "".join(x if x.endswith("\n") else f"{x}\n" for x in lines)
+        ctrl.maintscript.on_configure(combined)
+
+    if stop_then_start_scripts:
+        ctrl.maintscript.unconditionally_in_script(
+            "preinst",
+            textwrap.dedent(
+                """\
+            if {EMPTY_DPKG_ROOT_CONDITION} && [ "$1" = upgrade ] && {SERVICE_MANAGER_IS_SYSTEMD_CONDITION} ; then
+                deb-systemd-invoke stop {UNIT_FILES} >/dev/null || true
+            fi
+            """.format(
+                    EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                    SERVICE_MANAGER_IS_SYSTEMD_CONDITION=SERVICE_MANAGER_IS_SYSTEMD_CONDITION,
+                    UNIT_FILES=ctrl.maintscript.escape_shell_words(
+                        *stop_then_start_scripts
+                    ),
+                )
+            ),
+        )
+
+    if stop_in_prerm:
+        ctrl.maintscript.on_before_removal(
+            """\
+        if {EMPTY_DPKG_ROOT_CONDITION} && {SERVICE_MANAGER_IS_SYSTEMD_CONDITION} ; then
+            deb-systemd-invoke stop {UNIT_FILES} >/dev/null || true
+        fi
+        """.format(
+                EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                SERVICE_MANAGER_IS_SYSTEMD_CONDITION=SERVICE_MANAGER_IS_SYSTEMD_CONDITION,
+                UNIT_FILES=ctrl.maintscript.escape_shell_words(*stop_in_prerm),
+            )
+        )
+    if on_purge:
+        ctrl.maintscript.on_purge(
+            """\
+        if [ -x "/usr/bin/deb-systemd-helper" ]; then
+            deb-systemd-helper purge {UNITFILES} >/dev/null || true
+        fi
+        """.format(
+                UNITFILES=ctrl.maintscript.escape_shell_words(*stop_in_prerm),
+            )
+        )
+    ctrl.maintscript.on_removed(
+        textwrap.dedent(
+            """\
+        if {SERVICE_MANAGER_IS_SYSTEMD_CONDITION} ; then
+            systemctl --system daemon-reload >/dev/null || true
+        fi
+        """.format(
+                SERVICE_MANAGER_IS_SYSTEMD_CONDITION=SERVICE_MANAGER_IS_SYSTEMD_CONDITION
+            )
+        )
+    )
+
+
+def _remove_quote(v: str) -> str:
+    if v and v[0] == v[-1] and v[0] in ('"', "'"):
+        return v[1:-1]
+    return v
+
+
+def _find_and_analyze_systemd_service_files(
+    pkg: BinaryPackage,
+    fs_root: VirtualPath,
+    systemd_service_dir: Literal["system", "user"],
+) -> Iterable[SystemdUnit]:
+    service_dirs = [
+        f"./usr/lib/systemd/{systemd_service_dir}",
+        f"./lib/systemd/{systemd_service_dir}",
+    ]
+    had_install_sections = set()
+    aliases: Dict[str, List[str]] = collections.defaultdict(list)
+    seen = set()
+    all_files = []
+    expected_units = set()
+    expected_units_required_by = collections.defaultdict(list)
+
+    for d in service_dirs:
+        system_dir = fs_root.lookup(d)
+        if not system_dir:
+            continue
+        for child in system_dir.iterdir:
+            if child.is_symlink:
+                dest = os.path.basename(child.readlink())
+                aliases[dest].append(child.name)
+            elif child.is_file and child.name not in seen:
+                seen.add(child.name)
+                all_files.append(child)
+                if "@" in child.name:
+                    # dh_installsystemd does not check the contents of templated services,
+                    # and we match that.
+                    continue
+                with child.open() as fd:
+                    for line in fd:
+                        line = line.strip()
+                        line_lc = line.lower()
+                        if line_lc == "[install]":
+                            had_install_sections.add(child.name)
+                        elif line_lc.startswith("alias="):
+                            # This code assumes service names cannot contain spaces (as in
+                            # if you copy-paste it for another field it might not work)
+                            aliases[child.name].extend(
+                                _remove_quote(x) for x in line[6:].split()
+                            )
+                        elif line_lc.startswith("also="):
+                            # This code assumes service names cannot contain spaces (as in
+                            # if you copy-paste it for another field it might not work)
+                            for unit in (_remove_quote(x) for x in line[5:].split()):
+                                expected_units_required_by[unit].append(child.absolute)
+                                expected_units.add(unit)
+    for path in all_files:
+        if "@" in path.name:
+            # Match dh_installsystemd, which skips templated services
+            continue
+        names = aliases[path.name]
+        _, type_of_service = path.name.rsplit(".", 1)
+        expected_units.difference_update(names)
+        expected_units.discard(path.name)
+        names.extend(x[:-8] for x in list(names) if x.endswith(".service"))
+        names.insert(0, path.name)
+        if path.name.endswith(".service"):
+            names.insert(1, path.name[:-8])
+        yield SystemdUnit(
+            path,
+            names,
+            type_of_service,
+            systemd_service_dir,
+            # Bug (?) compat with dh_installsystemd. All units are started, but only
+            # enable those with an `[Install]` section.
+            # Possibly related bug #1055599
+            enable_by_default=path.name in had_install_sections,
+            start_by_default=True,
+            had_install_section=path.name in had_install_sections,
+        )
+
+    if expected_units:
+        for unit_name in expected_units:
+            required_by = expected_units_required_by[unit_name]
+            required_names = ", ".join(required_by)
+            _error(
+                f"The unit {unit_name} was required by {required_names} (via Also=...)"
+                f" but was not present in the package {pkg.name}"
+            )
+
+
+def generate_snippets_for_init_scripts(
+    services: Sequence[ServiceDefinition[None]],
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    for service_def in services:
+        script_name = service_def.path.name
+        script_installed_path = service_def.path.absolute
+
+        update_rcd_params = (
+            "defaults" if service_def.auto_enable_on_install else "defaults-disabled"
+        )
+
+        ctrl.maintscript.unconditionally_in_script(
+            "preinst",
+            textwrap.dedent(
+                """\
+            if [ "$1" = "install" ] && [ -n "$2" ] && [ -x {DPKG_ROOT}{SCRIPT_PATH} ] ; then
+                chmod +x {DPKG_ROOT}{SCRIPT_PATH} >/dev/null || true
+            fi
+               """.format(
+                    DPKG_ROOT=DPKG_ROOT,
+                    SCRIPT_PATH=ctrl.maintscript.escape_shell_words(
+                        script_installed_path
+                    ),
+                )
+            ),
+        )
+
+        lines = [
+            "if {EMPTY_DPKG_ROOT_CONDITION} && [ -x {SCRIPT_PATH} ]; then",
+            "    update-rc.d {SCRIPT_NAME} {UPDATE_RCD_PARAMS} >/dev/null || exit 1",
+        ]
+
+        if (
+            service_def.auto_start_in_install
+            and service_def.on_upgrade != "stop-then-start"
+        ):
+            lines.append('    if [ -z "$2" ]; then')
+            lines.append(
+                "        invoke-rc.d --skip-systemd-native {SCRIPT_NAME} start >/dev/null || exit 1".format(
+                    SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+                )
+            )
+            lines.append("    fi")
+
+        if service_def.on_upgrade in ("restart", "reload"):
+            lines.append('    if [ -n "$2" ]; then')
+            lines.append(
+                "        invoke-rc.d --skip-systemd-native {SCRIPT_NAME} {ACTION} >/dev/null || exit 1".format(
+                    SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+                    ACTION=service_def.on_upgrade,
+                )
+            )
+            lines.append("    fi")
+        elif service_def.on_upgrade == "stop-then-start":
+            lines.append(
+                "    invoke-rc.d --skip-systemd-native {SCRIPT_NAME} start >/dev/null || exit 1".format(
+                    SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+                )
+            )
+            ctrl.maintscript.unconditionally_in_script(
+                "preinst",
+                textwrap.dedent(
+                    """\
+                if {EMPTY_DPKG_ROOT_CONDITION} && [ "$1" = "upgrade" ] && [ -x {SCRIPT_PATH} ]; then
+                    invoke-rc.d --skip-systemd-native {SCRIPT_NAME} stop > /dev/null || true
+                fi
+                """.format(
+                        EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                        SCRIPT_PATH=ctrl.maintscript.escape_shell_words(
+                            script_installed_path
+                        ),
+                        SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+                    )
+                ),
+            )
+        elif service_def.on_upgrade != "do-nothing":
+            raise AssertionError(
+                f"Missing support for on_upgrade rule: {service_def.on_upgrade}"
+            )
+
+        lines.append("fi")
+        combined = "".join(x if x.endswith("\n") else f"{x}\n" for x in lines)
+        ctrl.maintscript.on_configure(
+            combined.format(
+                EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                DPKG_ROOT=DPKG_ROOT,
+                UPDATE_RCD_PARAMS=update_rcd_params,
+                SCRIPT_PATH=ctrl.maintscript.escape_shell_words(script_installed_path),
+                SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+            )
+        )
+
+        ctrl.maintscript.on_removed(
+            textwrap.dedent(
+                """\
+            if [ -x {DPKG_ROOT}{SCRIPT_PATH} ]; then
+                chmod -x {DPKG_ROOT}{SCRIPT_PATH} > /dev/null || true
+            fi
+            """.format(
+                    DPKG_ROOT=DPKG_ROOT,
+                    SCRIPT_PATH=ctrl.maintscript.escape_shell_words(
+                        script_installed_path
+                    ),
+                )
+            )
+        )
+        ctrl.maintscript.on_purge(
+            textwrap.dedent(
+                """\
+            if {EMPTY_DPKG_ROOT_CONDITION} ; then
+                update-rc.d {SCRIPT_NAME} remove >/dev/null
+            fi
+            """.format(
+                    SCRIPT_NAME=ctrl.maintscript.escape_shell_words(script_name),
+                    EMPTY_DPKG_ROOT_CONDITION=EMPTY_DPKG_ROOT_CONDITION,
+                )
+            )
+        )
+
+
+def detect_sysv_init_service_files(
+    fs_root: VirtualPath,
+    service_registry: ServiceRegistry[None],
+    _context: PackageProcessingContext,
+) -> None:
+    etc_init = fs_root.lookup("/etc/init.d")
+    if not etc_init:
+        return
+    for path in etc_init.iterdir:
+        if path.is_dir or not path.is_executable:
+            continue
+
+        service_registry.register_service(
+            path,
+            path.name,
+        )
diff --git a/src/debputy/plugin/debputy/shlib_metadata_detectors.py b/src/debputy/plugin/debputy/shlib_metadata_detectors.py
new file mode 100644
index 0000000..aa28fa9
--- /dev/null
+++ b/src/debputy/plugin/debputy/shlib_metadata_detectors.py
@@ -0,0 +1,47 @@
+from typing import List
+
+from debputy import elf_util
+from debputy.elf_util import ELF_LINKING_TYPE_DYNAMIC
+from debputy.plugin.api import (
+    VirtualPath,
+    PackageProcessingContext,
+)
+from debputy.plugin.api.impl import BinaryCtrlAccessorProvider
+
+SKIPPED_DEBUG_DIRS = [
+    "lib",
+    "lib64",
+    "usr",
+    "bin",
+    "sbin",
+    "opt",
+    "dev",
+    "emul",
+    ".build-id",
+]
+
+SKIP_DIRS = {f"./usr/lib/debug/{subdir}" for subdir in SKIPPED_DEBUG_DIRS}
+
+
+def _walk_filter(fs_path: VirtualPath, children: List[VirtualPath]) -> bool:
+    if fs_path.path in SKIP_DIRS:
+        children.clear()
+        return False
+    return True
+
+
+def detect_shlibdeps(
+    fs_root: VirtualPath,
+    ctrl: BinaryCtrlAccessorProvider,
+    _context: PackageProcessingContext,
+) -> None:
+    elf_files_to_process = elf_util.find_all_elf_files(
+        fs_root,
+        walk_filter=_walk_filter,
+        with_linking_type=ELF_LINKING_TYPE_DYNAMIC,
+    )
+
+    if not elf_files_to_process:
+        return
+
+    ctrl.dpkg_shlibdeps(elf_files_to_process)
diff --git a/src/debputy/plugin/debputy/strip_non_determinism.py b/src/debputy/plugin/debputy/strip_non_determinism.py
new file mode 100644
index 0000000..2f8fd39
--- /dev/null
+++ b/src/debputy/plugin/debputy/strip_non_determinism.py
@@ -0,0 +1,264 @@
+import dataclasses
+import os.path
+import re
+import subprocess
+from contextlib import ExitStack
+from enum import IntEnum
+from typing import Iterator, Optional, List, Callable, Any, Tuple, Union
+
+from debputy.plugin.api import VirtualPath
+from debputy.plugin.api.impl_types import PackageProcessingContextProvider
+from debputy.util import xargs, _info, escape_shell, _error
+
+
+class DetectionVerdict(IntEnum):
+    NOT_RELEVANT = 1
+    NEEDS_FILE_OUTPUT = 2
+    PROCESS = 3
+
+
+def _file_starts_with(
+    sequences: Union[bytes, Tuple[bytes, ...]]
+) -> Callable[[VirtualPath], bool]:
+    if isinstance(sequences, bytes):
+        longest_sequence = len(sequences)
+        sequences = (sequences,)
+    else:
+        longest_sequence = max(len(s) for s in sequences)
+
+    def _checker(path: VirtualPath) -> bool:
+        with path.open(byte_io=True, buffering=4096) as fd:
+            buffer = fd.read(longest_sequence)
+            return buffer in sequences
+
+    return _checker
+
+
+def _is_javadoc_file(path: VirtualPath) -> bool:
+    with path.open(buffering=4096) as fd:
+        c = fd.read(1024)
+        return "<!-- Generated by javadoc" in c
+
+
+class SndDetectionRule:
+    def initial_verdict(self, path: VirtualPath) -> DetectionVerdict:
+        raise NotImplementedError
+
+    def file_output_verdict(
+        self,
+        path: VirtualPath,
+        file_analysis: Optional[str],
+    ) -> bool:
+        raise TypeError(
+            "Should not have been called or the rule forgot to implement this method"
+        )
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ExtensionPlusFileOutputRule(SndDetectionRule):
+    extensions: Tuple[str, ...]
+    file_pattern: Optional[re.Pattern[str]] = None
+
+    def initial_verdict(self, path: VirtualPath) -> DetectionVerdict:
+        _, ext = os.path.splitext(path.name)
+        if ext not in self.extensions:
+            return DetectionVerdict.NOT_RELEVANT
+        if self.file_pattern is None:
+            return DetectionVerdict.PROCESS
+        return DetectionVerdict.NEEDS_FILE_OUTPUT
+
+    def file_output_verdict(
+        self,
+        path: VirtualPath,
+        file_analysis: str,
+    ) -> bool:
+        file_pattern = self.file_pattern
+        assert file_pattern is not None
+        m = file_pattern.search(file_analysis)
+        return m is not None
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ExtensionPlusContentCheck(SndDetectionRule):
+    extensions: Tuple[str, ...]
+    content_check: Callable[[VirtualPath], bool]
+
+    def initial_verdict(self, path: VirtualPath) -> DetectionVerdict:
+        _, ext = os.path.splitext(path.name)
+        if ext not in self.extensions:
+            return DetectionVerdict.NOT_RELEVANT
+        content_verdict = self.content_check(path)
+        if content_verdict:
+            return DetectionVerdict.PROCESS
+        return DetectionVerdict.NOT_RELEVANT
+
+
+class PyzipFileCheck(SndDetectionRule):
+    def _is_pyzip_file(self, path: VirtualPath) -> bool:
+        with path.open(byte_io=True, buffering=4096) as fd:
+            c = fd.read(32)
+            if not c.startswith(b"#!"):
+                return False
+
+            return b"\nPK\x03\x04" in c
+
+    def initial_verdict(self, path: VirtualPath) -> DetectionVerdict:
+        if self._is_pyzip_file(path):
+            return DetectionVerdict.PROCESS
+        return DetectionVerdict.NOT_RELEVANT
+
+
+# These detection rules should be aligned with `get_normalizer_for_file` in File::StripNondeterminism.
+# Note if we send a file too much, it is just bad for performance. If we send a file to little, we
+# risk non-determinism in the final output.
+SND_DETECTION_RULES: List[SndDetectionRule] = [
+    ExtensionPlusContentCheck(
+        extensions=(".a",),
+        content_check=_file_starts_with(
+            (
+                b"!<arch>\n",
+                b"!<thin>\n",
+            ),
+        ),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".png",),
+        content_check=_file_starts_with(b"\x89PNG\x0D\x0A\x1A\x0A"),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".gz", ".dz"),
+        content_check=_file_starts_with(b"\x1F\x8B"),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(
+            # .zip related
+            ".zip",
+            ".pk3",
+            ".epub",
+            ".whl",
+            ".xpi",
+            ".htb",
+            ".zhfst",
+            ".par",
+            ".codadef",
+            # .jar related
+            ".jar",
+            ".war",
+            ".hpi",
+            ".apk",
+            ".sym",
+        ),
+        content_check=_file_starts_with(
+            (
+                b"PK\x03\x04\x1F",
+                b"PK\x05\x06",
+                b"PK\x07\x08",
+            )
+        ),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(
+            ".mo",
+            ".gmo",
+        ),
+        content_check=_file_starts_with(
+            (
+                b"\x95\x04\x12\xde",
+                b"\xde\x12\x04\x95",
+            )
+        ),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".uimage",),
+        content_check=_file_starts_with(b"\x27\x05\x19\x56"),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".bflt",),
+        content_check=_file_starts_with(b"\x62\x46\x4C\x54"),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".jmod",),
+        content_check=_file_starts_with(b"JM"),
+    ),
+    ExtensionPlusContentCheck(
+        extensions=(".html",),
+        content_check=_is_javadoc_file,
+    ),
+    PyzipFileCheck(),
+    ExtensionPlusFileOutputRule(
+        extensions=(".cpio",),
+        # XXX: Add file output check (requires the file output support)
+    ),
+]
+
+
+def _detect_paths_with_possible_non_determinism(
+    fs_root: VirtualPath,
+) -> Iterator[VirtualPath]:
+    needs_file_output = []
+    for path in fs_root.all_paths():
+        if not path.is_file:
+            continue
+        verdict = DetectionVerdict.NOT_RELEVANT
+        needs_file_output_rules = []
+        for rule in SND_DETECTION_RULES:
+            v = rule.initial_verdict(path)
+            if v > verdict:
+                verdict = v
+            if verdict == DetectionVerdict.PROCESS:
+                yield path
+                break
+            elif verdict == DetectionVerdict.NEEDS_FILE_OUTPUT:
+                needs_file_output_rules.append(rule)
+
+        if verdict == DetectionVerdict.NEEDS_FILE_OUTPUT:
+            needs_file_output.append((path, needs_file_output_rules))
+
+    assert not needs_file_output
+    # FIXME: Implement file check
+
+
+def _apply_strip_non_determinism(timestamp: str, paths: List[VirtualPath]) -> None:
+    static_cmd = [
+        "strip-nondeterminism",
+        f"--timestamp={timestamp}",
+        "-v",
+        "--normalizers=+all",
+    ]
+    with ExitStack() as manager:
+        affected_files = [
+            manager.enter_context(p.replace_fs_path_content()) for p in paths
+        ]
+        for cmd in xargs(static_cmd, affected_files):
+            _info(
+                f"Removing (possible) unnecessary non-deterministic content via: {escape_shell(*cmd)}"
+            )
+            try:
+                subprocess.check_call(
+                    cmd,
+                    stdin=subprocess.DEVNULL,
+                    restore_signals=True,
+                )
+            except subprocess.CalledProcessError:
+                _error(
+                    "Attempting to remove unnecessary non-deterministic content failed. Please review"
+                    " the error from strip-nondeterminism above understand what went wrong."
+                )
+
+
+def strip_non_determinism(
+    fs_root: VirtualPath, _: Any, context: PackageProcessingContextProvider
+) -> None:
+    paths = list(_detect_paths_with_possible_non_determinism(fs_root))
+
+    if not paths:
+        _info("Detected no paths to be processed by strip-nondeterminism")
+        return
+
+    substitution = context._manifest.substitution
+
+    source_date_epoch = substitution.substitute(
+        "{{_DEBPUTY_SND_SOURCE_DATE_EPOCH}}", "Internal; strip-nondeterminism"
+    )
+
+    _apply_strip_non_determinism(source_date_epoch, paths)
diff --git a/src/debputy/plugin/debputy/types.py b/src/debputy/plugin/debputy/types.py
new file mode 100644
index 0000000..dc8d0ce
--- /dev/null
+++ b/src/debputy/plugin/debputy/types.py
@@ -0,0 +1,10 @@
+import dataclasses
+
+from debputy.manifest_parser.base_types import FileSystemMode
+
+
+@dataclasses.dataclass(slots=True)
+class DebputyCapability:
+    capabilities: str
+    capability_mode: FileSystemMode
+    definition_source: str
diff --git a/src/debputy/substitution.py b/src/debputy/substitution.py
new file mode 100644
index 0000000..0923d8f
--- /dev/null
+++ b/src/debputy/substitution.py
@@ -0,0 +1,336 @@
+import dataclasses
+import os
+import re
+from enum import IntEnum
+from typing import FrozenSet, NoReturn, Optional, Set, Mapping, TYPE_CHECKING, Self
+
+from debputy.architecture_support import (
+    dpkg_architecture_table,
+    DpkgArchitectureBuildProcessValuesTable,
+)
+from debputy.exceptions import DebputySubstitutionError
+from debputy.util import glob_escape
+
+if TYPE_CHECKING:
+    from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+    from debputy.plugin.api import VirtualPath
+
+
+SUBST_VAR_RE = re.compile(
+    r"""
+    ([{][{][ ]*)
+
+    (
+        _?[A-Za-z0-9]+
+        (?:[-_:][A-Za-z0-9]+)*
+    )
+
+    ([ ]*[}][}])
+""",
+    re.VERBOSE,
+)
+
+
+class VariableNameState(IntEnum):
+    UNDEFINED = 1
+    RESERVED = 2
+    DEFINED = 3
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class VariableContext:
+    debian_dir: "VirtualPath"
+
+
+class Substitution:
+    def substitute(
+        self,
+        value: str,
+        definition_source: str,
+        /,
+        escape_glob_characters: bool = False,
+    ) -> str:
+        raise NotImplementedError
+
+    def with_extra_substitutions(self, **extra_substitutions: str) -> "Substitution":
+        raise NotImplementedError
+
+    def with_unresolvable_substitutions(
+        self, *extra_substitutions: str
+    ) -> "Substitution":
+        raise NotImplementedError
+
+    def variable_state(self, variable_name: str) -> VariableNameState:
+        return VariableNameState.UNDEFINED
+
+    def is_used(self, variable_name: str) -> bool:
+        return False
+
+    def _mark_used(self, variable_name: str) -> None:
+        pass
+
+    def _replacement(self, matched_key: str, definition_source: str) -> str:
+        self._error(
+            "Cannot resolve {{" + matched_key + "}}."
+            f" The error occurred while trying to process {definition_source}"
+        )
+
+    def _error(
+        self,
+        msg: str,
+        *,
+        caused_by: Optional[BaseException] = None,
+    ) -> NoReturn:
+        raise DebputySubstitutionError(msg) from caused_by
+
+    def _apply_substitution(
+        self,
+        pattern: re.Pattern[str],
+        value: str,
+        definition_source: str,
+        /,
+        escape_glob_characters: bool = False,
+    ) -> str:
+        replacement = value
+        offset = 0
+        for match in pattern.finditer(value):
+            prefix, matched_key, suffix = match.groups()
+            replacement_value = self._replacement(matched_key, definition_source)
+            self._mark_used(matched_key)
+            if escape_glob_characters:
+                replacement_value = glob_escape(replacement_value)
+            s, e = match.span()
+            s += offset
+            e += offset
+            replacement = replacement[:s] + replacement_value + replacement[e:]
+            token_fluff_len = len(prefix) + len(suffix)
+            offset += len(replacement_value) - len(matched_key) - token_fluff_len
+        return replacement
+
+
+class NullSubstitution(Substitution):
+    def substitute(
+        self,
+        value: str,
+        definition_source: str,
+        /,
+        escape_glob_characters: bool = False,
+    ) -> str:
+        return value
+
+    def with_extra_substitutions(self, **extra_substitutions: str) -> "Substitution":
+        return self
+
+    def with_unresolvable_substitutions(
+        self, *extra_substitutions: str
+    ) -> "Substitution":
+        return self
+
+
+NULL_SUBSTITUTION = NullSubstitution()
+del NullSubstitution
+
+
+class SubstitutionImpl(Substitution):
+    __slots__ = (
+        "_used",
+        "_env",
+        "_plugin_feature_set",
+        "_static_variables",
+        "_unresolvable_substitutions",
+        "_dpkg_arch_table",
+        "_parent",
+        "_variable_context",
+    )
+
+    def __init__(
+        self,
+        /,
+        plugin_feature_set: Optional["PluginProvidedFeatureSet"] = None,
+        static_variables: Optional[Mapping[str, str]] = None,
+        unresolvable_substitutions: FrozenSet[str] = frozenset(),
+        dpkg_arch_table: Optional[DpkgArchitectureBuildProcessValuesTable] = None,
+        environment: Optional[Mapping[str, str]] = None,
+        parent: Optional["SubstitutionImpl"] = None,
+        variable_context: Optional[VariableContext] = None,
+    ) -> None:
+        self._used: Set[str] = set()
+        self._plugin_feature_set = plugin_feature_set
+        self._static_variables = (
+            dict(static_variables) if static_variables is not None else None
+        )
+        self._unresolvable_substitutions = unresolvable_substitutions
+        self._dpkg_arch_table = (
+            dpkg_arch_table
+            if dpkg_arch_table is not None
+            else dpkg_architecture_table()
+        )
+        self._env = environment if environment is not None else os.environ
+        self._parent = parent
+        if variable_context is not None:
+            self._variable_context = variable_context
+        elif self._parent is not None:
+            self._variable_context = self._parent._variable_context
+        else:
+            raise ValueError(
+                "variable_context is required either directly or via the parent"
+            )
+
+    def copy_for_subst_test(
+        self,
+        plugin_feature_set: "PluginProvidedFeatureSet",
+        variable_context: VariableContext,
+        *,
+        extra_substitutions: Optional[Mapping[str, str]] = None,
+        environment: Optional[Mapping[str, str]] = None,
+    ) -> "Self":
+        extra_substitutions_impl = (
+            dict(self._static_variables.items()) if self._static_variables else {}
+        )
+        if extra_substitutions:
+            extra_substitutions_impl.update(extra_substitutions)
+        return self.__class__(
+            plugin_feature_set=plugin_feature_set,
+            variable_context=variable_context,
+            static_variables=extra_substitutions_impl,
+            unresolvable_substitutions=self._unresolvable_substitutions,
+            dpkg_arch_table=self._dpkg_arch_table,
+            environment=environment if environment is not None else {},
+        )
+
+    def variable_state(self, key: str) -> VariableNameState:
+        if key.startswith("DEB_"):
+            if key in self._dpkg_arch_table:
+                return VariableNameState.DEFINED
+            return VariableNameState.RESERVED
+        plugin_feature_set = self._plugin_feature_set
+        if (
+            plugin_feature_set is not None
+            and key in plugin_feature_set.manifest_variables
+        ):
+            return VariableNameState.DEFINED
+        if key.startswith("env:"):
+            k = key[4:]
+            if k in self._env:
+                return VariableNameState.DEFINED
+            return VariableNameState.RESERVED
+        if self._static_variables is not None and key in self._static_variables:
+            return VariableNameState.DEFINED
+        if key in self._unresolvable_substitutions:
+            return VariableNameState.RESERVED
+        if self._parent is not None:
+            return self._parent.variable_state(key)
+        return VariableNameState.UNDEFINED
+
+    def is_used(self, variable_name: str) -> bool:
+        if variable_name in self._used:
+            return True
+        parent = self._parent
+        if parent is not None:
+            return parent.is_used(variable_name)
+        return False
+
+    def _mark_used(self, variable_name: str) -> None:
+        p = self._parent
+        while p:
+            # Find the parent that has the variable if possible. This ensures that is_used works
+            # correctly.
+            if p._static_variables is not None and variable_name in p._static_variables:
+                p._mark_used(variable_name)
+                break
+            plugin_feature_set = p._plugin_feature_set
+            if (
+                plugin_feature_set is not None
+                and variable_name in plugin_feature_set.manifest_variables
+                and not plugin_feature_set.manifest_variables[
+                    variable_name
+                ].is_documentation_placeholder
+            ):
+                p._mark_used(variable_name)
+                break
+            p = p._parent
+        self._used.add(variable_name)
+
+    def _replacement(self, key: str, definition_source: str) -> str:
+        if key.startswith("DEB_") and key in self._dpkg_arch_table:
+            return self._dpkg_arch_table[key]
+        if key.startswith("env:"):
+            k = key[4:]
+            if k in self._env:
+                return self._env[k]
+            self._error(
+                f'The environment does not contain the variable "{key}" '
+                f"(error occurred while trying to process {definition_source})"
+            )
+
+        # The order between extra_substitution and plugin_feature_set is leveraged by
+        # the tests to implement mocking variables. If the order needs tweaking,
+        # you will need a custom resolver for the tests to support mocking.
+        static_variables = self._static_variables
+        if static_variables and key in static_variables:
+            return static_variables[key]
+        plugin_feature_set = self._plugin_feature_set
+        if plugin_feature_set is not None:
+            provided_var = plugin_feature_set.manifest_variables.get(key)
+            if (
+                provided_var is not None
+                and not provided_var.is_documentation_placeholder
+            ):
+                v = provided_var.resolve(self._variable_context)
+                # cache it for next time.
+                if static_variables is None:
+                    static_variables = {}
+                    self._static_variables = static_variables
+                static_variables[key] = v
+                return v
+        if key in self._unresolvable_substitutions:
+            self._error(
+                "The variable {{" + key + "}}"
+                f" is not available while processing {definition_source}."
+            )
+        parent = self._parent
+        if parent is not None:
+            return parent._replacement(key, definition_source)
+        self._error(
+            "Cannot resolve {{" + key + "}}: it is not a known key."
+            f" The error occurred while trying to process {definition_source}"
+        )
+
+    def with_extra_substitutions(self, **extra_substitutions: str) -> "Substitution":
+        if not extra_substitutions:
+            return self
+        return SubstitutionImpl(
+            dpkg_arch_table=self._dpkg_arch_table,
+            environment=self._env,
+            static_variables=extra_substitutions,
+            parent=self,
+        )
+
+    def with_unresolvable_substitutions(
+        self,
+        *extra_substitutions: str,
+    ) -> "Substitution":
+        if not extra_substitutions:
+            return self
+        return SubstitutionImpl(
+            dpkg_arch_table=self._dpkg_arch_table,
+            environment=self._env,
+            unresolvable_substitutions=frozenset(extra_substitutions),
+            parent=self,
+        )
+
+    def substitute(
+        self,
+        value: str,
+        definition_source: str,
+        /,
+        escape_glob_characters: bool = False,
+    ) -> str:
+        if "{{" not in value:
+            return value
+        return self._apply_substitution(
+            SUBST_VAR_RE,
+            value,
+            definition_source,
+            escape_glob_characters=escape_glob_characters,
+        )
diff --git a/src/debputy/transformation_rules.py b/src/debputy/transformation_rules.py
new file mode 100644
index 0000000..8d9caae
--- /dev/null
+++ b/src/debputy/transformation_rules.py
@@ -0,0 +1,596 @@
+import dataclasses
+import os
+from typing import (
+    NoReturn,
+    Optional,
+    Callable,
+    Sequence,
+    Tuple,
+    List,
+    Literal,
+    Dict,
+    TypeVar,
+    cast,
+)
+
+from debputy.exceptions import (
+    DebputyRuntimeError,
+    PureVirtualPathError,
+    TestPathWithNonExistentFSPathError,
+)
+from debputy.filesystem_scan import FSPath
+from debputy.interpreter import (
+    extract_shebang_interpreter_from_file,
+)
+from debputy.manifest_conditions import ConditionContext, ManifestCondition
+from debputy.manifest_parser.base_types import (
+    FileSystemMode,
+    StaticFileSystemOwner,
+    StaticFileSystemGroup,
+    DebputyDispatchableType,
+)
+from debputy.manifest_parser.util import AttributePath
+from debputy.path_matcher import MatchRule
+from debputy.plugin.api import VirtualPath
+from debputy.plugin.debputy.types import DebputyCapability
+from debputy.util import _warn
+
+
+class TransformationRuntimeError(DebputyRuntimeError):
+    pass
+
+
+CreateSymlinkReplacementRule = Literal[
+    "error-if-exists",
+    "error-if-directory",
+    "abort-on-non-empty-directory",
+    "discard-existing",
+]
+
+
+VP = TypeVar("VP", bound=VirtualPath)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PreProvidedExclusion:
+    tag: str
+    description: str
+    pruner: Callable[[FSPath], None]
+
+
+class TransformationRule(DebputyDispatchableType):
+    __slots__ = ()
+
+    def transform_file_system(
+        self, fs_root: FSPath, condition_context: ConditionContext
+    ) -> None:
+        raise NotImplementedError
+
+    def _evaluate_condition(
+        self,
+        condition: Optional[ManifestCondition],
+        condition_context: ConditionContext,
+        result_if_condition_is_missing: bool = True,
+    ) -> bool:
+        if condition is None:
+            return result_if_condition_is_missing
+        return condition.evaluate(condition_context)
+
+    def _error(
+        self,
+        msg: str,
+        *,
+        caused_by: Optional[BaseException] = None,
+    ) -> NoReturn:
+        raise TransformationRuntimeError(msg) from caused_by
+
+    def _match_rule_had_no_matches(
+        self, match_rule: MatchRule, definition_source: str
+    ) -> NoReturn:
+        self._error(
+            f'The match rule "{match_rule.describe_match_short()}" in transformation "{definition_source}" did'
+            " not match any paths. Either the definition is redundant (and can be omitted) or the match rule is"
+            " incorrect."
+        )
+
+    def _fs_path_as_dir(
+        self,
+        path: VP,
+        definition_source: str,
+    ) -> VP:
+        if path.is_dir:
+            return path
+        path_type = "file" if path.is_file else 'symlink/"special file system object"'
+        self._error(
+            f"The path {path.path} was expected to be a directory (or non-existing) due to"
+            f" {definition_source}. However that path existed and is a {path_type}."
+            f" You may need a `remove: {path.path}` prior to {definition_source} to"
+            " to make this transformation succeed."
+        )
+
+    def _ensure_is_directory(
+        self,
+        fs_root: FSPath,
+        path_to_directory: str,
+        definition_source: str,
+    ) -> FSPath:
+        current, missing_parts = fs_root.attempt_lookup(path_to_directory)
+        current = self._fs_path_as_dir(cast("FSPath", current), definition_source)
+        if missing_parts:
+            return current.mkdirs("/".join(missing_parts))
+        return current
+
+
+class RemoveTransformationRule(TransformationRule):
+    __slots__ = (
+        "_match_rules",
+        "_keep_empty_parent_dirs",
+        "_definition_source",
+    )
+
+    def __init__(
+        self,
+        match_rules: Sequence[MatchRule],
+        keep_empty_parent_dirs: bool,
+        definition_source: AttributePath,
+    ) -> None:
+        self._match_rules = match_rules
+        self._keep_empty_parent_dirs = keep_empty_parent_dirs
+        self._definition_source = definition_source.path
+
+    def transform_file_system(
+        self,
+        fs_root: FSPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        matched_any = False
+        for match_rule in self._match_rules:
+            # Fully resolve the matches to avoid RuntimeError caused by collection changing size as a
+            # consequence of the removal: https://salsa.debian.org/debian/debputy/-/issues/52
+            matches = list(match_rule.finditer(fs_root))
+            for m in matches:
+                matched_any = True
+                parent = m.parent_dir
+                if parent is None:
+                    self._error(
+                        f"Cannot remove the root directory (triggered by {self._definition_source})"
+                    )
+                m.unlink(recursive=True)
+                if not self._keep_empty_parent_dirs:
+                    parent.prune_if_empty_dir()
+            # FIXME: `rm` should probably be forgiving or at least support a condition to avoid failures
+            if not matched_any:
+                self._match_rule_had_no_matches(match_rule, self._definition_source)
+
+
+class MoveTransformationRule(TransformationRule):
+    __slots__ = (
+        "_match_rule",
+        "_dest_path",
+        "_dest_is_dir",
+        "_definition_source",
+        "_condition",
+    )
+
+    def __init__(
+        self,
+        match_rule: MatchRule,
+        dest_path: str,
+        dest_is_dir: bool,
+        definition_source: AttributePath,
+        condition: Optional[ManifestCondition],
+    ) -> None:
+        self._match_rule = match_rule
+        self._dest_path = dest_path
+        self._dest_is_dir = dest_is_dir
+        self._definition_source = definition_source.path
+        self._condition = condition
+
+    def transform_file_system(
+        self, fs_root: FSPath, condition_context: ConditionContext
+    ) -> None:
+        if not self._evaluate_condition(self._condition, condition_context):
+            return
+        # Eager resolve is necessary to avoid "self-recursive" matching in special cases (e.g., **/*.la)
+        matches = list(self._match_rule.finditer(fs_root))
+        if not matches:
+            self._match_rule_had_no_matches(self._match_rule, self._definition_source)
+
+        target_dir: Optional[VirtualPath]
+        if self._dest_is_dir:
+            target_dir = self._ensure_is_directory(
+                fs_root,
+                self._dest_path,
+                self._definition_source,
+            )
+        else:
+            dir_part, basename = os.path.split(self._dest_path)
+            target_parent_dir = self._ensure_is_directory(
+                fs_root,
+                dir_part,
+                self._definition_source,
+            )
+            target_dir = target_parent_dir.get(basename)
+
+            if target_dir is None or not target_dir.is_dir:
+                if len(matches) > 1:
+                    self._error(
+                        f"Could not rename {self._match_rule.describe_match_short()} to {self._dest_path}"
+                        f" (from: {self._definition_source}).  Multiple paths matched the pattern and the"
+                        " destination was not a directory. Either correct the pattern to only match ony source"
+                        " OR define the destination to be a directory (E.g., add a trailing slash - example:"
+                        f' "{self._dest_path}/")'
+                    )
+                p = matches[0]
+                if p.path == self._dest_path:
+                    self._error(
+                        f"Error in {self._definition_source}, the source"
+                        f" {self._match_rule.describe_match_short()} matched {self._dest_path} making the"
+                        " rename redundant!?"
+                    )
+                p.parent_dir = target_parent_dir
+                p.name = basename
+                return
+
+        assert target_dir is not None and target_dir.is_dir
+        basenames: Dict[str, VirtualPath] = dict()
+        target_dir_path = target_dir.path
+
+        for m in matches:
+            if m.path == target_dir_path:
+                self._error(
+                    f"Error in {self._definition_source}, the source {self._match_rule.describe_match_short()}"
+                    f"matched {self._dest_path} (among other), but it is not possible to copy a directory into"
+                    " itself"
+                )
+            if m.name in basenames:
+                alt_path = basenames[m.name]
+                # We document "two *distinct*" paths.  However, as the glob matches are written, it should not be
+                # possible for a *single* glob to match the same path twice.
+                assert alt_path is not m
+                self._error(
+                    f"Could not rename {self._match_rule.describe_match_short()} to {self._dest_path}"
+                    f" (from: {self._definition_source}).  Multiple paths matched the pattern had the"
+                    f' same basename "{m.name}" ("{m.path}" vs. "{alt_path.path}").  Please correct the'
+                    f" pattern, so it only matches one path with that basename to avoid this conflict."
+                )
+            existing = m.get(m.name)
+            if existing and existing.is_dir:
+                self._error(
+                    f"Could not rename {self._match_rule.describe_match_short()} to {self._dest_path}"
+                    f" (from: {self._definition_source}).  The pattern matched {m.path} which would replace"
+                    f" the existing directory {existing.path}.  If this replacement is intentional, then please"
+                    f' remove "{existing.path}" first (e.g., via `- remove: "{existing.path}"`)'
+                )
+            basenames[m.name] = m
+            m.parent_dir = target_dir
+
+
+class CreateSymlinkPathTransformationRule(TransformationRule):
+    __slots__ = (
+        "_link_dest",
+        "_link_target",
+        "_replacement_rule",
+        "_definition_source",
+        "_condition",
+    )
+
+    def __init__(
+        self,
+        link_target: str,
+        link_dest: str,
+        replacement_rule: CreateSymlinkReplacementRule,
+        definition_source: AttributePath,
+        condition: Optional[ManifestCondition],
+    ) -> None:
+        self._link_target = link_target
+        self._link_dest = link_dest
+        self._replacement_rule = replacement_rule
+        self._definition_source = definition_source.path
+        self._condition = condition
+
+    def transform_file_system(
+        self,
+        fs_root: FSPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        if not self._evaluate_condition(self._condition, condition_context):
+            return
+        dir_path_part, link_name = os.path.split(self._link_dest)
+        dir_path = self._ensure_is_directory(
+            fs_root,
+            dir_path_part,
+            self._definition_source,
+        )
+        existing = dir_path.get(link_name)
+        if existing:
+            self._handle_existing_path(existing)
+        dir_path.add_symlink(link_name, self._link_target)
+
+    def _handle_existing_path(self, existing: VirtualPath) -> None:
+        replacement_rule = self._replacement_rule
+        if replacement_rule == "abort-on-non-empty-directory":
+            unlink = not existing.is_dir or not any(existing.iterdir)
+            reason = "the path is a non-empty directory"
+        elif replacement_rule == "discard-existing":
+            unlink = True
+            reason = "<<internal error: you should not see an error with this message>>"
+        elif replacement_rule == "error-if-directory":
+            unlink = not existing.is_dir
+            reason = "the path is a directory"
+        else:
+            assert replacement_rule == "error-if-exists"
+            unlink = False
+            reason = "the path exists"
+
+        if unlink:
+            existing.unlink(recursive=True)
+        else:
+            self._error(
+                f"Refusing to replace {existing.path} with a symlink; {reason} and"
+                f" the active replacement-rule was {self._replacement_rule}.  You can"
+                f' set the replacement-rule to "discard-existing", if you are not interested'
+                f" in the contents of {existing.path}. This error was triggered by {self._definition_source}."
+            )
+
+
+class CreateDirectoryTransformationRule(TransformationRule):
+    __slots__ = (
+        "_directories",
+        "_owner",
+        "_group",
+        "_mode",
+        "_definition_source",
+        "_condition",
+    )
+
+    def __init__(
+        self,
+        directories: Sequence[str],
+        owner: Optional[StaticFileSystemOwner],
+        group: Optional[StaticFileSystemGroup],
+        mode: Optional[FileSystemMode],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> None:
+        super().__init__()
+        self._directories = directories
+        self._owner = owner
+        self._group = group
+        self._mode = mode
+        self._definition_source = definition_source
+        self._condition = condition
+
+    def transform_file_system(
+        self,
+        fs_root: FSPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        if not self._evaluate_condition(self._condition, condition_context):
+            return
+        owner = self._owner
+        group = self._group
+        mode = self._mode
+        for directory in self._directories:
+            dir_path = self._ensure_is_directory(
+                fs_root,
+                directory,
+                self._definition_source,
+            )
+
+            if mode is not None:
+                try:
+                    desired_mode = mode.compute_mode(dir_path.mode, dir_path.is_dir)
+                except ValueError as e:
+                    self._error(
+                        f"Could not compute desired mode for {dir_path.path} as"
+                        f" requested in {self._definition_source}: {e.args[0]}",
+                        caused_by=e,
+                    )
+                dir_path.mode = desired_mode
+            dir_path.chown(owner, group)
+
+
+def _apply_owner_and_mode(
+    path: VirtualPath,
+    owner: Optional[StaticFileSystemOwner],
+    group: Optional[StaticFileSystemGroup],
+    mode: Optional[FileSystemMode],
+    capabilities: Optional[str],
+    capability_mode: Optional[FileSystemMode],
+    definition_source: str,
+) -> None:
+    if owner is not None or group is not None:
+        path.chown(owner, group)
+    if mode is not None:
+        try:
+            desired_mode = mode.compute_mode(path.mode, path.is_dir)
+        except ValueError as e:
+            raise TransformationRuntimeError(
+                f"Could not compute desired mode for {path.path} as"
+                f" requested in {definition_source}: {e.args[0]}"
+            ) from e
+        path.mode = desired_mode
+
+    if path.is_file and capabilities is not None:
+        cap_ref = path.metadata(DebputyCapability)
+        cap_value = cap_ref.value
+        if cap_value is not None:
+            _warn(
+                f"Replacing the capabilities set on path {path.path} from {cap_value.definition_source} due"
+                f" to {definition_source}."
+            )
+        assert capability_mode is not None
+        cap_ref.value = DebputyCapability(
+            capabilities,
+            capability_mode,
+            definition_source,
+        )
+
+
+class PathMetadataTransformationRule(TransformationRule):
+    __slots__ = (
+        "_match_rules",
+        "_owner",
+        "_group",
+        "_mode",
+        "_capabilities",
+        "_capability_mode",
+        "_recursive",
+        "_definition_source",
+        "_condition",
+    )
+
+    def __init__(
+        self,
+        match_rules: Sequence[MatchRule],
+        owner: Optional[StaticFileSystemOwner],
+        group: Optional[StaticFileSystemGroup],
+        mode: Optional[FileSystemMode],
+        recursive: bool,
+        capabilities: Optional[str],
+        capability_mode: Optional[FileSystemMode],
+        definition_source: str,
+        condition: Optional[ManifestCondition],
+    ) -> None:
+        super().__init__()
+        self._match_rules = match_rules
+        self._owner = owner
+        self._group = group
+        self._mode = mode
+        self._capabilities = capabilities
+        self._capability_mode = capability_mode
+        self._recursive = recursive
+        self._definition_source = definition_source
+        self._condition = condition
+        if self._capabilities is None and self._capability_mode is not None:
+            raise ValueError("capability_mode without capabilities")
+        if self._capabilities is not None and self._capability_mode is None:
+            raise ValueError("capabilities without capability_mode")
+
+    def transform_file_system(
+        self,
+        fs_root: FSPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        if not self._evaluate_condition(self._condition, condition_context):
+            return
+        owner = self._owner
+        group = self._group
+        mode = self._mode
+        capabilities = self._capabilities
+        capability_mode = self._capability_mode
+        definition_source = self._definition_source
+        d: Optional[List[FSPath]] = [] if self._recursive else None
+        needs_file_match = False
+        if self._owner is not None or self._group is not None or self._mode is not None:
+            needs_file_match = True
+
+        for match_rule in self._match_rules:
+            match_ok = False
+            saw_symlink = False
+            saw_directory = False
+
+            for path in match_rule.finditer(fs_root):
+                if path.is_symlink:
+                    saw_symlink = True
+                    continue
+                if path.is_file or not needs_file_match:
+                    match_ok = True
+                if path.is_dir:
+                    saw_directory = True
+                    if not match_ok and needs_file_match and self._recursive:
+                        match_ok = any(p.is_file for p in path.all_paths())
+                _apply_owner_and_mode(
+                    path,
+                    owner,
+                    group,
+                    mode,
+                    capabilities,
+                    capability_mode,
+                    definition_source,
+                )
+                if path.is_dir and d is not None:
+                    d.append(path)
+
+            if not match_ok:
+                if needs_file_match and (saw_directory or saw_symlink):
+                    _warn(
+                        f"The match rule {match_rule.describe_match_short()} (from {self._definition_source})"
+                        " did not match any files, but given the attributes it can only apply to files."
+                    )
+                elif saw_symlink:
+                    _warn(
+                        f"The match rule {match_rule.describe_match_short()} (from {self._definition_source})"
+                        ' matched symlinks, but "path-metadata" cannot apply to symlinks.'
+                    )
+                self._match_rule_had_no_matches(match_rule, self._definition_source)
+
+        if not d:
+            return
+        for recurse_dir in d:
+            for path in recurse_dir.all_paths():
+                if path.is_symlink:
+                    continue
+                _apply_owner_and_mode(
+                    path,
+                    owner,
+                    group,
+                    mode,
+                    capabilities,
+                    capability_mode,
+                    definition_source,
+                )
+
+
+class ModeNormalizationTransformationRule(TransformationRule):
+    __slots__ = ("_normalizations",)
+
+    def __init__(
+        self,
+        normalizations: Sequence[Tuple[MatchRule, FileSystemMode]],
+    ) -> None:
+        self._normalizations = normalizations
+
+    def transform_file_system(
+        self,
+        fs_root: FSPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        seen = set()
+        for match_rule, fs_mode in self._normalizations:
+            for path in match_rule.finditer(
+                fs_root, ignore_paths=lambda p: p.path in seen
+            ):
+                if path.is_symlink or path.path in seen:
+                    continue
+                seen.add(path.path)
+                try:
+                    desired_mode = fs_mode.compute_mode(path.mode, path.is_dir)
+                except ValueError as e:
+                    raise AssertionError(
+                        "Error while applying built-in mode normalization rule"
+                    ) from e
+                path.mode = desired_mode
+
+
+class NormalizeShebangLineTransformation(TransformationRule):
+    def transform_file_system(
+        self,
+        fs_root: VirtualPath,
+        condition_context: ConditionContext,
+    ) -> None:
+        for path in fs_root.all_paths():
+            if not path.is_file:
+                continue
+            try:
+                with path.open(byte_io=True, buffering=4096) as fd:
+                    interpreter = extract_shebang_interpreter_from_file(fd)
+            except (PureVirtualPathError, TestPathWithNonExistentFSPathError):
+                # Do not make tests unnecessarily complex to write
+                continue
+            if interpreter is None:
+                continue
+
+            if interpreter.fixup_needed:
+                interpreter.replace_shebang_line(path)
diff --git a/src/debputy/types.py b/src/debputy/types.py
new file mode 100644
index 0000000..05e68c9
--- /dev/null
+++ b/src/debputy/types.py
@@ -0,0 +1,9 @@
+from typing import TypeVar, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from debputy.plugin.api import VirtualPath
+    from debputy.filesystem_scan import FSPath
+
+
+VP = TypeVar("VP", "VirtualPath", "FSPath")
+S = TypeVar("S", str, bytes)
diff --git a/src/debputy/util.py b/src/debputy/util.py
new file mode 100644
index 0000000..4da2772
--- /dev/null
+++ b/src/debputy/util.py
@@ -0,0 +1,804 @@
+import argparse
+import collections
+import functools
+import glob
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from itertools import zip_longest
+from pathlib import Path
+from typing import (
+    NoReturn,
+    TYPE_CHECKING,
+    Union,
+    Set,
+    FrozenSet,
+    Optional,
+    TypeVar,
+    Dict,
+    Iterator,
+    Iterable,
+    Literal,
+    Tuple,
+    Sequence,
+    List,
+    Mapping,
+    Any,
+)
+
+from debian.deb822 import Deb822
+
+from debputy.architecture_support import DpkgArchitectureBuildProcessValuesTable
+from debputy.exceptions import DebputySubstitutionError
+
+if TYPE_CHECKING:
+    from debputy.packages import BinaryPackage
+    from debputy.substitution import Substitution
+
+
+T = TypeVar("T")
+
+
+SLASH_PRUNE = re.compile("//+")
+PKGNAME_REGEX = re.compile(r"[a-z0-9][-+.a-z0-9]+", re.ASCII)
+PKGVERSION_REGEX = re.compile(
+    r"""
+                 (?: \d+ : )?                # Optional epoch
+                 \d[0-9A-Za-z.+:~]*          # Upstream version (with no hyphens)
+                 (?: - [0-9A-Za-z.+:~]+ )*   # Optional debian revision (+ upstreams versions with hyphens)
+""",
+    re.VERBOSE | re.ASCII,
+)
+DEFAULT_PACKAGE_TYPE = "deb"
+DBGSYM_PACKAGE_TYPE = "deb"
+UDEB_PACKAGE_TYPE = "udeb"
+
+POSTINST_DEFAULT_CONDITION = (
+    '[ "$1" = "configure" ]'
+    ' || [ "$1" = "abort-upgrade" ]'
+    ' || [ "$1" = "abort-deconfigure" ]'
+    ' || [ "$1" = "abort-remove" ]'
+)
+
+
+_SPACE_RE = re.compile(r"\s")
+_DOUBLE_ESCAPEES = re.compile(r'([\n`$"\\])')
+_REGULAR_ESCAPEES = re.compile(r'([\s!"$()*+#;<>?@\[\]\\`|~])')
+_PROFILE_GROUP_SPLIT = re.compile(r">\s+<")
+_DEFAULT_LOGGER: Optional[logging.Logger] = None
+_STDOUT_HANDLER: Optional[logging.StreamHandler] = None
+_STDERR_HANDLER: Optional[logging.StreamHandler] = None
+
+
+def assume_not_none(x: Optional[T]) -> T:
+    if x is None:  # pragma: no cover
+        raise ValueError(
+            'Internal error: None was given, but the receiver assumed "not None" here'
+        )
+    return x
+
+
+def _info(msg: str) -> None:
+    global _DEFAULT_LOGGER
+    logger = _DEFAULT_LOGGER
+    if logger:
+        logger.info(msg)
+    # No fallback print for info
+
+
+def _error(msg: str, *, prog: Optional[str] = None) -> "NoReturn":
+    global _DEFAULT_LOGGER
+    logger = _DEFAULT_LOGGER
+    if logger:
+        logger.error(msg)
+    else:
+        me = os.path.basename(sys.argv[0]) if prog is None else prog
+        print(
+            f"{me}: error: {msg}",
+            file=sys.stderr,
+        )
+    sys.exit(1)
+
+
+def _warn(msg: str, *, prog: Optional[str] = None) -> None:
+    global _DEFAULT_LOGGER
+    logger = _DEFAULT_LOGGER
+    if logger:
+        logger.warning(msg)
+    else:
+        me = os.path.basename(sys.argv[0]) if prog is None else prog
+
+        print(
+            f"{me}: warning: {msg}",
+            file=sys.stderr,
+        )
+
+
+class ColorizedArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        _error(message, prog=self.prog)
+
+
+def ensure_dir(path: str) -> None:
+    if not os.path.isdir(path):
+        os.makedirs(path, mode=0o755, exist_ok=True)
+
+
+def _clean_path(orig_p: str) -> str:
+    p = SLASH_PRUNE.sub("/", orig_p)
+    if "." in p:
+        path_base = p
+        # We permit a single leading "./" because we add that when we normalize a path, and we want normalization
+        # of a normalized path to be a no-op.
+        if path_base.startswith("./"):
+            path_base = path_base[2:]
+            assert path_base
+        for segment in path_base.split("/"):
+            if segment in (".", ".."):
+                raise ValueError(
+                    'Please provide paths that are normalized (i.e., no ".." or ".").'
+                    f' Offending input "{orig_p}"'
+                )
+    return p
+
+
+def _normalize_path(path: str, with_prefix: bool = True) -> str:
+    path = path.strip("/")
+    if not path or path == ".":
+        return "."
+    if "//" in path or "." in path:
+        path = _clean_path(path)
+    if with_prefix ^ path.startswith("./"):
+        if with_prefix:
+            path = "./" + path
+        else:
+            path = path[2:]
+    return path
+
+
+def _normalize_link_target(link_target: str) -> str:
+    link_target = SLASH_PRUNE.sub("/", link_target.lstrip("/"))
+    result: List[str] = []
+    for segment in link_target.split("/"):
+        if segment in (".", ""):
+            # Ignore these - the empty string is generally a trailing slash
+            continue
+        if segment == "..":
+            # We ignore "root escape attempts" like the OS would (mapping /.. -> /)
+            if result:
+                result.pop()
+        else:
+            result.append(segment)
+    return "/".join(result)
+
+
+def _backslash_escape(m: re.Match[str]) -> str:
+    return "\\" + m.group(0)
+
+
+def _escape_shell_word(w: str) -> str:
+    if _SPACE_RE.match(w):
+        w = _DOUBLE_ESCAPEES.sub(_backslash_escape, w)
+        return f'"{w}"'
+    return _REGULAR_ESCAPEES.sub(_backslash_escape, w)
+
+
+def escape_shell(*args: str) -> str:
+    return " ".join(_escape_shell_word(w) for w in args)
+
+
+def print_command(*args: str) -> None:
+    print(f"   {escape_shell(*args)}")
+
+
+def debian_policy_normalize_symlink_target(
+    link_path: str,
+    link_target: str,
+    normalize_link_path: bool = False,
+) -> str:
+    if normalize_link_path:
+        link_path = _normalize_path(link_path)
+    elif not link_path.startswith("./"):
+        raise ValueError("Link part was not normalized")
+
+    link_path = link_path[2:]
+
+    if not link_target.startswith("/"):
+        link_target = "/" + os.path.dirname(link_path) + "/" + link_target
+
+    link_path_parts = link_path.split("/")
+    link_target_parts = [
+        s for s in _normalize_link_target(link_target).split("/") if s != "."
+    ]
+
+    assert link_path_parts
+
+    if link_target_parts and link_path_parts[0] == link_target_parts[0]:
+        # Per Debian Policy, must be relative
+
+        # First determine the length of the overlap
+        common_segment_count = 1
+        shortest_path_length = min(len(link_target_parts), len(link_path_parts))
+        while (
+            common_segment_count < shortest_path_length
+            and link_target_parts[common_segment_count]
+            == link_path_parts[common_segment_count]
+        ):
+            common_segment_count += 1
+
+        if common_segment_count == shortest_path_length and len(
+            link_path_parts
+        ) - 1 == len(link_target_parts):
+            normalized_link_target = "."
+        else:
+            up_dir_count = len(link_path_parts) - 1 - common_segment_count
+            normalized_link_target_parts = []
+            if up_dir_count:
+                up_dir_part = "../" * up_dir_count
+                # We overshoot with a single '/', so rstrip it away
+                normalized_link_target_parts.append(up_dir_part.rstrip("/"))
+            # Add the relevant down parts
+            normalized_link_target_parts.extend(
+                link_target_parts[common_segment_count:]
+            )
+
+            normalized_link_target = "/".join(normalized_link_target_parts)
+    else:
+        # Per Debian Policy, must be absolute
+        normalized_link_target = "/" + "/".join(link_target_parts)
+
+    return normalized_link_target
+
+
+def has_glob_magic(pattern: str) -> bool:
+    return glob.has_magic(pattern) or "{" in pattern
+
+
+def glob_escape(replacement_value: str) -> str:
+    if not glob.has_magic(replacement_value) or "{" not in replacement_value:
+        return replacement_value
+    return (
+        replacement_value.replace("[", "[[]")
+        .replace("]", "[]]")
+        .replace("*", "[*]")
+        .replace("?", "[?]")
+        .replace("{", "[{]")
+        .replace("}", "[}]")
+    )
+
+
+# TODO: This logic should probably be moved to `python-debian`
+def active_profiles_match(
+    profiles_raw: str,
+    active_build_profiles: Union[Set[str], FrozenSet[str]],
+) -> bool:
+    profiles_raw = profiles_raw.strip()
+    if profiles_raw[0] != "<" or profiles_raw[-1] != ">" or profiles_raw == "<>":
+        raise ValueError(
+            'Invalid Build-Profiles: Must start start and end with "<" + ">" but cannot be a literal "<>"'
+        )
+    profile_groups = _PROFILE_GROUP_SPLIT.split(profiles_raw[1:-1])
+    for profile_group_raw in profile_groups:
+        should_process_package = True
+        for profile_name in profile_group_raw.split():
+            negation = False
+            if profile_name[0] == "!":
+                negation = True
+                profile_name = profile_name[1:]
+
+            matched_profile = profile_name in active_build_profiles
+            if matched_profile == negation:
+                should_process_package = False
+                break
+
+        if should_process_package:
+            return True
+
+    return False
+
+
+def _parse_build_profiles(build_profiles_raw: str) -> FrozenSet[FrozenSet[str]]:
+    profiles_raw = build_profiles_raw.strip()
+    if profiles_raw[0] != "<" or profiles_raw[-1] != ">" or profiles_raw == "<>":
+        raise ValueError(
+            'Invalid Build-Profiles: Must start start and end with "<" + ">" but cannot be a literal "<>"'
+        )
+    profile_groups = _PROFILE_GROUP_SPLIT.split(profiles_raw[1:-1])
+    return frozenset(frozenset(g.split()) for g in profile_groups)
+
+
+def resolve_source_date_epoch(
+    command_line_value: Optional[int],
+    *,
+    substitution: Optional["Substitution"] = None,
+) -> int:
+    mtime = command_line_value
+    if mtime is None and "SOURCE_DATE_EPOCH" in os.environ:
+        sde_raw = os.environ["SOURCE_DATE_EPOCH"]
+        if sde_raw == "":
+            _error("SOURCE_DATE_EPOCH is set but empty.")
+        mtime = int(sde_raw)
+    if mtime is None and substitution is not None:
+        try:
+            sde_raw = substitution.substitute(
+                "{{SOURCE_DATE_EPOCH}}",
+                "Internal resolution",
+            )
+            mtime = int(sde_raw)
+        except (DebputySubstitutionError, ValueError):
+            pass
+    if mtime is None:
+        mtime = int(time.time())
+    os.environ["SOURCE_DATE_EPOCH"] = str(mtime)
+    return mtime
+
+
+def compute_output_filename(control_root_dir: str, is_udeb: bool) -> str:
+    with open(os.path.join(control_root_dir, "control"), "rt") as fd:
+        control_file = Deb822(fd)
+
+    package_name = control_file["Package"]
+    package_version = control_file["Version"]
+    package_architecture = control_file["Architecture"]
+    extension = control_file.get("Package-Type") or "deb"
+    if ":" in package_version:
+        package_version = package_version.split(":", 1)[1]
+    if is_udeb:
+        extension = "udeb"
+
+    return f"{package_name}_{package_version}_{package_architecture}.{extension}"
+
+
+_SCRATCH_DIR = None
+_DH_INTEGRATION_MODE = False
+
+
+def integrated_with_debhelper() -> None:
+    global _DH_INTEGRATION_MODE
+    _DH_INTEGRATION_MODE = True
+
+
+def scratch_dir() -> str:
+    global _SCRATCH_DIR
+    if _SCRATCH_DIR is not None:
+        return _SCRATCH_DIR
+    debputy_scratch_dir = "debian/.debputy/scratch-dir"
+    is_debputy_dir = True
+    if os.path.isdir("debian/.debputy") and not _DH_INTEGRATION_MODE:
+        _SCRATCH_DIR = debputy_scratch_dir
+    elif os.path.isdir("debian/.debhelper") or _DH_INTEGRATION_MODE:
+        _SCRATCH_DIR = "debian/.debhelper/_debputy/scratch-dir"
+        is_debputy_dir = False
+    else:
+        _SCRATCH_DIR = debputy_scratch_dir
+    ensure_dir(_SCRATCH_DIR)
+    if is_debputy_dir:
+        Path("debian/.debputy/.gitignore").write_text("*\n")
+    return _SCRATCH_DIR
+
+
+_RUNTIME_CONTAINER_DIR_KEY: Optional[str] = None
+
+
+def generated_content_dir(
+    *,
+    package: Optional["BinaryPackage"] = None,
+    subdir_key: Optional[str] = None,
+) -> str:
+    global _RUNTIME_CONTAINER_DIR_KEY
+    container_dir = _RUNTIME_CONTAINER_DIR_KEY
+    first_run = False
+
+    if container_dir is None:
+        first_run = True
+        container_dir = f"_pb-{os.getpid()}"
+        _RUNTIME_CONTAINER_DIR_KEY = container_dir
+
+    directory = os.path.join(scratch_dir(), container_dir)
+
+    if first_run and os.path.isdir(directory):
+        # In the unlikely case there is a re-run with exactly the same pid, `debputy` should not
+        # see "stale" data.
+        # TODO: Ideally, we would always clean up this directory on failure, but `atexit` is not
+        #  reliable enough for that and we do not have an obvious hook for it.
+        shutil.rmtree(directory)
+
+    directory = os.path.join(
+        directory,
+        "generated-fs-content",
+        f"pkg_{package.name}" if package else "no-package",
+    )
+    if subdir_key is not None:
+        directory = os.path.join(directory, subdir_key)
+
+    os.makedirs(directory, exist_ok=True)
+    return directory
+
+
+PerlIncDir = collections.namedtuple("PerlIncDir", ["vendorlib", "vendorarch"])
+PerlConfigData = collections.namedtuple("PerlConfigData", ["version", "debian_abi"])
+_PERL_MODULE_DIRS: Dict[str, PerlIncDir] = {}
+
+
+@functools.lru_cache(1)
+def _perl_config_data() -> PerlConfigData:
+    d = (
+        subprocess.check_output(
+            [
+                "perl",
+                "-MConfig",
+                "-e",
+                'print "$Config{version}\n$Config{debian_abi}\n"',
+            ]
+        )
+        .decode("utf-8")
+        .splitlines()
+    )
+    return PerlConfigData(*d)
+
+
+def _perl_version() -> str:
+    return _perl_config_data().version
+
+
+def perlxs_api_dependency() -> str:
+    # dh_perl used the build version of perl for this, so we will too.  Most of the perl cross logic
+    # assumes that the major version of build variant of Perl is the same as the host variant of Perl.
+    config = _perl_config_data()
+    if config.debian_abi is not None and config.debian_abi != "":
+        return f"perlapi-{config.debian_abi}"
+    return f"perlapi-{config.version}"
+
+
+def perl_module_dirs(
+    dpkg_architecture_variables: DpkgArchitectureBuildProcessValuesTable,
+    dctrl_bin: "BinaryPackage",
+) -> PerlIncDir:
+    global _PERL_MODULE_DIRS
+    arch = (
+        dctrl_bin.resolved_architecture
+        if dpkg_architecture_variables.is_cross_compiling
+        else "_default_"
+    )
+    module_dir = _PERL_MODULE_DIRS.get(arch)
+    if module_dir is None:
+        cmd = ["perl"]
+        if dpkg_architecture_variables.is_cross_compiling:
+            version = _perl_version()
+            inc_dir = f"/usr/lib/{dctrl_bin.deb_multiarch}/perl/cross-config-{version}"
+            # FIXME: This should not fallback to "build-arch" but on the other hand, we use the perl module dirs
+            #  for every package at the moment. So mandating correct perl dirs implies mandating perl-xs-dev in
+            #  cross builds... meh.
+            if os.path.exists(os.path.join(inc_dir, "Config.pm")):
+                cmd.append(f"-I{inc_dir}")
+        cmd.extend(
+            ["-MConfig", "-e", 'print "$Config{vendorlib}\n$Config{vendorarch}\n"']
+        )
+        output = subprocess.check_output(cmd).decode("utf-8").splitlines(keepends=False)
+        if len(output) != 2:
+            raise ValueError(
+                "Internal error: Unable to determine the perl include directories:"
+                f" Raw output from perl snippet: {output}"
+            )
+        module_dir = PerlIncDir(
+            vendorlib=_normalize_path(output[0]),
+            vendorarch=_normalize_path(output[1]),
+        )
+        _PERL_MODULE_DIRS[arch] = module_dir
+    return module_dir
+
+
+@functools.lru_cache(1)
+def detect_fakeroot() -> bool:
+    if os.getuid() != 0 or "LD_PRELOAD" not in os.environ:
+        return False
+    env = dict(os.environ)
+    del env["LD_PRELOAD"]
+    try:
+        return subprocess.check_output(["id", "-u"], env=env).strip() != b"0"
+    except subprocess.CalledProcessError:
+        print(
+            'Could not run "id -u" with LD_PRELOAD unset; assuming we are not run under fakeroot',
+            file=sys.stderr,
+        )
+        return False
+
+
+@functools.lru_cache(1)
+def _sc_arg_max() -> Optional[int]:
+    try:
+        return os.sysconf("SC_ARG_MAX")
+    except RuntimeError:
+        _warn("Could not resolve SC_ARG_MAX, falling back to a hard-coded limit")
+        return None
+
+
+def _split_xargs_args(
+    static_cmd: Sequence[str],
+    max_args_byte_len: int,
+    varargs: Iterable[str],
+    reuse_list_ok: bool,
+) -> Iterator[List[str]]:
+    static_cmd_len = len(static_cmd)
+    remaining_len = max_args_byte_len
+    pending_args = list(static_cmd)
+    for arg in varargs:
+        arg_len = len(arg.encode("utf-8")) + 1  # +1 for leading space
+        remaining_len -= arg_len
+        if not remaining_len:
+            if len(pending_args) <= static_cmd_len:
+                raise ValueError(
+                    f"Could not fit a single argument into the command line !?"
+                    f" {max_args_byte_len} (variable argument limit) < {arg_len} (argument length)"
+                )
+            yield pending_args
+            remaining_len = max_args_byte_len - arg_len
+            if reuse_list_ok:
+                pending_args.clear()
+                pending_args.extend(static_cmd)
+            else:
+                pending_args = list(static_cmd)
+        pending_args.append(arg)
+
+    if len(pending_args) > static_cmd_len:
+        yield pending_args
+
+
+def xargs(
+    static_cmd: Sequence[str],
+    varargs: Iterable[str],
+    *,
+    env: Optional[Mapping[str, str]] = None,
+    reuse_list_ok: bool = False,
+) -> Iterator[List[str]]:
+    max_args_bytes = _sc_arg_max()
+    # len overshoots with one space explaining the -1.  The _split_xargs_args
+    # will account for the space for the first argument
+    static_byte_len = (
+        len(static_cmd) - 1 + sum(len(a.encode("utf-8")) for a in static_cmd)
+    )
+    if max_args_bytes is not None:
+        if env is None:
+            # +2 for nul bytes after key and value
+            static_byte_len += sum(len(k) + len(v) + 2 for k, v in os.environb.items())
+        else:
+            # +2 for nul bytes after key and value
+            static_byte_len += sum(
+                len(k.encode("utf-8")) + len(v.encode("utf-8")) + 2
+                for k, v in env.items()
+            )
+        # Add a fixed buffer for OS overhead here (in case env and cmd both must be page-aligned or something like
+        # that)
+        static_byte_len += 2 * 4096
+    else:
+        # The 20 000 limit is from debhelper, and it did not account for environment.  So neither will we here.
+        max_args_bytes = 20_000
+    remain_len = max_args_bytes - static_byte_len
+    yield from _split_xargs_args(static_cmd, remain_len, varargs, reuse_list_ok)
+
+
+# itertools recipe
+def grouper(
+    iterable: Iterable[T],
+    n: int,
+    *,
+    incomplete: Literal["fill", "strict", "ignore"] = "fill",
+    fillvalue: Optional[T] = None,
+) -> Iterator[Tuple[T, ...]]:
+    """Collect data into non-overlapping fixed-length chunks or blocks"""
+    # grouper('ABCDEFG', 3, fillvalue='x') --> ABC DEF Gxx
+    # grouper('ABCDEFG', 3, incomplete='strict') --> ABC DEF ValueError
+    # grouper('ABCDEFG', 3, incomplete='ignore') --> ABC DEF
+    args = [iter(iterable)] * n
+    if incomplete == "fill":
+        return zip_longest(*args, fillvalue=fillvalue)
+    if incomplete == "strict":
+        return zip(*args, strict=True)
+    if incomplete == "ignore":
+        return zip(*args)
+    else:
+        raise ValueError("Expected fill, strict, or ignore")
+
+
+_LOGGING_SET_UP = False
+
+
+def _check_color() -> Tuple[bool, bool, Optional[str]]:
+    dpkg_or_default = os.environ.get(
+        "DPKG_COLORS", "never" if "NO_COLOR" in os.environ else "auto"
+    )
+    requested_color = os.environ.get("DEBPUTY_COLORS", dpkg_or_default)
+    bad_request = None
+    if requested_color not in {"auto", "always", "never"}:
+        bad_request = requested_color
+        requested_color = "auto"
+
+    if requested_color == "auto":
+        stdout_color = sys.stdout.isatty()
+        stderr_color = sys.stdout.isatty()
+    else:
+        enable = requested_color == "always"
+        stdout_color = enable
+        stderr_color = enable
+    return stdout_color, stderr_color, bad_request
+
+
+def program_name() -> str:
+    name = os.path.basename(sys.argv[0])
+    if name.endswith(".py"):
+        name = name[:-3]
+    if name == "__main__":
+        name = os.path.basename(os.path.dirname(sys.argv[0]))
+    # FIXME: Not optimal that we have to hardcode these kind of things here
+    if name == "debputy_cmd":
+        name = "debputy"
+    return name
+
+
+def package_cross_check_precheck(
+    pkg_a: "BinaryPackage",
+    pkg_b: "BinaryPackage",
+) -> Tuple[bool, bool]:
+    """Whether these two packages can do content cross-checks
+
+    :param pkg_a: The first package
+    :param pkg_b: The second package
+    :return: A tuple if two booleans. If the first is True, then binary_package_a may do content cross-checks
+      that invoĺves binary_package_b. If the second is True, then binary_package_b may do content cross-checks
+      that involves binary_package_a. Both can be True and both can be False at the same time, which
+      happens in common cases (arch:all + arch:any cases both to be False as a common example).
+    """
+
+    # Handle the two most obvious base-cases
+    if not pkg_a.should_be_acted_on or not pkg_b.should_be_acted_on:
+        return False, False
+    if pkg_a.is_arch_all ^ pkg_b.is_arch_all:
+        return False, False
+
+    a_may_see_b = True
+    b_may_see_a = True
+
+    a_bp = pkg_a.fields.get("Build-Profiles", "")
+    b_bp = pkg_b.fields.get("Build-Profiles", "")
+
+    if a_bp != b_bp:
+        a_bp_set = _parse_build_profiles(a_bp) if a_bp != "" else frozenset()
+        b_bp_set = _parse_build_profiles(b_bp) if b_bp != "" else frozenset()
+
+        # Check for build profiles being identically but just ordered differently.
+        if a_bp_set != b_bp_set:
+            # For simplicity, we let groups cancel each other out. If one side has no clauses
+            # left, then it will always be built when the other is built.
+            #
+            # Eventually, someone will be here with a special case where more complex logic is
+            # required. Good luck to you! Remember to add test cases for it (the existing logic
+            # has some for a reason and if the logic is going to be more complex, it will need
+            # tests cases to assert it fixes the problem and does not regress)
+            if a_bp_set - b_bp_set:
+                a_may_see_b = False
+            if b_bp_set - a_bp_set:
+                b_may_see_a = False
+
+    if pkg_a.declared_architecture != pkg_b.declared_architecture:
+        # Also here we could do a subset check, but wildcards vs. non-wildcards make that a pain
+        if pkg_a.declared_architecture != "any":
+            b_may_see_a = False
+        if pkg_a.declared_architecture != "any":
+            a_may_see_b = False
+
+    return a_may_see_b, b_may_see_a
+
+
+def setup_logging(
+    *, log_only_to_stderr: bool = False, reconfigure_logging: bool = False
+) -> None:
+    global _LOGGING_SET_UP, _DEFAULT_LOGGER, _STDOUT_HANDLER, _STDERR_HANDLER
+    if _LOGGING_SET_UP and not reconfigure_logging:
+        raise RuntimeError(
+            "Logging has already been configured."
+            " Use reconfigure_logging=True if you need to reconfigure it"
+        )
+    stdout_color, stderr_color, bad_request = _check_color()
+
+    if stdout_color or stderr_color:
+        try:
+            import colorlog
+        except ImportError:
+            stdout_color = False
+            stderr_color = False
+
+    if log_only_to_stderr:
+        stdout = sys.stderr
+        stdout_color = stderr_color
+    else:
+        stdout = sys.stderr
+
+    class LogLevelFilter(logging.Filter):
+        def __init__(self, threshold: int, above: bool):
+            super().__init__()
+            self.threshold = threshold
+            self.above = above
+
+        def filter(self, record: logging.LogRecord) -> bool:
+            if self.above:
+                return record.levelno >= self.threshold
+            else:
+                return record.levelno < self.threshold
+
+    color_format = (
+        "{bold}{name}{reset}: {bold}{log_color}{levelnamelower}{reset}: {message}"
+    )
+    colorless_format = "{name}: {levelnamelower}: {message}"
+
+    existing_stdout_handler = _STDOUT_HANDLER
+    existing_stderr_handler = _STDERR_HANDLER
+
+    if stdout_color:
+        stdout_handler = colorlog.StreamHandler(stdout)
+        stdout_handler.setFormatter(
+            colorlog.ColoredFormatter(color_format, style="{", force_color=True)
+        )
+        logger = colorlog.getLogger()
+        if existing_stdout_handler is not None:
+            logger.removeHandler(existing_stdout_handler)
+        _STDOUT_HANDLER = stdout_handler
+        logger.addHandler(stdout_handler)
+    else:
+        stdout_handler = logging.StreamHandler(stdout)
+        stdout_handler.setFormatter(logging.Formatter(colorless_format, style="{"))
+        logger = logging.getLogger()
+        if existing_stdout_handler is not None:
+            logger.removeHandler(existing_stdout_handler)
+        _STDOUT_HANDLER = stdout_handler
+        logger.addHandler(stdout_handler)
+
+    if stderr_color:
+        stderr_handler = colorlog.StreamHandler(sys.stderr)
+        stderr_handler.setFormatter(
+            colorlog.ColoredFormatter(color_format, style="{", force_color=True)
+        )
+        logger = logging.getLogger()
+        if existing_stdout_handler is not None:
+            logger.removeHandler(existing_stderr_handler)
+        _STDERR_HANDLER = stderr_handler
+        logger.addHandler(stderr_handler)
+    else:
+        stderr_handler = logging.StreamHandler(sys.stderr)
+        stderr_handler.setFormatter(logging.Formatter(colorless_format, style="{"))
+        logger = logging.getLogger()
+        if existing_stdout_handler is not None:
+            logger.removeHandler(existing_stderr_handler)
+        _STDERR_HANDLER = stderr_handler
+        logger.addHandler(stderr_handler)
+
+    stdout_handler.addFilter(LogLevelFilter(logging.WARN, False))
+    stderr_handler.addFilter(LogLevelFilter(logging.WARN, True))
+
+    name = program_name()
+
+    old_factory = logging.getLogRecordFactory()
+
+    def record_factory(
+        *args: Any, **kwargs: Any
+    ) -> logging.LogRecord:  # pragma: no cover
+        record = old_factory(*args, **kwargs)
+        record.levelnamelower = record.levelname.lower()
+        return record
+
+    logging.setLogRecordFactory(record_factory)
+
+    logging.getLogger().setLevel(logging.INFO)
+    _DEFAULT_LOGGER = logging.getLogger(name)
+
+    if bad_request:
+        _DEFAULT_LOGGER.warning(
+            f'Invalid color request for "{bad_request}" in either DEBPUTY_COLORS or DPKG_COLORS.'
+            ' Resetting to "auto".'
+        )
+
+    _LOGGING_SET_UP = True
diff --git a/src/debputy/version.py b/src/debputy/version.py
new file mode 100644
index 0000000..de56318
--- /dev/null
+++ b/src/debputy/version.py
@@ -0,0 +1,67 @@
+from typing import Optional, Callable
+
+__version__ = "N/A"
+
+IS_RELEASE_BUILD = False
+
+if __version__ in ("N/A",):
+    import subprocess
+
+    class LazyString:
+        def __init__(self, initializer: Callable[[], str]) -> None:
+            self._initializer = initializer
+            self._value: Optional[str] = None
+
+        def __str__(self) -> str:
+            value = object.__getattribute__(self, "_value")
+            if value is None:
+                value = object.__getattribute__(self, "_initializer")()
+                object.__setattr__(self, "_value", value)
+            return value
+
+        def __getattribute__(self, item):
+            value = str(self)
+            return getattr(value, item)
+
+        def __contains__(self, item):
+            return item in str(self)
+
+    def _initialize_version() -> str:
+        try:
+            devnull: Optional[int] = subprocess.DEVNULL
+        except AttributeError:
+            devnull = None  # Not supported, but not critical
+
+        try:
+            v = (
+                subprocess.check_output(
+                    ["git", "describe", "--tags"],
+                    stderr=devnull,
+                )
+                .strip()
+                .decode("utf-8")
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            try:
+                v = (
+                    subprocess.check_output(
+                        ["dpkg-parsechangelog", "-SVersion"],
+                        stderr=devnull,
+                    )
+                    .strip()
+                    .decode("utf-8")
+                )
+
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                v = "N/A"
+
+        if v.startswith("debian/"):
+            v = v[7:]
+        return v
+
+    __version__ = LazyString(_initialize_version)
+    IS_RELEASE_BUILD = False
+
+else:
+    # Disregard snapshot versions (gbp dch -S) as "release builds"
+    IS_RELEASE_BUILD = ".gbp" not in __version__
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..1f2ed3d
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,167 @@
+import os
+from typing import Mapping
+
+import pytest
+from debian.deb822 import Deb822
+from debian.debian_support import DpkgArchTable
+
+from debputy._deb_options_profiles import DebBuildOptionsAndProfiles
+from debputy.architecture_support import (
+    DpkgArchitectureBuildProcessValuesTable,
+    faked_arch_table,
+)
+from debputy.filesystem_scan import FSROOverlay
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage, SourcePackage
+from debputy.plugin.debputy.debputy_plugin import initialize_debputy_features
+from debputy.plugin.api.impl_types import (
+    DebputyPluginMetadata,
+)
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.plugin.api.impl import DebputyPluginInitializerProvider
+from debputy.substitution import (
+    NULL_SUBSTITUTION,
+    Substitution,
+    SubstitutionImpl,
+    VariableContext,
+)
+
+# Disable dpkg's translation layer.  It is very slow and disabling it makes it easier to debug
+# test-failure reports from systems with translations active.
+os.environ["DPKG_NLS"] = "0"
+
+
+@pytest.fixture(scope="session")
+def amd64_dpkg_architecture_variables() -> DpkgArchitectureBuildProcessValuesTable:
+    return faked_arch_table("amd64")
+
+
+@pytest.fixture(scope="session")
+def dpkg_arch_query() -> DpkgArchTable:
+    return DpkgArchTable.load_arch_table()
+
+
+@pytest.fixture()
+def source_package() -> SourcePackage:
+    return SourcePackage(
+        {
+            "Source": "foo",
+        }
+    )
+
+
+@pytest.fixture()
+def package_single_foo_arch_all_cxt_amd64(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+) -> Mapping[str, BinaryPackage]:
+    return {
+        p.name: p
+        for p in [
+            BinaryPackage(
+                Deb822(
+                    {
+                        "Package": "foo",
+                        "Architecture": "all",
+                    }
+                ),
+                amd64_dpkg_architecture_variables,
+                dpkg_arch_query,
+                is_main_package=True,
+            )
+        ]
+    }
+
+
+@pytest.fixture()
+def package_foo_w_udeb_arch_any_cxt_amd64(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+) -> Mapping[str, BinaryPackage]:
+    return {
+        p.name: p
+        for p in [
+            BinaryPackage(
+                Deb822(
+                    {
+                        "Package": "foo",
+                        "Architecture": "any",
+                    }
+                ),
+                amd64_dpkg_architecture_variables,
+                dpkg_arch_query,
+                is_main_package=True,
+            ),
+            BinaryPackage(
+                Deb822(
+                    {
+                        "Package": "foo-udeb",
+                        "Architecture": "any",
+                        "Package-Type": "udeb",
+                    }
+                ),
+                amd64_dpkg_architecture_variables,
+                dpkg_arch_query,
+            ),
+        ]
+    }
+
+
+@pytest.fixture(scope="session")
+def null_substitution() -> Substitution:
+    return NULL_SUBSTITUTION
+
+
+@pytest.fixture(scope="session")
+def _empty_debputy_plugin_feature_set() -> PluginProvidedFeatureSet:
+    return PluginProvidedFeatureSet()
+
+
+@pytest.fixture(scope="session")
+def amd64_substitution(
+    amd64_dpkg_architecture_variables,
+    _empty_debputy_plugin_feature_set,
+) -> Substitution:
+    debian_dir = FSROOverlay.create_root_dir("debian", "debian")
+    variable_context = VariableContext(
+        debian_dir,
+    )
+    return SubstitutionImpl(
+        plugin_feature_set=_empty_debputy_plugin_feature_set,
+        dpkg_arch_table=amd64_dpkg_architecture_variables,
+        static_variables=None,
+        environment={},
+        unresolvable_substitutions=frozenset(["SOURCE_DATE_EPOCH", "PACKAGE"]),
+        variable_context=variable_context,
+    )
+
+
+@pytest.fixture(scope="session")
+def no_profiles_or_build_options() -> DebBuildOptionsAndProfiles:
+    return DebBuildOptionsAndProfiles(environ={})
+
+
+@pytest.fixture(scope="session")
+def debputy_plugin_feature_set(
+    _empty_debputy_plugin_feature_set, amd64_substitution
+) -> PluginProvidedFeatureSet:
+    plugin_metadata = DebputyPluginMetadata(
+        plugin_name="debputy",
+        api_compat_version=1,
+        plugin_initializer=initialize_debputy_features,
+        plugin_loader=None,
+        plugin_path="<loaded-via-test>",
+    )
+    feature_set = _empty_debputy_plugin_feature_set
+    api = DebputyPluginInitializerProvider(
+        plugin_metadata,
+        feature_set,
+        amd64_substitution,
+    )
+    api.load_plugin()
+    return feature_set
+
+
+@pytest.fixture
+def attribute_path(request) -> AttributePath:
+    return AttributePath.builtin_path()[request.node.nodeid]
diff --git a/tests/data/custom-plugin.json.in b/tests/data/custom-plugin.json.in
new file mode 100644
index 0000000..67ca847
--- /dev/null
+++ b/tests/data/custom-plugin.json.in
@@ -0,0 +1,16 @@
+{
+  "plugin-initializer": "custom_plugin_initializer",
+  "api-compat-version": 1,
+  "packager-provided-files": [
+    {
+      "stem": "test-file-from-json",
+      "installed-path": "/usr/share/test-files/{name}.test",
+      "default-mode": "0644",
+      "allow-name-segment": true,
+      "reference-documentation": {
+          "description": "test of loading PPFs from a JSON",
+          "format-documentation-uris": ["man:ls(1)"]
+      }
+    }
+  ]
+}
diff --git a/tests/data/custom_plugin.py b/tests/data/custom_plugin.py
new file mode 100644
index 0000000..41d9779
--- /dev/null
+++ b/tests/data/custom_plugin.py
@@ -0,0 +1,25 @@
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    VirtualPath,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+)
+
+
+def _udeb_metadata_detector(
+    _path: VirtualPath,
+    ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    ctrl.substvars["Test:Udeb-Metadata-Detector"] = "was-run"
+
+
+def custom_plugin_initializer(api: DebputyPluginInitializer) -> None:
+    api.packager_provided_file(
+        "my-file",
+        "/no-where/this/is/a/test/plugin/{name}.conf",
+        post_formatting_rewrite=lambda x: x.replace("+", "_"),
+    )
+    api.metadata_or_maintscript_detector(
+        "udeb-only", _udeb_metadata_detector, package_type="udeb"
+    )
diff --git a/tests/plugin_tests/conftest.py b/tests/plugin_tests/conftest.py
new file mode 100644
index 0000000..f2a8aea
--- /dev/null
+++ b/tests/plugin_tests/conftest.py
@@ -0,0 +1,20 @@
+import os
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def workaround_debputys_own_test_suite() -> None:
+    # This fixture is only required as long as the tests are run inside `debputy`'s
+    # own test suite.  If you copy out a plugin + tests, you should *not* need this
+    # fixture.
+    #
+    # The problem appears because in the debputy source package, these plugins are
+    # always provided in their "installed" location.
+    orig = os.environ.get("DEBPUTY_TEST_PLUGIN_LOCATION")
+    os.environ["DEBPUTY_TEST_PLUGIN_LOCATION"] = "installed"
+    yield
+    if orig is None:
+        del os.environ["DEBPUTY_TEST_PLUGIN_LOCATION"]
+    else:
+        os.environ["DEBPUTY_TEST_PLUGIN_LOCATION"] = orig
diff --git a/tests/plugin_tests/gnome_test.py b/tests/plugin_tests/gnome_test.py
new file mode 100644
index 0000000..ec27a85
--- /dev/null
+++ b/tests/plugin_tests/gnome_test.py
@@ -0,0 +1,45 @@
+import pytest
+
+from debputy.plugin.api.test_api import (
+    initialize_plugin_under_test,
+    build_virtual_file_system,
+    package_metadata_context,
+)
+
+
+@pytest.mark.parametrize(
+    "version,expected_version,expected_next_version",
+    [
+        (
+            "1:3.36.1",
+            "1:3.36",
+            "1:3.38",
+        ),
+        (
+            "3.38.2",
+            "3.38",
+            "40",
+        ),
+        (
+            "40.2.0",
+            "40~",
+            "41~",
+        ),
+        (
+            "40",
+            "40~",
+            "41~",
+        ),
+    ],
+)
+def test_gnome_plugin(
+    version: str,
+    expected_version: str,
+    expected_next_version: str,
+) -> None:
+    plugin = initialize_plugin_under_test()
+    fs = build_virtual_file_system([])
+    context = package_metadata_context(binary_package_version=version)
+    metadata = plugin.run_metadata_detector("gnome-versions", fs, context)
+    assert metadata.substvars["gnome:Version"] == expected_version
+    assert metadata.substvars["gnome:NextVersion"] == expected_next_version
diff --git a/tests/plugin_tests/numpy3_test.data b/tests/plugin_tests/numpy3_test.data
new file mode 100644
index 0000000..22b65a2
--- /dev/null
+++ b/tests/plugin_tests/numpy3_test.data
@@ -0,0 +1,4 @@
+# Values taken from 1:1.24.2-1
+abi 9
+api 16
+api-min-version 1:1.22.0
diff --git a/tests/plugin_tests/numpy3_test.py b/tests/plugin_tests/numpy3_test.py
new file mode 100644
index 0000000..9b252fb
--- /dev/null
+++ b/tests/plugin_tests/numpy3_test.py
@@ -0,0 +1,38 @@
+import os
+
+import pytest
+
+from debputy.plugin.api.test_api import (
+    initialize_plugin_under_test,
+    build_virtual_file_system,
+    package_metadata_context,
+)
+
+DATA_FILE = os.path.join(os.path.dirname(__file__), "numpy3_test.data")
+
+
+@pytest.fixture(scope="session")
+def numpy3_stub_data_file() -> None:
+    os.environ["_NUMPY_TEST_PATH"] = DATA_FILE
+    yield
+    try:
+        del os.environ["_NUMPY_TEST_PATH"]
+    except KeyError:
+        pass
+
+
+def test_numpy3_plugin_arch_all(numpy3_stub_data_file) -> None:
+    plugin = initialize_plugin_under_test()
+    fs = build_virtual_file_system([])
+    context = package_metadata_context(package_fields={"Architecture": "all"})
+    metadata = plugin.run_metadata_detector("numpy-depends", fs, context)
+    assert metadata.substvars["python3:Depends"] == "python3-numpy"
+
+
+def test_numpy3_plugin_arch_any(numpy3_stub_data_file) -> None:
+    plugin = initialize_plugin_under_test()
+    fs = build_virtual_file_system([])
+    context = package_metadata_context(package_fields={"Architecture": "any"})
+    metadata = plugin.run_metadata_detector("numpy-depends", fs, context)
+    expected = "python3-numpy (>= 1:1.22.0), python3-numpy-abi9"
+    assert metadata.substvars["python3:Depends"] == expected
diff --git a/tests/plugin_tests/perl-openssl_test.py b/tests/plugin_tests/perl-openssl_test.py
new file mode 100644
index 0000000..37f2ba1
--- /dev/null
+++ b/tests/plugin_tests/perl-openssl_test.py
@@ -0,0 +1,33 @@
+import stat
+import os
+
+import pytest
+
+from debputy.plugin.api.test_api import (
+    initialize_plugin_under_test,
+    build_virtual_file_system,
+    package_metadata_context,
+)
+
+STUB_CMD = os.path.join(os.path.dirname(__file__), "perl-ssl_test.sh")
+
+
+@pytest.fixture(scope="session")
+def perl_ssl_stub_cmd() -> None:
+    os.environ["_PERL_SSL_DEFAULTS_TEST_PATH"] = STUB_CMD
+    mode = stat.S_IMODE(os.stat(STUB_CMD).st_mode)
+    if (mode & 0o500) != 0o500:
+        os.chmod(STUB_CMD, mode | 0o500)
+    yield
+    try:
+        del os.environ["_PERL_SSL_DEFAULTS_TEST_PATH"]
+    except KeyError:
+        pass
+
+
+def test_perl_openssl(perl_ssl_stub_cmd) -> None:
+    plugin = initialize_plugin_under_test()
+    fs = build_virtual_file_system([])
+    context = package_metadata_context(package_fields={"Architecture": "all"})
+    metadata = plugin.run_metadata_detector("perl-openssl-abi", fs, context)
+    assert metadata.substvars["perl:Depends"] == "perl-openssl-abi-3"
diff --git a/tests/plugin_tests/perl-ssl_test.sh b/tests/plugin_tests/perl-ssl_test.sh
new file mode 100755
index 0000000..5238dc7
--- /dev/null
+++ b/tests/plugin_tests/perl-ssl_test.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# The original script looks up libssl.so and extract part of the SONAME,
+# which is all adequately stubbed by:
+echo 3
diff --git a/tests/test_apply_compression.py b/tests/test_apply_compression.py
new file mode 100644
index 0000000..70817f9
--- /dev/null
+++ b/tests/test_apply_compression.py
@@ -0,0 +1,33 @@
+from debputy.filesystem_scan import build_virtual_fs
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.debputy.package_processors import apply_compression
+
+
+def test_apply_compression():
+    # TODO: This test should be a proper plugin test
+    fs_root = build_virtual_fs(
+        [
+            virtual_path_def(
+                "./usr/share/man/man1/foo.1",
+                materialized_content="manpage content",
+            ),
+            virtual_path_def("./usr/share/man/man1/bar.1", link_target="foo.1"),
+            virtual_path_def(
+                "./usr/share/man/de/man1/bar.1", link_target="../../man1/foo.1"
+            ),
+        ],
+        read_write_fs=True,
+    )
+    apply_compression(fs_root, None, None)
+
+    assert fs_root.lookup("./usr/share/man/man1/foo.1") is None
+    assert fs_root.lookup("./usr/share/man/man1/foo.1.gz") is not None
+    assert fs_root.lookup("./usr/share/man/man1/bar.1") is None
+    bar_symlink = fs_root.lookup("./usr/share/man/man1/bar.1.gz")
+    assert bar_symlink is not None
+    assert bar_symlink.readlink() == "foo.1.gz"
+
+    assert fs_root.lookup("./usr/share/man/de/man1/bar.1") is None
+    de_bar_symlink = fs_root.lookup("./usr/share/man/de/man1/bar.1.gz")
+    assert de_bar_symlink is not None
+    assert de_bar_symlink.readlink() == "../../man1/foo.1.gz"
diff --git a/tests/test_architecture.py b/tests/test_architecture.py
new file mode 100644
index 0000000..b0431bc
--- /dev/null
+++ b/tests/test_architecture.py
@@ -0,0 +1,59 @@
+from debputy.architecture_support import faked_arch_table
+
+
+# Ensure our mocks seem to be working reasonably
+def test_mock_arch_table():
+    amd64_native_table = faked_arch_table("amd64")
+    amd64_cross_table = faked_arch_table("amd64", build_arch="i386")
+    amd64_cross_target_table = faked_arch_table("amd64", target_arch="arm64")
+    all_differ_table = faked_arch_table("amd64", build_arch="i386", target_arch="arm64")
+
+    for var_stem in ["ARCH", "MULTIARCH"]:
+        host_var = f"DEB_HOST_{var_stem}"
+        build_var = f"DEB_BUILD_{var_stem}"
+        target_var = f"DEB_TARGET_{var_stem}"
+
+        assert (
+            amd64_cross_table.current_host_arch == amd64_native_table.current_host_arch
+        )
+        assert amd64_native_table[host_var] == amd64_native_table[build_var]
+        assert amd64_native_table[host_var] == amd64_native_table[target_var]
+
+        # HOST_ARCH differ in a cross build, but the rest remain the same
+        assert amd64_cross_table[host_var] == amd64_native_table[host_var]
+        assert amd64_cross_table[target_var] == amd64_native_table[target_var]
+        assert amd64_cross_table[build_var] != amd64_native_table[build_var]
+        assert amd64_cross_table[target_var] == amd64_native_table[target_var]
+        assert (
+            amd64_cross_table.current_host_multiarch
+            == amd64_native_table.current_host_multiarch
+        )
+
+        # TARGET_ARCH differ in a cross-compiler build, but the rest remain the same
+        assert amd64_cross_target_table[host_var] == amd64_native_table[host_var]
+        assert amd64_cross_target_table[target_var] != amd64_native_table[target_var]
+        assert amd64_cross_target_table[build_var] == amd64_native_table[build_var]
+        assert (
+            amd64_cross_target_table.current_host_multiarch
+            == amd64_native_table.current_host_multiarch
+        )
+
+        # TARGET_ARCH differ in a cross-compiler build, but the rest remain the same
+        assert all_differ_table[host_var] == amd64_native_table[host_var]
+        assert all_differ_table[target_var] != amd64_native_table[target_var]
+        assert all_differ_table[build_var] != amd64_native_table[build_var]
+        assert all_differ_table[build_var] == amd64_cross_table[build_var]
+        assert all_differ_table[target_var] == amd64_cross_target_table[target_var]
+        assert (
+            all_differ_table.current_host_arch == amd64_native_table.current_host_arch
+        )
+        assert (
+            all_differ_table.current_host_multiarch
+            == amd64_native_table.current_host_multiarch
+        )
+
+    # Finally, check is_cross_compiling
+    assert not amd64_native_table.is_cross_compiling
+    assert amd64_cross_table.is_cross_compiling
+    assert not amd64_cross_target_table.is_cross_compiling
+    assert all_differ_table.is_cross_compiling
diff --git a/tests/test_cross_check_precheck.py b/tests/test_cross_check_precheck.py
new file mode 100644
index 0000000..41bf01c
--- /dev/null
+++ b/tests/test_cross_check_precheck.py
@@ -0,0 +1,124 @@
+from typing import Optional
+
+import pytest
+
+from debputy.plugin.api.test_api import package_metadata_context
+from debputy.util import package_cross_check_precheck
+
+
+@pytest.mark.parametrize(
+    "a_arch,b_arch,a_bp,b_bp,act_on_a,act_on_b,ex_res_a2b,ex_res_b2a",
+    [
+        # Both way OK
+        ("any", "any", None, None, True, True, True, True),
+        ("all", "all", None, None, True, True, True, True),
+        ("any", "any", "<!noudeb>", "<!noudeb>", True, True, True, True),
+        # OK as well. Same BPs just reordered
+        (
+            "any",
+            "any",
+            "<!noudeb !noinsttests>",
+            "<!noinsttests !noudeb>",
+            True,
+            True,
+            True,
+            True,
+        ),
+        (
+            "any",
+            "any",
+            "<!noudeb> <!noinsttests>",
+            "<!noinsttests> <!noudeb>",
+            True,
+            True,
+            True,
+            True,
+        ),
+        # One way OK
+        ("any", "any", None, "<!noudeb>", True, True, True, False),
+        ("any", "any", None, "<pkg.foo.positive-build>", True, True, True, False),
+        # One way OK - BP is clearly a subset of the other
+        (
+            "any",
+            "any",
+            "<!noudeb>",
+            "<!noudeb> <!noinsttests>",
+            True,
+            True,
+            True,
+            False,
+        ),
+        (
+            "any",
+            "any",
+            "<pos>",
+            "<pos> <pkg.foo.positive-build>",
+            True,
+            True,
+            True,
+            False,
+        ),
+        # Currently fails but should probably allow one way
+        (
+            "any",
+            "any",
+            "<!nopython>",
+            "<!noudeb> <!notestests>",
+            True,
+            True,
+            False,
+            False,
+        ),
+        (
+            "any",
+            "any",
+            "<!nopython>",
+            "<!noudeb> <pkg.foo.positive-build>",
+            True,
+            True,
+            False,
+            False,
+        ),
+        # Negative tests
+        ("any", "all", None, None, True, True, False, False),
+        ("all", "all", None, None, True, False, False, False),
+        ("any", "any", None, None, False, True, False, False),
+        ("i386", "amd64", None, None, True, True, False, False),
+    ],
+)
+def test_generate_deb_filename(
+    a_arch: str,
+    b_arch: str,
+    a_bp: Optional[str],
+    b_bp: Optional[str],
+    act_on_a: bool,
+    act_on_b: bool,
+    ex_res_a2b: bool,
+    ex_res_b2a: bool,
+):
+    pkg_a_fields = {
+        "Package": "pkg-a",
+        "Architecture": a_arch,
+    }
+    if a_bp is not None:
+        pkg_a_fields["Build-Profiles"] = a_bp
+
+    pkg_b_fields = {
+        "Package": "pkg-b",
+        "Architecture": b_arch,
+    }
+    if b_bp is not None:
+        pkg_b_fields["Build-Profiles"] = b_bp
+
+    pkg_a = package_metadata_context(
+        package_fields=pkg_a_fields,
+        should_be_acted_on=act_on_a,
+    ).binary_package
+    pkg_b = package_metadata_context(
+        package_fields=pkg_b_fields,
+        should_be_acted_on=act_on_b,
+    ).binary_package
+
+    assert package_cross_check_precheck(pkg_a, pkg_b) == (ex_res_a2b, ex_res_b2a)
+    # Inverted should functionally give the same answer
+    assert package_cross_check_precheck(pkg_b, pkg_a) == (ex_res_b2a, ex_res_a2b)
diff --git a/tests/test_deb_packaging_support.py b/tests/test_deb_packaging_support.py
new file mode 100644
index 0000000..d47526d
--- /dev/null
+++ b/tests/test_deb_packaging_support.py
@@ -0,0 +1,218 @@
+import pytest
+
+from debputy.deb_packaging_support import install_upstream_changelog
+from debputy.filesystem_scan import build_virtual_fs
+from debputy.plugin.api import virtual_path_def
+
+
+@pytest.mark.parametrize(
+    "upstream_changelog_name,other_files",
+    [
+        (
+            "changelog.txt",
+            [
+                "changelog.md",
+                "CHANGELOG.rst",
+                "random-file",
+            ],
+        ),
+        (
+            "CHANGELOG.rst",
+            [
+                "doc/CHANGELOG.txt",
+                "docs/CHANGELOG.md",
+            ],
+        ),
+        (
+            "docs/CHANGELOG.rst",
+            [
+                "docs/history.md",
+            ],
+        ),
+        (
+            "changelog",
+            [],
+        ),
+    ],
+)
+def test_upstream_changelog_from_source(
+    package_single_foo_arch_all_cxt_amd64,
+    upstream_changelog_name,
+    other_files,
+) -> None:
+    upstream_changelog_content = "Some upstream changelog"
+    dctrl = package_single_foo_arch_all_cxt_amd64["foo"]
+    data_fs_root = build_virtual_fs([], read_write_fs=True)
+    upstream_fs_contents = [
+        virtual_path_def("CHANGELOG", materialized_content="Some upstream changelog")
+    ]
+    upstream_fs_contents.extend(
+        virtual_path_def(x, materialized_content="Wrong file!") for x in other_files
+    )
+    source_fs_root = build_virtual_fs(upstream_fs_contents)
+
+    install_upstream_changelog(dctrl, data_fs_root, source_fs_root)
+
+    upstream_changelog = data_fs_root.lookup(f"usr/share/doc/{dctrl.name}/changelog")
+    assert upstream_changelog is not None
+    assert upstream_changelog.is_file
+    with upstream_changelog.open() as fd:
+        content = fd.read()
+    assert upstream_changelog_content == content
+
+
+@pytest.mark.parametrize(
+    "upstream_changelog_basename,other_data_files,other_source_files",
+    [
+        (
+            "CHANGELOG",
+            [
+                "history.txt",
+                "changes.md",
+            ],
+            [
+                "changelog",
+                "doc/CHANGELOG.txt",
+                "docs/CHANGELOG.md",
+            ],
+        ),
+        (
+            "changelog",
+            [
+                "history.txt",
+                "changes.md",
+            ],
+            [
+                "changelog",
+                "doc/CHANGELOG.txt",
+                "docs/CHANGELOG.md",
+            ],
+        ),
+        (
+            "changes.md",
+            [
+                "changelog.rst",
+            ],
+            ["changelog"],
+        ),
+    ],
+)
+def test_upstream_changelog_from_data_fs(
+    package_single_foo_arch_all_cxt_amd64,
+    upstream_changelog_basename,
+    other_data_files,
+    other_source_files,
+) -> None:
+    upstream_changelog_content = "Some upstream changelog"
+    dctrl = package_single_foo_arch_all_cxt_amd64["foo"]
+    doc_dir = f"./usr/share/doc/{dctrl.name}"
+    data_fs_contents = [
+        virtual_path_def(
+            f"{doc_dir}/{upstream_changelog_basename}",
+            materialized_content="Some upstream changelog",
+        )
+    ]
+    data_fs_contents.extend(
+        virtual_path_def(
+            f"{doc_dir}/{x}",
+            materialized_content="Wrong file!",
+        )
+        for x in other_data_files
+    )
+    data_fs_root = build_virtual_fs(data_fs_contents, read_write_fs=True)
+    source_fs_root = build_virtual_fs(
+        [
+            virtual_path_def(
+                x,
+                materialized_content="Wrong file!",
+            )
+            for x in other_source_files
+        ]
+    )
+
+    install_upstream_changelog(dctrl, data_fs_root, source_fs_root)
+
+    upstream_changelog = data_fs_root.lookup(f"usr/share/doc/{dctrl.name}/changelog")
+    assert upstream_changelog is not None
+    assert upstream_changelog.is_file
+    with upstream_changelog.open() as fd:
+        content = fd.read()
+    assert upstream_changelog_content == content
+
+
+def test_upstream_changelog_pre_installed_compressed(
+    package_single_foo_arch_all_cxt_amd64,
+) -> None:
+    dctrl = package_single_foo_arch_all_cxt_amd64["foo"]
+    changelog = f"./usr/share/doc/{dctrl.name}/changelog.gz"
+    data_fs_root = build_virtual_fs(
+        [virtual_path_def(changelog, fs_path="/nowhere/should/not/be/resolved")],
+        read_write_fs=True,
+    )
+    source_fs_root = build_virtual_fs(
+        [virtual_path_def("changelog", materialized_content="Wrong file!")]
+    )
+
+    install_upstream_changelog(dctrl, data_fs_root, source_fs_root)
+
+    upstream_ch_compressed = data_fs_root.lookup(
+        f"usr/share/doc/{dctrl.name}/changelog.gz"
+    )
+    assert upstream_ch_compressed is not None
+    assert upstream_ch_compressed.is_file
+    upstream_ch_uncompressed = data_fs_root.lookup(
+        f"usr/share/doc/{dctrl.name}/changelog"
+    )
+    assert upstream_ch_uncompressed is None
+
+
+def test_upstream_changelog_no_matches(
+    package_single_foo_arch_all_cxt_amd64,
+) -> None:
+    dctrl = package_single_foo_arch_all_cxt_amd64["foo"]
+    doc_dir = f"./usr/share/doc/{dctrl.name}"
+    data_fs_root = build_virtual_fs(
+        [
+            virtual_path_def(
+                f"{doc_dir}/random-file", materialized_content="Wrong file!"
+            ),
+            virtual_path_def(
+                f"{doc_dir}/changelog.Debian", materialized_content="Wrong file!"
+            ),
+        ],
+        read_write_fs=True,
+    )
+    source_fs_root = build_virtual_fs(
+        [virtual_path_def("some-random-file", materialized_content="Wrong file!")]
+    )
+
+    install_upstream_changelog(dctrl, data_fs_root, source_fs_root)
+
+    upstream_ch_compressed = data_fs_root.lookup(
+        f"usr/share/doc/{dctrl.name}/changelog.gz"
+    )
+    assert upstream_ch_compressed is None
+    upstream_ch_uncompressed = data_fs_root.lookup(
+        f"usr/share/doc/{dctrl.name}/changelog"
+    )
+    assert upstream_ch_uncompressed is None
+
+
+def test_upstream_changelog_salsa_issue_49(
+    package_single_foo_arch_all_cxt_amd64,
+) -> None:
+    # https://salsa.debian.org/debian/debputy/-/issues/49
+    dctrl = package_single_foo_arch_all_cxt_amd64["foo"]
+    doc_dir = f"./usr/share/doc/{dctrl.name}"
+    data_fs_root = build_virtual_fs(
+        [virtual_path_def(f"{doc_dir}", link_target="foo-data")], read_write_fs=True
+    )
+    source_fs_root = build_virtual_fs(
+        [virtual_path_def("changelog", materialized_content="Wrong file!")]
+    )
+
+    install_upstream_changelog(dctrl, data_fs_root, source_fs_root)
+
+    doc_dir = data_fs_root.lookup(f"usr/share/doc/{dctrl.name}")
+    assert doc_dir is not None
+    assert doc_dir.is_symlink
diff --git a/tests/test_debputy_plugin.py b/tests/test_debputy_plugin.py
new file mode 100644
index 0000000..a5d7758
--- /dev/null
+++ b/tests/test_debputy_plugin.py
@@ -0,0 +1,1246 @@
+import os
+import textwrap
+from typing import Sequence
+
+import pytest
+
+from debputy.exceptions import (
+    DebputyManifestVariableRequiresDebianDirError,
+    DebputySubstitutionError,
+)
+from debputy.manifest_parser.base_types import SymbolicMode
+from debputy.manifest_parser.util import AttributePath
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.api.spec import DSD
+from debputy.plugin.api.test_api import (
+    build_virtual_file_system,
+    package_metadata_context,
+)
+from debputy.plugin.api.test_api import manifest_variable_resolution_context
+from debputy.plugin.api.test_api.test_impl import initialize_plugin_under_test_preloaded
+from debputy.plugin.api.test_api.test_spec import DetectedService
+from debputy.plugin.debputy.debputy_plugin import initialize_debputy_features
+from debputy.plugin.debputy.private_api import load_libcap
+from debputy.plugin.debputy.service_management import SystemdServiceContext
+from debputy.plugin.debputy.types import DebputyCapability
+
+
+def test_debputy_packager_provided_files():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    ppf_by_stem = plugin.packager_provided_files_by_stem()
+    # Verify that all the files are loaded
+    assert set(ppf_by_stem.keys()) == {
+        "tmpfiles",
+        "sysusers",
+        "bash-completion",
+        "pam",
+        "ppp.ip-up",
+        "ppp.ip-down",
+        "logrotate",
+        "logcheck.cracking",
+        "logcheck.violations",
+        "logcheck.violations.ignore",
+        "logcheck.ignore.workstation",
+        "logcheck.ignore.server",
+        "logcheck.ignore.paranoid",
+        "mime",
+        "sharedmimeinfo",
+        "if-pre-up",
+        "if-up",
+        "if-down",
+        "if-post-down",
+        "cron.hourly",
+        "cron.daily",
+        "cron.weekly",
+        "cron.monthly",
+        "cron.yearly",
+        "cron.d",
+        "initramfs-hook",
+        "modprobe",
+        "gsettings-override",
+        "lintian-overrides",
+        "bug-script",
+        "bug-control",
+        "bug-presubj",
+        "changelog",
+        "NEWS",
+        "copyright",
+        "README.Debian",
+        "TODO",
+        "doc-base",
+        "shlibs",
+        "symbols",
+        "alternatives",
+        "init",
+        "default",
+        "templates",
+        # dh_installsytemd
+        "mount",
+        "path",
+        "service",
+        "socket",
+        "target",
+        "timer",
+        "@path",
+        "@service",
+        "@socket",
+        "@target",
+        "@timer",
+    }
+    # Verify the post_rewrite_hook
+    assert (
+        ppf_by_stem["logcheck.ignore.paranoid"].compute_dest("foo.bar")[1] == "foo_bar"
+    )
+    # Verify custom formats work
+    assert ppf_by_stem["tmpfiles"].compute_dest("foo.bar")[1] == "foo.bar.conf"
+    assert ppf_by_stem["sharedmimeinfo"].compute_dest("foo.bar")[1] == "foo.bar.xml"
+    assert ppf_by_stem["modprobe"].compute_dest("foo.bar")[1] == "foo.bar.conf"
+    assert (
+        ppf_by_stem["gsettings-override"].compute_dest("foo.bar", assigned_priority=20)[
+            1
+        ]
+        == "20_foo.bar.gschema.override"
+    )
+
+
+def test_debputy_docbase_naming() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    doc_base_pff = plugin.packager_provided_files_by_stem()["doc-base"]
+    fs_root = build_virtual_file_system(
+        [virtual_path_def("foo.doc-base", content="Document: bar")]
+    )
+    _, basename = doc_base_pff.compute_dest("foo", path=fs_root["foo.doc-base"])
+    assert basename == "foo.bar"
+
+
+def test_debputy_adr_examples() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    issues = plugin.automatic_discard_rules_examples_with_issues()
+    assert not issues
+
+
+def test_debputy_metadata_detector_gsettings_dependencies():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    # By default, the plugin will not add a substvars
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector("gsettings-dependencies", fs_root)
+    assert "misc:Depends" not in metadata.substvars
+
+    # It will not react if there is only directories or non-files
+    fs_root = build_virtual_file_system(["./usr/share/glib-2.0/schemas/some-dir/"])
+    metadata = plugin.run_metadata_detector("gsettings-dependencies", fs_root)
+    assert "misc:Depends" not in metadata.substvars
+
+    # However, it will if there is a file beneath the schemas dir
+    fs_root = build_virtual_file_system(["./usr/share/glib-2.0/schemas/foo.xml"])
+    metadata = plugin.run_metadata_detector("gsettings-dependencies", fs_root)
+    assert (
+        metadata.substvars["misc:Depends"]
+        == "dconf-gsettings-backend | gsettings-backend"
+    )
+
+
+def test_debputy_metadata_detector_initramfs_hooks():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "initramfs-hooks"
+
+    # By default, the plugin will not add a trigger
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.triggers == []
+
+    # It will not react if the directory is empty
+    fs_root = build_virtual_file_system(
+        [
+            # Use an absolute path to verify that also work (it should and third-party plugin are likely
+            # use absolute paths)
+            "/usr/share/initramfs-tools/hooks/"
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.triggers == []
+
+    # However, it will if there is a file beneath the schemas dir
+    fs_root = build_virtual_file_system(["./usr/share/initramfs-tools/hooks/some-hook"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    result = [t.serialized_format() for t in metadata.triggers]
+    assert result == ["activate-noawait update-initramfs"]
+
+
+def test_debputy_metadata_detector_systemd_tmpfiles():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "systemd-tmpfiles"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    # It only reacts to ".conf" files
+    fs_root = build_virtual_file_system(["./usr/lib/tmpfiles.d/foo"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            "./usr/lib/tmpfiles.d/foo.conf",
+            "./etc/tmpfiles.d/foo.conf",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 1
+    snippet = snippets[0]
+    assert snippet.maintscript == "postinst"
+    assert snippet.registration_method == "on_configure"
+    # The snippet should use "systemd-tmpfiles [...] --create foo.conf ..."
+    assert "--create foo.conf" in snippet.plugin_provided_script
+    # The "foo.conf" should only be listed once
+    assert snippet.plugin_provided_script.count("foo.conf") == 1
+
+
+def test_debputy_metadata_detector_systemd_sysusers():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "systemd-sysusers"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    # It only reacts to ".conf" files
+    fs_root = build_virtual_file_system(["./usr/lib/sysusers.d/foo"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(["./usr/lib/sysusers.d/foo.conf"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 1
+    snippet = snippets[0]
+    assert snippet.maintscript == "postinst"
+    assert snippet.registration_method == "on_configure"
+    # The snippet should use "systemd-sysusers [...] foo.conf ..."
+    assert "systemd-sysusers" in snippet.plugin_provided_script
+    assert "foo.conf" in snippet.plugin_provided_script
+    # The "foo.conf" should only be listed once
+    assert snippet.plugin_provided_script.count("foo.conf") == 1
+
+
+def test_debputy_metadata_detector_xfonts():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "xfonts"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+    assert "misc:Depends" not in metadata.substvars
+
+    # It ignores files in the X11 dir and directories starting with ".".
+    fs_root = build_virtual_file_system(
+        ["./usr/share/fonts/X11/foo", "./usr/share/fonts/X11/.a/"]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+    assert "misc:Depends" not in metadata.substvars
+
+    fs_root = build_virtual_file_system(
+        [
+            "./usr/share/fonts/X11/some-font-dir/",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert metadata.substvars["misc:Depends"] == "xfonts-utils"
+    assert len(snippets) == 2
+    assert set(s.maintscript for s in snippets) == {"postinst", "postrm"}
+    postinst_snippet = metadata.maintscripts(maintscript="postinst")[0]
+    postrm_snippet = metadata.maintscripts(maintscript="postrm")[0]
+
+    assert postinst_snippet.maintscript == "postinst"
+    assert postinst_snippet.registration_method == "unconditionally_in_script"
+    assert (
+        "update-fonts-scale some-font-dir"
+        not in postinst_snippet.plugin_provided_script
+    )
+    assert "--x11r7-layout some-font-dir" in postinst_snippet.plugin_provided_script
+    assert (
+        f"update-fonts-alias --include" not in postinst_snippet.plugin_provided_script
+    )
+
+    assert postrm_snippet.maintscript == "postrm"
+    assert postrm_snippet.registration_method == "unconditionally_in_script"
+    assert (
+        "update-fonts-scale some-font-dir" not in postrm_snippet.plugin_provided_script
+    )
+    assert "--x11r7-layout some-font-dir" in postrm_snippet.plugin_provided_script
+    assert f"update-fonts-alias --exclude" not in postrm_snippet.plugin_provided_script
+
+
+def test_debputy_metadata_detector_xfonts_scale_and_alias():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+
+    metadata_detector_id = "xfonts"
+    package_name = "bar"
+    fs_root = build_virtual_file_system(
+        [
+            "./usr/share/fonts/X11/some-font-dir/",
+            f"./etc/X11/xfonts/some-font-dir/{package_name}.scale",
+            f"./etc/X11/xfonts/some-font-dir/{package_name}.alias",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(
+        metadata_detector_id,
+        fs_root,
+        package_metadata_context(
+            package_fields={
+                "Package": package_name,
+            }
+        ),
+    )
+    snippets = metadata.maintscripts()
+    assert metadata.substvars["misc:Depends"] == "xfonts-utils"
+    assert len(snippets) == 2
+    assert set(s.maintscript for s in snippets) == {"postinst", "postrm"}
+    postinst_snippet = metadata.maintscripts(maintscript="postinst")[0]
+    postrm_snippet = metadata.maintscripts(maintscript="postrm")[0]
+
+    assert postinst_snippet.maintscript == "postinst"
+    assert postinst_snippet.registration_method == "unconditionally_in_script"
+    assert "update-fonts-scale some-font-dir" in postinst_snippet.plugin_provided_script
+    assert "--x11r7-layout some-font-dir" in postinst_snippet.plugin_provided_script
+    assert (
+        f"update-fonts-alias --include /etc/X11/xfonts/some-font-dir/{package_name}.alias some-font-dir"
+        in postinst_snippet.plugin_provided_script
+    )
+
+    assert postrm_snippet.maintscript == "postrm"
+    assert postrm_snippet.registration_method == "unconditionally_in_script"
+    assert "update-fonts-scale some-font-dir" in postrm_snippet.plugin_provided_script
+    assert "--x11r7-layout some-font-dir" in postrm_snippet.plugin_provided_script
+    assert (
+        f"update-fonts-alias --exclude /etc/X11/xfonts/some-font-dir/{package_name}.alias some-font-dir"
+        in postrm_snippet.plugin_provided_script
+    )
+
+
+def test_debputy_metadata_detector_icon_cache():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "icon-cache"
+    icon_dir = "usr/share/icons"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            # Ignored subdirs (dh_icons ignores them too)
+            f"./{icon_dir}/gnome/foo.png",
+            f"./{icon_dir}/hicolor/foo.png",
+            # Unknown image format, so it does not trigger the update-icon-caches call
+            f"./{icon_dir}/subdir-a/unknown-image-format.img",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            f"./{icon_dir}/subdir-a/foo.png",
+            f"./{icon_dir}/subdir-b/subsubdir/bar.svg",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 2
+    assert set(s.maintscript for s in snippets) == {"postinst", "postrm"}
+    postinst_snippet = metadata.maintscripts(maintscript="postinst")[0]
+    postrm_snippet = metadata.maintscripts(maintscript="postrm")[0]
+
+    assert postinst_snippet.registration_method == "on_configure"
+    assert postrm_snippet.registration_method == "unconditionally_in_script"
+
+    # Directory order is stable according to the BinaryPackagePath API.
+    assert (
+        f"update-icon-caches /{icon_dir}/subdir-a /{icon_dir}/subdir-b"
+        in postinst_snippet.plugin_provided_script
+    )
+    assert (
+        f"update-icon-caches /{icon_dir}/subdir-a /{icon_dir}/subdir-b"
+        in postrm_snippet.plugin_provided_script
+    )
+
+
+def test_debputy_metadata_detector_kernel_modules():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "kernel-modules"
+    module_dir = "lib/modules"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            # Ignore files directly in the path or with wrong extension
+            f"./{module_dir}/README",
+            f"./{module_dir}/3.11/ignored-file.txt",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            f"./{module_dir}/3.11/foo.ko",
+            f"./usr/{module_dir}/3.12/bar.ko.xz",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 4  # Two for each version
+    assert set(s.maintscript for s in snippets) == {"postinst", "postrm"}
+    postinst_snippets = metadata.maintscripts(maintscript="postinst")
+    postrm_snippets = metadata.maintscripts(maintscript="postrm")
+
+    assert len(postinst_snippets) == 2
+    assert len(postrm_snippets) == 2
+    assert {s.registration_method for s in postinst_snippets} == {"on_configure"}
+    assert {s.registration_method for s in postrm_snippets} == {
+        "unconditionally_in_script"
+    }
+
+    assert (
+        "depmod -a -F /boot/System.map-3.11 3.11"
+        in postinst_snippets[0].plugin_provided_script
+    )
+    assert (
+        "depmod -a -F /boot/System.map-3.12 3.12"
+        in postinst_snippets[1].plugin_provided_script
+    )
+
+    assert (
+        "depmod -a -F /boot/System.map-3.11 3.11"
+        in postrm_snippets[0].plugin_provided_script
+    )
+    assert (
+        "depmod -a -F /boot/System.map-3.12 3.12"
+        in postrm_snippets[1].plugin_provided_script
+    )
+
+
+def test_debputy_metadata_detector_dpkg_shlibdeps():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "dpkg-shlibdeps"
+    skip_root_dir = "usr/lib/debug/"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(
+        [
+            "./usr/share/doc/foo/copyright",
+            virtual_path_def("./usr/lib/debputy/test.py", fs_path=__file__),
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert "shlibs:Depends" not in metadata.substvars
+
+    fs_root = build_virtual_file_system(
+        [
+            # Verify that certain directories are skipped as promised
+            virtual_path_def(f"./{skip_root_dir}/bin/ls", fs_path="/bin/ls")
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert "shlibs:Depends" not in metadata.substvars
+
+    # But we detect ELF binaries elsewhere
+    fs_root = build_virtual_file_system(
+        [virtual_path_def(f"./bin/ls", fs_path="/bin/ls")]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    # Do not make assertions about the content of `shlibs:Depends` as
+    # package name and versions change over time.
+    assert "shlibs:Depends" in metadata.substvars
+
+    # Re-run to verify it runs for udebs as well
+    metadata = plugin.run_metadata_detector(
+        metadata_detector_id,
+        fs_root,
+        context=package_metadata_context(
+            package_fields={"Package-Type": "udeb"},
+        ),
+    )
+    assert "shlibs:Depends" in metadata.substvars
+
+
+def test_debputy_metadata_detector_pycompile_files():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "pycompile-files"
+    module_dir = "usr/lib/python3/dist-packages"
+
+    # By default, the plugin will not add anything
+    fs_root = build_virtual_file_system(["./bin/ls"])
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            # Ignore files in unknown directories by default
+            "./random-dir/foo.py",
+            # Must be in "dist-packages" to count
+            "./usr/lib/python3/foo.py",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    assert metadata.maintscripts() == []
+
+    fs_root = build_virtual_file_system(
+        [
+            f"./{module_dir}/debputy/foo.py",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 2
+    assert set(s.maintscript for s in snippets) == {"postinst", "prerm"}
+    postinst_snippets = metadata.maintscripts(maintscript="postinst")
+    prerm_snippets = metadata.maintscripts(maintscript="prerm")
+
+    assert len(postinst_snippets) == 1
+    assert len(prerm_snippets) == 1
+    assert {s.registration_method for s in postinst_snippets} == {"on_configure"}
+    assert {s.registration_method for s in prerm_snippets} == {
+        "unconditionally_in_script"
+    }
+
+    assert "py3compile -p foo" in postinst_snippets[0].plugin_provided_script
+
+    assert "py3clean -p foo" in prerm_snippets[0].plugin_provided_script
+
+
+def test_debputy_metadata_detector_pycompile_files_private_package_dir():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    metadata_detector_id = "pycompile-files"
+    module_dir = "usr/share/foo"
+
+    fs_root = build_virtual_file_system(
+        [
+            f"./{module_dir}/debputy/foo.py",
+        ]
+    )
+    metadata = plugin.run_metadata_detector(metadata_detector_id, fs_root)
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 2
+    assert set(s.maintscript for s in snippets) == {"postinst", "prerm"}
+    postinst_snippets = metadata.maintscripts(maintscript="postinst")
+    prerm_snippets = metadata.maintscripts(maintscript="prerm")
+
+    assert len(postinst_snippets) == 1
+    assert len(prerm_snippets) == 1
+    assert {s.registration_method for s in postinst_snippets} == {"on_configure"}
+    assert {s.registration_method for s in prerm_snippets} == {
+        "unconditionally_in_script"
+    }
+
+    assert (
+        f"py3compile -p foo /{module_dir}"
+        in postinst_snippets[0].plugin_provided_script
+    )
+
+    assert "py3clean -p foo" in prerm_snippets[0].plugin_provided_script
+
+
+def _extract_service(
+    services: Sequence[DetectedService[DSD]], name: str
+) -> DetectedService[DSD]:
+    v = [s for s in services if name in s.names]
+    assert len(v) == 1
+    return v[0]
+
+
+def test_system_service_detection() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    systemd_service_root_dir = "usr/lib/systemd"
+    systemd_service_system_dir = f"{systemd_service_root_dir}/system"
+    systemd_service_user_dir = f"{systemd_service_root_dir}/user"
+
+    services, _ = plugin.run_service_detection_and_integrations(
+        "systemd", build_virtual_file_system([])
+    )
+    assert not services
+
+    services, _ = plugin.run_service_detection_and_integrations(
+        "systemd",
+        build_virtual_file_system(
+            [f"{systemd_service_system_dir}/", f"{systemd_service_user_dir}/"]
+        ),
+    )
+    assert not services
+
+    fs_root = build_virtual_file_system(
+        [
+            virtual_path_def(
+                f"{systemd_service_system_dir}/foo.service",
+                content=textwrap.dedent(
+                    """\
+            Alias="myname.service"
+            [Install]
+            """
+                ),
+            ),
+            virtual_path_def(
+                f"{systemd_service_system_dir}/foo@.service",
+                content=textwrap.dedent(
+                    """\
+            # dh_installsystemd ignores template services - we do for now as well.
+            Alias="ignored.service"
+            [Install]
+            """
+                ),
+            ),
+            virtual_path_def(
+                f"{systemd_service_system_dir}/alias.service", link_target="foo.service"
+            ),
+            virtual_path_def(f"{systemd_service_system_dir}/bar.timer", content=""),
+        ]
+    )
+    services, metadata = plugin.run_service_detection_and_integrations(
+        "systemd",
+        fs_root,
+        service_context_type_hint=SystemdServiceContext,
+    )
+    assert len(services) == 2
+    assert {s.names[0] for s in services} == {"foo.service", "bar.timer"}
+    foo_service = _extract_service(services, "foo.service")
+    assert set(foo_service.names) == {
+        "foo.service",
+        "foo",
+        "alias",
+        "alias.service",
+        "myname.service",
+        "myname",
+    }
+    assert foo_service.type_of_service == "service"
+    assert foo_service.service_scope == "system"
+    assert foo_service.enable_by_default
+    assert foo_service.start_by_default
+    assert foo_service.default_upgrade_rule == "restart"
+    assert foo_service.service_context.had_install_section
+
+    bar_timer = _extract_service(services, "bar.timer")
+    assert set(bar_timer.names) == {"bar.timer"}
+    assert bar_timer.type_of_service == "timer"
+    assert bar_timer.service_scope == "system"
+    assert not bar_timer.enable_by_default
+    assert bar_timer.start_by_default
+    assert bar_timer.default_upgrade_rule == "restart"
+    assert not bar_timer.service_context.had_install_section
+
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 4
+    postinsts = metadata.maintscripts(maintscript="postinst")
+    assert len(postinsts) == 2
+    enable_postinst, start_postinst = postinsts
+    assert (
+        "deb-systemd-helper debian-installed foo.service"
+        in enable_postinst.plugin_provided_script
+    )
+    assert (
+        "deb-systemd-invoke start foo.service" in start_postinst.plugin_provided_script
+    )
+    assert (
+        "deb-systemd-invoke restart foo.service"
+        in start_postinst.plugin_provided_script
+    )
+
+
+def test_sysv_service_detection() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    init_dir = "etc/init.d"
+
+    services, _ = plugin.run_service_detection_and_integrations(
+        "sysvinit", build_virtual_file_system([])
+    )
+    assert not services
+
+    services, _ = plugin.run_service_detection_and_integrations(
+        "sysvinit",
+        build_virtual_file_system(
+            [
+                f"{init_dir}/",
+            ]
+        ),
+    )
+    assert not services
+
+    services, _ = plugin.run_service_detection_and_integrations(
+        "sysvinit",
+        build_virtual_file_system(
+            [
+                virtual_path_def(
+                    f"{init_dir}/README",
+                    mode=0o644,
+                ),
+            ]
+        ),
+    )
+    assert not services
+
+    fs_root = build_virtual_file_system(
+        [
+            virtual_path_def(
+                f"{init_dir}/foo",
+                mode=0o755,
+            ),
+        ]
+    )
+    services, metadata = plugin.run_service_detection_and_integrations(
+        "sysvinit", fs_root
+    )
+    assert len(services) == 1
+    assert {s.names[0] for s in services} == {"foo"}
+    foo_service = _extract_service(services, "foo")
+    assert set(foo_service.names) == {"foo"}
+    assert foo_service.type_of_service == "service"
+    assert foo_service.service_scope == "system"
+    assert foo_service.enable_by_default
+    assert foo_service.start_by_default
+    assert foo_service.default_upgrade_rule == "restart"
+
+    snippets = metadata.maintscripts()
+    assert len(snippets) == 4
+    postinsts = metadata.maintscripts(maintscript="postinst")
+    assert len(postinsts) == 1
+    postinst = postinsts[0]
+    assert postinst.registration_method == "on_configure"
+    assert "" in postinst.plugin_provided_script
+    assert "update-rc.d foo defaults" in postinst.plugin_provided_script
+    assert (
+        "invoke-rc.d --skip-systemd-native foo start" in postinst.plugin_provided_script
+    )
+    assert (
+        "invoke-rc.d --skip-systemd-native foo restart"
+        in postinst.plugin_provided_script
+    )
+
+
+def test_debputy_manifest_variables() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    manifest_variables_no_dch = plugin.manifest_variables()
+    assert manifest_variables_no_dch.keys() == {
+        "DEB_BUILD_ARCH",
+        "DEB_BUILD_ARCH_ABI",
+        "DEB_BUILD_ARCH_BITS",
+        "DEB_BUILD_ARCH_CPU",
+        "DEB_BUILD_ARCH_ENDIAN",
+        "DEB_BUILD_ARCH_LIBC",
+        "DEB_BUILD_ARCH_OS",
+        "DEB_BUILD_GNU_CPU",
+        "DEB_BUILD_GNU_SYSTEM",
+        "DEB_BUILD_GNU_TYPE",
+        "DEB_BUILD_MULTIARCH",
+        "DEB_HOST_ARCH",
+        "DEB_HOST_ARCH_ABI",
+        "DEB_HOST_ARCH_BITS",
+        "DEB_HOST_ARCH_CPU",
+        "DEB_HOST_ARCH_ENDIAN",
+        "DEB_HOST_ARCH_LIBC",
+        "DEB_HOST_ARCH_OS",
+        "DEB_HOST_GNU_CPU",
+        "DEB_HOST_GNU_SYSTEM",
+        "DEB_HOST_GNU_TYPE",
+        "DEB_HOST_MULTIARCH",
+        "DEB_SOURCE",
+        "DEB_TARGET_ARCH",
+        "DEB_TARGET_ARCH_ABI",
+        "DEB_TARGET_ARCH_BITS",
+        "DEB_TARGET_ARCH_CPU",
+        "DEB_TARGET_ARCH_ENDIAN",
+        "DEB_TARGET_ARCH_LIBC",
+        "DEB_TARGET_ARCH_OS",
+        "DEB_TARGET_GNU_CPU",
+        "DEB_TARGET_GNU_SYSTEM",
+        "DEB_TARGET_GNU_TYPE",
+        "DEB_TARGET_MULTIARCH",
+        "DEB_VERSION",
+        "DEB_VERSION_EPOCH_UPSTREAM",
+        "DEB_VERSION_UPSTREAM",
+        "DEB_VERSION_UPSTREAM_REVISION",
+        "PACKAGE",
+        "SOURCE_DATE_EPOCH",
+        "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE",
+        "_DEBPUTY_SND_SOURCE_DATE_EPOCH",
+        "path:BASH_COMPLETION_DIR",
+        "path:GNU_INFO_DIR",
+        "token:CLOSE_CURLY_BRACE",
+        "token:DOUBLE_CLOSE_CURLY_BRACE",
+        "token:DOUBLE_OPEN_CURLY_BRACE",
+        "token:NEWLINE",
+        "token:NL",
+        "token:OPEN_CURLY_BRACE",
+        "token:TAB",
+    }
+
+    for v in [
+        "DEB_SOURCE",
+        "DEB_VERSION",
+        "DEB_VERSION_EPOCH_UPSTREAM",
+        "DEB_VERSION_UPSTREAM",
+        "DEB_VERSION_UPSTREAM_REVISION",
+        "SOURCE_DATE_EPOCH",
+        "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE",
+        "_DEBPUTY_SND_SOURCE_DATE_EPOCH",
+    ]:
+        with pytest.raises(DebputyManifestVariableRequiresDebianDirError):
+            manifest_variables_no_dch[v]
+
+    with pytest.raises(DebputySubstitutionError):
+        manifest_variables_no_dch["PACKAGE"]
+
+    dch_content = textwrap.dedent(
+        """\
+        mscgen (1:0.20-15) unstable; urgency=medium
+
+          * Irrelevant stuff here...
+          * Also, some details have been tweaked for better testing
+
+         -- Niels Thykier <niels@thykier.net>  Mon, 09 Oct 2023 14:50:06 +0000
+        """
+    )
+
+    debian_dir = build_virtual_file_system(
+        [virtual_path_def("changelog", content=dch_content)]
+    )
+    resolution_context = manifest_variable_resolution_context(debian_dir=debian_dir)
+    manifest_variables = plugin.manifest_variables(
+        resolution_context=resolution_context
+    )
+
+    assert manifest_variables["DEB_SOURCE"] == "mscgen"
+    assert manifest_variables["DEB_VERSION"] == "1:0.20-15"
+    assert manifest_variables["_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE"] == "1:0.20-15"
+
+    assert manifest_variables["DEB_VERSION_EPOCH_UPSTREAM"] == "1:0.20"
+    assert manifest_variables["DEB_VERSION_UPSTREAM"] == "0.20"
+    assert manifest_variables["DEB_VERSION_UPSTREAM_REVISION"] == "0.20-15"
+    assert manifest_variables["SOURCE_DATE_EPOCH"] == "1696863006"
+    assert manifest_variables["_DEBPUTY_SND_SOURCE_DATE_EPOCH"] == "1696863006"
+
+    # This one remains unresolvable
+    with pytest.raises(DebputySubstitutionError):
+        manifest_variables["PACKAGE"]
+
+    static_values = {
+        "path:BASH_COMPLETION_DIR": "/usr/share/bash-completion/completions",
+        "path:GNU_INFO_DIR": "/usr/share/info",
+    }
+
+    for k, v in static_values.items():
+        assert manifest_variables[k] == v
+
+    dch_content_bin_nmu = textwrap.dedent(
+        """\
+        mscgen (1:0.20-15+b4) unstable; urgency=medium, binary-only=yes
+
+          * Some binNMU entry here
+
+         -- Niels Thykier <niels@thykier.net>  Mon, 10 Nov 2023 16:01:17 +0000
+
+        mscgen (1:0.20-15) unstable; urgency=medium
+
+          * Irrelevant stuff here...
+          * Also, some details have been tweaked for better testing
+
+         -- Niels Thykier <niels@thykier.net>  Mon, 09 Oct 2023 14:50:06 +0000
+        """
+    )
+
+    debian_dir_bin_nmu = build_virtual_file_system(
+        [virtual_path_def("changelog", content=dch_content_bin_nmu)]
+    )
+    resolution_context_bin_nmu = manifest_variable_resolution_context(
+        debian_dir=debian_dir_bin_nmu
+    )
+    manifest_variables_bin_nmu = plugin.manifest_variables(
+        resolution_context=resolution_context_bin_nmu
+    )
+
+    assert manifest_variables_bin_nmu["DEB_SOURCE"] == "mscgen"
+    assert manifest_variables_bin_nmu["DEB_VERSION"] == "1:0.20-15+b4"
+    assert (
+        manifest_variables_bin_nmu["_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE"] == "1:0.20-15"
+    )
+
+    assert manifest_variables_bin_nmu["DEB_VERSION_EPOCH_UPSTREAM"] == "1:0.20"
+    assert manifest_variables_bin_nmu["DEB_VERSION_UPSTREAM"] == "0.20"
+    assert manifest_variables_bin_nmu["DEB_VERSION_UPSTREAM_REVISION"] == "0.20-15+b4"
+    assert manifest_variables_bin_nmu["SOURCE_DATE_EPOCH"] == "1699632077"
+    assert manifest_variables_bin_nmu["_DEBPUTY_SND_SOURCE_DATE_EPOCH"] == "1696863006"
+
+
+def test_cap_validator() -> None:
+    has_libcap, _, is_valid_cap = load_libcap()
+
+    if not has_libcap:
+        if os.environ.get("DEBPUTY_REQUIRE_LIBCAP", "") != "":
+            pytest.fail("Could not load libcap, but DEBPUTY_REQUIRE_CAP was non-empty")
+        pytest.skip("Could not load libcap.so")
+    assert not is_valid_cap("foo")
+    assert is_valid_cap("cap_dac_override,cap_bpf,cap_net_admin=ep")
+
+
+def test_clean_la_files() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    fs_root = build_virtual_file_system(
+        [virtual_path_def("usr/bin/foo", content="#!/bin/sh\n")]
+    )
+    # Does nothing by default
+    plugin.run_package_processor(
+        "clean-la-files",
+        fs_root,
+    )
+
+    la_file_content = textwrap.dedent(
+        """\
+    dependency_libs = 'foo bar'
+    another_line = 'foo bar'
+    """
+    )
+    expected_content = textwrap.dedent(
+        """\
+        dependency_libs = ''
+        another_line = 'foo bar'
+        """
+    )
+    la_file_content_no_change = expected_content
+    expected_content = textwrap.dedent(
+        """\
+        dependency_libs = ''
+        another_line = 'foo bar'
+        """
+    )
+
+    fs_root = build_virtual_file_system(
+        [
+            virtual_path_def("usr/lib/libfoo.la", materialized_content=la_file_content),
+            virtual_path_def(
+                "usr/lib/libfoo-unchanged.la",
+                content=la_file_content_no_change,
+            ),
+        ]
+    )
+
+    plugin.run_package_processor(
+        "clean-la-files",
+        fs_root,
+    )
+    for basename in ("libfoo.la", "libfoo-unchanged.la"):
+        la_file = fs_root.lookup(f"usr/lib/{basename}")
+        assert la_file is not None and la_file.is_file
+        if basename == "libfoo-unchanged.la":
+            # it should never have been rewritten
+            assert not la_file.has_fs_path
+        else:
+            assert la_file.has_fs_path
+        with la_file.open() as fd:
+            rewritten_content = fd.read()
+            assert rewritten_content == expected_content
+
+
+def test_strip_nondeterminism() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+
+    fs_root = build_virtual_file_system(
+        [
+            # Note, we are only testing a negative example as a positive example crashes
+            # because we do not have a SOURCE_DATE_EPOCH value/substitution
+            virtual_path_def("test/not-really-a-png.png", content="Not a PNG")
+        ]
+    )
+
+    plugin.run_package_processor(
+        "strip-nondeterminism",
+        fs_root,
+    )
+
+
+def test_translate_capabilities() -> None:
+    attribute_path = AttributePath.test_path()
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+
+    fs_root = build_virtual_file_system([virtual_path_def("usr/bin/foo", mode=0o4755)])
+
+    foo = fs_root.lookup("usr/bin/foo")
+    assert foo is not None
+    assert foo.is_file
+    assert foo.is_read_write
+
+    metadata_no_cap = plugin.run_metadata_detector(
+        "translate-capabilities",
+        fs_root,
+    )
+
+    assert not metadata_no_cap.maintscripts(maintscript="postinst")
+
+    cap = foo.metadata(DebputyCapability)
+    assert not cap.is_present
+    assert cap.can_write
+    cap.value = DebputyCapability(
+        capabilities="cap_net_raw+ep",
+        capability_mode=SymbolicMode.parse_filesystem_mode(
+            "u-s",
+            attribute_path["cap_mode"],
+        ),
+        definition_source="test",
+    )
+    metadata_w_cap = plugin.run_metadata_detector(
+        "translate-capabilities",
+        fs_root,
+    )
+
+    postinsts = metadata_w_cap.maintscripts(maintscript="postinst")
+    assert len(postinsts) == 1
+    postinst = postinsts[0]
+    assert postinst.registration_method == "on_configure"
+    assert "setcap cap_net_raw+ep " in postinst.plugin_provided_script
+    assert "chmod u-s " in postinst.plugin_provided_script
+
+
+def test_pam_auth_update() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+
+    fs_root = build_virtual_file_system(["usr/bin/foo"])
+
+    empty_metadata = plugin.run_metadata_detector("pam-auth-update", fs_root)
+    assert not empty_metadata.maintscripts()
+
+    fs_root = build_virtual_file_system(["/usr/share/pam-configs/foo-pam"])
+
+    pam_metadata = plugin.run_metadata_detector("pam-auth-update", fs_root)
+    postinsts = pam_metadata.maintscripts(maintscript="postinst")
+    assert len(postinsts) == 1
+    prerms = pam_metadata.maintscripts(maintscript="prerm")
+    assert len(prerms) == 1
+
+    postinst = postinsts[0]
+    assert postinst.registration_method == "on_configure"
+    assert "pam-auth-update --package" in postinst.plugin_provided_script
+
+    prerms = prerms[0]
+    assert prerms.registration_method == "on_before_removal"
+    assert "pam-auth-update --package --remove foo-pam" in prerms.plugin_provided_script
+
+
+def test_auto_depends_solink() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        initialize_debputy_features,
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+
+    fs_root = build_virtual_file_system(["usr/bin/foo"])
+
+    empty_metadata = plugin.run_metadata_detector(
+        "auto-depends-arch-any-solink",
+        fs_root,
+    )
+    assert "misc:Depends" not in empty_metadata.substvars
+    fs_root = build_virtual_file_system(
+        [
+            "usr/lib/x86_64-linux-gnu/libfoo.la",
+            virtual_path_def(
+                "usr/lib/x86_64-linux-gnu/libfoo.so", link_target="libfoo.so.1"
+            ),
+        ]
+    )
+
+    still_empty_metadata = plugin.run_metadata_detector(
+        "auto-depends-arch-any-solink",
+        fs_root,
+    )
+    assert "misc:Depends" not in still_empty_metadata.substvars
+
+    libfoo1_fs_root = build_virtual_file_system(
+        [
+            virtual_path_def(
+                "usr/lib/x86_64-linux-gnu/libfoo.so.1", link_target="libfoo.so.1.0.0"
+            ),
+        ]
+    )
+
+    context_correct = package_metadata_context(
+        package_fields={
+            "Package": "libfoo-dev",
+        },
+        accessible_package_roots=[
+            (
+                {
+                    "Package": "libfoo1",
+                    "Architecture": "any",
+                },
+                libfoo1_fs_root,
+            )
+        ],
+    )
+    sodep_metadata = plugin.run_metadata_detector(
+        "auto-depends-arch-any-solink",
+        fs_root,
+        context=context_correct,
+    )
+    assert "misc:Depends" in sodep_metadata.substvars
+    assert sodep_metadata.substvars["misc:Depends"] == "libfoo1 (= ${binary:Version})"
+
+    context_incorrect = package_metadata_context(
+        package_fields={"Package": "libfoo-dev", "Architecture": "all"},
+        accessible_package_roots=[
+            (
+                {
+                    "Package": "foo",
+                    "Architecture": "all",
+                },
+                build_virtual_file_system([]),
+            )
+        ],
+    )
+    sodep_metadata = plugin.run_metadata_detector(
+        "auto-depends-arch-any-solink",
+        fs_root,
+        context=context_incorrect,
+    )
+    assert "misc:Depends" not in sodep_metadata.substvars
+
+    context_too_many_matches = package_metadata_context(
+        package_fields={"Package": "libfoo-dev"},
+        accessible_package_roots=[
+            (
+                {
+                    "Package": "libfoo1-a",
+                    "Architecture": "any",
+                },
+                libfoo1_fs_root,
+            ),
+            (
+                {
+                    "Package": "libfoo1-b",
+                    "Architecture": "any",
+                },
+                libfoo1_fs_root,
+            ),
+        ],
+    )
+    sodep_metadata = plugin.run_metadata_detector(
+        "auto-depends-arch-any-solink",
+        fs_root,
+        context=context_too_many_matches,
+    )
+    assert "misc:Depends" not in sodep_metadata.substvars
diff --git a/tests/test_declarative_parser.py b/tests/test_declarative_parser.py
new file mode 100644
index 0000000..a5061cb
--- /dev/null
+++ b/tests/test_declarative_parser.py
@@ -0,0 +1,211 @@
+from typing import List, TypedDict, NotRequired, Annotated, Union, Mapping
+
+import pytest
+
+from debputy.highlevel_manifest import PackageTransformationDefinition
+from debputy.manifest_parser.base_types import DebputyParsedContent, TypeMapping
+from debputy.manifest_parser.declarative_parser import (
+    DebputyParseHint,
+    ParserGenerator,
+)
+from debputy.manifest_parser.mapper_code import type_mapper_str2package
+from debputy.manifest_parser.parser_data import ParserContextData
+from debputy.manifest_parser.util import AttributePath
+from debputy.packages import BinaryPackage
+from debputy.substitution import NULL_SUBSTITUTION
+from tutil import faked_binary_package
+
+
+class TFinalEntity(DebputyParsedContent):
+    sources: List[str]
+    install_as: NotRequired[str]
+    into: NotRequired[List[BinaryPackage]]
+    recursive: NotRequired[bool]
+
+
+class TSourceEntity(TypedDict):
+    sources: NotRequired[List[str]]
+    source: Annotated[NotRequired[str], DebputyParseHint.target_attribute("sources")]
+    as_: NotRequired[
+        Annotated[
+            str,
+            DebputyParseHint.target_attribute("install_as"),
+            DebputyParseHint.conflicts_with_source_attributes("sources"),
+        ]
+    ]
+    into: NotRequired[Union[BinaryPackage, List[BinaryPackage]]]
+    recursive: NotRequired[bool]
+
+
+TSourceEntityAltFormat = Union[TSourceEntity, List[str], str]
+
+
+foo_package = faked_binary_package("foo")
+context_packages = {
+    foo_package.name: foo_package,
+}
+context_package_states = {
+    p.name: PackageTransformationDefinition(
+        p,
+        NULL_SUBSTITUTION,
+        False,
+    )
+    for p in context_packages.values()
+}
+
+
+class TestParserContextData(ParserContextData):
+    @property
+    def _package_states(self) -> Mapping[str, PackageTransformationDefinition]:
+        return context_package_states
+
+    @property
+    def binary_packages(self) -> Mapping[str, BinaryPackage]:
+        return context_packages
+
+
+@pytest.fixture
+def parser_context():
+    return TestParserContextData()
+
+
+@pytest.mark.parametrize(
+    "source_payload,expected_data,expected_attribute_path,parse_content,source_content",
+    [
+        (
+            {"sources": ["foo", "bar"]},
+            {"sources": ["foo", "bar"]},
+            {
+                "sources": "sources",
+            },
+            TFinalEntity,
+            None,
+        ),
+        (
+            {"sources": ["foo", "bar"], "install-as": "as-value"},
+            {"sources": ["foo", "bar"], "install_as": "as-value"},
+            {"sources": "sources", "install_as": "install-as"},
+            TFinalEntity,
+            None,
+        ),
+        (
+            {"sources": ["foo", "bar"], "install-as": "as-value", "into": ["foo"]},
+            {
+                "sources": ["foo", "bar"],
+                "install_as": "as-value",
+                "into": [foo_package],
+            },
+            {"sources": "sources", "install_as": "install-as", "into": "into"},
+            TFinalEntity,
+            None,
+        ),
+        (
+            {"source": "foo", "as": "as-value", "into": ["foo"]},
+            {
+                "sources": ["foo"],
+                "install_as": "as-value",
+                "into": [foo_package],
+            },
+            {"sources": "source", "install_as": "as", "into": "into"},
+            TFinalEntity,
+            TSourceEntity,
+        ),
+        (
+            {"source": "foo", "as": "as-value", "into": ["foo"]},
+            {
+                "sources": ["foo"],
+                "install_as": "as-value",
+                "into": [foo_package],
+            },
+            {"sources": "source", "install_as": "as", "into": "into"},
+            TFinalEntity,
+            TSourceEntityAltFormat,
+        ),
+        (
+            ["foo", "bar"],
+            {
+                "sources": ["foo", "bar"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            TSourceEntityAltFormat,
+        ),
+        (
+            "foo",
+            {
+                "sources": ["foo"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            TSourceEntityAltFormat,
+        ),
+        (
+            "foo",
+            {
+                "sources": ["foo"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            str,
+        ),
+        (
+            ["foo", "bar"],
+            {
+                "sources": ["foo", "bar"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            List[str],
+        ),
+        (
+            "foo",
+            {
+                "sources": ["foo"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            Union[str, List[str]],
+        ),
+        (
+            ["foo", "bar"],
+            {
+                "sources": ["foo", "bar"],
+            },
+            {"sources": "parse-root"},
+            TFinalEntity,
+            Union[str, List[str]],
+        ),
+        (
+            {"source": "foo", "recursive": True},
+            {
+                "sources": ["foo"],
+                "recursive": True,
+            },
+            {"sources": "source", "recursive": "recursive"},
+            TFinalEntity,
+            TSourceEntityAltFormat,
+        ),
+    ],
+)
+def test_declarative_parser_ok(
+    attribute_path: AttributePath,
+    parser_context: ParserContextData,
+    source_payload,
+    expected_data,
+    expected_attribute_path,
+    parse_content,
+    source_content,
+):
+    pg = ParserGenerator()
+    pg.register_mapped_type(TypeMapping(BinaryPackage, str, type_mapper_str2package))
+    parser = pg.parser_from_typed_dict(
+        parse_content,
+        source_content=source_content,
+    )
+    data_path = attribute_path["parse-root"]
+    parsed_data = parser.parse_input(
+        source_payload, data_path, parser_context=parser_context
+    )
+    assert expected_data == parsed_data
+    attributes = {k: data_path[k].name for k in expected_attribute_path}
+    assert attributes == expected_attribute_path
diff --git a/tests/test_fs_metadata.py b/tests/test_fs_metadata.py
new file mode 100644
index 0000000..14a397f
--- /dev/null
+++ b/tests/test_fs_metadata.py
@@ -0,0 +1,770 @@
+import dataclasses
+import textwrap
+from typing import Tuple, List, Optional, Union
+
+import pytest
+
+from debputy.filesystem_scan import PathDef, build_virtual_fs
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.intermediate_manifest import PathType, IntermediateManifest, TarMember
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.api.test_api import build_virtual_file_system
+from debputy.transformation_rules import TransformationRuntimeError
+
+
+@pytest.fixture()
+def manifest_parser_pkg_foo(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_single_foo_arch_all_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> YAMLManifestParser:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+    return YAMLManifestParser(
+        "debian/test-debputy.manifest",
+        source_package,
+        package_single_foo_arch_all_cxt_amd64,
+        amd64_substitution,
+        amd64_dpkg_architecture_variables,
+        dpkg_arch_query,
+        no_profiles_or_build_options,
+        debputy_plugin_feature_set,
+        debian_dir=debian_dir,
+    )
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class Expected:
+    mtime: Optional[float]
+    mode: Optional[int] = None
+    link_target: Optional[str] = None
+    owner: str = "root"
+    group: str = "root"
+    has_fs_path: bool = True
+
+
+def _show_name_on_error(_: str) -> bool:
+    return False
+
+
+def _has_fs_path(tm: TarMember) -> bool:
+    return tm.fs_path is not None
+
+
+def verify_paths(
+    intermediate_manifest: IntermediateManifest,
+    expected_results: List[Tuple[Union[str, PathDef], Expected]],
+) -> None:
+    result = {tm.member_path: tm for tm in intermediate_manifest}
+    expected_table = {
+        f"./{p}" if isinstance(p, str) else f"./{p.path_name}": e
+        for p, e in expected_results
+    }
+
+    for path_name, expected in expected_table.items():
+        tm = result[path_name]
+        if tm.path_type == PathType.SYMLINK:
+            assert tm.link_target == expected.link_target or _show_name_on_error(
+                path_name
+            )
+        else:
+            assert tm.link_target == "" or _show_name_on_error(path_name)
+        if expected.mode is not None:
+            assert oct(tm.mode) == oct(expected.mode) or _show_name_on_error(path_name)
+        if expected.mtime is not None:
+            assert tm.mtime == expected.mtime or _show_name_on_error(path_name)
+        assert tm.owner == expected.owner or _show_name_on_error(path_name)
+        assert tm.group == expected.group or _show_name_on_error(path_name)
+        assert _has_fs_path(tm) == expected.has_fs_path or _show_name_on_error(
+            path_name
+        )
+
+    del result["./"]
+    if len(result) != len(expected_results):
+        for tm in result.values():
+            assert tm.member_path in expected_table
+
+
+def test_mtime_clamp_and_builtin_dir_mode(manifest_parser_pkg_foo):
+    manifest = manifest_parser_pkg_foo.build_manifest()
+    claim_mtime_to = 255
+    path_defs: List[Tuple[PathDef, Expected]] = [
+        (
+            virtual_path_def("usr/", mode=0o700, mtime=10, fs_path="/nowhere/usr/"),
+            Expected(mode=0o755, mtime=10),
+        ),
+        (
+            virtual_path_def(
+                "usr/bin/", mode=0o2534, mtime=5000, fs_path="/nowhere/usr/bin/"
+            ),
+            Expected(mode=0o755, mtime=claim_mtime_to),
+        ),
+        (
+            virtual_path_def(
+                "usr/bin/my-exec",
+                mtime=5000,
+                fs_path="/nowhere/usr/bin/my-exec",
+                link_target="../../some/where/else",
+            ),
+            # Implementation detail; symlinks do not refer to their FS path in the intermediate manifest.
+            Expected(
+                mtime=claim_mtime_to, link_target="/some/where/else", has_fs_path=False
+            ),
+        ),
+    ]
+
+    fs_root = build_virtual_fs([d[0] for d in path_defs], read_write_fs=True)
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+    verify_paths(intermediate_manifest, path_defs)
+
+
+def test_transformations_create_symlink(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+             -  create-symlink:
+                      path: 'usr/bin/my-exec'
+                      target: '../../some/where/else'
+             - create-symlink:
+                      path: 'usr/bin/{{PACKAGE}}'
+                      target: '/usr/lib/{{DEB_HOST_MULTIARCH}}/{{PACKAGE}}/tool'
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    fs_root = build_virtual_fs(["./"], read_write_fs=True)
+    expected_results = [
+        ("usr/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        ("usr/bin/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        (
+            "usr/bin/my-exec",
+            Expected(
+                mtime=claim_mtime_to, link_target="/some/where/else", has_fs_path=False
+            ),
+        ),
+        (
+            "usr/bin/foo",
+            Expected(
+                mtime=claim_mtime_to,
+                # Test is using a "static" dpkg-architecture, so it will always be `x86_64-linux-gnu`
+                link_target="../lib/x86_64-linux-gnu/foo/tool",
+                has_fs_path=False,
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformations_create_symlink_replace_success(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+             -  create-symlink:
+                      path: 'usr/bin/my-exec'
+                      target: '../../some/where/else'
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    clamp_mtime_to = 255
+    fs_root = build_virtual_fs(["./usr/bin/my-exec"], read_write_fs=True)
+    expected_results = [
+        ("usr/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        ("usr/bin/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        (
+            "usr/bin/my-exec",
+            Expected(
+                mtime=clamp_mtime_to, link_target="/some/where/else", has_fs_path=False
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, clamp_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+@pytest.mark.parametrize(
+    "replacement_rule, reason",
+    [
+        (
+            "abort-on-non-empty-directory",
+            "the path is a non-empty directory",
+        ),
+        (
+            "error-if-directory",
+            "the path is a directory",
+        ),
+        (
+            "error-if-exists",
+            "the path exists",
+        ),
+    ],
+)
+def test_transformations_create_symlink_replace_failure(
+    manifest_parser_pkg_foo, replacement_rule, reason
+):
+    content = textwrap.dedent(
+        f"""\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+             -  create-symlink:
+                      path: 'usr/share/foo'
+                      target: 'somewhere-else'
+                      replacement-rule: {replacement_rule}
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    clamp_mtime_to = 255
+    fs_root = build_virtual_fs(["./usr/share/foo/bar"], read_write_fs=True)
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    with pytest.raises(TransformationRuntimeError) as e_info:
+        manifest.apply_to_binary_staging_directory("foo", fs_root, clamp_mtime_to)
+
+    msg = (
+        f"Refusing to replace ./usr/share/foo with a symlink; {reason} and the active"
+        f" replacement-rule was {replacement_rule}.  You can set the replacement-rule to"
+        ' "discard-existing", if you are not interested in the contents of ./usr/share/foo. This error'
+        " was triggered by packages.foo.transformations[0].create-symlink <Search for: usr/share/foo>."
+    )
+    assert e_info.value.args[0] == msg
+
+
+def test_transformations_create_symlink_replace_with_explicit_remove(
+    manifest_parser_pkg_foo,
+):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove: usr/share/foo
+            - create-symlink:
+                      path: 'usr/share/foo'
+                      target: 'somewhere-else'
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    clamp_mtime_to = 255
+    fs_root = build_virtual_fs(["./usr/share/foo/bar"], read_write_fs=True)
+    expected_results = [
+        ("usr/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        ("usr/share/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        (
+            "usr/share/foo",
+            Expected(
+                mtime=clamp_mtime_to, link_target="somewhere-else", has_fs_path=False
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, clamp_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformations_create_symlink_replace_with_replacement_rule(
+    manifest_parser_pkg_foo,
+):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove: usr/share/foo
+            - create-symlink:
+                      path: 'usr/share/foo'
+                      target: 'somewhere-else'
+                      replacement-rule: 'discard-existing'
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    clamp_mtime_to = 255
+    fs_root = build_virtual_fs(["./usr/share/foo/bar"], read_write_fs=True)
+    expected_results = [
+        ("usr/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        ("usr/share/", Expected(mode=0o755, mtime=clamp_mtime_to, has_fs_path=False)),
+        (
+            "usr/share/foo",
+            Expected(
+                mtime=clamp_mtime_to, link_target="somewhere-else", has_fs_path=False
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, clamp_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformations_path_metadata(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+             - path-metadata:
+                    path: 'usr/bin/my-exec'
+                    mode: "-x"
+                    owner: "bin"
+                    group: 2
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    fs_root = build_virtual_fs(
+        [
+            virtual_path_def(
+                "./usr/bin/my-exec", fs_path="/no-where", mode=0o755, mtime=10
+            ),
+        ],
+        read_write_fs=True,
+    )
+    expected_results = [
+        ("usr/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        ("usr/bin/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        (
+            "usr/bin/my-exec",
+            Expected(
+                mtime=10,
+                has_fs_path=True,
+                mode=0o644,
+                owner="bin",
+                group="bin",
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformations_directories(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-directories:
+                  path: some/empty/directory
+                  mode: "0700"
+              - create-directories: another/empty/directory
+              - create-directories:
+                  path: a/third-empty/directory
+                  owner: www-data
+                  group: www-data
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def("some/empty/", mtime=10, fs_path="/nowhere/some/empty"),
+        virtual_path_def(
+            "some/empty/directory/",
+            mode=0o755,
+            mtime=10,
+            fs_path="/nowhere/some/empty/directory",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    expected_results = [
+        ("some/", Expected(mode=0o755, mtime=10, has_fs_path=True)),
+        ("some/empty/", Expected(mode=0o755, mtime=10, has_fs_path=True)),
+        (
+            "some/empty/directory/",
+            Expected(mode=0o700, mtime=10, has_fs_path=True),
+        ),
+        ("another/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        (
+            "another/empty/",
+            Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False),
+        ),
+        (
+            "another/empty/directory/",
+            Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False),
+        ),
+        ("a/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        (
+            "a/third-empty/",
+            Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False),
+        ),
+        (
+            "a/third-empty/directory/",
+            Expected(
+                mode=0o755,
+                mtime=claim_mtime_to,
+                owner="www-data",
+                group="www-data",
+                has_fs_path=False,
+            ),
+        ),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformation_remove(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove: some/empty
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/empty/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/empty/directory/",
+            mode=0o755,
+            mtime=10,
+            fs_path="/nowhere/some/empty/directory",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    expected_results = []
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformation_remove_keep_empty(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove:
+                path: some/empty
+                keep-empty-parent-dirs: true
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/empty/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/empty/directory/",
+            mode=0o755,
+            mtime=10,
+            fs_path="/nowhere/some/empty/directory",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    expected_results = [
+        ("some/", Expected(mode=0o755, mtime=10)),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformation_remove_glob(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove: some/*.json
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/foo.json",
+            mode=0o600,
+            mtime=10,
+        ),
+        virtual_path_def(
+            "some/bar.json",
+            mode=0o600,
+            mtime=10,
+        ),
+        virtual_path_def(
+            "some/empty/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/bar.txt", mode=0o600, mtime=10, fs_path="/nowhere/some/bar.txt"
+        ),
+        virtual_path_def(
+            "some/bar.JSON", mode=0o600, mtime=10, fs_path="/nowhere/some/bar.JSON"
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    expected_results = [
+        ("some/", Expected(mode=0o755, mtime=10)),
+        ("some/empty/", Expected(mode=0o755, mtime=10)),
+        ("some/bar.txt", Expected(mode=0o644, mtime=10)),
+        # Survives because pattern is case-sensitive
+        ("some/bar.JSON", Expected(mode=0o644, mtime=10)),
+    ]
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformation_remove_no_match(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - remove: some/non-existing-path
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/empty/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/empty/directory/",
+            mode=0o755,
+            mtime=10,
+            fs_path="/nowhere/some/empty/directory",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    with pytest.raises(TransformationRuntimeError) as e_info:
+        manifest.apply_to_binary_staging_directory("foo", fs_root, claim_mtime_to)
+    expected = (
+        'The match rule "./some/non-existing-path" in transformation'
+        ' "packages.foo.transformations[0].remove <Search for: some/non-existing-path>" did not match any paths. Either'
+        " the definition is redundant (and can be omitted) or the match rule is incorrect."
+    )
+    assert expected == e_info.value.args[0]
+
+
+def test_transformation_move_basic(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - move:
+                source: some/dir
+                target: new/dir/where-else
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/dir/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/dir/some-dir-symlink1", mtime=10, link_target="/abs/some-target1"
+        ),
+        virtual_path_def(
+            "some/dir/some-dir-symlink2", mtime=10, link_target="../some-target2"
+        ),
+        virtual_path_def(
+            "some/dir/some-dir-symlink3",
+            mtime=10,
+            link_target="/new/dir/where-else/some-target3",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    expected_results = [
+        ("some/", Expected(mode=0o755, mtime=10)),
+        ("new/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        ("new/dir/", Expected(mode=0o755, mtime=claim_mtime_to, has_fs_path=False)),
+        ("new/dir/where-else/", Expected(mode=0o755, mtime=10)),
+        # FIXME: should be 10
+        (
+            "new/dir/where-else/some-dir-symlink1",
+            Expected(mtime=None, link_target="/abs/some-target1", has_fs_path=False),
+        ),
+        (
+            "new/dir/where-else/some-dir-symlink2",
+            Expected(mtime=None, link_target="../some-target2", has_fs_path=False),
+        ),
+        (
+            "new/dir/where-else/some-dir-symlink3",
+            Expected(mtime=None, link_target="some-target3", has_fs_path=False),
+        ),
+    ]
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+
+    print(intermediate_manifest)
+
+    verify_paths(intermediate_manifest, expected_results)
+
+
+def test_transformation_move_no_match(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+            - move:
+                source: some/non-existing-path
+                target: some/where-else
+    """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    claim_mtime_to = 255
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/empty/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/empty/directory/",
+            mode=0o755,
+            mtime=10,
+            fs_path="/nowhere/some/empty/directory",
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    with pytest.raises(TransformationRuntimeError) as e_info:
+        manifest.apply_to_binary_staging_directory("foo", fs_root, claim_mtime_to)
+    expected = (
+        'The match rule "./some/non-existing-path" in transformation'
+        ' "packages.foo.transformations[0].move <Search for: some/non-existing-path>" did not match any paths. Either'
+        " the definition is redundant (and can be omitted) or the match rule is incorrect."
+    )
+    assert expected == e_info.value.args[0]
+
+
+def test_builtin_mode_normalization(manifest_parser_pkg_foo):
+    manifest = manifest_parser_pkg_foo.build_manifest()
+    claim_mtime_to = 255
+    sh_script_content = "#!/bin/sh"
+    python_script_content = "#! /usr/bin/python"
+    unrelated_content = "... random stuff ..."
+    paths = [
+        virtual_path_def("some/", mode=0o700, mtime=10, fs_path="/nowhere/some"),
+        virtual_path_def(
+            "some/dir/", mode=0o700, mtime=10, fs_path="/nowhere/some/empty"
+        ),
+        virtual_path_def(
+            "some/dir/script.sh",
+            mode=0o600,
+            mtime=10,
+            fs_path="/nowhere/script.sh",
+            content=sh_script_content,
+        ),
+        virtual_path_def(
+            "some/dir/script.py",
+            mode=0o600,
+            mtime=10,
+            fs_path="/nowhere/script.py",
+            content=python_script_content,
+        ),
+        virtual_path_def(
+            "some/dir/non-script-file",
+            mode=0o600,
+            mtime=10,
+            fs_path="/nowhere/non-script-file",
+            content=unrelated_content,
+        ),
+    ]
+    fs_root = build_virtual_fs(paths, read_write_fs=True)
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    expected_results = [
+        ("some/", Expected(mode=0o755, mtime=10)),
+        ("some/dir/", Expected(mode=0o755, mtime=10)),
+        ("some/dir/script.sh", Expected(mode=0o755, mtime=10)),
+        ("some/dir/script.py", Expected(mode=0o755, mtime=10)),
+        ("some/dir/non-script-file", Expected(mode=0o644, mtime=10)),
+    ]
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+
+    intermediate_manifest = manifest.apply_to_binary_staging_directory(
+        "foo", fs_root, claim_mtime_to
+    )
+
+    print(intermediate_manifest)
+
+    verify_paths(intermediate_manifest, expected_results)
diff --git a/tests/test_install_rules.py b/tests/test_install_rules.py
new file mode 100644
index 0000000..c8ffb84
--- /dev/null
+++ b/tests/test_install_rules.py
@@ -0,0 +1,1059 @@
+import textwrap
+
+import pytest
+
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.installations import (
+    InstallSearchDirContext,
+    NoMatchForInstallPatternError,
+    SearchDir,
+)
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.api.test_api import build_virtual_file_system
+
+
+@pytest.fixture()
+def manifest_parser_pkg_foo(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_single_foo_arch_all_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> YAMLManifestParser:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+    return YAMLManifestParser(
+        "debian/test-debputy.manifest",
+        source_package,
+        package_single_foo_arch_all_cxt_amd64,
+        amd64_substitution,
+        amd64_dpkg_architecture_variables,
+        dpkg_arch_query,
+        no_profiles_or_build_options,
+        debputy_plugin_feature_set,
+        debian_dir=debian_dir,
+    )
+
+
+@pytest.fixture()
+def manifest_parser_pkg_foo_w_udeb(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_foo_w_udeb_arch_any_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> YAMLManifestParser:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+    return YAMLManifestParser(
+        "debian/test-debputy.manifest",
+        source_package,
+        package_foo_w_udeb_arch_any_cxt_amd64,
+        amd64_substitution,
+        amd64_dpkg_architecture_variables,
+        dpkg_arch_query,
+        no_profiles_or_build_options,
+        debputy_plugin_feature_set,
+        debian_dir=debian_dir,
+    )
+
+
+def test_install_rules(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/tmp/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/tmp/usr/bin/foo",
+                content="#!/bin/sh\n",
+                mtime=10,
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/tmp/usr/bin/foo-util",
+                content="#!/bin/sh\n",
+                mtime=10,
+            ),
+            virtual_path_def(
+                "usr/bin/tool.sh",
+                fs_path="/nowhere/debian/tmp/usr/bin/tool.sh",
+                link_target="./foo",
+            ),
+            virtual_path_def("usr/share/", fs_path="/nowhere/debian/tmp/usr/share"),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/tmp/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/tmp/usr/share/foo/foo.txt",
+                content="A text file",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              - /usr/share/foo
+              - /usr/bin/foo
+              - /usr/bin/foo-util
+          - install:
+              source: usr/bin/tool.sh
+              as: usr/bin/tool
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    ub_dir = foo_fs_root.lookup("/usr/bin")
+    assert ub_dir is not None
+    assert ub_dir.is_dir
+    assert not ub_dir.has_fs_path  # This will be "generated"
+
+    tool = ub_dir.get("tool")
+    assert tool is not None
+    assert tool.is_symlink
+    assert tool.readlink() == "./foo"
+
+    assert {"foo", "foo-util", "tool"} == {p.name for p in ub_dir.iterdir}
+    for n in ["foo", "foo-util"]:
+        assert ub_dir[n].mtime == 10
+    usf_dir = foo_fs_root.lookup("/usr/share/foo")
+    assert usf_dir is not None
+    assert usf_dir.is_dir
+    # Here we are installing an actual directory, so it should be present too
+    assert usf_dir.has_fs_path
+    assert usf_dir.fs_path == "/nowhere/debian/tmp/usr/share/foo"
+    assert {"foo.txt"} == {p.name for p in usf_dir.iterdir}
+
+
+def test_multi_dest_install_rules(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere"),
+            virtual_path_def("source/", fs_path="/nowhere/source"),
+            virtual_path_def("source/foo/", fs_path="/nowhere/foo"),
+            virtual_path_def(
+                "source/foo/foo-a.data",
+                fs_path="/nowhere/foo/foo-a.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/foo/foo-b.data",
+                fs_path="/nowhere/foo/foo-b.data",
+                link_target="./foo-a.data",
+            ),
+            virtual_path_def("source/bar/", fs_path="/nowhere/bar"),
+            virtual_path_def(
+                "source/bar/bar-a.data",
+                fs_path="/nowhere/bar/bar-a.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/bar/bar-b.data",
+                fs_path="/nowhere/bar/bar-b.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/tool.sh",
+                fs_path="/nowhere/source/tool.sh",
+                content="#!/bin/sh\n# run some command ...",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - multi-dest-install:
+              sources:
+              - source/foo/*
+              - source/bar
+              dest-dirs:
+              - usr/share/foo
+              - usr/share/foo2
+          - multi-dest-install:
+              source: source/tool.sh
+              as:
+               - usr/share/foo/tool
+               - usr/share/foo2/tool
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    for stem in ["foo", "foo2"]:
+        foo_dir = foo_fs_root.lookup(f"/usr/share/{stem}")
+        assert foo_dir is not None
+        assert foo_dir.is_dir
+
+        assert {"foo-a.data", "foo-b.data", "bar", "tool"} == {
+            p.name for p in foo_dir.iterdir
+        }
+
+        tool = foo_dir["tool"]
+        assert tool.is_file
+        with tool.open() as fd:
+            content = fd.read()
+        assert content.startswith("#!/bin/sh")
+        foo_a = foo_dir["foo-a.data"]
+        assert foo_a.is_file
+        assert foo_a.fs_path == "/nowhere/foo/foo-a.data"
+        with foo_a.open() as fd:
+            content = fd.read()
+        assert "data" in content
+        foo_b = foo_dir["foo-b.data"]
+        assert foo_b.is_symlink
+        assert foo_b.readlink() == "./foo-a.data"
+
+        bar = foo_dir["bar"]
+        assert bar.is_dir
+        assert {"bar-a.data", "bar-b.data"} == {p.name for p in bar.iterdir}
+        assert {"/nowhere/bar/bar-a.data", "/nowhere/bar/bar-b.data"} == {
+            p.fs_path for p in bar.iterdir
+        }
+
+
+def test_install_rules_with_glob(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/tmp/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/tmp/usr/bin/foo",
+                content="#!/bin/sh\n",
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/tmp/usr/bin/foo-util",
+                content="#!/bin/sh\n",
+            ),
+            virtual_path_def(
+                "usr/bin/tool.sh",
+                fs_path="/nowhere/debian/tmp/usr/bin/tool.sh",
+                link_target="./foo",
+            ),
+            virtual_path_def("usr/share/", fs_path="/nowhere/debian/tmp/usr/share"),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/tmp/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/tmp/usr/share/foo/foo.txt",
+                content="A text file",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              source: usr/bin/tool.sh
+              as: usr/bin/tool
+          - install:
+              - /usr/share/foo
+              - /usr/bin/foo*
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    ub_dir = foo_fs_root.lookup("/usr/bin")
+    assert ub_dir is not None
+    assert ub_dir.is_dir
+    assert not ub_dir.has_fs_path  # This will be "generated"
+
+    tool = ub_dir.get("tool")
+    assert tool is not None
+    assert tool.is_symlink
+    assert tool.readlink() == "./foo"
+
+    assert {"foo", "foo-util", "tool"} == {p.name for p in ub_dir.iterdir}
+    usf_dir = foo_fs_root.lookup("/usr/share/foo")
+    assert usf_dir is not None
+    assert usf_dir.is_dir
+    # Here we are installing an actual directory, so it should be present too
+    assert usf_dir.has_fs_path
+    assert usf_dir.fs_path == "/nowhere/debian/tmp/usr/share/foo"
+    assert {"foo.txt"} == {p.name for p in usf_dir.iterdir}
+
+
+def test_install_rules_auto_discard_rules_dir(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp/usr"),
+            virtual_path_def("usr/lib/", fs_path="/nowhere/debian/tmp/usr/lib"),
+            virtual_path_def(
+                "usr/lib/libfoo.so.1.0.0",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0",
+                content="Not really an ELF FILE",
+            ),
+            virtual_path_def(
+                "usr/lib/libfoo.la",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.la",
+                content="Not really a LA FILE",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              - /usr/lib
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    lib_dir = foo_fs_root.lookup("/usr/lib")
+    assert lib_dir is not None
+    assert lib_dir.is_dir
+    assert lib_dir.has_fs_path
+    assert lib_dir.fs_path == "/nowhere/debian/tmp/usr/lib"
+
+    so_file = lib_dir.get("libfoo.so.1.0.0")
+    assert so_file is not None
+    assert so_file.is_file
+    assert so_file.has_fs_path
+    assert so_file.fs_path == "/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0"
+
+    assert {"libfoo.so.1.0.0"} == {p.name for p in lib_dir.iterdir}
+
+
+def test_install_rules_auto_discard_rules_glob(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp/usr"),
+            virtual_path_def("usr/lib/", fs_path="/nowhere/debian/tmp/usr/lib"),
+            virtual_path_def(
+                "usr/lib/libfoo.so.1.0.0",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0",
+                content="Not really an ELF FILE",
+            ),
+            virtual_path_def(
+                "usr/lib/libfoo.la",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.la",
+                content="Not really an ELF FILE",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              - /usr/lib/*
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    lib_dir = foo_fs_root.lookup("/usr/lib")
+    assert lib_dir is not None
+    assert lib_dir.is_dir
+    assert not lib_dir.has_fs_path
+
+    so_file = lib_dir.get("libfoo.so.1.0.0")
+    assert so_file is not None
+    assert so_file.is_file
+    assert so_file.has_fs_path
+    assert so_file.fs_path == "/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0"
+
+    assert {"libfoo.so.1.0.0"} == {p.name for p in lib_dir.iterdir}
+
+
+def test_install_rules_auto_discard_rules_overruled_by_explicit_install_rule(
+    manifest_parser_pkg_foo,
+) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp/usr"),
+            virtual_path_def("usr/lib/", fs_path="/nowhere/debian/tmp/usr/lib"),
+            virtual_path_def(
+                "usr/lib/libfoo.so.1.0.0",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0",
+                content="Not really an ELF FILE",
+            ),
+            virtual_path_def(
+                "usr/lib/libfoo.la",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.la",
+                content="Not really an ELF FILE",
+            ),
+            virtual_path_def(
+                "usr/lib/libfoo.so",
+                fs_path="/nowhere/debian/tmp/usr/lib/libfoo.so",
+                link_target="libfoo.so.1.0.0",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              - /usr/lib
+              - /usr/lib/libfoo.la
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    lib_dir = foo_fs_root.lookup("/usr/lib")
+    assert lib_dir is not None
+    assert lib_dir.is_dir
+    assert lib_dir.has_fs_path
+    assert lib_dir.fs_path == "/nowhere/debian/tmp/usr/lib"
+
+    so_file = lib_dir.get("libfoo.so.1.0.0")
+    assert so_file is not None
+    assert so_file.is_file
+    assert so_file.has_fs_path
+    assert so_file.fs_path == "/nowhere/debian/tmp/usr/lib/libfoo.so.1.0.0"
+
+    la_file = lib_dir.get("libfoo.la")
+    assert la_file is not None
+    assert la_file.is_file
+    assert la_file.has_fs_path
+    assert la_file.fs_path == "/nowhere/debian/tmp/usr/lib/libfoo.la"
+
+    so_link = lib_dir.get("libfoo.so")
+    assert so_link is not None
+    assert so_link.is_symlink
+    assert so_link.readlink() == "libfoo.so.1.0.0"
+
+    assert {"libfoo.so.1.0.0", "libfoo.so", "libfoo.la"} == {
+        p.name for p in lib_dir.iterdir
+    }
+
+
+def test_install_rules_install_as_with_var(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere"),
+            virtual_path_def("build/", fs_path="/nowhere/build"),
+            virtual_path_def(
+                "build/private-arch-tool.sh",
+                fs_path="/nowhere/build/private-arch-tool.sh",
+                content="#!/bin/sh\n",
+            ),
+        ]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              source: build/private-arch-tool.sh
+              as: /usr/lib/{{DEB_HOST_MULTIARCH}}/foo/private-arch-tool
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_dir, all_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_dir],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    # The variable is always resolved in amd64 context, so we can hard code the resolved
+    # variable
+    tool = foo_fs_root.lookup("/usr/lib/x86_64-linux-gnu/foo/private-arch-tool")
+    assert tool is not None
+    assert tool.is_file
+    assert tool.fs_path == "/nowhere/build/private-arch-tool.sh"
+
+
+def test_install_rules_no_matches(manifest_parser_pkg_foo) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere"),
+            virtual_path_def("build/", fs_path="/nowhere/build"),
+            virtual_path_def(
+                "build/private-arch-tool.sh",
+                fs_path="/nowhere/build/private-arch-tool.sh",
+                content="#!/bin/sh\n",
+            ),
+        ]
+    )
+    debian_tmp_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp"),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              # Typo: the path should have ended with ".sh"
+              source: build/private-arch-tool
+              as: /usr/lib/foo/private-arch-tool
+        """
+    )
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    with pytest.raises(NoMatchForInstallPatternError) as e_info:
+        manifest.perform_installations(
+            install_request_context=InstallSearchDirContext(
+                [
+                    SearchDir(debian_tmp_dir, all_pkgs),
+                    SearchDir(debian_source_root_dir, all_pkgs),
+                ],
+                [debian_tmp_dir],
+            )
+        )
+    expected_msg = (
+        "There were no matches for build/private-arch-tool in /nowhere/debian/tmp, /nowhere"
+        " (definition: installations[0].install <Search for: build/private-arch-tool>)."
+        " Match rule: ./build/private-arch-tool (the exact path / no globbing)"
+    )
+    assert e_info.value.message == expected_msg
+
+
+def test_install_rules_per_package_search_dirs(manifest_parser_pkg_foo_w_udeb) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_tmp_deb_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp-deb"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp-deb/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/tmp-deb/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/tmp-deb/usr/bin/foo",
+                content="#!/bin/sh\ndeb",
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/tmp-deb/usr/bin/foo-util",
+                content="#!/bin/sh\ndeb",
+            ),
+            virtual_path_def(
+                "usr/bin/tool.sh",
+                fs_path="/nowhere/debian/tmp-deb/usr/bin/tool.sh",
+                link_target="./foo",
+            ),
+            virtual_path_def("usr/share/", fs_path="/nowhere/debian/tmp-deb/usr/share"),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/tmp-deb/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/tmp-deb/usr/share/foo/foo.txt",
+                content="A deb text file",
+            ),
+        ]
+    )
+    debian_tmp_udeb_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/tmp-udeb"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/tmp-udeb/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/tmp-udeb/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/tmp-udeb/usr/bin/foo",
+                content="#!/bin/sh\nudeb",
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/tmp-udeb/usr/bin/foo-util",
+                content="#!/bin/sh\nudeb",
+            ),
+            virtual_path_def(
+                "usr/bin/tool.sh",
+                fs_path="/nowhere/debian/tmp-udeb/usr/bin/tool.sh",
+                link_target="./foo",
+            ),
+            virtual_path_def(
+                "usr/share/", fs_path="/nowhere/debian/tmp-udeb/usr/share"
+            ),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/tmp-udeb/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/tmp-udeb/usr/share/foo/foo.txt",
+                content="A udeb text file",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              source: usr/bin/tool.sh
+              as: usr/bin/tool
+              into:
+                - foo
+                - foo-udeb
+          - install:
+              sources:
+                - /usr/share/foo
+                - /usr/bin/foo*
+              into:
+                - foo
+                - foo-udeb
+        """
+    )
+    manifest = manifest_parser_pkg_foo_w_udeb.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+    all_deb_pkgs = frozenset({p for p in all_pkgs if not p.is_udeb})
+    all_udeb_pkgs = frozenset({p for p in all_pkgs if p.is_udeb})
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_tmp_deb_dir, all_deb_pkgs),
+                SearchDir(debian_tmp_udeb_dir, all_udeb_pkgs),
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_tmp_deb_dir],
+        )
+    )
+    for pkg, ptype in [
+        ("foo", "deb"),
+        ("foo-udeb", "udeb"),
+    ]:
+        assert pkg in result
+        fs_root = result[pkg].fs_root
+
+        ub_dir = fs_root.lookup("/usr/bin")
+        assert ub_dir is not None
+        assert ub_dir.is_dir
+        assert not ub_dir.has_fs_path  # This will be "generated"
+
+        tool = ub_dir.get("tool")
+        assert tool is not None
+        assert tool.is_symlink
+        assert tool.readlink() == "./foo"
+
+        assert {"foo", "foo-util", "tool"} == {p.name for p in ub_dir.iterdir}
+
+        for p in ub_dir.iterdir:
+            assert p.has_fs_path
+            assert f"/nowhere/debian/tmp-{ptype}/usr/bin" in p.fs_path
+
+        usf_dir = fs_root.lookup("/usr/share/foo")
+        assert usf_dir is not None
+        assert usf_dir.is_dir
+        # Here we are installing an actual directory, so it should be present too
+        assert usf_dir.has_fs_path
+        assert usf_dir.fs_path == f"/nowhere/debian/tmp-{ptype}/usr/share/foo"
+        assert {"foo.txt"} == {p.name for p in usf_dir.iterdir}
+        foo_txt = usf_dir["foo.txt"]
+        assert foo_txt.fs_path == f"/nowhere/debian/tmp-{ptype}/usr/share/foo/foo.txt"
+
+
+def test_install_rules_multi_into(manifest_parser_pkg_foo_w_udeb) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere"),
+            virtual_path_def("source/", fs_path="/nowhere/source"),
+            virtual_path_def("source/foo/", fs_path="/nowhere/foo"),
+            virtual_path_def(
+                "source/foo/foo-a.data",
+                fs_path="/nowhere/foo/foo-a.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/foo/foo-b.data",
+                fs_path="/nowhere/foo/foo-b.data",
+                link_target="./foo-a.data",
+            ),
+            virtual_path_def("source/bar/", fs_path="/nowhere/bar"),
+            virtual_path_def(
+                "source/bar/bar-a.data",
+                fs_path="/nowhere/bar/bar-a.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/bar/bar-b.data",
+                fs_path="/nowhere/bar/bar-b.data",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/tool.sh",
+                fs_path="/nowhere/source/tool.sh",
+                content="#!/bin/sh\n# run some command ...",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install:
+              sources:
+              - source/foo/*
+              - source/bar
+              dest-dir: usr/share/foo
+              into:
+              - foo
+              - foo-udeb
+          - install:
+              source: source/tool.sh
+              as: usr/share/foo/tool
+              into:
+              - foo
+              - foo-udeb
+        """
+    )
+    manifest = manifest_parser_pkg_foo_w_udeb.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [],
+        )
+    )
+    for pkg in ["foo", "foo-udeb"]:
+        assert pkg in result
+        foo_fs_root = result[pkg].fs_root
+
+        foo_dir = foo_fs_root.lookup("/usr/share/foo")
+        assert foo_dir is not None
+        assert foo_dir.is_dir
+
+        assert {"foo-a.data", "foo-b.data", "bar", "tool"} == {
+            p.name for p in foo_dir.iterdir
+        }
+
+        tool = foo_dir["tool"]
+        assert tool.is_file
+        with tool.open() as fd:
+            content = fd.read()
+        assert content.startswith("#!/bin/sh")
+        foo_a = foo_dir["foo-a.data"]
+        assert foo_a.is_file
+        assert foo_a.fs_path == "/nowhere/foo/foo-a.data"
+        with foo_a.open() as fd:
+            content = fd.read()
+        assert "data" in content
+        foo_b = foo_dir["foo-b.data"]
+        assert foo_b.is_symlink
+        assert foo_b.readlink() == "./foo-a.data"
+
+        bar = foo_dir["bar"]
+        assert bar.is_dir
+        assert {"bar-a.data", "bar-b.data"} == {p.name for p in bar.iterdir}
+        assert {"/nowhere/bar/bar-a.data", "/nowhere/bar/bar-b.data"} == {
+            p.fs_path for p in bar.iterdir
+        }
+
+
+def test_auto_install_d_pkg(manifest_parser_pkg_foo_w_udeb) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [virtual_path_def(".", fs_path="/nowhere")]
+    )
+    debian_foo_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/foo"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/foo/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/foo/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/foo/usr/bin/foo",
+                content="#!/bin/sh\ndeb",
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/foo/usr/bin/foo-util",
+                content="#!/bin/sh\ndeb",
+            ),
+            virtual_path_def(
+                "usr/bin/tool",
+                fs_path="/nowhere/debian/foo/usr/bin/tool",
+                link_target="./foo",
+            ),
+            virtual_path_def("usr/share/", fs_path="/nowhere/debian/foo/usr/share"),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/foo/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/foo/usr/share/foo/foo.txt",
+                content="A deb text file",
+            ),
+        ]
+    )
+    debian_foo_udeb_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere/debian/foo-udeb"),
+            virtual_path_def("usr/", fs_path="/nowhere/debian/foo-udeb/usr"),
+            virtual_path_def("usr/bin/", fs_path="/nowhere/debian/foo-udeb/usr/bin"),
+            virtual_path_def(
+                "usr/bin/foo",
+                fs_path="/nowhere/debian/foo-udeb/usr/bin/foo",
+                content="#!/bin/sh\nudeb",
+            ),
+            virtual_path_def(
+                "usr/bin/foo-util",
+                fs_path="/nowhere/debian/foo-udeb/usr/bin/foo-util",
+                content="#!/bin/sh\nudeb",
+            ),
+            virtual_path_def(
+                "usr/bin/tool",
+                fs_path="/nowhere/debian/foo-udeb/usr/bin/tool",
+                link_target="./foo",
+            ),
+            virtual_path_def(
+                "usr/share/", fs_path="/nowhere/debian/foo-udeb/usr/share"
+            ),
+            virtual_path_def(
+                "usr/share/foo/", fs_path="/nowhere/debian/foo-udeb/usr/share/foo"
+            ),
+            virtual_path_def(
+                "usr/share/foo/foo.txt",
+                fs_path="/nowhere/debian/foo-udeb/usr/share/foo/foo.txt",
+                content="A udeb text file",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        """
+    )
+    manifest = manifest_parser_pkg_foo_w_udeb.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [debian_foo_dir],
+            {
+                "foo": debian_foo_dir,
+                "foo-udeb": debian_foo_udeb_dir,
+            },
+        )
+    )
+    for pkg in ["foo", "foo-udeb"]:
+        assert pkg in result
+        fs_root = result[pkg].fs_root
+        ub_dir = fs_root.lookup("/usr/bin")
+        assert ub_dir is not None
+        assert ub_dir.is_dir
+        assert ub_dir.has_fs_path
+        assert ub_dir.fs_path == f"/nowhere/debian/{pkg}/usr/bin"
+
+        assert {"foo", "foo-util", "tool"} == {p.name for p in ub_dir.iterdir}
+
+        tool = ub_dir.get("tool")
+        assert tool is not None
+        assert tool.is_symlink
+        assert tool.readlink() == "./foo"
+
+        for p in ub_dir.iterdir:
+            assert p.has_fs_path
+            assert f"/nowhere/debian/{pkg}/usr/bin" in p.fs_path
+
+        usf_dir = fs_root.lookup("/usr/share/foo")
+        assert usf_dir is not None
+        assert usf_dir.is_dir
+        # Here we are installing an actual directory, so it should be present too
+        assert usf_dir.has_fs_path
+        assert usf_dir.fs_path == f"/nowhere/debian/{pkg}/usr/share/foo"
+        assert {"foo.txt"} == {p.name for p in usf_dir.iterdir}
+        foo_txt = usf_dir["foo.txt"]
+        assert foo_txt.fs_path == f"/nowhere/debian/{pkg}/usr/share/foo/foo.txt"
+
+
+def test_install_doc_rules_ignore_udeb(manifest_parser_pkg_foo_w_udeb) -> None:
+    debian_source_root_dir = build_virtual_file_system(
+        [
+            virtual_path_def(".", fs_path="/nowhere"),
+            virtual_path_def("source/", fs_path="/nowhere/source"),
+            virtual_path_def("source/foo/", fs_path="/nowhere/foo"),
+            virtual_path_def(
+                "source/foo/foo-a.txt",
+                fs_path="/nowhere/foo/foo-a.txt",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/foo/foo-b.txt",
+                fs_path="/nowhere/foo/foo-b.txt",
+                link_target="./foo-a.txt",
+            ),
+            virtual_path_def("source/html/", fs_path="/nowhere/html"),
+            virtual_path_def(
+                "source/html/bar-a.html",
+                fs_path="/nowhere/html/bar-a.html",
+                content="data file",
+            ),
+            virtual_path_def(
+                "source/html/bar-b.html",
+                fs_path="/nowhere/html/bar-b.html",
+                content="data file",
+            ),
+        ]
+    )
+    manifest_content = textwrap.dedent(
+        """\
+        manifest-version: "0.1"
+        installations:
+          - install-doc:
+              sources:
+              - source/foo/*
+              - source/html
+        """
+    )
+    manifest = manifest_parser_pkg_foo_w_udeb.parse_manifest(fd=manifest_content)
+    all_pkgs = frozenset(manifest.all_packages)
+
+    result = manifest.perform_installations(
+        install_request_context=InstallSearchDirContext(
+            [
+                SearchDir(debian_source_root_dir, all_pkgs),
+            ],
+            [],
+        )
+    )
+    assert "foo" in result
+    foo_fs_root = result["foo"].fs_root
+
+    foo_dir = foo_fs_root.lookup("/usr/share/doc/foo")
+    assert foo_dir is not None
+    assert foo_dir.is_dir
+
+    assert {"foo-a.txt", "foo-b.txt", "html"} == {p.name for p in foo_dir.iterdir}
+
+    foo_a = foo_dir["foo-a.txt"]
+    assert foo_a.is_file
+    assert foo_a.fs_path == "/nowhere/foo/foo-a.txt"
+    foo_b = foo_dir["foo-b.txt"]
+    assert foo_b.is_symlink
+    assert foo_b.readlink() == "./foo-a.txt"
+
+    html_dir = foo_dir["html"]
+    assert html_dir.is_dir
+    assert {"bar-a.html", "bar-b.html"} == {p.name for p in html_dir.iterdir}
+    assert {"/nowhere/html/bar-a.html", "/nowhere/html/bar-b.html"} == {
+        p.fs_path for p in html_dir.iterdir
+    }
+
+    assert "foo-udeb" in result
+    foo_udeb_fs_root = result["foo-udeb"].fs_root
+
+    udeb_doc_dir = foo_udeb_fs_root.lookup("/usr/share/doc")
+    assert udeb_doc_dir is None
diff --git a/tests/test_interpreter.py b/tests/test_interpreter.py
new file mode 100644
index 0000000..6cbfd44
--- /dev/null
+++ b/tests/test_interpreter.py
@@ -0,0 +1,162 @@
+import textwrap
+from typing import Optional
+
+import pytest
+
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.interpreter import extract_shebang_interpreter
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.api.test_api import build_virtual_file_system
+from debputy.transformation_rules import NormalizeShebangLineTransformation
+
+
+@pytest.mark.parametrize(
+    "raw_shebang,original_command,command_full_basename,command_stem,correct_command,corrected_shebang_line",
+    [
+        (
+            b"#!       /usr/bin/false\r\n",
+            "/usr/bin/false",
+            "false",
+            "false",
+            None,
+            None,
+        ),
+        (
+            b"#!/usr/bin/python3 -b",
+            "/usr/bin/python3",
+            "python3",
+            "python",
+            "/usr/bin/python3",
+            None,
+        ),
+        (
+            b"#!/usr/bin/env python3 -b",
+            "/usr/bin/env python3",
+            "python3",
+            "python",
+            "/usr/bin/python3",
+            "#! /usr/bin/python3 -b",
+        ),
+        (
+            b"#! /bin/env python3.12-dbg -b",
+            "/bin/env python3.12-dbg",
+            "python3.12-dbg",
+            "python",
+            "/usr/bin/python3.12-dbg",
+            "#! /usr/bin/python3.12-dbg -b",
+        ),
+        (
+            b"#! /usr/bin/bash",
+            "/usr/bin/bash",
+            "bash",
+            "bash",
+            "/bin/bash",
+            "#! /bin/bash",
+        ),
+        (
+            b"#! /usr/bin/env sh",
+            "/usr/bin/env sh",
+            "sh",
+            "sh",
+            "/bin/sh",
+            "#! /bin/sh",
+        ),
+        (
+            b"#! /usr/local/bin/perl",
+            "/usr/local/bin/perl",
+            "perl",
+            "perl",
+            "/usr/bin/perl",
+            "#! /usr/bin/perl",
+        ),
+    ],
+)
+def test_interpreter_detection(
+    raw_shebang: bytes,
+    original_command: str,
+    command_full_basename: str,
+    command_stem: str,
+    correct_command: Optional[str],
+    corrected_shebang_line: Optional[str],
+) -> None:
+    interpreter = extract_shebang_interpreter(raw_shebang)
+    # The `and ...` part is just to get the raw line in the error message
+    assert interpreter is not None or raw_shebang == b""
+
+    assert interpreter.original_command == original_command
+    assert interpreter.command_full_basename == command_full_basename
+    assert interpreter.command_stem == command_stem
+    assert interpreter.correct_command == correct_command
+    assert interpreter.corrected_shebang_line == corrected_shebang_line
+    assert interpreter.fixup_needed == (corrected_shebang_line is not None)
+
+
+@pytest.mark.parametrize(
+    "raw_data",
+    [
+        b"#!#!#!       /usr/bin/false",
+        b"#!perl",  # Used in files as an editor hint
+        b"\x7FELF/usr/bin/perl",
+        b"\x00\01\x02\x03/usr/bin/perl",
+        b"PK\x03\x03/usr/bin/perl",
+    ],
+)
+def test_interpreter_negative(raw_data: bytes) -> None:
+    assert extract_shebang_interpreter(raw_data) is None
+
+
+@pytest.fixture
+def empty_manifest(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_single_foo_arch_all_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> HighLevelManifest:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+    return YAMLManifestParser(
+        "debian/test-debputy.manifest",
+        source_package,
+        package_single_foo_arch_all_cxt_amd64,
+        amd64_substitution,
+        amd64_dpkg_architecture_variables,
+        dpkg_arch_query,
+        no_profiles_or_build_options,
+        debputy_plugin_feature_set,
+        debian_dir=debian_dir,
+    ).build_manifest()
+
+
+def test_interpreter_rewrite(empty_manifest: HighLevelManifest) -> None:
+    condition_context = empty_manifest.condition_context("foo")
+    fs_root = build_virtual_file_system(
+        [
+            virtual_path_def("usr/bin/foo", content="random data"),
+            virtual_path_def(
+                "usr/bin/foo.sh",
+                materialized_content="#!/usr/bin/sh\nset -e\n",
+            ),
+        ]
+    )
+    interpreter_normalization = NormalizeShebangLineTransformation()
+    interpreter_normalization.transform_file_system(fs_root, condition_context)
+    foo = fs_root.lookup("usr/bin/foo")
+    foo_sh = fs_root.lookup("usr/bin/foo.sh")
+
+    assert foo.is_file
+    with foo.open() as fd:
+        assert fd.read() == "random data"
+
+    assert foo_sh.is_file
+    with foo_sh.open() as fd:
+        expected = textwrap.dedent(
+            """\
+        #! /bin/sh
+        set -e
+        """
+        )
+        assert fd.read() == expected
diff --git a/tests/test_migrations.py b/tests/test_migrations.py
new file mode 100644
index 0000000..dc07d4c
--- /dev/null
+++ b/tests/test_migrations.py
@@ -0,0 +1,1767 @@
+import io
+import textwrap
+from typing import Iterable, Callable, Optional, List, Tuple, Sequence
+
+import pytest
+
+from debputy.dh_migration.migrators import Migrator
+from debputy.dh_migration.migrators_impl import (
+    migrate_tmpfile,
+    migrate_lintian_overrides_files,
+    detect_pam_files,
+    migrate_doc_base_files,
+    migrate_installexamples_file,
+    migrate_installdocs_file,
+    migrate_install_file,
+    migrate_maintscript,
+    migrate_links_files,
+    detect_dh_addons,
+    migrate_not_installed_file,
+    migrate_installman_file,
+    migrate_bash_completion,
+    migrate_installinfo_file,
+    migrate_dh_installsystemd_files,
+    detect_obsolete_substvars,
+    MIGRATION_TARGET_DH_DEBPUTY,
+    MIGRATION_TARGET_DH_DEBPUTY_RRR,
+    detect_dh_addons_zz_debputy_rrr,
+)
+from debputy.dh_migration.models import (
+    FeatureMigration,
+    AcceptableMigrationIssues,
+    UnsupportedFeature,
+)
+from debputy.highlevel_manifest import HighLevelManifest
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.plugin.api import virtual_path_def, VirtualPath
+from debputy.plugin.api.test_api import (
+    build_virtual_file_system,
+)
+
+
+DEBIAN_DIR_ENTRY = virtual_path_def(".", fs_path="/nowhere/debian")
+
+
+@pytest.fixture()
+def manifest_parser_pkg_foo_factory(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_single_foo_arch_all_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> Callable[[], YAMLManifestParser]:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+
+    def _factory():
+        return YAMLManifestParser(
+            "debian/test-debputy.manifest",
+            source_package,
+            package_single_foo_arch_all_cxt_amd64,
+            amd64_substitution,
+            amd64_dpkg_architecture_variables,
+            dpkg_arch_query,
+            no_profiles_or_build_options,
+            debputy_plugin_feature_set,
+            debian_dir=debian_dir,
+        )
+
+    return _factory
+
+
+@pytest.fixture(scope="session")
+def accept_no_migration_issues() -> AcceptableMigrationIssues:
+    return AcceptableMigrationIssues(frozenset())
+
+
+@pytest.fixture(scope="session")
+def accept_any_migration_issues() -> AcceptableMigrationIssues:
+    return AcceptableMigrationIssues(frozenset(["ALL"]))
+
+
+@pytest.fixture
+def empty_manifest_pkg_foo(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+) -> HighLevelManifest:
+    return manifest_parser_pkg_foo_factory().build_manifest()
+
+
+def run_migrator(
+    migrator: Migrator,
+    path: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    *,
+    migration_target=MIGRATION_TARGET_DH_DEBPUTY,
+) -> FeatureMigration:
+    feature_migration = FeatureMigration(migrator.__name__)
+    migrator(
+        path,
+        manifest,
+        acceptable_migration_issues,
+        feature_migration,
+        migration_target,
+    )
+    return feature_migration
+
+
+def _assert_unsupported_feature(
+    migrator: Migrator,
+    path: VirtualPath,
+    manifest: HighLevelManifest,
+    acceptable_migration_issues: AcceptableMigrationIssues,
+):
+    with pytest.raises(UnsupportedFeature) as e:
+        run_migrator(migrator, path, manifest, acceptable_migration_issues)
+    return e
+
+
+def _write_manifest(manifest: HighLevelManifest) -> str:
+    with io.StringIO() as fd:
+        manifest.mutable_manifest.write_to(fd)
+        return fd.getvalue()
+
+
+def _verify_migrator_generates_parsable_manifest(
+    migrator: Migrator,
+    parser_factory: Callable[[], YAMLManifestParser],
+    acceptable_migration_issues: AcceptableMigrationIssues,
+    dh_config_name: str,
+    dh_config_content: str,
+    expected_manifest_content: str,
+    expected_warnings: Optional[List[str]] = None,
+    expected_renamed_paths: Optional[List[Tuple[str, str]]] = None,
+    expected_removals: Optional[List[str]] = None,
+    required_plugins: Optional[Sequence[str]] = tuple(),
+    dh_config_mode: Optional[int] = None,
+) -> None:
+    # No file, no changes
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    migration = run_migrator(
+        migrator,
+        empty_fs,
+        parser_factory().build_manifest(),
+        acceptable_migration_issues,
+    )
+
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    if dh_config_mode is None:
+        if dh_config_content.startswith(("#!/usr/bin/dh-exec", "#! /usr/bin/dh-exec")):
+            dh_config_mode = 0o755
+        else:
+            dh_config_mode = 0o644
+
+    # Test with a dh_config file now
+    fs_w_dh_config = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                dh_config_name,
+                fs_path=f"/nowhere/debian/{dh_config_name}",
+                content=dh_config_content,
+                mode=dh_config_mode,
+            ),
+        ]
+    )
+    manifest = parser_factory().build_manifest()
+
+    migration = run_migrator(
+        migrator,
+        fs_w_dh_config,
+        manifest,
+        acceptable_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    if expected_warnings is not None:
+        assert migration.warnings == expected_warnings
+    else:
+        assert not migration.warnings
+    assert migration.remove_paths_on_success == [f"/nowhere/debian/{dh_config_name}"]
+    if expected_removals is None:
+        assert migration.remove_paths_on_success == [
+            f"/nowhere/debian/{dh_config_name}"
+        ]
+    else:
+        assert migration.remove_paths_on_success == expected_removals
+    if expected_renamed_paths is not None:
+        assert migration.rename_paths_on_success == expected_renamed_paths
+    else:
+        assert not migration.rename_paths_on_success
+    assert tuple(migration.required_plugins) == tuple(required_plugins)
+    actual_manifest = _write_manifest(manifest)
+    assert actual_manifest == expected_manifest_content
+
+    # Verify that the output is actually parsable
+    parser_factory().parse_manifest(fd=actual_manifest)
+
+
+def test_migrate_tmpfile(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = migrate_tmpfile
+    empty_debian_dir = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    migration = run_migrator(
+        migrator,
+        empty_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+    tmpfile_debian_dir = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("tmpfile", fs_path="/nowhere/debian/tmpfile"),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        tmpfile_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert migration.rename_paths_on_success == [
+        ("/nowhere/debian/tmpfile", "/nowhere/debian/tmpfiles")
+    ]
+
+    tmpfile_debian_dir = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            # Use real paths here to make `cmp -s` discover that they are the same
+            virtual_path_def("tmpfile", fs_path="debian/control"),
+            virtual_path_def("tmpfiles", fs_path="debian/control"),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        tmpfile_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    assert migration.anything_to_do
+    assert not migration.warnings
+    assert migration.remove_paths_on_success == ["debian/control"]
+    assert not migration.rename_paths_on_success
+
+    conflict_tmpfile_debian_dir = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            # Use real paths here to make `cmp -s` discover a difference
+            virtual_path_def("tmpfile", fs_path="debian/control"),
+            virtual_path_def("tmpfiles", fs_path="debian/changelog"),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        conflict_tmpfile_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert len(migration.warnings) == 1
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+    conflict_tmpfile_debian_dir = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("tmpfile", fs_path="/nowhere/debian/tmpfile"),
+            virtual_path_def("tmpfiles/", fs_path="/nowhere/debian/tmpfiles"),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        conflict_tmpfile_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert len(migration.warnings) == 1
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+    conflict_tmpfile_debian_dir = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "tmpfile",
+                link_target="/nowhere/debian/tmpfiles",
+                fs_path="/nowhere/debian/tmpfile",
+            ),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        conflict_tmpfile_debian_dir,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert len(migration.warnings) == 1
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+
+def test_migrate_lintian_overrides_files(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+    accept_any_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = migrate_lintian_overrides_files
+    no_override_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    single_noexec_override_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "foo.lintian-overrides",
+                fs_path="/nowhere/no-exec/debian/foo.lintian-overrides",
+            ),
+        ]
+    )
+    single_exec_override_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "foo.lintian-overrides",
+                fs_path="/nowhere/exec/debian/foo.lintian-overrides",
+                mode=0o755,
+            ),
+        ]
+    )
+    for no_issue_fs in [no_override_fs, single_noexec_override_fs]:
+        migration = run_migrator(
+            migrator,
+            no_issue_fs,
+            empty_manifest_pkg_foo,
+            accept_no_migration_issues,
+        )
+
+        assert not migration.anything_to_do
+        assert not migration.warnings
+        assert not migration.remove_paths_on_success
+        assert not migration.rename_paths_on_success
+
+    _assert_unsupported_feature(
+        migrator,
+        single_exec_override_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    migration = run_migrator(
+        migrator,
+        single_exec_override_fs,
+        empty_manifest_pkg_foo,
+        accept_any_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    assert len(migration.warnings) == 1
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+
+def test_detect_pam_files(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_pam_files
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    pam_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("pam", fs_path="/nowhere/debian/foo.pam"),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        empty_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert migration.assumed_compat is None
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+    migration = run_migrator(
+        migrator,
+        pam_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert migration.assumed_compat == 14
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+
+
+def test_migrate_doc_base_files(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = migrate_doc_base_files
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    doc_base_ok_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("doc-base", fs_path="/nowhere/debian/doc-base"),
+            virtual_path_def(
+                "foo.doc-base.EX", fs_path="/nowhere/debian/foo.doc-base.EX"
+            ),
+        ]
+    )
+    doc_base_migration_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "foo.doc-base.bar", fs_path="/nowhere/debian/foo.doc-base.bar"
+            ),
+        ]
+    )
+
+    for no_change_fs in [empty_fs, doc_base_ok_fs]:
+        migration = run_migrator(
+            migrator,
+            no_change_fs,
+            empty_manifest_pkg_foo,
+            accept_no_migration_issues,
+        )
+
+        assert not migration.anything_to_do
+        assert not migration.warnings
+        assert not migration.remove_paths_on_success
+        assert not migration.rename_paths_on_success
+
+    migration = run_migrator(
+        migrator,
+        doc_base_migration_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert migration.rename_paths_on_success == [
+        ("/nowhere/debian/foo.doc-base.bar", "/nowhere/debian/foo.bar.doc-base")
+    ]
+
+
+def test_migrate_dh_installsystemd_files(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = migrate_dh_installsystemd_files
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+    files_ok_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("@service", fs_path="/nowhere/debian/@service"),
+            virtual_path_def("foo.@service", fs_path="/nowhere/debian/foo.@service"),
+        ]
+    )
+    migration_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def("foo@.service", fs_path="/nowhere/debian/foo@.service"),
+        ]
+    )
+
+    for no_change_fs in [empty_fs, files_ok_fs]:
+        migration = run_migrator(
+            migrator,
+            no_change_fs,
+            empty_manifest_pkg_foo,
+            accept_no_migration_issues,
+        )
+
+        assert not migration.anything_to_do
+        assert not migration.warnings
+        assert not migration.remove_paths_on_success
+        assert not migration.rename_paths_on_success
+
+    migration = run_migrator(
+        migrator,
+        migration_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert migration.rename_paths_on_success == [
+        ("/nowhere/debian/foo@.service", "/nowhere/debian/foo.@service")
+    ]
+
+
+def test_migrate_installexamples_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+        bar
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-examples:
+                sources:
+                - foo/*
+                - bar
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installexamples_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "examples",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_installinfo_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+        bar
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-docs:
+                sources:
+                - foo/*
+                - bar
+                dest-dir: '{{path:GNU_INFO_DIR}}'
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installinfo_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "info",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_installinfo_file_conditionals(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        #!/usr/bin/dh-exec
+        foo/* <!pkg.foo.noinfo>
+        bar <!pkg.foo.noinfo>
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-docs:
+                sources:
+                - foo/*
+                - bar
+                dest-dir: '{{path:GNU_INFO_DIR}}'
+                when:
+                  build-profiles-matches: <!pkg.foo.noinfo>
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installinfo_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "info",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_installexamples_file_single_source(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-examples:
+                source: foo/*
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installexamples_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "examples",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_installdocs_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+        bar
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-docs:
+                sources:
+                - foo/*
+                - bar
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installdocs_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "docs",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_installdocs_file_single_source(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-docs:
+                source: foo/*
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installdocs_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "docs",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        bar usr/bin
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                source: bar
+                dest-dir: usr/bin
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file_conditionals_simple_arch(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        #!/usr/bin/dh-exec
+        bar usr/bin  [linux-any]
+        foo usr/bin  [linux-any]
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - bar
+                - foo
+                dest-dir: usr/bin
+                when:
+                  arch-matches: linux-any
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file_util_linux_locales(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    # Parts of the `d/util-linux-locales.install` file. It uses d/tmp for most of its paths
+    # and that breaks the default dest-dir (dh_install always strips --sourcedir, `debputy`
+    # currently does not)
+    dh_config_content = textwrap.dedent(
+        """\
+        #!/usr/bin/dh-exec
+        usr/share/locale/*/*/util-linux.mo
+
+        # bsdextrautils
+        debian/tmp/usr/share/man/*/man1/col.1 <!nodoc>
+
+        debian/tmp/usr/share/man/*/man3/libblkid.3 <!nodoc>
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - usr/share/man/*/man1/col.1
+                - usr/share/man/*/man3/libblkid.3
+                when:
+                  build-profiles-matches: <!nodoc>
+            - install:
+                source: usr/share/locale/*/*/util-linux.mo
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file_conditionals_simple_combined_cond(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    for cond in ["<!foo> <!bar> [linux-any]", "[linux-any] <!foo> <!bar>"]:
+        dh_config_content = textwrap.dedent(
+            """\
+            #!/usr/bin/dh-exec
+            bar usr/bin  {CONDITION}
+            foo usr/bin  {CONDITION}
+        """
+        ).format(CONDITION=cond)
+        expected_manifest_content = textwrap.dedent(
+            """\
+                manifest-version: '0.1'
+                installations:
+                - install:
+                    sources:
+                    - bar
+                    - foo
+                    dest-dir: usr/bin
+                    when:
+                      all-of:
+                      - arch-matches: linux-any
+                      - build-profiles-matches: <!foo> <!bar>
+        """
+        )
+        _verify_migrator_generates_parsable_manifest(
+            migrate_install_file,
+            manifest_parser_pkg_foo_factory,
+            accept_no_migration_issues,
+            "install",
+            dh_config_content,
+            expected_manifest_content,
+        )
+
+
+def test_migrate_install_file_conditionals_unknown_subst(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_any_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        #!/usr/bin/dh-exec
+        bar ${unknown_substvar}
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            definitions:
+              variables:
+                unknown_substvar: 'TODO: Provide variable value for unknown_substvar'
+            installations:
+            - install:
+                source: bar
+                dest-dir: '{{unknown_substvar}}'
+    """
+    )
+    expected_warning = (
+        "TODO: MANUAL MIGRATION of unresolved substitution variable {{unknown_substvar}}"
+        ' from ./install line 2 token "${unknown_substvar}"'
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_any_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+        expected_warnings=[expected_warning],
+    )
+
+
+def test_migrate_install_file_multidest(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        # Issue #66
+        # - observed in kafs-client / the original install file copied in here.
+
+        src/aklog-kafs        usr/bin
+        src/kafs-check-config usr/bin
+        #
+        src/kafs-preload usr/sbin
+        #
+        src/kafs-dns     usr/libexec
+        #
+        conf/cellservdb.conf usr/share/kafs-client
+        conf/client.conf     etc/kafs
+        #
+        conf/kafs_dns.conf etc/request-key.d
+        #
+        conf/cellservdb.conf usr/share/kafs
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - src/aklog-kafs
+                - src/kafs-check-config
+                dest-dir: usr/bin
+            - install:
+                source: src/kafs-preload
+                dest-dir: usr/sbin
+            - install:
+                source: src/kafs-dns
+                dest-dir: usr/libexec
+            - install:
+                source: conf/client.conf
+                dest-dir: etc/kafs
+            - install:
+                source: conf/kafs_dns.conf
+                dest-dir: etc/request-key.d
+            - multi-dest-install:
+                source: conf/cellservdb.conf
+                dest-dirs:
+                - usr/share/kafs-client
+                - usr/share/kafs
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file_multidest_default_dest(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        # Relaed to issue #66 - testing corner case not present in the original install file
+
+        src/aklog-kafs        usr/bin
+        src/kafs-check-config usr/bin
+        #
+        src/kafs-preload usr/sbin
+        #
+        src/kafs-dns     usr/libexec
+        #
+        usr/share/kafs-client/cellservdb.conf
+        conf/client.conf     etc/kafs
+        #
+        conf/kafs_dns.conf etc/request-key.d
+        #
+        usr/share/kafs-client/cellservdb.conf usr/share/kafs
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - src/aklog-kafs
+                - src/kafs-check-config
+                dest-dir: usr/bin
+            - install:
+                source: src/kafs-preload
+                dest-dir: usr/sbin
+            - install:
+                source: src/kafs-dns
+                dest-dir: usr/libexec
+            - install:
+                source: conf/client.conf
+                dest-dir: etc/kafs
+            - install:
+                source: conf/kafs_dns.conf
+                dest-dir: etc/request-key.d
+            - multi-dest-install:
+                source: usr/share/kafs-client/cellservdb.conf
+                dest-dirs:
+                - usr/share/kafs
+                - usr/share/kafs-client
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_install_file_multidest_default_dest_warning(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        # Relaed to issue #66 - testing corner case not present in the original install file
+
+        src/aklog-kafs        usr/bin
+        src/kafs-check-config usr/bin
+        #
+        src/kafs-preload usr/sbin
+        #
+        src/kafs-dns     usr/libexec
+        #
+        usr/share/kafs-*/cellservdb.conf
+        conf/client.conf     etc/kafs
+        #
+        conf/kafs_dns.conf etc/request-key.d
+        #
+        usr/share/kafs-*/cellservdb.conf usr/share/kafs
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - src/aklog-kafs
+                - src/kafs-check-config
+                dest-dir: usr/bin
+            - install:
+                source: src/kafs-preload
+                dest-dir: usr/sbin
+            - install:
+                source: src/kafs-dns
+                dest-dir: usr/libexec
+            - install:
+                source: conf/client.conf
+                dest-dir: etc/kafs
+            - install:
+                source: conf/kafs_dns.conf
+                dest-dir: etc/request-key.d
+            - multi-dest-install:
+                source: usr/share/kafs-*/cellservdb.conf
+                dest-dirs:
+                - usr/share/kafs
+                - 'FIXME: usr/share/kafs-* (could not reliably compute the dest dir)'
+    """
+    )
+    warnings = [
+        "TODO: FIXME left in dest-dir(s) of some installation rules."
+        " Please review these and remove the FIXME (plus correct as necessary)"
+    ]
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+        expected_warnings=warnings,
+    )
+
+
+def test_migrate_installman_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        man/foo.1 man/bar.1
+        man2/*.2
+        man3/bar.3 man3/bar.de.3
+        man/de/man3/bar.pl.3
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install-man:
+                sources:
+                - man/foo.1
+                - man/bar.1
+                - man2/*.2
+                - man/de/man3/bar.pl.3
+            - install-man:
+                sources:
+                - man3/bar.3
+                - man3/bar.de.3
+                language: derive-from-basename
+    """
+    )
+    expected_warnings = [
+        'Detected manpages that might rely on "derive-from-basename" logic.  Please double check'
+        " that the generated `install-man` rules are correct"
+    ]
+    _verify_migrator_generates_parsable_manifest(
+        migrate_installman_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "manpages",
+        dh_config_content,
+        expected_manifest_content,
+        expected_warnings=expected_warnings,
+    )
+
+
+def test_migrate_install_dh_exec_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        #!/usr/bin/dh-exec
+
+        foo/script.sh => usr/bin/script
+        => usr/bin/bar
+        usr/bin/* usr/share/foo/extra/* usr/share/foo/extra
+        another-util usr/share/foo/extra
+        # This will not be merged with `=> usr/bin/bar`
+        usr/share/foo/features
+        usr/share/foo/bugs
+        some-file.txt usr/share/foo/online-doc
+        # TODO: Support migration of these
+        # pathA pathB  conditional/arch [linux-anx]
+        # <!pkg.foo.condition>  another-path conditional/profile
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                source: usr/bin/bar
+            - install:
+                source: foo/script.sh
+                as: usr/bin/script
+            - install:
+                sources:
+                - usr/bin/*
+                - usr/share/foo/extra/*
+                - another-util
+                dest-dir: usr/share/foo/extra
+            - install:
+                source: some-file.txt
+                dest-dir: usr/share/foo/online-doc
+            - install:
+                sources:
+                - usr/share/foo/features
+                - usr/share/foo/bugs
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_install_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "install",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_maintscript(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        rm_conffile /etc/foo.conf
+        mv_conffile /etc/bar.conf /etc/new-foo.conf 1.0~ bar
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            packages:
+              foo:
+                conffile-management:
+                - remove:
+                    path: /etc/foo.conf
+                - rename:
+                    source: /etc/bar.conf
+                    target: /etc/new-foo.conf
+                    prior-to-version: 1.0~
+                    owning-package: bar
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_maintscript,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "maintscript",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_not_installed_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*.txt bar/${DEB_HOST_MULTIARCH}/*.so*
+        baz/script.sh
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - discard:
+              - foo/*.txt
+              - bar/{{DEB_HOST_MULTIARCH}}/*.so*
+              - baz/script.sh
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_not_installed_file,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "not-installed",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_migrate_links_files(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        usr/share/target usr/bin/symlink
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            packages:
+              foo:
+                transformations:
+                - create-symlink:
+                    path: usr/bin/symlink
+                    target: /usr/share/target
+    """
+    )
+    _verify_migrator_generates_parsable_manifest(
+        migrate_links_files,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "links",
+        dh_config_content,
+        expected_manifest_content,
+    )
+
+
+def test_detect_obsolete_substvars(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_obsolete_substvars
+
+    dctrl_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: any
+    Description: ...
+    Depends: ${misc:Depends},
+      ${shlibs:Depends},
+      bar (>= 1.0~) | baz, ${so:Depends},
+    """
+    )
+    dctrl_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control",
+                content=dctrl_content,
+            ),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        dctrl_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    msg = (
+        "The following relationship substitution variables can be removed from foo:"
+        " ${misc:Depends}, ${shlibs:Depends}, ${so:Depends}"
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+
+def test_detect_obsolete_substvars_remove_field(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_obsolete_substvars
+
+    dctrl_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: any
+    Description: ...
+    Pre-Depends: ${misc:Pre-Depends}
+    Depends: bar (>= 1.0~) | baz
+    """
+    )
+    dctrl_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control",
+                content=dctrl_content,
+            ),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        dctrl_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    msg = (
+        "The following relationship fields can be removed from foo: Pre-Depends."
+        "  (The content in them would be applied automatically.)"
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+
+def test_detect_obsolete_substvars_remove_field_essential(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_obsolete_substvars
+
+    dctrl_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: any
+    Description: ...
+    Essential: yes
+    # Obsolete because the package is essential
+    Pre-Depends: ${shlibs:Depends}
+    Depends: bar (>= 1.0~) | baz
+    """
+    )
+    dctrl_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control",
+                content=dctrl_content,
+            ),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        dctrl_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    msg = (
+        "The following relationship fields can be removed from foo: Pre-Depends."
+        "  (The content in them would be applied automatically.)"
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+
+def test_detect_obsolete_substvars_remove_field_non_essential(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_obsolete_substvars
+
+    dctrl_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: any
+    Description: ...
+    # This is not obsolete since the package is not essential
+    Pre-Depends: ${shlibs:Depends}
+    Depends: bar (>= 1.0~) | baz
+    """
+    )
+    dctrl_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control",
+                content=dctrl_content,
+            ),
+        ]
+    )
+
+    migration = run_migrator(
+        migrator,
+        dctrl_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+
+def test_detect_dh_addons(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+    accept_any_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_dh_addons
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+
+    dctrl_no_addons_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13)
+
+    Package: foo
+    Architecture: all
+    Description: ...
+    """
+    )
+
+    dctrl_w_addons_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: all
+    Description: ...
+    """
+    )
+
+    dctrl_w_migrateable_addons_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-debputy,
+                   dh-sequence-numpy3,
+
+    Package: foo
+    Architecture: all
+    Description: ...
+    """
+    )
+
+    dctrl_no_addons_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control-without-addons",
+                content=dctrl_no_addons_content,
+            ),
+        ]
+    )
+    dctrl_w_addons_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control-with-addons",
+                content=dctrl_w_addons_content,
+            ),
+        ]
+    )
+    dctrl_w_migrateable_addons_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control-with-migrateable-addons",
+                content=dctrl_w_migrateable_addons_content,
+            ),
+        ]
+    )
+    no_ctrl_msg = (
+        "Cannot find debian/control. Detection of unsupported/missing dh-sequence addon"
+        " could not be performed. Please ensure the package will Build-Depend on dh-sequence-zz-debputy"
+        " and not rely on any other debhelper sequence addons except those debputy explicitly supports."
+    )
+    missing_debputy_bd_msg = "Missing Build-Depends on dh-sequence-zz-debputy"
+    unsupported_sequence_msg = (
+        'The dh addon "foo" is not known to work with dh-debputy and might malfunction'
+    )
+
+    migration = run_migrator(
+        migrator,
+        empty_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [no_ctrl_msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    migration = run_migrator(
+        migrator,
+        dctrl_no_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [missing_debputy_bd_msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    _assert_unsupported_feature(
+        migrator,
+        dctrl_w_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    migration = run_migrator(
+        migrator,
+        dctrl_w_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_any_migration_issues,
+    )
+
+    assert migration.anything_to_do
+    assert migration.warnings == [unsupported_sequence_msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    migration = run_migrator(
+        migrator,
+        dctrl_w_migrateable_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_any_migration_issues,
+    )
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert migration.required_plugins == ["numpy3"]
+
+
+def test_detect_dh_addons_rrr(
+    empty_manifest_pkg_foo: HighLevelManifest,
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    migrator = detect_dh_addons_zz_debputy_rrr
+    empty_fs = build_virtual_file_system([DEBIAN_DIR_ENTRY])
+
+    dctrl_no_addons_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13)
+
+    Package: foo
+    Architecture: all
+    Description: ...
+    """
+    )
+
+    dctrl_w_addons_content = textwrap.dedent(
+        """\
+    Source: foo
+    Build-Depends: debhelper-compat (= 13),
+                   dh-sequence-zz-debputy-rrr,
+                   dh-sequence-foo,
+
+    Package: foo
+    Architecture: all
+    Description: ...
+    """
+    )
+
+    dctrl_no_addons_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control-without-addons",
+                content=dctrl_no_addons_content,
+            ),
+        ]
+    )
+    dctrl_w_addons_fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                "control",
+                fs_path="/nowhere/debian/control-with-addons",
+                content=dctrl_w_addons_content,
+            ),
+        ]
+    )
+    no_ctrl_msg = (
+        "Cannot find debian/control. Detection of unsupported/missing dh-sequence addon"
+        " could not be performed. Please ensure the package will Build-Depend on dh-sequence-zz-debputy-rrr."
+    )
+    missing_debputy_bd_msg = "Missing Build-Depends on dh-sequence-zz-debputy-rrr"
+
+    migration = run_migrator(
+        migrator,
+        empty_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+        migration_target=MIGRATION_TARGET_DH_DEBPUTY_RRR,
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [no_ctrl_msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    migration = run_migrator(
+        migrator,
+        dctrl_no_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+    assert migration.anything_to_do
+    assert migration.warnings == [missing_debputy_bd_msg]
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+    migration = run_migrator(
+        migrator,
+        dctrl_w_addons_fs,
+        empty_manifest_pkg_foo,
+        accept_no_migration_issues,
+    )
+
+    assert not migration.anything_to_do
+    assert not migration.warnings
+    assert not migration.remove_paths_on_success
+    assert not migration.rename_paths_on_success
+    assert not migration.required_plugins
+
+
+def test_migrate_bash_completion_file_no_changes(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        compgen -A
+    """
+    )
+    dh_config_name = "bash-completion"
+    fs = build_virtual_file_system(
+        [
+            DEBIAN_DIR_ENTRY,
+            virtual_path_def(
+                dh_config_name,
+                fs_path=f"/nowhere/debian/{dh_config_name}",
+                content=dh_config_content,
+            ),
+        ]
+    )
+    migration = run_migrator(
+        migrate_bash_completion,
+        fs,
+        manifest_parser_pkg_foo_factory().build_manifest(),
+        accept_no_migration_issues,
+    )
+    assert not migration.rename_paths_on_success
+    assert not migration.remove_paths_on_success
+    assert not migration.warnings
+    assert not migration.required_plugins
+
+
+def test_migrate_bash_completion_file(
+    manifest_parser_pkg_foo_factory: Callable[[], YAMLManifestParser],
+    accept_no_migration_issues: AcceptableMigrationIssues,
+) -> None:
+    dh_config_content = textwrap.dedent(
+        """\
+        foo/*
+        bar baz
+        debian/bar-completion bar
+        debian/foo-completion foo
+        debian/*.cmpl
+    """
+    )
+    expected_manifest_content = textwrap.dedent(
+        """\
+            manifest-version: '0.1'
+            installations:
+            - install:
+                sources:
+                - foo/*
+                - debian/*.cmpl
+                dest-dir: '{{path:BASH_COMPLETION_DIR}}'
+            - install:
+                source: bar
+                as: '{{path:BASH_COMPLETION_DIR}}/baz'
+    """
+    )
+    expected_renames = [
+        ("debian/bar-completion", "debian/foo.bar.bash-completion"),
+        ("debian/foo-completion", "debian/foo.bash-completion"),
+    ]
+    _verify_migrator_generates_parsable_manifest(
+        migrate_bash_completion,
+        manifest_parser_pkg_foo_factory,
+        accept_no_migration_issues,
+        "bash-completion",
+        dh_config_content,
+        expected_manifest_content,
+        expected_renamed_paths=expected_renames,
+    )
diff --git a/tests/test_output_filename.py b/tests/test_output_filename.py
new file mode 100644
index 0000000..fab0e98
--- /dev/null
+++ b/tests/test_output_filename.py
@@ -0,0 +1,27 @@
+from pathlib import Path
+
+import pytest
+
+from debputy.util import compute_output_filename
+
+
+def write_unpacked_deb(root: Path, package: str, version: str, arch: str):
+    (root / "control").write_text(
+        f"Package: {package}\nVersion: {version}\nArchitecture: {arch}\n"
+    )
+
+
+@pytest.mark.parametrize(
+    "package,version,arch,is_udeb,expected",
+    [
+        ("fake", "1.0", "amd64", False, "fake_1.0_amd64.deb"),
+        ("fake", "1.0", "amd64", True, "fake_1.0_amd64.udeb"),
+        ("fake", "2:1.0", "amd64", False, "fake_1.0_amd64.deb"),
+        ("fake", "2:1.0", "amd64", True, "fake_1.0_amd64.udeb"),
+        ("fake", "3.0", "all", False, "fake_3.0_all.deb"),
+        ("fake", "3.0", "all", True, "fake_3.0_all.udeb"),
+    ],
+)
+def test_generate_deb_filename(tmp_path, package, version, arch, is_udeb, expected):
+    write_unpacked_deb(tmp_path, package, version, arch)
+    assert compute_output_filename(str(tmp_path), is_udeb) == expected
diff --git a/tests/test_packager_provided_files.py b/tests/test_packager_provided_files.py
new file mode 100644
index 0000000..149564d
--- /dev/null
+++ b/tests/test_packager_provided_files.py
@@ -0,0 +1,210 @@
+import random
+from typing import cast
+
+import pytest
+
+from debputy.packager_provided_files import detect_all_packager_provided_files
+from debputy.plugin.api import DebputyPluginInitializer
+from debputy.plugin.api.feature_set import PluginProvidedFeatureSet
+from debputy.plugin.api.test_api import (
+    InitializedPluginUnderTest,
+    build_virtual_file_system,
+)
+from debputy.plugin.api.test_api.test_impl import initialize_plugin_under_test_preloaded
+from tutil import faked_binary_package, binary_package_table
+
+
+def ppf_test_plugin(api: DebputyPluginInitializer) -> None:
+    api.packager_provided_file(
+        "arch-specific-dash",
+        "/some/test-directory/{name}.conf",
+        allow_architecture_segment=True,
+    )
+    api.packager_provided_file(
+        "arch.specific.dot",
+        "/some/test.directory/{name}",
+        allow_architecture_segment=True,
+    )
+
+    api.packager_provided_file(
+        "arch.specific.with.priority",
+        "/some/test.priority.directory/{priority:02}-{name}",
+        allow_architecture_segment=True,
+        default_priority=60,
+    )
+
+    api.packager_provided_file(
+        "packageless-fallback",
+        "/some/test-plfb/{name}",
+        packageless_is_fallback_for_all_packages=True,
+    )
+    api.packager_provided_file(
+        "packageless.fallback",
+        "/some/test.plfb/{name}",
+        packageless_is_fallback_for_all_packages=True,
+    )
+
+
+@pytest.mark.parametrize(
+    "package_name,basename,install_target,is_main_binary",
+    [
+        ("foo", "foo.arch-specific-dash", "./some/test-directory/foo.conf", True),
+        # main package match
+        ("foo", "arch-specific-dash", "./some/test-directory/foo.conf", True),
+        # arch match
+        ("foo", "foo.arch-specific-dash.amd64", "./some/test-directory/foo.conf", True),
+        # Matches with periods in both package name and in the file type
+        ("foo.bar", "foo.bar.arch.specific.dot", "./some/test.directory/foo.bar", True),
+        ("foo.bar", "arch.specific.dot", "./some/test.directory/foo.bar", True),
+        (
+            "foo.bar",
+            "foo.bar.arch.specific.dot.amd64",
+            "./some/test.directory/foo.bar",
+            True,
+        ),
+        # Priority
+        (
+            "foo.bar",
+            "foo.bar.arch.specific.with.priority",
+            "./some/test.priority.directory/60-foo.bar",
+            True,
+        ),
+        (
+            "foo.bar",
+            "arch.specific.with.priority",
+            "./some/test.priority.directory/60-foo.bar",
+            True,
+        ),
+        (
+            "foo.bar",
+            "foo.bar.arch.specific.with.priority.amd64",
+            "./some/test.priority.directory/60-foo.bar",
+            True,
+        ),
+        # Name
+        (
+            "foo.bar",
+            "foo.bar.special.name.arch.specific.with.priority",
+            "./some/test.priority.directory/60-special.name",
+            True,
+        ),
+        (
+            "foo.bar",
+            "foo.bar.special.name.arch.specific.with.priority.amd64",
+            "./some/test.priority.directory/60-special.name",
+            True,
+        ),
+        (
+            "foo.bar",
+            "packageless-fallback",
+            "./some/test-plfb/foo.bar",
+            False,
+        ),
+        (
+            "foo.bar",
+            "packageless.fallback",
+            "./some/test.plfb/foo.bar",
+            False,
+        ),
+    ],
+)
+def test_packager_provided_files(
+    package_name: str, basename: str, install_target: str, is_main_binary: bool
+) -> None:
+    # Inject our custom files
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        ppf_test_plugin,
+        plugin_name="pff-test-plugin",
+    )
+    debputy_plugin_feature_set = _fetch_debputy_plugin_feature_set(plugin)
+
+    debian_dir = build_virtual_file_system([basename])
+    binary_under_test = faked_binary_package(
+        package_name, is_main_package=is_main_binary
+    )
+    main_package = (
+        binary_under_test if is_main_binary else faked_binary_package("main-pkg")
+    )
+    binaries = [main_package]
+    if not is_main_binary:
+        binaries.append(binary_under_test)
+    binary_packages = binary_package_table(*binaries)
+
+    ppf = detect_all_packager_provided_files(
+        debputy_plugin_feature_set.packager_provided_files,
+        debian_dir,
+        binary_packages,
+    )
+    assert package_name in ppf
+    all_matched = ppf[package_name].auto_installable
+    assert len(all_matched) == 1
+    matched = all_matched[0]
+    assert basename == matched.path.name
+    actual_install_target = "/".join(matched.compute_dest())
+    assert actual_install_target == install_target
+
+
+@pytest.mark.parametrize(
+    "package_name,expected_basename,non_matched",
+    [
+        ("foo", "foo.arch-specific-dash", ["arch-specific-dash"]),
+        (
+            "foo",
+            "foo.arch-specific-dash.amd64",
+            [
+                "foo.arch-specific-dash",
+                "arch-specific-dash",
+                "foo.arch-specific-dash.i386",
+            ],
+        ),
+        (
+            "foo",
+            "foo.arch-specific-dash",
+            ["arch-specific-dash", "foo.arch-specific-dash.i386"],
+        ),
+    ],
+)
+def test_packager_provided_files_priority(
+    package_name, expected_basename, non_matched
+) -> None:
+    assert len(non_matched) > 0
+    # Inject our custom files
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        ppf_test_plugin,
+        plugin_name="pff-test-plugin",
+    )
+    debputy_plugin_feature_set = _fetch_debputy_plugin_feature_set(plugin)
+    binary_packages = binary_package_table(faked_binary_package(package_name))
+    all_entries_base = [x for x in non_matched]
+
+    for order in (0, len(all_entries_base), None):
+        all_entries = all_entries_base.copy()
+        print(f"Order: {order}")
+        if order is not None:
+            all_entries.insert(order, expected_basename)
+        else:
+            all_entries.append(expected_basename)
+            # Ensure there are no order dependencies in the test by randomizing it.
+            random.shuffle(all_entries)
+
+        debian_dir = build_virtual_file_system(all_entries)
+        ppf = detect_all_packager_provided_files(
+            debputy_plugin_feature_set.packager_provided_files,
+            debian_dir,
+            binary_packages,
+        )
+        assert package_name in ppf
+        all_matched = ppf[package_name].auto_installable
+        assert len(all_matched) == 1
+        matched = all_matched[0]
+        assert expected_basename == matched.path.name
+
+
+def _fetch_debputy_plugin_feature_set(
+    plugin: InitializedPluginUnderTest,
+) -> PluginProvidedFeatureSet:
+    # Very much not public API, but we need it to avoid testing on production data (also, it is hard to find
+    # relevant debputy files for all the cases we want to test).
+    return cast("InitializedPluginUnderTestImpl", plugin)._feature_set
diff --git a/tests/test_packer_pack.py b/tests/test_packer_pack.py
new file mode 100644
index 0000000..17529ef
--- /dev/null
+++ b/tests/test_packer_pack.py
@@ -0,0 +1,86 @@
+import argparse
+import json
+from pathlib import Path
+
+from debputy.commands import deb_packer
+from debputy.intermediate_manifest import TarMember, PathType
+
+
+def write_unpacked_deb(root: Path, package: str, version: str, arch: str):
+    debian = root / "DEBIAN"
+    debian.mkdir(mode=0o755)
+    (debian / "control").write_text(
+        f"Package: {package}\nVersion: {version}\nArchitecture: {arch}\n"
+    )
+
+
+def test_pack_smoke(tmp_path):
+    mtime = 1668973695
+
+    root_dir = tmp_path / "root"
+    root_dir.mkdir()
+    write_unpacked_deb(root_dir, "fake", "1.0", "amd64")
+    output_path = tmp_path / "out"
+    output_path.mkdir()
+    deb_file = Path(output_path) / "output.deb"
+
+    parsed_args = argparse.Namespace(
+        is_udeb=False, compression_level=None, compression_strategy=None
+    )
+
+    data_compression = deb_packer.COMPRESSIONS["xz"]
+    data_compression_cmd = data_compression.as_cmdline(parsed_args)
+    ctrl_compression = data_compression
+    ctrl_compression_cmd = data_compression_cmd
+
+    package_manifest = tmp_path / "temporary-manifest.json"
+    package_manifest.write_text(
+        json.dumps(
+            [
+                TarMember.virtual_path(
+                    "./", PathType.DIRECTORY, mode=0o755, mtime=1668973695
+                ).to_manifest()
+            ]
+        )
+    )
+
+    deb_packer.pack(
+        str(deb_file),
+        ctrl_compression,
+        data_compression,
+        str(root_dir),
+        str(package_manifest),
+        mtime,
+        ctrl_compression_cmd,
+        data_compression_cmd,
+        prefer_raw_exceptions=True,
+    )
+
+    binary = deb_file.read_bytes()
+
+    assert binary == (
+        b"!<arch>\n"
+        b"debian-binary   1668973695  0     0     100644  4         `\n"
+        b"2.0\n"
+        b"control.tar.xz  1668973695  0     0     100644  244       `\n"
+        b"\xfd7zXZ\x00\x00\x04\xe6\xd6\xb4F\x04\xc0\xb4\x01\x80P!\x01\x16\x00\x00\x00"
+        b"\x00\x00\x00\x00\x19\x87 E\xe0'\xff\x00\xac]\x00\x17\x0b\xbc\x1c}"
+        b"\x01\x95\xc0\x1dJ>y\x15\xc2\xcc&\xa3^\x11\xb5\x81\xa6\x8cI\xd2\xf0m\xdd\x04"
+        b"M\xb2|Tdy\xf5\x00H\xab\xa6B\x11\x8d2\x0e\x1d\xf8F\x9e\x9a\xb0\xb8_]\xa3;M"
+        b"t\x90\x9a\xe3)\xeb\xadF\xfet'b\x05\x85\xd5\x04g\x7f\x89\xeb=(\xfd\xf6"
+        b'"p\xc3\x91\xf2\xd3\xd2\xb3\xed%i\x9a\xfa\\\xde7\xd5\x01\x18I\x14D\x10E'
+        b"\xba\xdf\xfb\x12{\x84\xc4\x10\x08,\xbc\x9e\xac+w\x07\r`|\xcfFL#\xbb"
+        b"S\x91\xb4\\\x9b\x80&\x1d\x9ej\x13\xe3\x13\x02=\xe9\xd5\xcf\xb0\xdf?L\xf1\x96"
+        b"\xd2\xc6bh\x19|?\xc2j\xe58If\xb7Y\xb9\x18:\x00\x00|\xfb\xcf\x82e/\xd05"
+        b"\x00\x01\xd0\x01\x80P\x00\x00\xc9y\xeem\xb1\xc4g\xfb\x02\x00\x00\x00"
+        b"\x00\x04YZ"
+        b"data.tar.xz     1668973695  0     0     100644  168       `\n"
+        b"\xfd7zXZ\x00\x00\x04\xe6\xd6\xb4F\x04\xc0h\x80P!\x01\x16\x00\x00\x00\x00"
+        b"\x00\x00\x00\x00\xc2bi\xe8\xe0'\xff\x00`]\x00\x17\x0b\xbc\x1c}"
+        b"\x01\x95\xc0\x1dJ>y\x15\xc2\xcc&\xa3^\x11\xb5\x81\xa6\x8cI\xd2\xf0m\xdd\x04"
+        b"M\xb2|Tdy\xf5\x00H\xab\xa6B\x11\x8d2\x0e\x1d\xf8F\x9e\x9a\xb0\xb8_]\xa4W%"
+        b"\xa2\x14N\xb9\xe7\xbd\xf3a\x16\xe5\xb7\xe6\x80\x95\xcc\xe6+\xe1;I"
+        b"\xf2\x1f\xed\x08\xac\xd7UZ\xc0P\x0b\xfb\nK\xef~\xcb\x8f\x80\x00\x9b\x19\xf8A"
+        b"Q_\xe7\xeb\x00\x01\x84\x01\x80P\x00\x00(3\xf1\xfa\xb1\xc4g\xfb"
+        b"\x02\x00\x00\x00\x00\x04YZ"
+    )
diff --git a/tests/test_parser.py b/tests/test_parser.py
new file mode 100644
index 0000000..bc041fc
--- /dev/null
+++ b/tests/test_parser.py
@@ -0,0 +1,473 @@
+import textwrap
+
+import pytest
+
+from debputy import DEBPUTY_DOC_ROOT_DIR
+from debputy.exceptions import DebputySubstitutionError
+from debputy.highlevel_manifest_parser import YAMLManifestParser
+from debputy.manifest_parser.exceptions import ManifestParseException
+from debputy.plugin.api.test_api import build_virtual_file_system
+
+
+def normalize_doc_link(message) -> str:
+    return message.replace(DEBPUTY_DOC_ROOT_DIR, "{{DEBPUTY_DOC_ROOT_DIR}}")
+
+
+@pytest.fixture()
+def manifest_parser_pkg_foo(
+    amd64_dpkg_architecture_variables,
+    dpkg_arch_query,
+    source_package,
+    package_single_foo_arch_all_cxt_amd64,
+    amd64_substitution,
+    no_profiles_or_build_options,
+    debputy_plugin_feature_set,
+) -> YAMLManifestParser:
+    # We need an empty directory to avoid triggering packager provided files.
+    debian_dir = build_virtual_file_system([])
+    return YAMLManifestParser(
+        "debian/test-debputy.manifest",
+        source_package,
+        package_single_foo_arch_all_cxt_amd64,
+        amd64_substitution,
+        amd64_dpkg_architecture_variables,
+        dpkg_arch_query,
+        no_profiles_or_build_options,
+        debputy_plugin_feature_set,
+        debian_dir=debian_dir,
+    )
+
+
+def test_parsing_no_manifest(manifest_parser_pkg_foo):
+    manifest = manifest_parser_pkg_foo.build_manifest()
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+    assert [p.name for p in manifest.active_packages] == ["foo"]
+
+
+def test_parsing_version_only(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    """
+    )
+
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    assert [p.name for p in manifest.all_packages] == ["foo"]
+    assert [p.name for p in manifest.active_packages] == ["foo"]
+
+
+def test_parsing_variables(manifest_parser_pkg_foo):
+    # https://salsa.debian.org/debian/debputy/-/issues/58
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    definitions:
+      variables:
+        LIBPATH: "/usr/lib/{{DEB_HOST_MULTIARCH}}"
+        SONAME: "1"
+        LETTER_O: "o"
+    installations:
+      - install:
+           source: build/libfoo.so.{{SONAME}}
+           dest-dir: "{{LIBPATH}}"
+           into: f{{LETTER_O}}{{LETTER_O}}
+    packages:
+      f{{LETTER_O}}{{LETTER_O}}:
+        transformations:
+          - create-symlink:
+              path: "{{LIBPATH}}/libfoo.so.{{SONAME}}.0.0"
+              target: "{{LIBPATH}}/libfoo.so.{{SONAME}}"
+    """
+    )
+    manifest_parser_pkg_foo.parse_manifest(fd=content)
+    # TODO: Verify that the substitution is applied correctly throughout
+    # (currently, the test just verifies that we do not reject the manifest)
+
+
+@pytest.mark.parametrize(
+    "varname",
+    [
+        "PACKAGE",
+        "DEB_HOST_ARCH",
+        "DEB_BLAH_ARCH",
+        "env:UNEXISTING",
+        "token:TAB",
+    ],
+)
+def test_parsing_variables_reserved(manifest_parser_pkg_foo, varname):
+    content = textwrap.dedent(
+        f"""\
+    manifest-version: '0.1'
+    definitions:
+      variables:
+        '{varname}': "test"
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = f'The variable "{varname}" is already reserved/defined. Error triggered by definitions.variables.{varname}.'
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_parsing_variables_interdependent_ok(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    definitions:
+      variables:
+        DOC_PATH: "/usr/share/doc/foo"
+        EXAMPLE_PATH: "{{DOC_PATH}}/examples"
+    installations:
+    - install:
+        source: foo.example
+        dest-dir: "{{EXAMPLE_PATH}}"
+    """
+    )
+
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    resolved = manifest.substitution.substitute("{{EXAMPLE_PATH}}", "test")
+    assert resolved == "/usr/share/doc/foo/examples"
+
+
+def test_parsing_variables_unused(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        f"""\
+    manifest-version: '0.1'
+    definitions:
+      variables:
+        UNUSED: "test"
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        'The variable "UNUSED" is unused. Either use it or remove it.'
+        " The variable was declared at definitions.variables.UNUSED."
+    )
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_parsing_package_foo_empty(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        "The attribute packages.foo must be a non-empty mapping. Please see"
+        " {{DEBPUTY_DOC_ROOT_DIR}}/MANIFEST-FORMAT.md#binary-package-rules for the documentation."
+    )
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_parsing_package_bar_empty(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        bar:
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    assert 'package "bar" is not present' in e_info.value.args[0]
+
+
+def test_transformations_no_list(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              create-symlinks:
+                 path: a
+                 target: b
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    assert "packages.foo.transformations" in e_info.value.args[0]
+    assert "must be a list" in e_info.value.args[0]
+
+
+def test_create_symlinks_missing_path(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  target: b
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        "The following keys were required but not present at packages.foo.transformations[0].create-symlink: 'path'"
+        " (Documentation: "
+        "{{DEBPUTY_DOC_ROOT_DIR}}/MANIFEST-FORMAT.md#create-symlinks-transformation-rule-create-symlink)"
+    )
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_create_symlinks_unknown_replacement_rule(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  path: usr/share/foo
+                  target: /usr/share/bar
+                  replacement-rule: golf
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        'The attribute "packages.foo.transformations[0].create-symlink.replacement-rule <Search for: usr/share/foo>"'
+        " did not have a valid structure/type: Value (golf) must be one of the following literal values:"
+        ' "error-if-exists", "error-if-directory", "abort-on-non-empty-directory", "discard-existing"'
+    )
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_create_symlinks_missing_target(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  path: a
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        "The following keys were required but not present at packages.foo.transformations[0].create-symlink: 'target'"
+        " (Documentation: "
+        "{{DEBPUTY_DOC_ROOT_DIR}}/MANIFEST-FORMAT.md#create-symlinks-transformation-rule-create-symlink)"
+    )
+    assert normalize_doc_link(e_info.value.args[0]) == msg
+
+
+def test_create_symlinks_not_normalized_path(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  path: ../bar
+                  target: b
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    expected = (
+        'The path "../bar" provided in packages.foo.transformations[0].create-symlink.path <Search for: ../bar>'
+        ' should be relative to the root of the package and not use any ".." or "." segments.'
+    )
+    assert e_info.value.args[0] == expected
+
+
+def test_unresolvable_subst_in_source_context(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    installations:
+    - install:
+       source: "foo.sh"
+       as: "usr/bin/{{PACKAGE}}"
+    """
+    )
+
+    with pytest.raises(DebputySubstitutionError) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    expected = (
+        "The variable {{PACKAGE}} is not available while processing installations[0].install.as"
+        " <Search for: foo.sh>."
+    )
+
+    assert e_info.value.args[0] == expected
+
+
+def test_yaml_error_duplicate_key(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  path: ../bar
+                  target: b
+                  # Duplicate key error
+                  path: ../foo
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    assert "duplicate key" in e_info.value.args[0]
+
+
+def test_yaml_error_tab_start(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - create-symlink:
+                  path: ../bar
+                  target: b
+    # Tab is not allowed here in this case.
+    \ta
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    assert "'\\t' that cannot start any token" in e_info.value.args[0]
+
+
+def test_yaml_octal_mode_int(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            transformations:
+              - path-metadata:
+                  path: usr/share/bar
+                  mode: 0755
+    """
+    )
+
+    with pytest.raises(ManifestParseException) as e_info:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+    msg = (
+        'The attribute "packages.foo.transformations[0].path-metadata.mode <Search for: usr/share/bar>" did not'
+        " have a valid structure/type: The attribute must be a FileSystemMode (string)"
+    )
+
+    assert e_info.value.args[0] == msg
+
+
+def test_yaml_clean_after_removal(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            clean-after-removal:
+            - /var/log/foo/*.log
+            - /var/log/foo/*.log.gz
+            - path: /var/log/foo/
+              ignore-non-empty-dir: true
+            - /etc/non-conffile-configuration.conf
+            - path: /var/cache/foo
+              recursive: true
+
+    """
+    )
+
+    manifest_parser_pkg_foo.parse_manifest(fd=content)
+
+
+def test_binary_version(manifest_parser_pkg_foo):
+    content = textwrap.dedent(
+        """\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            binary-version: 1:2.3
+
+    """
+    )
+
+    manifest = manifest_parser_pkg_foo.parse_manifest(fd=content)
+    assert manifest.package_state_for("foo").binary_version == "1:2.3"
+
+
+@pytest.mark.parametrize(
+    "path,is_accepted",
+    [
+        ("usr/bin/foo", False),
+        ("var/cache/foo*", False),
+        ("var/cache/foo", True),
+        ("var/cache/foo/", True),
+        ("var/cache/foo/*", True),
+        ("var/cache/foo/*.*", True),
+        ("var/cache/foo/*.txt", True),
+        ("var/cache/foo/cache.*", True),
+        ("etc/foo*", False),
+        ("etc/foo/*", True),
+        ("etc/foo/", True),
+        # /var/log is special-cased
+        ("/var/log/foo*", True),
+        ("/var/log/foo/*.*", True),
+        ("/var/log/foo/", True),
+        # Unsupported pattern at the time of writing
+        ("/var/log/foo/*.*.*", False),
+        # Questionable rules
+        ("*", False),
+        ("*.la", False),
+        ("*/foo/*", False),
+    ],
+)
+def test_yaml_clean_after_removal_unsafe_path(
+    manifest_parser_pkg_foo,
+    path: str,
+    is_accepted: bool,
+) -> None:
+    content = textwrap.dedent(
+        f"""\
+    manifest-version: '0.1'
+    packages:
+        foo:
+            clean-after-removal:
+            - {path}
+    """
+    )
+
+    if is_accepted:
+        manifest_parser_pkg_foo.parse_manifest(fd=content)
+    else:
+        with pytest.raises(ManifestParseException) as e_info:
+            manifest_parser_pkg_foo.parse_manifest(fd=content)
diff --git a/tests/test_path.py b/tests/test_path.py
new file mode 100644
index 0000000..a9e826e
--- /dev/null
+++ b/tests/test_path.py
@@ -0,0 +1,47 @@
+from typing import cast
+
+import pytest
+
+from debputy.exceptions import SymlinkLoopError
+from debputy.filesystem_scan import VirtualPathBase
+from debputy.plugin.api import virtual_path_def
+from debputy.plugin.api.test_api import build_virtual_file_system
+
+
+def test_symlink_lookup() -> None:
+    fs = build_virtual_file_system(
+        [
+            virtual_path_def("./usr/share/doc/bar", link_target="foo"),
+            "./usr/share/doc/foo/copyright",
+            virtual_path_def("./usr/share/bar/data", link_target="../foo/data"),
+            "./usr/share/foo/data/foo.dat",
+            virtual_path_def("./usr/share/baz/data", link_target="/usr/share/foo/data"),
+            virtual_path_def(
+                "./usr/share/test/loop-a", link_target="/usr/share/test/loop-b"
+            ),
+            virtual_path_def("./usr/share/test/loop-b", link_target="./loop-c"),
+            virtual_path_def("./usr/share/test/loop-c", link_target="../test/loop-a"),
+        ]
+    )
+    assert fs.lookup("/usr/share/doc/bar/copyright") is not None
+    assert fs.lookup("/usr/share/bar/data/foo.dat") is not None
+    assert fs.lookup("/usr/share/baz/data/foo.dat") is not None
+
+    vp_fs: VirtualPathBase = cast("VirtualPathBase", fs)
+    p, missing = vp_fs.attempt_lookup("/usr/share/doc/foo/non-existent")
+    assert p.path == "./usr/share/doc/foo"
+    assert missing == ["non-existent"]
+
+    p, missing = vp_fs.attempt_lookup("/usr/share/bar/data/non-existent")
+    assert p.path == "./usr/share/foo/data"
+    assert missing == ["non-existent"]
+
+    p, missing = vp_fs.attempt_lookup("/usr/share/baz/data/non-existent")
+    assert p.path == "./usr/share/foo/data"
+    assert missing == ["non-existent"]
+
+    # The symlink can be looked up
+    assert fs.lookup("./usr/share/test/loop-a") is not None
+    with pytest.raises(SymlinkLoopError):
+        # But resolving it will cause issues
+        fs.lookup("./usr/share/test/loop-a/")
diff --git a/tests/test_plugin_tester.py b/tests/test_plugin_tester.py
new file mode 100644
index 0000000..8078a02
--- /dev/null
+++ b/tests/test_plugin_tester.py
@@ -0,0 +1,285 @@
+import json
+import os.path
+from typing import List, Tuple, Type, cast
+
+import pytest
+
+from debputy.exceptions import DebputyFSIsROError
+from debputy.plugin.api import (
+    DebputyPluginInitializer,
+    BinaryCtrlAccessor,
+    PackageProcessingContext,
+    VirtualPath,
+    virtual_path_def,
+)
+from debputy.exceptions import PluginConflictError, PluginAPIViolationError
+from debputy.plugin.api.impl import DebputyPluginInitializerProvider
+from debputy.plugin.api.impl_types import automatic_discard_rule_example
+from debputy.plugin.api.test_api import (
+    build_virtual_file_system,
+    package_metadata_context,
+    initialize_plugin_under_test,
+)
+from debputy.plugin.api.test_api.test_impl import (
+    initialize_plugin_under_test_preloaded,
+    initialize_plugin_under_test_from_inline_json,
+)
+
+CUSTOM_PLUGIN_JSON_FILE = os.path.join(
+    os.path.dirname(__file__), "data", "custom-plugin.json.in"
+)
+
+
+def bad_metadata_detector_fs_rw(
+    path: VirtualPath,
+    _ctrl: BinaryCtrlAccessor,
+    _context: PackageProcessingContext,
+) -> None:
+    del path["foo"]
+
+
+def conflicting_plugin(api: DebputyPluginInitializer) -> None:
+    api.packager_provided_file(
+        "logrotate",
+        "/some/where/that/is/not/etc/logrotate.d/{name}",
+    )
+
+
+def bad_plugin(api: DebputyPluginInitializer) -> None:
+    api.metadata_or_maintscript_detector("fs_rw", bad_metadata_detector_fs_rw)
+
+
+def adr_inconsistent_example_plugin(api: DebputyPluginInitializerProvider) -> None:
+    api.automatic_discard_rule(
+        "adr-example-test",
+        lambda p: p.name == "discard-me",
+        examples=automatic_discard_rule_example(
+            "foo/discard-me",
+            ("bar/discard-me", False),
+            "baz/something",
+            ("discard-me/foo", False),
+        ),
+    )
+
+
+def test_conflict_with_debputy():
+    with pytest.raises(PluginConflictError) as e_info:
+        initialize_plugin_under_test_preloaded(
+            1,
+            conflicting_plugin,
+            plugin_name="conflicting-plugin",
+        )
+    message = (
+        'The stem "logrotate" is registered twice for packager provided files.'
+        " Once by debputy and once by conflicting-plugin"
+    )
+    assert message == e_info.value.args[0]
+
+
+def test_metadata_read_only():
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        bad_plugin,
+        plugin_name="bad-plugin",
+    )
+    fs = build_virtual_file_system(["./foo"])
+    with pytest.raises(PluginAPIViolationError) as e_info:
+        plugin.run_metadata_detector("fs_rw", fs)
+
+    assert isinstance(e_info.value.__cause__, DebputyFSIsROError)
+
+
+def test_packager_provided_files():
+    plugin = initialize_plugin_under_test(plugin_desc_file=CUSTOM_PLUGIN_JSON_FILE)
+    assert plugin.packager_provided_files_by_stem().keys() == {
+        "my-file",
+        "test-file-from-json",
+    }
+    my_file = [p for p in plugin.packager_provided_files() if p.stem == "my-file"][0]
+
+    assert my_file.stem == "my-file"
+    assert my_file.compute_dest("g++-3.1")[1] == "g__-3.1.conf"
+
+
+def test_path_checks():
+    symlink_path = "./foo"
+    with pytest.raises(ValueError) as e_info:
+        virtual_path_def(symlink_path, link_target="/bar", mode=0o0755)
+    assert (
+        e_info.value.args[0]
+        == f'Please do not provide mode for symlinks. Triggered by "{symlink_path}"'
+    )
+    with pytest.raises(ValueError) as e_info:
+        virtual_path_def(symlink_path + "/", link_target="/bar")
+    msg = (
+        "Path name looks like a directory, but a symlink target was also provided."
+        f' Please remove the trailing slash OR the symlink_target. Triggered by "{symlink_path}/"'
+    )
+    assert e_info.value.args[0] == msg
+
+
+def test_metadata_detector_applies_to_check():
+    plugin_name = "custom-plugin"
+    metadata_detector_id = "udeb-only"
+    plugin = initialize_plugin_under_test(plugin_desc_file=CUSTOM_PLUGIN_JSON_FILE)
+    with pytest.raises(ValueError) as e_info:
+        plugin.run_metadata_detector(
+            metadata_detector_id,
+            build_virtual_file_system(["./usr/share/doc/foo/copyright"]),
+        )
+    msg = f'The detector "{metadata_detector_id}" from {plugin_name} does not apply to the given package.'
+    assert e_info.value.args[0].startswith(msg)
+
+    metadata = plugin.run_metadata_detector(
+        metadata_detector_id,
+        build_virtual_file_system(["./usr/share/doc/foo/copyright"]),
+        context=package_metadata_context(package_fields={"Package-Type": "udeb"}),
+    )
+    assert metadata.substvars["Test:Udeb-Metadata-Detector"] == "was-run"
+
+
+@pytest.mark.parametrize(
+    "variables,exec_type",
+    [
+        (
+            [("DEBPUTY_VAR", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("_DEBPUTY_VAR", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("_FOO", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("path:_var", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("path:DEBPUTY_VAR", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("DEB_VAR", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("DPKG_VAR", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("PACKAGE", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("foo:var", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("env:var", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("SOURCE_DATE_EPOCH", "RESERVED")],
+            ValueError,
+        ),
+        (
+            [("!MY_VAR", "INVALID_NAME")],
+            ValueError,
+        ),
+        (
+            [("VALUE_DEPENDS_ON_VAR", "{{UNKNOWN_VAR}}")],
+            ValueError,
+        ),
+        (
+            [("VALUE_DEPENDS_ON_VAR", "{{DEB_HOST_ARCH}}")],
+            ValueError,
+        ),
+        (
+            [("DEFINED_TWICE", "ONCE"), ("DEFINED_TWICE", "TWICE")],
+            PluginConflictError,
+        ),
+    ],
+)
+def test_invalid_manifest_variables(
+    variables: List[Tuple[str, str]],
+    exec_type: Type[Exception],
+) -> None:
+    def _initializer(api: DebputyPluginInitializer):
+        with pytest.raises(exec_type):
+            for varname, value in variables:
+                api.manifest_variable(varname, value)
+
+    initialize_plugin_under_test_preloaded(
+        1,
+        _initializer,
+        plugin_name="test-plugin",
+        load_debputy_plugin=False,
+    )
+
+
+def test_valid_manifest_variables() -> None:
+    variables = {
+        "PLUGIN_VAR": "TEST VALUE",
+        "ANOTHER_PLUGIN_VAR": "ANOTHER VALUE",
+        "path:SOMEWHERE_DIR": "/usr/share/some-where",
+    }
+
+    def _initializer(api: DebputyPluginInitializer):
+        for k, v in variables.items():
+            api.manifest_variable(k, v)
+
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        _initializer,
+        plugin_name="test-plugin",
+        load_debputy_plugin=False,
+    )
+
+    assert plugin.declared_manifest_variables == variables.keys()
+
+
+def test_valid_manifest_variables_json() -> None:
+    variables = {
+        "PLUGIN_VAR": "TEST VALUE",
+        "ANOTHER_PLUGIN_VAR": "ANOTHER VALUE",
+        "path:SOMEWHERE_DIR": "/usr/share/some-where",
+    }
+    content = {
+        "api-compat-version": 1,
+        "manifest-variables": [
+            {
+                "name": k,
+                "value": v,
+            }
+            for k, v in variables.items()
+        ],
+    }
+    plugin = initialize_plugin_under_test_from_inline_json(
+        "test-plugin",
+        json.dumps(content),
+    )
+    assert plugin.declared_manifest_variables == variables.keys()
+
+
+def test_automatic_discard_rules_example() -> None:
+    plugin = initialize_plugin_under_test_preloaded(
+        1,
+        # Internal API used
+        cast("PluginInitializationEntryPoint", adr_inconsistent_example_plugin),
+        # API is restricted
+        plugin_name="debputy",
+        load_debputy_plugin=False,
+    )
+    issues = plugin.automatic_discard_rules_examples_with_issues()
+    assert len(issues) == 1
+    issue = issues[0]
+    assert issue.name == "adr-example-test"
+    assert issue.example_index == 0
+    assert set(issue.inconsistent_paths) == {
+        "/discard-me/foo",
+        "/bar/discard-me",
+        "/baz/something",
+    }
diff --git a/tests/test_substitute.py b/tests/test_substitute.py
new file mode 100644
index 0000000..a83cc7f
--- /dev/null
+++ b/tests/test_substitute.py
@@ -0,0 +1,66 @@
+import pytest
+
+from debputy.architecture_support import faked_arch_table
+from debputy.dh_migration.models import (
+    DHMigrationSubstitution,
+    AcceptableMigrationIssues,
+    FeatureMigration,
+)
+from debputy.filesystem_scan import FSROOverlay
+from debputy.highlevel_manifest import MutableYAMLManifest
+from debputy.substitution import SubstitutionImpl, VariableContext
+
+MOCK_ENV = {
+    # This conflicts with the dpkg arch table intentionally (to ensure we can tell which one is being resolved)
+    "DEB_HOST_ARCHITECTURE": "i386",
+}
+MOCK_DPKG_ARCH_TABLE = faked_arch_table("amd64", build_arch="i386")
+MOCK_VARIABLE_CONTEXT = VariableContext(FSROOverlay.create_root_dir("debian", "debian"))
+
+
+@pytest.mark.parametrize(
+    "value,expected",
+    [
+        (
+            "unchanged",
+            "unchanged",
+        ),
+        (
+            "unchanged\\{{\n}}",
+            "unchanged\\{{\n}}",
+        ),  # Newline is not an allowed part of a substitution
+        (
+            "{{token:DOUBLE_OPEN_CURLY_BRACE}}{{token:NL}}{{token:DOUBLE_CLOSE_CURLY_BRACE}}",
+            "{{\n}}",
+        ),
+        (
+            "{{token:DOUBLE_OPEN_CURLY_BRACE}}token:TAB}}{{token:TAB{{token:DOUBLE_CLOSE_CURLY_BRACE}}",
+            "{{token:TAB}}{{token:TAB}}",
+        ),
+        (
+            "/usr/lib/{{DEB_HOST_MULTIARCH}}",
+            f'/usr/lib/{MOCK_DPKG_ARCH_TABLE["DEB_HOST_MULTIARCH"]}',
+        ),
+    ],
+)
+def test_substitution_match(debputy_plugin_feature_set, value, expected) -> None:
+    subst = SubstitutionImpl(
+        plugin_feature_set=debputy_plugin_feature_set,
+        dpkg_arch_table=MOCK_DPKG_ARCH_TABLE,
+        environment=MOCK_ENV,
+        variable_context=MOCK_VARIABLE_CONTEXT,
+    )
+    replacement = subst.substitute(value, "test def")
+    assert replacement == expected
+
+
+def test_migrate_substitution() -> None:
+    feature_migration = FeatureMigration("test migration")
+    subst = DHMigrationSubstitution(
+        MOCK_DPKG_ARCH_TABLE,
+        AcceptableMigrationIssues(frozenset()),
+        feature_migration,
+        MutableYAMLManifest({}),
+    )
+    replacement = subst.substitute("usr/lib/${DEB_HOST_MULTIARCH}/foo", "test def")
+    assert replacement == "usr/lib/{{DEB_HOST_MULTIARCH}}/foo"
diff --git a/tests/test_symbolic_mode.py b/tests/test_symbolic_mode.py
new file mode 100644
index 0000000..a0ad81d
--- /dev/null
+++ b/tests/test_symbolic_mode.py
@@ -0,0 +1,25 @@
+import pytest
+
+from debputy.manifest_parser.base_types import SymbolicMode
+
+
+@pytest.mark.parametrize(
+    "base_mode,is_dir,symbolic_mode,expected",
+    [
+        (0o0644, False, "u+rwX,og=rX", 0o0644),
+        (0o0000, False, "u+rwX,og=rX", 0o0644),
+        (0o0400, True, "u+rwX,og=rX", 0o0755),
+        (0o0000, True, "u+rwX,og=rX", 0o0755),
+        (0o2400, False, "u+rwxs,og=rx", 0o04755),
+        (0o7400, False, "u=rwX,og=rX", 0o0644),
+        (0o0641, False, "u=rwX,og=rX", 0o0755),
+        (0o4755, False, "a-x", 0o04644),
+    ],
+)
+def test_generate_deb_filename(
+    attribute_path, base_mode, is_dir, symbolic_mode, expected
+):
+    print(attribute_path.path)
+    parsed_mode = SymbolicMode.parse_filesystem_mode(symbolic_mode, attribute_path)
+    actual = parsed_mode.compute_mode(base_mode, is_dir)
+    assert oct(actual)[2:] == oct(expected)[2:]
diff --git a/tests/test_symlink_normalization.py b/tests/test_symlink_normalization.py
new file mode 100644
index 0000000..0b11dc8
--- /dev/null
+++ b/tests/test_symlink_normalization.py
@@ -0,0 +1,35 @@
+import pytest
+
+from debputy.util import debian_policy_normalize_symlink_target
+
+
+@pytest.mark.parametrize(
+    "link_path,link_target,expected",
+    [
+        ("usr/share/doc/pkg/my-symlink", "/etc/foo.conf", "/etc/foo.conf"),
+        ("usr/share/doc/pkg/my-symlink", "/usr/share/doc/pkg", "."),
+        ("usr/share/doc/pkg/my-symlink", "/usr/share/doc/pkg/.", "."),
+        ("usr/share/doc/pkg/my-symlink", "/usr/share/bar/../doc/pkg/.", "."),
+        (
+            "usr/share/doc/pkg/my-symlink",
+            "/usr/share/bar/../doc/pkg/../other-pkg",
+            "../other-pkg",
+        ),
+        ("usr/share/doc/pkg/my-symlink", "/usr/share/doc/other-pkg/.", "../other-pkg"),
+        ("usr/share/doc/pkg/my-symlink", "../other-pkg/.", "../other-pkg"),
+        ("usr/share/doc/pkg/my-symlink", "/usr/share/doc/other-pkg", "../other-pkg"),
+        ("usr/share/doc/pkg/my-symlink", "../other-pkg", "../other-pkg"),
+        (
+            "usr/share/doc/pkg/my-symlink",
+            "/usr/share/doc/pkg/../../../../etc/foo.conf",
+            "/etc/foo.conf",
+        ),
+    ],
+)
+def test_symlink_normalization(link_path: str, link_target: str, expected: str) -> None:
+    actual = debian_policy_normalize_symlink_target(
+        link_path,
+        link_target,
+        normalize_link_path=True,
+    )
+    assert actual == expected
diff --git a/tests/tutil.py b/tests/tutil.py
new file mode 100644
index 0000000..9b622b9
--- /dev/null
+++ b/tests/tutil.py
@@ -0,0 +1,66 @@
+from typing import Tuple, Mapping
+
+from debian.deb822 import Deb822
+from debian.debian_support import DpkgArchTable
+
+from debputy.architecture_support import (
+    faked_arch_table,
+    DpkgArchitectureBuildProcessValuesTable,
+)
+from debputy.packages import BinaryPackage
+
+_DPKG_ARCHITECTURE_TABLE_NATIVE_AMD64 = None
+_DPKG_ARCH_QUERY_TABLE = None
+
+
+def faked_binary_package(
+    package, architecture="any", section="misc", is_main_package=False, **fields
+) -> BinaryPackage:
+    _arch_data_tables_loaded()
+
+    dpkg_arch_table, dpkg_arch_query = _arch_data_tables_loaded()
+    return BinaryPackage(
+        Deb822(
+            {
+                "Package": package,
+                "Architecture": architecture,
+                "Section": section,
+                **fields,
+            }
+        ),
+        dpkg_arch_table,
+        dpkg_arch_query,
+        is_main_package=is_main_package,
+    )
+
+
+def binary_package_table(*args: BinaryPackage) -> Mapping[str, BinaryPackage]:
+    packages = list(args)
+    if not any(p.is_main_package for p in args):
+        p = args[0]
+        np = faked_binary_package(
+            p.name,
+            architecture=p.declared_architecture,
+            section=p.archive_section,
+            is_main_package=True,
+            **{
+                k: v
+                for k, v in p.fields.items()
+                if k.lower() not in ("package", "architecture", "section")
+            },
+        )
+        packages[0] = np
+    return {p.name: p for p in packages}
+
+
+def _arch_data_tables_loaded() -> (
+    Tuple[DpkgArchitectureBuildProcessValuesTable, DpkgArchTable]
+):
+    global _DPKG_ARCHITECTURE_TABLE_NATIVE_AMD64
+    global _DPKG_ARCH_QUERY_TABLE
+    if _DPKG_ARCHITECTURE_TABLE_NATIVE_AMD64 is None:
+        _DPKG_ARCHITECTURE_TABLE_NATIVE_AMD64 = faked_arch_table("amd64")
+    if _DPKG_ARCH_QUERY_TABLE is None:
+        # TODO: Make a faked table instead, so we do not have data dependencies in the test.
+        _DPKG_ARCH_QUERY_TABLE = DpkgArchTable.load_arch_table()
+    return _DPKG_ARCHITECTURE_TABLE_NATIVE_AMD64, _DPKG_ARCH_QUERY_TABLE