infralink-ops 0.2.67__tar.gz

infralink_ops-0.2.67/.github/workflows/publish-pypi.yml

@@ -0,0 +1,91 @@
+name: Publish Python package
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing Infralink Ops release tag to publish to TestPyPI
+        required: true
+        type: string
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: refs/tags/${{ github.event.release.tag_name || inputs.tag }}
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install release dependencies
+        env:
+          PIP_EXTRA_INDEX_URL: ${{ github.event_name == 'workflow_dispatch' && 'https://test.pypi.org/simple' || '' }}
+        run: python -m pip install --disable-pip-version-check "twine>=6.0" -e ".[dev]"
+      - name: Verify release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: >-
+          python -c "import os, tomllib;
+          version = tomllib.load(open('pyproject.toml', 'rb'))['project']['version'];
+          actual = os.environ['RELEASE_TAG']; expected = f'v{version}';
+          assert actual == expected, f'release tag {actual!r} must equal {expected!r}'"
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distribution metadata
+        run: python -m twine check dist/*
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/infralink-ops
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/infralink-ops
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

infralink_ops-0.2.67/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.venv/

infralink_ops-0.2.67/.woodpecker.yml

@@ -0,0 +1,56 @@
+steps:
+  docs-contract:
+    image: python:3.12-slim-bookworm
+    commands:
+      - python -m pip install --disable-pip-version-check pytest
+      - python -m pytest -q tests/test_docs_contract.py
+
+  test-python:
+    image: python:3.12-slim-bookworm
+    commands:
+      - sed -i 's|http://deb.debian.org|https://deb.debian.org|g' /etc/apt/sources.list.d/debian.sources
+      - apt-get update && apt-get install --yes --no-install-recommends git && rm -rf /var/lib/apt/lists/*
+      # Infralink is distributed from GitHub rather than a package index. Keep this
+      # CI fixture deterministic while the package declaration admits 0.6.x.
+      - python -m pip install --disable-pip-version-check 'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3'
+      - python -m pip install --disable-pip-version-check -e '.[dev]'
+      - python -m ruff check src tests
+      - python -m ruff format --check src tests
+      - python -m pytest -q
+      - python -m build
+      - python -m venv /tmp/infralink-ops-wheel
+      - /tmp/infralink-ops-wheel/bin/pip install --disable-pip-version-check 'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3'
+      - /tmp/infralink-ops-wheel/bin/pip install --disable-pip-version-check dist/*.whl
+      - cd /tmp && /tmp/infralink-ops-wheel/bin/python -c 'import infralink_ops'
+
+  build-infralink-ops-controller:
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      registry: ghcr.io
+      repo: ghcr.io/cyberstorm-dev/infralink-ops-controller
+      dockerfile: Dockerfile.controller
+      context: .
+      dry_run: true
+      tags:
+        - local-test-${CI_COMMIT_SHA:0:7}
+
+  publish-infralink-ops-controller:
+    image: woodpeckerci/plugin-docker-buildx
+    depends_on:
+      - build-infralink-ops-controller
+    when:
+      - event: push
+        branch: main
+    settings:
+      registry: ghcr.io
+      repo: ghcr.io/cyberstorm-dev/infralink-ops-controller
+      dockerfile: Dockerfile.controller
+      context: .
+      tags:
+        - head
+        - main
+        - sha-${CI_COMMIT_SHA:0:7}
+      username:
+        from_secret: ghcr_username
+      password:
+        from_secret: ghcr_token

infralink_ops-0.2.67/Dockerfile

@@ -0,0 +1,18 @@
+ARG GITEA_IMAGE=gitea/gitea:1.27.2
+ARG GITLEAKS_IMAGE=zricethezav/gitleaks:v8.30.0
+
+FROM ${GITLEAKS_IMAGE} AS gitleaks
+
+FROM ${GITEA_IMAGE}
+
+USER root
+COPY --from=gitleaks /usr/bin/gitleaks /usr/local/bin/gitleaks
+COPY gitea-hooks/pre-receive-gitleaks /usr/local/lib/infralink-gitea-hooks/pre-receive-gitleaks
+COPY gitea-hooks/install-receive-gate /usr/local/lib/infralink-gitea-hooks/install-receive-gate
+COPY gitea-hooks/entrypoint /usr/local/bin/infralink-gitea-entrypoint
+RUN chmod 0755 /usr/local/lib/infralink-gitea-hooks/* \
+    /usr/local/bin/infralink-gitea-entrypoint \
+    && mkdir -p /usr/local/share/infralink-gitea/git-template/hooks/pre-receive.d \
+    && cp /usr/local/lib/infralink-gitea-hooks/pre-receive-gitleaks /usr/local/share/infralink-gitea/git-template/hooks/pre-receive.d/20-infralink-gitleaks \
+    && git config --system init.templateDir /usr/local/share/infralink-gitea/git-template
+ENTRYPOINT ["/usr/local/bin/infralink-gitea-entrypoint"]

infralink_ops-0.2.67/Dockerfile.controller

@@ -0,0 +1,60 @@
+FROM python@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
+
+ARG BWS_VERSION=1.0.0
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN sed -i 's|http://deb.debian.org|https://deb.debian.org|g' /etc/apt/sources.list.d/debian.sources \
+    && apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        gnupg \
+        iptables \
+        jq \
+        lsb-release \
+        nftables \
+        openssh-client \
+        unzip \
+        util-linux \
+        yq \
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg \
+        | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+    && chmod a+r /etc/apt/keyrings/docker.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" \
+        > /etc/apt/sources.list.d/docker.list \
+    && apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends docker-ce-cli docker-compose-plugin \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL "https://github.com/bitwarden/sdk/releases/download/bws-v${BWS_VERSION}/bws-x86_64-unknown-linux-gnu-${BWS_VERSION}.zip" \
+        -o /tmp/bws.zip \
+    && unzip -q /tmp/bws.zip -d /tmp \
+    && install -m 0755 /tmp/bws /usr/local/bin/bws \
+    && rm -f /tmp/bws.zip /tmp/bws
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+# Infralink is not published to a package index; pin the controller build input
+# while pyproject.toml expresses the supported 0.6.x compatibility range.
+RUN python -m pip install --disable-pip-version-check --no-cache-dir \
+        'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3' \
+    && python -m pip install --disable-pip-version-check --no-cache-dir . \
+    && command -v infralink-controller-registry-checkout \
+    && command -v infralink-controller-config-consumers \
+    && command -v infralink-controller-adapter \
+    && command -v infralink-controller-runtime-directories \
+    && command -v infralink-controller-host-interface \
+    && command -v infralink-controller-doctor \
+    && command -v infralink-controller-firewall \
+    && command -v infralink-controller-image-resolution \
+    && command -v infralink-controller-reference \
+    && command -v infralink-controller-template-dependencies
+
+CMD ["infralink-ops", "--help"]

infralink_ops-0.2.67/Dockerfile.ops

@@ -0,0 +1,11 @@
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN python -m pip install --disable-pip-version-check .
+
+ENTRYPOINT ["infralink-ops"]

infralink_ops-0.2.67/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: infralink-ops
+Version: 0.2.67
+Summary: Operational runtime for direct Infralink registry projections
+Requires-Python: >=3.10
+Requires-Dist: infralink<0.7,>=0.6
+Requires-Dist: jinja2>=3.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Infralink Ops
+
+## BLUF
+
+This repo packages the public controller runtime for managed hosts. Deployment
+intent, private templates, and secret aliases remain in the environment
+registry; live-service acceptance remains environment-owned operational state.
+
+Use it when you need bounded host primitives for registry checkout, template
+rendering, config projection, Docker image retention, Compose consumer
+activation, firewall verification, secret rendering, or host doctor evidence.
+
+Do not use this repo to select fleet desired state. Registry revisions, service
+definitions, image pins, hostnames, and secret bindings come from the
+environment registry.
+
+## Reader Paths
+
+| Goal | Start here |
+| --- | --- |
+| Understand the runtime boundary | [Controller runtime guide](docs/controller-runtime-guide.md) |
+| Debug a stale RelayOS staging rollout | [Controller runtime guide](docs/controller-runtime-guide.md#triage-a-stale-host) |
+| Check available CLIs | [`pyproject.toml`](pyproject.toml) |
+| Inspect host-installed launcher assets | [`src/infralink_ops/assets/`](src/infralink_ops/assets/) |
+| Review controller behavior | [`src/infralink_ops/`](src/infralink_ops/) and [`tests/`](tests/) |
+
+## How It Fits
+
+```mermaid
+flowchart LR
+    registry["configured registry revision"] --> checkout["/var/lib/infralink/registry"]
+    checkout --> render["template render and static config projection"]
+    render --> consumers["Compose consumer validate/activate"]
+    consumers --> evidence["doctor, metrics, and logs"]
+    evidence --> operator["environment-owned acceptance"]
+```
+
+This repo implements the bounded primitives in the middle of the flow. It does
+not own the registry data model or the environment-specific acceptance result.
+
+## Main CLIs
+
+| Command | Purpose |
+| --- | --- |
+| `infralink-controller-registry-checkout fetch` | Fetch a declared registry ref into an existing clean checkout. |
+| `infralink-controller-template-render` | Render registry-declared templates from explicit inputs. |
+| `infralink-controller-config-consumers validate\|activate` | Validate or recreate services affected by rendered config changes. |
+| `infralink-controller-images retain-and-prune` | Keep selected immutable Docker images and prune stale cache images. |
+| `infralink-controller-render-secrets` | Resolve registry-declared render-secret bindings through BWS. |
+| `infralink-controller-firewall render\|verify` | Render or verify declared nftables policy. |
+| `infralink-controller-doctor` | Read-only host-runtime check for registry, reconcile, Compose, firewall, and metrics evidence. |
+| `infralink-host doctor\|reconcile\|bootstrap --apply` | Host launcher installed from [`src/infralink_ops/assets/infralink-host`](src/infralink_ops/assets/infralink-host). |
+
+Each command is intentionally narrow. Commands receive explicit inputs and
+return bounded machine-readable envelopes where possible.
+
+## Authority Boundary
+
+| This repo owns | This repo does not own |
+| --- | --- |
+| Controller image build recipe. | Which registry revision a host should run. |
+| Host launcher and systemd unit assets. | Service definitions, hostnames, DNS, certificates, or image pins. |
+| Runtime primitives with bounded inputs and outputs. | Tenant or application policy. |
+| Doctor and evidence helpers. | Live-service acceptance criteria. |
+| BWS resolution primitive. | BWS secret values or registry secret declarations. |
+
+For RelayOS IRC, source/config/image repos feed the registry first:
+
+```mermaid
+flowchart LR
+    deploy["relayos-deploy docs and deploy contract"]
+    config["relayos-irc-config"]
+    modules["custom-modules"]
+    images["relayos-irc-containers"]
+    registry["infra-registry"]
+    ops["infralink-ops controller"]
+    host["managed host"]
+
+    config --> registry
+    modules --> images
+    images --> deploy
+    deploy --> registry
+    registry --> ops
+    ops --> host
+```
+
+## GHCR and BWS
+
+The controller image publishes to
+[cyberstorm-dev packages](https://github.com/orgs/cyberstorm-dev/packages) as
+`ghcr.io/cyberstorm-dev/infralink-ops-controller`.
+
+BWS access is runtime-only. This repo contains the resolver and tests for the
+resolver contract; the token and secret object names belong to the environment
+registry and host runtime.
+
+## Verify Changes
+
+Run the same checks Woodpecker runs:
+
+```bash
+python -m pip install --disable-pip-version-check \
+  'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3'
+python -m pip install --disable-pip-version-check -e '.[dev]'
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m pytest -q
+python -m build
+```
+
+Infralink Ops declares compatibility with Infralink `>=0.6,<0.7`. Until
+Infralink is published to PyPI, bootstrap a released, checksum-pinned wheel
+before installing Ops so a clean environment does not attempt an unavailable
+index resolution.
+
+The controller image publish step runs only on `main` pushes. Pull requests use
+Docker buildx dry-run validation.
+
+## Triage A Stale Host
+
+Check in this order:
+
+1. Confirm the environment selected the intended registry revision.
+2. Confirm `/var/lib/infralink/registry` has the expected checkout.
+3. Run `infralink-host doctor` for read-only host evidence.
+4. Inspect `/var/lib/infralink/reconcile-result.yml` as the last reconcile
+   result, not as desired state.
+5. Check whether `infralink-host-reconcile.timer` ran after the registry change.
+6. Check rendered files under `/opt/services/config`.
+7. Check the affected Compose service or application-specific behavior.
+
+Do not repair desired-state drift by editing `/opt/services` directly. Fix the
+registry or source repo that owns the value, then let the controller reconcile.
+
+## Development Contract
+
+- Keep commands agent-friendly: explicit inputs, bounded output, stable exit
+  behavior, and machine-readable evidence.
+- Keep provider-specific policy out of generic primitives unless the command
+  name says it is provider-specific.
+- Add tests for every command contract, runtime boundary, and failure mode.
+- Keep README-level docs focused on operator entrypoints; put command-specific
+  details in focused guides or tests.

infralink_ops-0.2.67/README.md

@@ -0,0 +1,143 @@
+# Infralink Ops
+
+## BLUF
+
+This repo packages the public controller runtime for managed hosts. Deployment
+intent, private templates, and secret aliases remain in the environment
+registry; live-service acceptance remains environment-owned operational state.
+
+Use it when you need bounded host primitives for registry checkout, template
+rendering, config projection, Docker image retention, Compose consumer
+activation, firewall verification, secret rendering, or host doctor evidence.
+
+Do not use this repo to select fleet desired state. Registry revisions, service
+definitions, image pins, hostnames, and secret bindings come from the
+environment registry.
+
+## Reader Paths
+
+| Goal | Start here |
+| --- | --- |
+| Understand the runtime boundary | [Controller runtime guide](docs/controller-runtime-guide.md) |
+| Debug a stale RelayOS staging rollout | [Controller runtime guide](docs/controller-runtime-guide.md#triage-a-stale-host) |
+| Check available CLIs | [`pyproject.toml`](pyproject.toml) |
+| Inspect host-installed launcher assets | [`src/infralink_ops/assets/`](src/infralink_ops/assets/) |
+| Review controller behavior | [`src/infralink_ops/`](src/infralink_ops/) and [`tests/`](tests/) |
+
+## How It Fits
+
+```mermaid
+flowchart LR
+    registry["configured registry revision"] --> checkout["/var/lib/infralink/registry"]
+    checkout --> render["template render and static config projection"]
+    render --> consumers["Compose consumer validate/activate"]
+    consumers --> evidence["doctor, metrics, and logs"]
+    evidence --> operator["environment-owned acceptance"]
+```
+
+This repo implements the bounded primitives in the middle of the flow. It does
+not own the registry data model or the environment-specific acceptance result.
+
+## Main CLIs
+
+| Command | Purpose |
+| --- | --- |
+| `infralink-controller-registry-checkout fetch` | Fetch a declared registry ref into an existing clean checkout. |
+| `infralink-controller-template-render` | Render registry-declared templates from explicit inputs. |
+| `infralink-controller-config-consumers validate\|activate` | Validate or recreate services affected by rendered config changes. |
+| `infralink-controller-images retain-and-prune` | Keep selected immutable Docker images and prune stale cache images. |
+| `infralink-controller-render-secrets` | Resolve registry-declared render-secret bindings through BWS. |
+| `infralink-controller-firewall render\|verify` | Render or verify declared nftables policy. |
+| `infralink-controller-doctor` | Read-only host-runtime check for registry, reconcile, Compose, firewall, and metrics evidence. |
+| `infralink-host doctor\|reconcile\|bootstrap --apply` | Host launcher installed from [`src/infralink_ops/assets/infralink-host`](src/infralink_ops/assets/infralink-host). |
+
+Each command is intentionally narrow. Commands receive explicit inputs and
+return bounded machine-readable envelopes where possible.
+
+## Authority Boundary
+
+| This repo owns | This repo does not own |
+| --- | --- |
+| Controller image build recipe. | Which registry revision a host should run. |
+| Host launcher and systemd unit assets. | Service definitions, hostnames, DNS, certificates, or image pins. |
+| Runtime primitives with bounded inputs and outputs. | Tenant or application policy. |
+| Doctor and evidence helpers. | Live-service acceptance criteria. |
+| BWS resolution primitive. | BWS secret values or registry secret declarations. |
+
+For RelayOS IRC, source/config/image repos feed the registry first:
+
+```mermaid
+flowchart LR
+    deploy["relayos-deploy docs and deploy contract"]
+    config["relayos-irc-config"]
+    modules["custom-modules"]
+    images["relayos-irc-containers"]
+    registry["infra-registry"]
+    ops["infralink-ops controller"]
+    host["managed host"]
+
+    config --> registry
+    modules --> images
+    images --> deploy
+    deploy --> registry
+    registry --> ops
+    ops --> host
+```
+
+## GHCR and BWS
+
+The controller image publishes to
+[cyberstorm-dev packages](https://github.com/orgs/cyberstorm-dev/packages) as
+`ghcr.io/cyberstorm-dev/infralink-ops-controller`.
+
+BWS access is runtime-only. This repo contains the resolver and tests for the
+resolver contract; the token and secret object names belong to the environment
+registry and host runtime.
+
+## Verify Changes
+
+Run the same checks Woodpecker runs:
+
+```bash
+python -m pip install --disable-pip-version-check \
+  'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3'
+python -m pip install --disable-pip-version-check -e '.[dev]'
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m pytest -q
+python -m build
+```
+
+Infralink Ops declares compatibility with Infralink `>=0.6,<0.7`. Until
+Infralink is published to PyPI, bootstrap a released, checksum-pinned wheel
+before installing Ops so a clean environment does not attempt an unavailable
+index resolution.
+
+The controller image publish step runs only on `main` pushes. Pull requests use
+Docker buildx dry-run validation.
+
+## Triage A Stale Host
+
+Check in this order:
+
+1. Confirm the environment selected the intended registry revision.
+2. Confirm `/var/lib/infralink/registry` has the expected checkout.
+3. Run `infralink-host doctor` for read-only host evidence.
+4. Inspect `/var/lib/infralink/reconcile-result.yml` as the last reconcile
+   result, not as desired state.
+5. Check whether `infralink-host-reconcile.timer` ran after the registry change.
+6. Check rendered files under `/opt/services/config`.
+7. Check the affected Compose service or application-specific behavior.
+
+Do not repair desired-state drift by editing `/opt/services` directly. Fix the
+registry or source repo that owns the value, then let the controller reconcile.
+
+## Development Contract
+
+- Keep commands agent-friendly: explicit inputs, bounded output, stable exit
+  behavior, and machine-readable evidence.
+- Keep provider-specific policy out of generic primitives unless the command
+  name says it is provider-specific.
+- Add tests for every command contract, runtime boundary, and failure mode.
+- Keep README-level docs focused on operator entrypoints; put command-specific
+  details in focused guides or tests.

infralink_ops-0.2.67/docs/controller-runtime-guide.md

@@ -0,0 +1,72 @@
+# Infralink Ops controller runtime guide
+
+## BLUF
+
+Use this guide to understand what the host controller can do and what
+evidence it can produce.
+
+The controller applies a registry revision that another layer selected. It does
+not choose tenant config, image digests, secrets, DNS, or service policy.
+
+## Runtime Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Registry as Registry declaration
+    participant Host as infralink-host-reconcile.timer
+    participant Checkout as /var/lib/infralink/registry
+    participant Render as Template and config projection
+    participant Compose as Compose consumers
+    participant Evidence as Doctor and metrics
+
+    Registry->>Host: configured revision and controller image
+    Host->>Checkout: fetch explicit ref
+    Host->>Render: render templates and materialize config trees
+    Render->>Compose: validate affected consumers
+    Compose->>Compose: activate changed services
+    Compose->>Evidence: publish reconcile result
+```
+
+## Controller Primitives
+
+| Primitive | Command | Evidence |
+| --- | --- | --- |
+| Registry checkout | `infralink-controller-registry-checkout fetch` | Detached registry revision. |
+| Template rendering | `infralink-controller-template-render` | Rendered files from explicit inputs. |
+| Static config trees | `materialize_config_tree` | Changed paths below the declared target. |
+| Compose consumers | `infralink-controller-config-consumers validate\|activate` | Affected consumers and services. |
+| Image retention | `infralink-controller-images retain-and-prune` | Selected immutable image retained; stale cache images pruned. |
+| Secrets | `infralink-controller-render-secrets` | BWS-backed rendered values without committing secrets. |
+| Firewall | `infralink-controller-firewall render\|verify` | Declared nftables table or runtime drift result. |
+| Doctor | `infralink-controller-doctor` | Read-only host consistency envelope. |
+
+## BWS Contract
+
+The controller can resolve registry-declared BWS bindings at runtime. It must
+not commit secret values, print tokens, or infer undeclared secret names.
+
+Failure to resolve BWS is a registry/runtime failure. Do not fix it by hardcoding
+a value into source, rendered config, or a Compose file.
+
+## GHCR Contract
+
+Woodpecker publishes the controller image to
+[cyberstorm-dev packages](https://github.com/orgs/cyberstorm-dev/packages) as
+`ghcr.io/cyberstorm-dev/infralink-ops-controller` on `main` pushes.
+
+Use immutable `sha-<short-sha>` tags or digests for evidence. Do not use `head` or `main` as acceptance evidence.
+
+## Triage A Stale Host
+
+1. Confirm the registry revision that the environment intended to run.
+2. Confirm `/var/lib/infralink/registry` resolved to that revision.
+3. Run `infralink-host doctor`.
+4. Check `systemctl status infralink-host-reconcile.timer`.
+5. Inspect `/var/lib/infralink/reconcile-result.yml` for the last reconcile
+   evidence.
+6. Inspect rendered files under `/opt/services/config`.
+7. Check the live service using environment-owned acceptance criteria.
+
+If evidence points to a wrong source value, fix the owning source repository or
+registry declaration. If evidence points to controller behavior, fix this repo
+with tests and publish a new controller image.