@homeflare/alchemy 0.24.0 → 0.25.1

package/docs/paperless.md

@@ -0,0 +1,115 @@
+# Paperless — `@homeflare/alchemy/paperless`
+
+Four resources — `Paperless.Tag`, `Paperless.DocumentType`, `Paperless.StoragePath`,
+`Paperless.CustomField` — the taxonomy Paperless-ngx writes through Django's internal models,
+create-or-update and never deleted by default. Workflows and mail accounts are a later slice.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props:
+
+| variable          | holds                                                     |
+| ----------------- | --------------------------------------------------------- |
+| `PAPERLESS_URL`   | the instance origin, e.g. `https://paperless.example.com` |
+| `PAPERLESS_TOKEN` | a scoped Paperless-ngx API token                          |
+
+⛔ **Neither has a default.** A package that fell back to a loopback address would let a consumer
+who forgot the variable watch every call fail against a machine that is not theirs.
+
+⚠️ **`Authorization: Token <value>`, not `Bearer`** — Paperless-ngx's own `securitySchemes`
+states the "Token" prefix explicitly.
+
+⚠️ **Every call carries `Accept: application/json; version=10`**, pinned to the API version this
+family was walked against (`REST_FRAMEWORK.DEFAULT_VERSION` at v3.1.1). An estate upgrade that
+moves the default cannot silently change what this package receives without that assertion
+failing first.
+
+## Every create carries `owner`, null when undeclared
+
+🔴 **This is the one behaviour that had to be measured, not guessed.**
+`OwnedObjectSerializer.create` (Paperless-ngx `documents/serialisers.py:495-502` at v3.1.1) sets
+the owner to the TOKEN USER whenever the field is absent from the body. Omitting an undeclared
+prop the way you might expect — `Netbox.Prefix`'s pattern for an undeclared foreign key — would
+silently create an object owned by whichever credential ran the deploy: invisible to every other
+user, and a second row beside the estate's `owner: null` one on the next apply. So `Tag`,
+`DocumentType` and `StoragePath` always send `owner: null` unless `owner` is declared.
+
+⛔ `Paperless.CustomField` has **no owner field at all** — its wire body is exactly `{name,
+data_type, extra_data}`, measured against the schema. It is not `OwnedObjectSerializer`-based.
+
+## Adopt is never silent (H1)
+
+★ **`read` answers `Unowned(attrs)` on every match**, never plain attributes. Paperless has no
+ownership marker this package can check — `owner` is the estate's own prop, not proof of who
+created a row — so, per the house's 2026-09-21 decision, identical is not ours. `--adopt` (or
+`.pipe(adopt(true))`) is required to bind an existing tag, document type, storage path or custom
+field, the same posture as any other marker-less API.
+
+## `CustomField.dataType` is create-only
+
+⛔ **A change is refused at plan time, never a PATCH and never a replace.** Changing a custom
+field's data type in Paperless deletes that field's value on every document that carries it — a
+replace (delete + recreate) is exactly as destructive as a PATCH would be, just under a different
+name. Declaring a different `dataType` against a live object fails the plan with both values
+named; retire the old field and create a new one instead.
+
+⚠️ The reconciler this family replaces asserted "Paperless forbids a data_type change" — that
+claim is **unverified** at v3.1.1 (`CustomFieldSerializer.validate` and `CustomFieldViewSet`
+contain no such refusal). This package refuses the change regardless, because the destructive
+side effect is real whether or not the vendor also refuses it.
+
+## Removal is `retain`
+
+Every family defaults to `retain` — a tag, document type, storage path or custom field id is
+referenced by every document that carries it, and Paperless does not offer a "detach first"
+option. `delete` is fully implemented; dropping a declaration does not delete the object unless
+the caller opts into `.pipe(RemovalPolicy.destroy())`.
+
+## Locate is by name only before there is state; identity is the stored id after
+
+`MatchingModel` (Paperless-ngx `models.py:79-89`) has `UniqueConstraint(name, owner)` plus a
+unique name where owner is null. Before a declaration has ever been deployed — a genuine first
+create, or the engine's own `--adopt` probe — `matching.ts` locates candidates with a
+case-insensitive `name__iexact` filter, wide enough to see every case-variant Paperless holds,
+and then narrows to the exact-case, exact-owner row in this process (the same locate-then-identify
+split `Netbox.Prefix` uses for its VRF). A locate that matches more than the 20-row page it reads
+is refused as "not a natural key".
+
+⛔ **Once a declaration has state, identity is the stored numeric id, not `(name, owner)`.**
+Renaming a tag, or re-owning any of the three owned families, is an ordinary edit — and locating
+by the _new_ name/owner would miss the row this declaration already wrote, PATCHing nothing and
+POSTing a second object under the new name while the original sat there permanently orphaned
+(`list()` always answers `[]` by design, so `nuke` can never find it either). `diff`/`reconcile`
+locate by the id Alchemy's engine already has on hand (`output.id`) instead: a changed name/owner
+becomes an in-place PATCH of that same id — Paperless allows renaming all four types by PATCH, and
+every document keeps its tag/type/path/field because the id never changes. If that id no longer
+exists live (deleted out of band), the plan refuses loudly rather than silently creating a
+replacement; adopt the live object back or drop it from state first.
+
+`destroy` locates the same way — by `output.id` once state exists, so a row renamed out of band
+after its last deploy is still found and deleted by id rather than silently missed by a
+now-stale name. Unlike `diff`/`reconcile`, a missing `output.id` at delete time is not a refusal:
+the object being already gone is exactly the idempotent success `delete` reports.
+
+## Generated, not hand-typed
+
+`generated/types/*.ts` and `generated/constraints/*.ts` come from `bun codegen/paperless.ts`
+against Paperless-ngx 3.1.1's own served OpenAPI document — see
+[`codegen/paperless.md`](../../../codegen/paperless.md) for the full provenance chain. A prop's
+enum-shaped fields (`matchingAlgorithm`, `dataType`) are typed by indexing into the generated
+request interface (`PaperlessTagRequest['matching_algorithm']`), never retyped by hand.
+
+## Usage
+
+```ts
+import { paperlessProviders, Tag } from '@homeflare/alchemy/paperless';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+// PAPERLESS_URL and PAPERLESS_TOKEN in the deploy's environment.
+export default async () => {
+  const app = await alchemy('paperless-taxonomy');
+  const invoices = await Tag('invoices', { name: 'Invoices', color: '#a6cee3' });
+  await app.finalize();
+};
+// wire the stack: Layer.mergeAll(paperlessProviders(), …).pipe(Layer.provide(FetchHttpClient.layer))
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -68,6 +68,10 @@
       "types": "./dist/linux/index.d.ts",
       "default": "./dist/linux/index.js"
     },
+    "./paperless": {
+      "types": "./dist/paperless/index.d.ts",
+      "default": "./dist/paperless/index.js"
+    },
     "./release": {
       "types": "./dist/release/index.d.ts",
       "default": "./dist/release/index.js"

package/src/linux/fake-linux-host.ts

@@ -185,6 +185,8 @@ export const fakeLinuxHost = (options: FakeLinuxOptions = {}) => {
       enabled: state.enabled ?? false,
       loadedSha: state.loadedSha === undefined ? digest(text) : state.loadedSha,
       ...(state.masked === undefined ? {} : { masked: state.masked }),
+      ...(state.activeState === undefined ? {} : { activeState: state.activeState }),
+      ...(state.subState === undefined ? {} : { subState: state.subState }),
     });
   };
 

package/src/linux/fake-systemd.ts

@@ -15,6 +15,21 @@ export type UnitState = {
   active: boolean;
   enabled: boolean;
   masked?: boolean;
+  /**
+   * Force `ActiveState` to a value `start`/`stop`/`restart` below never produce, for tests: a
+   * timer-driven oneshot mid-run (`activating`, `active` left `false`) or a crashed unit (`failed`).
+   * ⚠️ REASONED NOT MEASURED — a synthetic override to exercise unit-form.ts's `isUnitRunning`
+   *   exactly, not a systemd state-machine model; see fake-linux-host.ts's `placeUnit`.
+   */
+  activeState?: 'activating' | 'failed';
+  /**
+   * Force `SubState` independent of the default derived from `activeState` — `'start'` is already
+   * the default for `activeState: 'activating'` and is accepted here only so a test can say so
+   * explicitly. Systemd's crash-restart backoff (`auto-restart` / `auto-restart-queued`, both still
+   * `ActiveState=activating` — systemd's `service.c` `state_translation_table`) needs
+   * `activeState: 'activating'` ABOVE plus one of these, to tell it apart from a genuine start.
+   */
+  subState?: 'start' | 'auto-restart' | 'auto-restart-queued';
 };
 
 export type FakeSystemdDeps = {
@@ -45,12 +60,24 @@ export const fakeSystemd = (deps: FakeSystemdDeps) => {
       if (deps.failShow) return fail(1, 'Failed to connect to bus: No such file');
       const known = state !== undefined || onDisk !== undefined;
       const loaded = state?.loadedSha !== undefined;
+      // ★ `activeState`/`subState` (above) override the plain active/inactive read for a state
+      //   start/stop/restart never produce on their own — see `UnitState.activeState`.
+      const activeState = state?.activeState ?? (state?.active === true ? 'active' : 'inactive');
+      const subState =
+        state?.subState ??
+        (activeState === 'activating'
+          ? 'start'
+          : activeState === 'failed'
+            ? 'failed'
+            : activeState === 'active'
+              ? 'running'
+              : 'dead');
       return ok(
         [
           `Id=${name}`,
           `LoadState=${state?.masked === true ? 'masked' : known && loaded ? 'loaded' : 'not-found'}`,
-          `ActiveState=${state?.active === true ? 'active' : 'inactive'}`,
-          `SubState=${state?.active === true ? 'running' : 'dead'}`,
+          `ActiveState=${activeState}`,
+          `SubState=${subState}`,
           `UnitFileState=${state?.masked === true ? 'masked' : onDisk === undefined ? '' : state?.enabled === true ? 'enabled' : 'disabled'}`,
           `FragmentPath=${onDisk === undefined ? '' : deps.pathOf(name)}`,
           `NeedDaemonReload=${onDisk !== undefined && state?.loadedSha !== deps.digest(onDisk) && loaded ? 'yes' : 'no'}`,
@@ -92,10 +119,17 @@ export const fakeSystemd = (deps: FakeSystemdDeps) => {
     }
     if (verb === 'start' || verb === 'restart') {
       current.active = true;
+      // ★ A real start/restart leaves whatever synthetic `activating`/`auto-restart` snapshot a
+      //   test placed and lands the unit in an ordinary `active` — the override does not survive
+      //   an actual systemctl action, any more than it would on a real host.
+      delete current.activeState;
+      delete current.subState;
       return ok();
     }
     if (verb === 'stop') {
       current.active = false;
+      delete current.activeState;
+      delete current.subState;
       return ok();
     }
     return fail(64, `fake systemctl: unsupported ${args.join(' ')}`);

package/src/linux/unit-activating.test.ts

@@ -0,0 +1,164 @@
+/**
+ * `started: false` against a unit that is `ActiveState=activating` — the timer-driven `Type=oneshot`
+ * scenario `isUnitRunning` (unit-form.ts) exists for, and the crash-restart (`auto-restart`)
+ * `SubState` that scenario must not be confused with. Split from unit-lifecycle.test.ts to stay
+ * under this file's line cap; see that file for the rest of the family's behaviour.
+ *
+ * ⛔ THE BUG THIS GUARDS: before `isUnitRunning`, `diffUnit` read `ActiveState=activating` on a
+ *   `started: false` unit as drift and planned `update`; `settle` then called `systemctl stop` on a
+ *   check that was already running, mid-run, driven by its own `.timer`. A redeploy must plan to
+ *   nothing while the run is in progress — these tests are that redeploy.
+ * ⛔ THE SECOND BUG THAT ALMOST SHIPPED WITH THE FIRST FIX: an `activating` unit whose `SubState`
+ *   is `auto-restart` (or `auto-restart-queued`) is systemd's crash-restart backoff, not a start —
+ *   see isUnitRunning's own comment. A `started: false` unit that is crash-looping must still be
+ *   stopped; the "auto-restart backoff is still drift" test below is that case.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { type SystemdUnitProps, isUnitRunning, renderUnit } from './unit-form.ts';
+import { diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-node-check.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+/** ⛔ No `[Install]`: a timer-driven oneshot is `enabled: false` — its `.timer` starts it, not `systemctl enable`. */
+const content = renderUnit([
+  { lines: [['Description', 'a PVE node check']], name: 'Unit' },
+  {
+    lines: [
+      ['Type', 'oneshot'],
+      ['ExecStart', '/usr/bin/check-node'],
+    ],
+    name: 'Service',
+  },
+]);
+const props: SystemdUnitProps = { content, enabled: false, name: NAME, started: false };
+const host = () => fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+const verbs = (calls: string[][]) =>
+  calls.filter((call) => call[0] === 'systemctl').map((call) => call[1]);
+
+/** `readUnit` narrowed to defined, so callers can pass it straight to diffUnit/reconcileUnit. */
+const outputFor = async (fake: ReturnType<typeof host>, of: SystemdUnitProps) => {
+  const found = await readUnit(fake.runner, of);
+  if (found === undefined) throw new Error(`${of.name} not found on the fake host`);
+  return found;
+};
+
+describe('isUnitRunning — the one predicate diff and settle share', () => {
+  test('active always counts as running, whatever started declares', () => {
+    expect(isUnitRunning('active', 'running', true)).toBe(true);
+    expect(isUnitRunning('active', 'running', false)).toBe(true);
+  });
+  test('a genuine start counts as running only when started is declared', () => {
+    expect(isUnitRunning('activating', 'start', true)).toBe(true);
+    expect(isUnitRunning('activating', 'start', false)).toBe(false);
+  });
+  // ⛔ Added on adversarial review: `auto-restart`/`auto-restart-queued` are ALSO
+  //   `ActiveState=activating` (systemd's crash-restart backoff, service.c), not a fresh start —
+  //   see isUnitRunning's own comment. Without this, started: false would stop enforcing itself on
+  //   exactly the unit most in need of it: one that is crash-looping.
+  test('auto-restart backoff always counts as running — it is a crash loop, not a fresh start', () => {
+    expect(isUnitRunning('activating', 'auto-restart', false)).toBe(true);
+    expect(isUnitRunning('activating', 'auto-restart-queued', false)).toBe(true);
+  });
+  test('inactive and failed never count as running', () => {
+    expect(isUnitRunning('inactive', 'dead', true)).toBe(false);
+    expect(isUnitRunning('failed', 'failed', false)).toBe(false);
+  });
+});
+
+describe('started: false against a oneshot mid-run', () => {
+  test('activating, everything else converged: diff is noop', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'activating', enabled: false, subState: 'start' });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'noop' });
+  });
+
+  test('active is drift: diff is update, and settle stops it', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { active: true, enabled: false });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, props, output);
+    expect(verbs(fake.calls.slice(before))).toContain('stop');
+    expect(settled.active).toBe(false);
+  });
+
+  test('activating during an unrelated unit-file update: settle does not stop it', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'activating', enabled: false, subState: 'start' });
+    const output = await outputFor(fake, props);
+    const changed = { ...props, content: content.replace('check-node', 'check-node-v2') };
+    expect(await diffUnit(fake.runner, changed, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    await reconcileUnit(fake.runner, changed, output);
+    expect(verbs(fake.calls.slice(before))).not.toContain('stop');
+  });
+
+  test('failed is not running either: diff is noop', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, content, { activeState: 'failed', enabled: false });
+    const output = await outputFor(fake, props);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'noop' });
+  });
+
+  // ⛔ ADVERSARIAL-REVIEW CASE: `activating` is not only a fresh start. A unit that was started by
+  //   hand and now crash-loops (`Restart=on-failure`) sits in `ActiveState=activating`,
+  //   `SubState=auto-restart` for nearly all of its wall-clock time. The oneshot exemption above
+  //   must NOT swallow this one — started: false has to keep stopping it, same as plain `active`.
+  test('auto-restart backoff is still drift: diff is update, and settle still stops it', async () => {
+    const fake = host();
+    const crashy = renderUnit([
+      { lines: [['Description', 'started by hand, now crash-looping']], name: 'Unit' },
+      {
+        lines: [
+          ['ExecStart', '/usr/bin/flaky'],
+          ['Restart', 'on-failure'],
+          ['RestartSec', '5'],
+        ],
+        name: 'Service',
+      },
+    ]);
+    const crashyProps: SystemdUnitProps = {
+      content: crashy,
+      enabled: false,
+      name: NAME,
+      started: false,
+    };
+    fake.placeUnit(PATH, crashy, {
+      activeState: 'activating',
+      enabled: false,
+      subState: 'auto-restart',
+    });
+    const output = await outputFor(fake, crashyProps);
+    expect(await diffUnit(fake.runner, crashyProps, output)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, crashyProps, output);
+    expect(verbs(fake.calls.slice(before))).toContain('stop');
+    expect(settled.active).toBe(false);
+  });
+});
+
+describe('started: true (or omitted) keeps counting activating as running', () => {
+  test('no start is issued while the unit is already activating', async () => {
+    const fake = host();
+    const enabledContent = renderUnit([
+      { lines: [['Description', 'a long-running service']], name: 'Unit' },
+      { lines: [['ExecStart', '/usr/bin/thing']], name: 'Service' },
+      { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+    ]);
+    const started: SystemdUnitProps = { content: enabledContent, name: NAME };
+    fake.placeUnit(PATH, enabledContent, {
+      activeState: 'activating',
+      enabled: true,
+      subState: 'start',
+    });
+    const output = await outputFor(fake, started);
+    expect(await diffUnit(fake.runner, started, output)).toEqual({ action: 'noop' });
+    const before = fake.calls.length;
+    const settled = await reconcileUnit(fake.runner, started, output);
+    expect(verbs(fake.calls.slice(before))).not.toContain('start');
+    expect(settled.active).toBe(true);
+  });
+});

package/src/linux/unit-form.ts

@@ -90,6 +90,57 @@ export const digestOf = (text: string): string => sha256Hex(new TextEncoder().en
 export const configDigest = (restartOn: readonly string[] | undefined): string =>
   digestOf((restartOn ?? []).join('\n'));
 
+/**
+ * Whether `activeState`/`subState` count as "the unit is running" against a declared `started` —
+ * the ONE place this decision is made, so `diffUnit` (unit-lifecycle.ts) and `settle`
+ * (unit-settle.ts) can never disagree about it.
+ *
+ * ⛔ WHY THIS EXISTS: a `Type=oneshot` service driven by a `.timer` (no `[Install]`, declared
+ *   `started: false, enabled: false` — its timer starts it, not this resource) reports
+ *   `ActiveState=activating` for the run's whole duration, not an instant. Written for the PVE
+ *   node-check unit that first hit this: ~1.2s, every 60s. A plan taken mid-run must not read that
+ *   run as drift, and a deploy must not `systemctl stop` a check that is already in flight.
+ * ★ systemd.service(5) §`Type=`, `oneshot` (man7.org mirror, read 2026-09-23): with no
+ *   `RemainAfterExit=`, the service manager holds the unit `activating` for as long as
+ *   `ExecStart=` runs, then moves it straight to `dead`/`inactive` (or `failed`) — it never passes
+ *   through `active`. So for `started: false`, `activating` is exactly a run in progress, and
+ *   `active` is the one state a oneshot never reaches on its own: that is the drift, and the only
+ *   thing settle stops.
+ * ⛔ CRASH-LOOP GUARD, added on adversarial review: `ActiveState=activating` is not only "starting
+ *   for the first time" — a service with `Restart=` waiting out its `RestartSec=` backoff between
+ *   crash attempts is ALSO `activating`, with `SubState=auto-restart` (or `auto-restart-queued`).
+ *   A unit declared `started: false` that is crash-looping sits there for nearly all of its
+ *   wall-clock time. Without this guard the oneshot exemption above would read that loop as
+ *   converged forever, and a deploy would never again issue the `stop` that ends it — silently
+ *   defeating `started: false` on exactly the unit that most needs it enforced. So only a genuine
+ *   start (`SubState` anything else — `start`, `start-pre`, `start-post`, …) gets the exemption;
+ *   an auto-restart substate counts as running regardless of `started`, same as `active` does.
+ * ★ SOURCE, not measured against a live host: systemd's own `service.c`
+ *   `state_translation_table` (github.com/systemd/systemd, read 2026-09-23) maps both
+ *   `SERVICE_AUTO_RESTART` and `SERVICE_AUTO_RESTART_QUEUED` to `UNIT_ACTIVATING`, and
+ *   `unit-def.c`'s `service_state_table` names their `SubState` strings `"auto-restart"` and
+ *   `"auto-restart-queued"`. ⚠️ REASONED NOT MEASURED: no unit was actually crash-looped and read
+ *   back with `systemctl show` for this change — the systemd source is the citation, unlike
+ *   systemctl.ts's own header, which is a live-host trace.
+ * ⚠️ THE TRADE-OFF THIS ACCEPTS: a `Type=notify` (or other long-running type) unit stuck in a
+ *   genuine `activating`/`start` with `started: false` — never reaching `active` and never
+ *   crash-looping either — reads as converged, not drift, until it reaches `active`. A unit hung
+ *   like that is exactly the case a human should look at, not one this predicate auto-corrects by
+ *   stopping it out from under whatever else depends on it.
+ * ★ `started: true` (the default, when omitted) is unchanged: `active` or `activating` (any
+ *   `subState`) both count as running, so a start already in flight is never started twice.
+ */
+export const isUnitRunning = (
+  activeState: string,
+  subState: string | undefined,
+  started: boolean,
+): boolean => {
+  if (activeState === 'active') return true;
+  if (activeState !== 'activating') return false;
+  if (subState === 'auto-restart' || subState === 'auto-restart-queued') return true;
+  return started;
+};
+
 /** Sections → an INI unit file. ★ Keys and values pass through untouched; see the file header. */
 export const renderUnit = (sections: readonly UnitSection[]): string =>
   `${sections

package/src/linux/unit-lifecycle.ts

@@ -27,6 +27,7 @@ import {
   UNIT_WRITE,
   configDigest,
   digestOf,
+  isUnitRunning,
   unitPathFor,
   unitText,
 } from './unit-form.ts';
@@ -75,10 +76,16 @@ export const diffUnit = async (
   const live = await readUnit(runner, news);
   if (live === undefined || live.unitSha256 !== desired) return update();
   if (live.enabled !== (news.enabled !== false)) return update();
-  if (live.active !== (news.started !== false)) return update();
   // ⚠️ systemd's own word for "the file on disk is newer than what I loaded" — a write that landed
-  //   without its reload. It is drift that neither digest can see.
+  //   without its reload. It is drift that neither digest can see. ★ Also the freshest read of
+  //   ActiveState/SubState — not `live.active`, which is a raw "active or activating" reading with
+  //   no SubState in it. Whether the current state counts as drift against `started` is the
+  //   isUnitRunning policy (unit-form.ts), shared with settle so the two can never disagree.
   const status = await showUnit(runner, news.name);
+  const wantStarted = news.started !== false;
+  if (isUnitRunning(status.activeState, status.subState, wantStarted) !== wantStarted) {
+    return update();
+  }
   return status.needDaemonReload ? update() : { action: 'noop' };
 };
 

package/src/linux/unit-settle.ts

@@ -13,6 +13,7 @@ import {
   type SystemdUnitAttributes,
   type SystemdUnitProps,
   configDigest,
+  isUnitRunning,
   unitPathFor,
 } from './unit-form.ts';
 import {
@@ -81,10 +82,13 @@ export const settle = async (
   try {
     if (wantEnabled && (!isEnabled || step.changed)) await enableUnit(runner, props.name);
     if (!wantEnabled && isEnabled) await disableUnit(runner, props.name);
-    const active = step.status.activeState === 'active' || step.status.activeState === 'activating';
+    // ★ isUnitRunning (unit-form.ts): the same started-aware policy diffUnit uses, so a unit this
+    //   deploy never touches — a `started: false` oneshot mid-run — is never stopped here either.
+    //   `subState` is what tells that mid-run apart from a crash-restart backoff, which still stops.
+    const running = isUnitRunning(step.status.activeState, step.status.subState, wantStarted);
     if (!wantStarted) {
-      if (active) await stopUnit(runner, props.name);
-    } else if (!active) await startUnit(runner, props.name);
+      if (running) await stopUnit(runner, props.name);
+    } else if (!running) await startUnit(runner, props.name);
     else if (step.changed || step.configChanged) await restartUnit(runner, props.name);
   } catch (cause) {
     return undo(cause instanceof Error ? cause.message : String(cause));
@@ -96,7 +100,7 @@ export const settle = async (
    *   as drift, in either direction.
    */
   const after = await showUnit(runner, props.name);
-  if (wantStarted && after.activeState !== 'active' && after.activeState !== 'activating') {
+  if (wantStarted && !isUnitRunning(after.activeState, after.subState, wantStarted)) {
     return undo(`systemctl reported success but the unit is ${after.activeState}.`);
   }
   const settled = attributesOf(props, step.desired, after);

package/src/paperless/client.ts

@@ -0,0 +1,88 @@
+/**
+ * One authenticated call to the Paperless-ngx REST API at `/api`.
+ *
+ * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. Paperless-ngx's `securitySchemes.tokenAuth`
+ *   (the v3.1.1 served schema) states the "Token" prefix explicitly — the same DRF
+ *   `TokenAuthentication` NetBox uses (netbox/client.ts), a different vendor, same convention.
+ *
+ * ⛔ `Accept: application/json; version=10` ON EVERY CALL. Paperless-ngx versions its API with
+ *   DRF's `AcceptHeaderVersioning` (`REST_FRAMEWORK.DEFAULT_VERSION = '10'`, measured against the
+ *   v3.1.1 source). Omitting the header still answers — DRF falls back to `DEFAULT_VERSION` — but
+ *   pinning it here means an estate upgrade that moves the default cannot silently change what
+ *   this package receives without a version bump of its own noticing.
+ *
+ * ⚠️ A LIST IS WRAPPED, A DETAIL IS NOT: `{count, next, previous, results: […]}` vs. the bare
+ *   object — the same DRF pagination shape NetBox uses.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { PaperlessCredentials, type PaperlessCredentialsError } from './credentials.ts';
+import { type PaperlessError, PaperlessUnavailable, statusToError } from './errors.ts';
+
+const PATH_PREFIX = '/api';
+const API_VERSION = '10';
+
+export interface PaperlessList<T> {
+  readonly count: number;
+  readonly next: string | null;
+  readonly previous: string | null;
+  readonly results: readonly T[];
+}
+
+export type PaperlessRow = Record<string, unknown>;
+
+/**
+ * ⚠️ `PaperlessCredentials` IS PART OF THIS, NOT JUST `HttpClient`. `paperless()` reads the lazy
+ *   credentials service (`yield* yield* PaperlessCredentials`), so a stack that wires the
+ *   providers without also providing a credentials layer should fail to TYPECHECK, not fail at
+ *   the first call. `providers.ts` supplies `environmentLayer` by default for exactly this.
+ */
+export type PaperlessRequirements = HttpClient.HttpClient | PaperlessCredentials;
+
+/** One JSON call. Returns the parsed body, or `undefined` for an empty response (DELETE). */
+export const paperless = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+): Effect.Effect<T, PaperlessError | PaperlessCredentialsError, PaperlessRequirements> =>
+  Effect.gen(function* () {
+    const credentials = yield* yield* PaperlessCredentials;
+    const url = `${credentials.url}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: `application/json; version=${API_VERSION}`,
+        Authorization: `Token ${credentials.token}`,
+      }),
+      // ⛔ Content-Type on `bodyText`, not the header map — `bodyText(s)` with no second argument
+      //   sets `text/plain` and overwrites a `Content-Type` set earlier via `setHeaders`, because
+      //   it is piped afterwards (measured against `@homeflare/alchemy/forgejo`, netbox/client.ts).
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(
+        Effect.mapError(
+          (cause) => new PaperlessUnavailable({ detail: String(cause), method, path, status: 0 }),
+        ),
+      );
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(statusToError(response.status, method, path, detail.slice(0, 500)));
+    }
+    const text = yield* response.text.pipe(
+      Effect.mapError(
+        () =>
+          new PaperlessUnavailable({
+            detail: 'body read failed',
+            method,
+            path,
+            status: response.status,
+          }),
+      ),
+    );
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });

package/src/paperless/constraint-guard.ts

@@ -0,0 +1,50 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK — the generator resolves every key
+ *   in its source scan against the vendor document, so a key absent here means the tables were
+ *   not regenerated, which the message says. Same posture as `../netbox/constraint-guard.ts`.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type EndpointConstraints,
+  type EndpointKey,
+  type PaperlessBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+import { PAPERLESS_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { PAPERLESS_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = PAPERLESS_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/paperless.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+export const bodyViolations = (
+  key: EndpointKey,
+  body: PaperlessBody,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), body, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition.
+ */
+export const guardBody = (
+  key: EndpointKey | undefined,
+  body: PaperlessBody,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = bodyViolations(key, body, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });