@homeflare/alchemy 0.15.0 → 0.19.0

package/dist/linux/remote-file-form.d.ts

@@ -0,0 +1,47 @@
+import { type RegionSpec } from './region.ts';
+export interface RemoteFileProps {
+    /** Absolute path on the host. ⚠️ The parent directory must exist — declare a HostDirectory. */
+    path: string;
+    /** UTF-8 text: the whole file, or the region's body. ⛔ Never a secret — see the file header. */
+    content: string;
+    /**
+     * Own a block inside a file this resource does not own, instead of the whole file.
+     * ⛔ In region mode `mode`, `owner` and `group` apply ONLY to a file this resource creates: an
+     *   existing file keeps the mode and ownership its owner gave it, because changing them would be
+     *   a second, undeclared claim on a file we only borrowed four lines of.
+     */
+    region?: RegionSpec;
+    /**
+     * Create the file when it is absent. Region mode only; whole-file mode always creates.
+     * ⛔ Default `false`: a region declared against a path that does not exist is far more often a
+     *   typo (a wrong `/etc` path) than an intention, and creating it would hide the typo.
+     */
+    create?: boolean;
+    /** Permission bits. @default 0o644 */
+    mode?: number;
+    /** User name or numeric uid. Omitted: whoever the runner writes as. */
+    owner?: string | number;
+    /** Group name or numeric gid. Omitted: the directory's default group. */
+    group?: string | number;
+}
+export interface RemoteFileAttributes {
+    path: string;
+    /** SHA-256 of the WHOLE file on disk, in both modes. */
+    sha256: string;
+    /** SHA-256 of the part this resource owns — in region mode, of the region's body alone. */
+    contentSha256: string;
+    /**
+     * The block this resource owns, when it owns only a block.
+     * ⛔ IT IS IN THE ATTRIBUTES ON PURPOSE. Alchemy's `delete` handler is given the attributes and
+     *   nothing else, and without the marker name a delete could not find the block — it could only
+     *   delete the whole file, which belongs to someone else.
+     */
+    region?: RegionSpec;
+    mode: number;
+    uid: number;
+    gid: number;
+    size: number;
+}
+export declare const DEFAULT_MODE = 420;
+export declare const fileProblems: (props: RemoteFileProps) => string[];
+//# sourceMappingURL=remote-file-form.d.ts.map

package/dist/linux/remote-file-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file-form.d.ts","sourceRoot":"","sources":["../../src/linux/remote-file-form.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,MAAQ,CAAC;AAclC,eAAO,MAAM,YAAY,UAAW,eAAe,KAAG,MAAM,EAoB3D,CAAC"}

package/dist/linux/remote-file-lifecycle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RemoteFile's diff / reconcile / delete over a HostRunner, so the whole lifecycle runs against a
+ * fake host in tests with no ssh and no real write. What it would write is worked out next door
+ * (remote-file-plan.ts); this file is the part that decides to act.
+ *
+ * ⛔ IN REGION MODE, DRIFT MEANS THE REGION AND NOTHING ELSE. Every byte outside the markers belongs
+ *   to another owner, so a change there must never plan an update — otherwise the two owners fight
+ *   on every deploy and this resource loses the right to be in that file at all.
+ * ⚠️ THE WRITE REPLACES THE INODE, in both modes. A process holding the old file keeps reading it
+ *   until it reopens, and a hard link to the path stops tracking. That is the price of never
+ *   leaving a torn file, and it is the trade the launchd family already makes.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { type HostRunner } from '../launchd/runner.ts';
+import { type RemoteFileAttributes, type RemoteFileProps } from './remote-file-form.ts';
+export { readFileAttributes } from './remote-file-plan.ts';
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one), so a runner's own
+ *   refusals fail the plan instead of arriving halfway through the apply.
+ */
+export declare const diffFile: (runner: HostRunner, news: RemoteFileProps, output: RemoteFileAttributes) => Promise<Diff>;
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts). It lets such a generation take over what is already at the path — the
+ * takeover the plan's probe would have allowed, had it run.
+ * ★ IN REGION MODE THE FILE BEING THERE IS NOT A TAKEOVER: it belongs to someone else by
+ *   definition. What this resource claims is the block, so only a block already present with other
+ *   content is the thing adoption is asked about.
+ */
+export declare const reconcileFile: (runner: HostRunner, props: RemoteFileProps, output?: RemoteFileAttributes, adopt?: boolean) => Promise<RemoteFileAttributes>;
+/**
+ * Whole-file mode removes the file. ⛔ REGION MODE REMOVES ONLY THE BLOCK, leaving every other byte
+ *   identical — removing the file would delete another owner's configuration. Idempotent both ways.
+ */
+export declare const deleteFile: (runner: HostRunner, output: RemoteFileAttributes) => Promise<void>;
+//# sourceMappingURL=remote-file-lifecycle.d.ts.map

package/dist/linux/remote-file-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file-lifecycle.d.ts","sourceRoot":"","sources":["../../src/linux/remote-file-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,sBAAsB,CAAC;AAErE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,QAAQ,WACX,UAAU,QACZ,eAAe,UACb,oBAAoB,KAC3B,OAAO,CAAC,IAAI,CAed,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,SACX,eAAe,WACb,oBAAoB,sBAE5B,OAAO,CAAC,oBAAoB,CA6D9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,WACb,UAAU,UACV,oBAAoB,KAC3B,OAAO,CAAC,IAAI,CAkBd,CAAC"}

package/dist/linux/remote-file-plan.d.ts

@@ -0,0 +1,33 @@
+import type { HostRunner, WriteOptions } from '../launchd/runner.ts';
+import { type RegionSpec } from './region.ts';
+import { type RemoteFileAttributes, type RemoteFileProps } from './remote-file-form.ts';
+export declare const decoder: TextDecoder;
+export declare const encoder: TextEncoder;
+export declare const refuse: (path: string, message: string) => Error;
+export type Identity = {
+    readonly uid?: number;
+    readonly gid?: number;
+};
+/** Validate, then resolve owner and group names to ids through the runner. */
+export declare const identity: (runner: HostRunner, props: RemoteFileProps) => Promise<Identity>;
+export declare const digestOf: (text: string) => string;
+/** The digest of the part this resource owns, or `undefined` when that part is not there. */
+export declare const ownedDigest: (file: string | undefined, region: RegionSpec | undefined) => string | undefined;
+/** The file as it is now, plus the digest of the part this resource owns. */
+export declare const readFileAttributes: (runner: HostRunner, path: string, region: RegionSpec | undefined) => Promise<RemoteFileAttributes | undefined>;
+export type Plan = {
+    /** The whole file's new bytes, in both modes. */
+    readonly bytes: Uint8Array;
+    readonly write: WriteOptions;
+    /** The bytes on disk right now, or `undefined` when nothing is there. */
+    readonly before: string | undefined;
+    /** Nothing to do: the file already says what we declare, with the mode and owner we declare. */
+    readonly converged: boolean;
+};
+/**
+ * ⛔ A SYMLINK OR A DIRECTORY IS REFUSED, NOT REPLACED. The write is a rename(2), which over a
+ *   symlink replaces the LINK — quietly taking the path from whatever put it there (a config
+ *   manager's `/etc` entries are symlinks, and so is `/etc/resolv.conf` on most Linux hosts).
+ */
+export declare const planWrite: (runner: HostRunner, props: RemoteFileProps, want: Identity) => Promise<Plan>;
+//# sourceMappingURL=remote-file-plan.d.ts.map

package/dist/linux/remote-file-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file-plan.d.ts","sourceRoot":"","sources":["../../src/linux/remote-file-plan.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAY,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,KAAK,UAAU,EAA4B,MAAM,aAAa,CAAC;AACxE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAErB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,OAAO,aAAoB,CAAC;AACzC,eAAO,MAAM,OAAO,aAAoB,CAAC;AAEzC,eAAO,MAAM,MAAM,SAAU,MAAM,WAAW,MAAM,KAAG,KACT,CAAC;AAK/C,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,WAAkB,UAAU,SAAS,eAAe,KAAG,OAAO,CAAC,QAAQ,CAc3F,CAAC;AAEF,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAyC,CAAC;AAElF,6FAA6F;AAC7F,eAAO,MAAM,WAAW,SAChB,MAAM,GAAG,SAAS,UAChB,UAAU,GAAG,SAAS,KAC7B,MAAM,GAAG,SAKX,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,WACrB,UAAU,QACZ,MAAM,UACJ,UAAU,GAAG,SAAS,KAC7B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAe1C,CAAC;AAQF,MAAM,MAAM,IAAI,GAAG;IACjB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,WACZ,UAAU,SACX,eAAe,QAChB,QAAQ,KACb,OAAO,CAAC,IAAI,CA+Cd,CAAC"}

package/dist/linux/remote-file.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `Remote.File` — one text file on a Linux host, declared: content, mode, owner, group — or one
+ * MANAGED BLOCK inside a file this resource does not own.
+ *
+ * - create / update — atomic write (stage beside the target, chown, chmod, rename), skipped when
+ *   the host already says what we declare; then read back and compared.
+ * - read — lstat plus the SHA-256 of the file and of the part this resource owns.
+ * - diff — the declared digest against the stored AND the on-disk one, plus mode and owner.
+ * - replace — only when `path` changes; create-before-delete.
+ * - delete — removes the file, or in region mode only the block.
+ *
+ * ⛔ NEVER A SECRET — see remote-file-form.ts.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt` (docs/ownership.md): a file already at the path, or a
+ *   block already carrying the markers, reads as `Unowned`.
+ * ★ IT IS A SEPARATE RESOURCE FROM `Host.File`, not a flag on it: the two have different attributes
+ *   (a region name that a delete cannot work without) and different promises about the rest of the
+ *   file, and folding them together would make every existing Mac HostFile's state shape change.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+export type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+export interface RemoteFile extends Resource<'Remote.File', RemoteFileProps, RemoteFileAttributes> {
+}
+export declare const RemoteFile: import("alchemy").ResourceClass<RemoteFile>;
+export declare const RemoteFileProvider: () => import("effect/Layer").Layer<Provider.Provider<RemoteFile>, never, HostRunnerService>;
+//# sourceMappingURL=remote-file.d.ts.map

package/dist/linux/remote-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file.d.ts","sourceRoot":"","sources":["../../src/linux/remote-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQnF,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEnF,MAAM,WAAW,UAAW,SAAQ,QAAQ,CAC1C,aAAa,EACb,eAAe,EACf,oBAAoB,CACrB;CAAG;AAEJ,eAAO,MAAM,UAAU,6CAAsC,CAAC;AAE9D,eAAO,MAAM,kBAAkB,6FA0C5B,CAAC"}

package/dist/linux/ssh-command.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The wire format the ssh runner speaks: how an argv becomes one remote `sh` script, and how that
+ * script's real exit code comes back. Pure functions, so every quoting and framing rule is tested
+ * without opening a connection.
+ *
+ * ⛔ `ssh host <words>` IS NOT AN EXECVE. ssh joins its trailing arguments with spaces and the
+ *   REMOTE LOGIN SHELL parses the result, so an unquoted path with a space, a `$`, a backtick or a
+ *   `;` is re-parsed as shell syntax on the other side. Everything therefore goes through
+ *   `shellQuote`, and the remote command is always `/bin/sh -c '<script>'` — a POSIX shell named
+ *   explicitly, so a csh or fish login shell only ever execs it.
+ * ⛔ AN EXIT CODE FROM ssh IS AMBIGUOUS. ssh exits 255 for its own failures (connection refused,
+ *   host key changed, auth) and otherwise passes the remote exit code through — and a remote
+ *   command may itself exit 255. A runner that read the code alone would report "the file is not
+ *   there" for a dropped connection, which is the exact "never infer success from an empty result"
+ *   failure. So every script ends by printing its own status on stderr behind a PER-RUNNER NONCE,
+ *   and a result without that line is a transport failure, never data.
+ * ⚠️ THE NONCE IS NOT DECORATION. Without it a remote program that happens to print the marker on
+ *   stderr could claim any exit code it liked; with a fresh random nonce per runner, the only thing
+ *   that can produce the line is the script we sent.
+ */
+/** A script whose work found nothing at the path. ★ Chosen from the 64–113 range sh leaves free. */
+export declare const ABSENT = 66;
+/**
+ * One argument, safe for a POSIX shell. ⛔ Single quotes, because they quote EVERYTHING; the
+ *   `'\''` dance is how a literal quote gets through.
+ */
+export declare const shellQuote: (arg: string) => string;
+/** An argv as one shell command line. */
+export declare const quoteArgv: (argv: readonly string[]) => string;
+/**
+ * Wrap a script so its status comes back unambiguously.
+ *
+ * ⛔ THE SCRIPT RUNS IN A SUBSHELL, AND THAT IS NOT COSMETIC. Several of the scripts end a branch
+ *   with `exit <code>` to say "nothing was there"; at the top level that exit leaves the shell
+ *   immediately and the marker line NEVER PRINTS — so the caller sees a framed result missing its
+ *   frame and, correctly, calls it a transport failure. 🔴 MEASURED 2026-09-22 against a live
+ *   Debian 13 host: `stat` of a missing path came back as "the remote command did not report a
+ *   status (ssh exit 66)" instead of "nothing is at this path". Inside `( … )` the exit leaves only
+ *   the subshell, `$?` carries the code out, and the frame always runs.
+ * ⚠️ The leading `\n` matters too: a program whose last stderr line has no newline would otherwise
+ *   glue itself to the marker and the marker would not be found.
+ */
+export declare const frameScript: (script: string, nonce: string) => string;
+export type Framed = {
+    readonly exitCode: number;
+    readonly stderr: string;
+};
+/**
+ * The remote exit code and the stderr that belongs to the command, or `undefined` when the marker
+ * is absent — which means the script never ran to its end: ssh failed, the connection dropped, or
+ * the remote shell could not parse what we sent. ⛔ The caller must treat `undefined` as an error,
+ * never as an answer.
+ */
+export declare const parseFramed: (stderr: string, nonce: string) => Framed | undefined;
+/**
+ * The fixed ssh options, in front of anything a caller adds.
+ * ⛔ `BatchMode=yes` — a deploy that stops to ask for a passphrase is the failure "no password
+ *   prompts" names, and with BatchMode ssh fails at once instead.
+ * ⛔ NOTHING HERE WEAKENS HOST VERIFICATION. No `StrictHostKeyChecking`, no `UserKnownHostsFile`:
+ *   the operator's own ssh config and known_hosts decide who the host is, and a changed key stays
+ *   a refusal. A runner that turned that off would make a man-in-the-middle a deploy target.
+ * ★ `-T`: no pseudo-terminal, so the remote shell's stdout stays the bytes the program wrote.
+ */
+export declare const sshArgv: (host: string, script: string, options: {
+    readonly connectTimeoutSec: number;
+    readonly sshArgs?: readonly string[];
+}) => readonly string[];
+//# sourceMappingURL=ssh-command.d.ts.map

package/dist/linux/ssh-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-command.d.ts","sourceRoot":"","sources":["../../src/linux/ssh-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oGAAoG;AACpG,eAAO,MAAM,MAAM,KAAK,CAAC;AAEzB;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAS,MAAM,KAAG,MAGxC,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,SAAS,SAAU,SAAS,MAAM,EAAE,KAAG,MAAwC,CAAC;AAI7F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,SAAS,MAAM,KAAG,MAC6B,CAAC;AAE1F,MAAM,MAAM,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,SAAS,MAAM,KAAG,MAAM,GAAG,SAMpE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,SACZ,MAAM,UACJ,MAAM,WACL;IAAE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,KACpF,SAAS,MAAM,EAejB,CAAC"}

package/dist/linux/ssh-runner.d.ts

@@ -0,0 +1,22 @@
+import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+export type SshRunnerOptions = {
+    /** The destination exactly as the operator's own ssh config names it (`Host` block or user@host). */
+    readonly host: string;
+    /** Extra ssh options, after the fixed safety set and before the destination. */
+    readonly sshArgs?: readonly string[];
+    /** Kill a connection after this long. @default 120_000 */
+    readonly execTimeoutMs?: number;
+    /** ssh's own `ConnectTimeout`. @default 10 */
+    readonly connectTimeoutSec?: number;
+};
+/** What the process on the far end did — or an Error, when we cannot say that it ran at all. */
+export declare const runRemote: (options: Required<Pick<SshRunnerOptions, 'host' | 'connectTimeoutSec' | 'execTimeoutMs'>> & Pick<SshRunnerOptions, 'sshArgs'>, nonce: string, script: string, stdin?: Uint8Array) => Promise<ExecResult>;
+/**
+ * Connect once to learn who we are, then hand back the runner.
+ * ⛔ THE PROBE IS THE FAIL-CLOSED GATE. `effectiveUid()` is synchronous on HostRunner, so the uid
+ *   must be known before the first provider call; and `uname -s` refuses a host whose `stat -c`,
+ *   `base64` and `mv -f` are not the Linux spellings this runner sends. A host that cannot answer
+ *   both is a thrown Error at construction, not a stack that half-deploys.
+ */
+export declare const sshRunner: (options: SshRunnerOptions) => Promise<HostRunner>;
+//# sourceMappingURL=ssh-runner.d.ts.map

package/dist/linux/ssh-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-runner.d.ts","sourceRoot":"","sources":["../../src/linux/ssh-runner.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAWnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAmCF,gGAAgG;AAChG,eAAO,MAAM,SAAS,YACX,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,mBAAmB,GAAG,eAAe,CAAC,CAAC,GACvF,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,SAC5B,MAAM,UACL,MAAM,UACN,UAAU,KACjB,OAAO,CAAC,UAAU,CAiBpB,CAAC;AAUF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,YAAmB,gBAAgB,KAAG,OAAO,CAAC,UAAU,CA6D7E,CAAC"}

package/dist/linux/ssh-scripts.d.ts

@@ -0,0 +1,27 @@
+import type { FileStat, WriteOptions } from '../launchd/runner.ts';
+export declare const statScript: (path: string) => string;
+/** ★ base64 on the wire: stdout then carries no byte that a shell, a pty or a locale can alter. */
+export declare const readScript: (path: string) => string;
+/** ⛔ `rm -f` is idempotent for an absent path and still FAILS for a directory, which is what keeps
+ *    HostRunner.removeFile from quietly removing something that is not a file. */
+export declare const removeScript: (path: string) => string;
+export declare const execScript: (argv: readonly string[]) => string;
+/**
+ * Write bytes (fed on stdin) so `path` holds the old file or the new one and never a torn mix.
+ *
+ * ⛔ NOT `install`. GNU coreutils `install` opens the destination and writes THROUGH it — unlike
+ *   macOS's, which stages and renames — so a deploy interrupted mid-write would leave a truncated
+ *   config where a whole one used to be. Staging beside the target and `mv` (rename(2), same
+ *   directory so never EXDEV) is the only atomic spelling available over a shell.
+ * ⛔ `set -C` and `umask 077`: the staged file is created O_EXCL, so a symlink or a file planted at
+ *   the temp name is a refusal rather than a write through it, and it is unreadable by anyone else
+ *   in the moment before its mode is set.
+ * ⚠️ chown BEFORE chmod: chown by root clears setuid/setgid, so the other order silently drops a
+ *   declared 4755 — the same ordering localRunner keeps for the same reason.
+ * ⚠️ Each step removes the staged file before it fails, so a failed write leaves no litter beside
+ *   a file someone else owns.
+ */
+export declare const writeScript: (path: string, temp: string, options: WriteOptions) => string;
+/** `stat -c '%f %a %u %g %s'` output → a FileStat, or `undefined` when it is not that shape. */
+export declare const parseStat: (stdout: string) => FileStat | undefined;
+//# sourceMappingURL=ssh-scripts.d.ts.map

package/dist/linux/ssh-scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-scripts.d.ts","sourceRoot":"","sources":["../../src/linux/ssh-scripts.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAMnE,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MAGzC,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MAGzC,CAAC;AAEF;kFACkF;AAClF,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAwC,CAAC;AAErF,eAAO,MAAM,UAAU,SAAU,SAAS,MAAM,EAAE,KAAG,MAAyB,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,QAAQ,MAAM,WAAW,YAAY,KAAG,MAyB/E,CAAC;AASF,gGAAgG;AAChG,eAAO,MAAM,SAAS,WAAY,MAAM,KAAG,QAAQ,GAAG,SAgBrD,CAAC"}

package/dist/linux/systemctl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The `systemctl` subcommands the systemd family uses, over a HostRunner, plus the parser for the
+ * one that returns data.
+ *
+ * ★ MEASURED 2026-09-22 on Debian 13, systemd 257 (257.13-1~deb13u1), read-only — nothing was
+ *   enabled, started or reloaded to write this:
+ *
+ *   - `systemctl show -p <list> <unit>` EXITS 0 FOR A UNIT THAT DOES NOT EXIST, and answers with
+ *     the properties it would have had:
+ *         Id=hf-nonexistent-xyz.service   LoadState=not-found
+ *         ActiveState=inactive            SubState=dead
+ *         FragmentPath=                   UnitFileState=
+ *     ⛔ SO THE EXIT CODE IS NOT THE ANSWER — `LoadState` is. A provider that read exit 0 as "the
+ *       unit is there" would adopt a unit that does not exist and then never write its file.
+ *   - The properties come back in systemd's own order, not the order asked for, so the output is a
+ *     map and never positional.
+ *   - `systemctl is-enabled <unknown>` exits **4** and prints `not-found`; `is-active <unknown>`
+ *     exits **4** and prints `inactive`. Both are answers, not errors.
+ *   - `UnitFileState=static` is exactly systemd's name for a unit file with no `[Install]` section
+ *     (measured: the journal daemon is `static`, the ssh daemon is `enabled`).
+ *   - `/etc/systemd/system` is `root:root 0755` — the admin drop-in directory, ahead of the
+ *     vendor's `/usr/lib/systemd/system` in systemd's own search order.
+ * ⚠️ REASONED, NOT MEASURED: the write subcommands. `daemon-reload`, `enable`, `disable`, `start`,
+ *   `stop` and `restart` were never run for this file, because running them would change a live
+ *   host. Each is therefore checked the same way: exit 0 or an Error carrying systemd's stderr, and
+ *   the state is read back with `show` afterwards rather than assumed.
+ * ⛔ NEVER PUT `show` STDOUT WITH NO PROPERTY FILTER IN AN ERROR: the unfiltered property set
+ *   carries the unit's whole environment block.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+export declare const SYSTEMCTL = "systemctl";
+/** The properties every read asks for. ⛔ Never `Environment` — see the header. */
+export declare const SHOW_PROPERTIES: readonly ['Id', 'LoadState', 'ActiveState', 'SubState', 'UnitFileState', 'FragmentPath', 'NeedDaemonReload'];
+export declare class SystemctlError extends Error {
+    constructor(command: string, exitCode: number, stderr: string);
+}
+export type UnitStatus = {
+    /** `loaded`, `not-found`, `masked`, `error`, `bad-setting`. ⛔ The authority on existence. */
+    readonly loadState: string;
+    /** systemd knows this unit: it has a unit file or is loaded. */
+    readonly known: boolean;
+    readonly activeState: string;
+    readonly subState?: string;
+    /** `enabled`, `disabled`, `static`, `masked`, … Empty for a unit with no unit file. */
+    readonly unitFileState?: string;
+    /** The unit file systemd would read. Empty when there is none. */
+    readonly fragmentPath?: string;
+    /** systemd's own view that its on-disk unit files are newer than what it has loaded. */
+    readonly needDaemonReload: boolean;
+};
+/** `key=value` lines into a map. ⚠️ First wins: systemd never repeats a key, a truncated read might. */
+export declare const parseShow: (stdout: string) => Map<string, string>;
+export declare const statusOf: (stdout: string) => UnitStatus;
+export declare const showUnit: (runner: HostRunner, name: string) => Promise<UnitStatus>;
+/** ⛔ After every unit-file write or removal, and before enable/start reads it. */
+export declare const daemonReload: (runner: HostRunner) => Promise<void>;
+export declare const enableUnit: (runner: HostRunner, name: string) => Promise<void>;
+export declare const disableUnit: (runner: HostRunner, name: string) => Promise<void>;
+export declare const startUnit: (runner: HostRunner, name: string) => Promise<void>;
+export declare const stopUnit: (runner: HostRunner, name: string) => Promise<void>;
+/**
+ * ⛔ `restart`, NOT `reload-or-restart`. The reloading form asks the unit to re-read its config in
+ *   place when it declares `ExecReload=`, which means "did the change take effect?" has two
+ *   different answers depending on the unit — and a deploy cannot report a half-applied change.
+ */
+export declare const restartUnit: (runner: HostRunner, name: string) => Promise<void>;
+//# sourceMappingURL=systemctl.d.ts.map

package/dist/linux/systemctl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemctl.d.ts","sourceRoot":"","sources":["../../src/linux/systemctl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,kFAAkF;AAClF,eAAO,MAAM,eAAe,YAC1B,IAAI,EACJ,WAAW,EACX,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,CACV,CAAC;AAEX,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAG5D;CACF;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,SAAS,WAAY,MAAM,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAS5D,CAAC;AAEF,eAAO,MAAM,QAAQ,WAAY,MAAM,KAAG,UAiBzC,CAAC;AAEF,eAAO,MAAM,QAAQ,WAAkB,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,UAAU,CAgBnF,CAAC;AAUF,kFAAkF;AAClF,eAAO,MAAM,YAAY,WAAY,UAAU,KAAG,OAAO,CAAC,IAAI,CAAmC,CAAC;AAElG,eAAO,MAAM,UAAU,WAAY,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CACrC,CAAC;AAEtC,eAAO,MAAM,WAAW,WAAY,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CACrC,CAAC;AAEvC,eAAO,MAAM,SAAS,WAAY,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CACrC,CAAC;AAErC,eAAO,MAAM,QAAQ,WAAY,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CACrC,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAY,UAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CACrC,CAAC"}

package/dist/linux/unit-form.d.ts

@@ -0,0 +1,78 @@
+export type UnitSection = {
+    /** `Unit`, `Service`, `Timer`, `Install`, … — verbatim, including its capitalisation. */
+    readonly name: string;
+    /**
+     * The section's lines, in order. A repeated key is allowed and meaningful in systemd
+     * (`ExecStartPre=` twice runs twice), so this is a list of pairs, never an object.
+     */
+    readonly lines: readonly (readonly [key: string, value: string])[];
+};
+export type SystemdUnitProps = {
+    /** Unit name WITH its suffix, e.g. `thing.service`. The unit file's name on disk. */
+    name: string;
+    /** The whole unit file, verbatim. Mutually exclusive with `sections`. */
+    content?: string;
+    /** The unit file as sections, rendered in the order given. Mutually exclusive with `content`. */
+    sections?: readonly UnitSection[];
+    /** Directory the unit file goes in. @default '/etc/systemd/system' */
+    directory?: string;
+    /** `systemctl enable` / `disable`. @default true */
+    enabled?: boolean;
+    /** `systemctl start` / `stop`. @default true */
+    started?: boolean;
+    /**
+     * Digests of things this unit READS that live outside its unit file — a rendered config file's
+     * `sha256` attribute, most often. A change here restarts the unit; nothing else does.
+     * ⚠️ A hand edit of that file is NOT noticed: the digest in state still matches what the stack
+     *   declared, so the unit reads converged. That limit is the same one the Mac side records.
+     */
+    restartOn?: readonly string[];
+};
+export type SystemdUnitAttributes = {
+    name: string;
+    unitPath: string;
+    /** SHA-256 of the unit file this resource wrote. */
+    unitSha256: string;
+    /** SHA-256 of `restartOn`, so a config change is a diff. */
+    configSha256: string;
+    loadState: string;
+    activeState: string;
+    unitFileState?: string;
+    enabled: boolean;
+    active: boolean;
+};
+/** ★ systemd's admin drop-in directory, ahead of the vendor's in its search order (measured). */
+export declare const DEFAULT_UNIT_DIRECTORY = "/etc/systemd/system";
+/**
+ * Directories systemd looks in for a unit file it can enable.
+ * ★ MEASURED 2026-09-22 with `systemd-analyze unit-paths` on Debian 13 / systemd 257, minus the
+ *   per-user and generator directories, which are not places a stack writes. `/lib/systemd/system`
+ *   is the same directory before the /usr merge, where the measured host has only the merged name.
+ * ⛔ WHY IT IS ENFORCED. `systemctl enable <name>` looks the unit up BY NAME; a unit file outside
+ *   these directories is invisible to that lookup, so an enabled unit declared into, say, `/opt`
+ *   writes its file, reloads, and then fails at `enable` with the file already on disk.
+ */
+export declare const UNIT_SEARCH_DIRECTORIES: readonly ['/etc/systemd/system', '/run/systemd/system', '/usr/local/lib/systemd/system', '/usr/lib/systemd/system', '/lib/systemd/system'];
+/** ⛔ The unit file's mode and owner are systemd's rule, not a choice: readable, never writable. */
+export declare const UNIT_WRITE: {
+    readonly gid: 0;
+    readonly mode: 420;
+    readonly uid: 0;
+};
+export declare const digestOf: (text: string) => string;
+/** The digests of everything outside the unit file that should restart it, as one value. */
+export declare const configDigest: (restartOn: readonly string[] | undefined) => string;
+/** Sections → an INI unit file. ★ Keys and values pass through untouched; see the file header. */
+export declare const renderUnit: (sections: readonly UnitSection[]) => string;
+export declare const unitText: (props: SystemdUnitProps) => string;
+export declare const unitPathFor: (props: SystemdUnitProps) => string;
+/**
+ * Every refusal at once, so one plan shows the whole list.
+ * ⛔ THE TWO STRUCTURAL RULES, both proven by systemd's own output rather than assumed:
+ *   - `enabled: true` needs an `[Install]` section. `systemctl enable` has nothing to link without
+ *     one, and systemd's name for a unit file that has none is `UnitFileState=static` — measured on
+ *     a live host, where the journal daemon reads `static` and the ssh daemon reads `enabled`.
+ *   - A `.timer` needs a `[Timer]` section, and a timer's `[Install]` is what arms it at boot.
+ */
+export declare const unitProblems: (props: SystemdUnitProps, expect?: string) => string[];
+//# sourceMappingURL=unit-form.d.ts.map

package/dist/linux/unit-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-form.d.ts","sourceRoot":"","sources":["../../src/linux/unit-form.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,WAAW,GAAG;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,YAClC,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,yBAAyB,EACzB,qBAAqB,CACb,CAAC;AAEX,mGAAmG;AACnG,eAAO,MAAM,UAAU;aAAK,GAAG,EAAE,CAAC;aAAE,IAAI,EAAE,GAAK;aAAE,GAAG,EAAE,CAAC;CAAW,CAAC;AAEnE,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAmD,CAAC;AAE5F,4FAA4F;AAC5F,eAAO,MAAM,YAAY,cAAe,SAAS,MAAM,EAAE,GAAG,SAAS,KAAG,MAChC,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,UAAU,aAAc,SAAS,WAAW,EAAE,KAAG,MAKzC,CAAC;AAEtB,eAAO,MAAM,QAAQ,UAAW,gBAAgB,KAAG,MACA,CAAC;AAEpD,eAAO,MAAM,WAAW,UAAW,gBAAgB,KAAG,MACQ,CAAC;AAoB/D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,UAAW,gBAAgB,WAAW,MAAM,KAAG,MAAM,EAmC7E,CAAC"}

package/dist/linux/unit-handlers.d.ts

@@ -0,0 +1,15 @@
+import type { Diff } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { HostRunner } from '../launchd/runner.ts';
+import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
+export declare const readHandler: (runner: HostRunner, olds: SystemdUnitProps, output: SystemdUnitAttributes | undefined) => Effect.Effect<SystemdUnitAttributes | undefined, Error>;
+export declare const diffHandler: (runner: HostRunner, instanceId: string, news: Input<SystemdUnitProps>, output: SystemdUnitAttributes | undefined, expect?: string) => Effect.Effect<Diff | undefined, Error>;
+export declare const reconcileHandler: (runner: HostRunner, args: {
+    fqn: string;
+    instanceId: string;
+    news: SystemdUnitProps;
+    output: SystemdUnitAttributes | undefined;
+}, expect?: string) => Effect.Effect<SystemdUnitAttributes, Error>;
+export declare const deleteHandler: (runner: HostRunner, output: SystemdUnitAttributes) => Effect.Effect<void, Error>;
+//# sourceMappingURL=unit-handlers.d.ts.map

package/dist/linux/unit-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-handlers.d.ts","sourceRoot":"","sources":["../../src/linux/unit-handlers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,eAAO,MAAM,WAAW,WACd,UAAU,QACZ,gBAAgB,UACd,qBAAqB,GAAG,SAAS,KACxC,MAAM,CAAC,MAAM,CAAC,qBAAqB,GAAG,SAAS,EAAE,KAAK,CAKrD,CAAC;AAEL,eAAO,MAAM,WAAW,WACd,UAAU,cACN,MAAM,QACZ,KAAK,CAAC,gBAAgB,CAAC,UACrB,qBAAqB,GAAG,SAAS,WAChC,MAAM,KACd,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,KAAK,CAgBvC,CAAC;AAEF,eAAO,MAAM,gBAAgB,WACnB,UAAU,QACZ;IACJ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC3C,WACQ,MAAM,KACd,MAAM,CAAC,MAAM,CAAC,qBAAqB,EAAE,KAAK,CAG1C,CAAC;AAEJ,eAAO,MAAM,aAAa,WAChB,UAAU,UACV,qBAAqB,KAC5B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAA2C,CAAC"}

package/dist/linux/unit-lifecycle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Systemd.Unit's read / diff / reconcile / delete as plain async functions over a HostRunner, so
+ * the whole lifecycle runs against a fake host with no real systemd.
+ *
+ * ⛔ WHAT A DEPLOY DOES NOT DO — the rule this family was built around. It NEVER mass-restarts.
+ *   A unit is restarted only when THIS resource's unit file changed, or when a digest the
+ *   declaration itself listed in `restartOn` changed. A unit that is already running the content
+ *   we declare is left strictly alone: no restart, no reload, not even a `start`. An estate rebuild
+ *   must be able to reach a host that holds a vault, a UPS handler or a clock without bouncing
+ *   them, and "the deploy ran" must never be a reason anything went down.
+ * ★ THE ORDER IS WRITE, RELOAD, ENABLE, THEN START OR RESTART. systemd reads the unit file at
+ *   `daemon-reload`, so writing it while the old unit runs changes nothing yet, and a write that
+ *   fails leaves the old unit running rather than leaving nothing running.
+ * ⚠️ A FAILED START LEAVES THE UNIT DOWN. On an update the new unit file stays and state keeps the
+ *   previous digest, so the next deploy retries. On a CREATE the file this deploy wrote is removed
+ *   and systemd reloaded again: left behind, the next plan's recovery read finds a unit with no
+ *   state, reports it `Unowned`, and every later deploy demands `--adopt` for our own file.
+ * ⛔ A MASKED UNIT IS SOMEONE'S DECISION, NOT DRIFT. `systemctl mask` survives reboots and makes
+ *   start fail; unmasking here would silently overrule whoever masked it.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { type HostRunner } from '../launchd/runner.ts';
+import { type SystemdUnitAttributes, type SystemdUnitProps } from './unit-form.ts';
+/** Throw every refusal at once, so one plan shows the whole list. */
+export declare const assertValid: (props: SystemdUnitProps, expect?: string) => void;
+/** What is on the host now: the unit file's digest and systemd's view. `undefined` when neither. */
+export declare const readUnit: (runner: HostRunner, props: SystemdUnitProps) => Promise<SystemdUnitAttributes | undefined>;
+/** ⛔ Writing a unit file and driving systemd are root's, so refuse up front rather than mid-apply. */
+export declare const assertMayWrite: (runner: HostRunner, name: string) => void;
+export declare const diffUnit: (runner: HostRunner, news: SystemdUnitProps, output: SystemdUnitAttributes, expect?: string) => Promise<Diff>;
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts): it lets such a generation take over a unit already on the host.
+ * ★ AN ADOPTED UNIT THAT ALREADY MATCHES IS NOT RESTARTED. That is the whole point of adopting one:
+ *   the estate's live services come under declaration without a single bounce.
+ */
+export declare const reconcileUnit: (runner: HostRunner, props: SystemdUnitProps, output: SystemdUnitAttributes | undefined, adopt?: boolean, expect?: string) => Promise<SystemdUnitAttributes>;
+/**
+ * Stop, disable, remove the unit file, reload. Idempotent.
+ * ⛔ DELETING THE DECLARATION STOPS THE SERVICE. That is what removing it from the stack means, and
+ *   it is why a unit that must outlive its declaration is adopted rather than deleted.
+ */
+export declare const deleteUnit: (runner: HostRunner, output: SystemdUnitAttributes) => Promise<void>;
+//# sourceMappingURL=unit-lifecycle.d.ts.map

package/dist/linux/unit-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-lifecycle.d.ts","sourceRoot":"","sources":["../../src/linux/unit-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,sBAAsB,CAAC;AACrE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAOtB,MAAM,gBAAgB,CAAC;AAOxB,qEAAqE;AACrE,eAAO,MAAM,WAAW,UAAW,gBAAgB,WAAW,MAAM,KAAG,IAGtE,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,QAAQ,WACX,UAAU,SACX,gBAAgB,KACtB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAK3C,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,cAAc,WAAY,UAAU,QAAQ,MAAM,KAAG,IAOjE,CAAC;AAYF,eAAO,MAAM,QAAQ,WACX,UAAU,QACZ,gBAAgB,UACd,qBAAqB,WACpB,MAAM,KACd,OAAO,CAAC,IAAI,CA0Bd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,SACX,gBAAgB,UACf,qBAAqB,GAAG,SAAS,4BAEhC,MAAM,KACd,OAAO,CAAC,qBAAqB,CA+C/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,WACb,UAAU,UACV,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAed,CAAC"}

package/dist/linux/unit-settle.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The step that decides whether anything on the host actually moves: enablement, running state and
+ * — only for a real change — a restart. Split from unit-lifecycle.ts because it is the rule the
+ * whole family exists to keep, and it should be readable on its own.
+ *
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT. `changed` is set by the caller from the four
+ *   things that earn one (unit-lifecycle.ts reconcileUnit); `configChanged` is a digest the
+ *   DECLARATION itself listed. Nothing else restarts a unit — not a re-run, not an unrelated
+ *   resource in the same deploy, not `--adopt`.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import { type SystemdUnitAttributes, type SystemdUnitProps } from './unit-form.ts';
+import { type UnitStatus } from './systemctl.ts';
+export declare const refuse: (name: string, message: string) => Error;
+export declare const attributesOf: (props: SystemdUnitProps, unitSha256: string, status: UnitStatus) => SystemdUnitAttributes;
+export type Settle = {
+    readonly before: Uint8Array | undefined;
+    /** The unit file or systemd's view of it changed in a way that earns a restart. */
+    readonly changed: boolean;
+    readonly configChanged: boolean;
+    readonly desired: string;
+    readonly path: string;
+    readonly status: UnitStatus;
+};
+/**
+ * Bring enablement and running state to the declaration, restarting ONLY for a real change.
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT: the unit file changed, or a digest the caller
+ *   listed changed. Nothing else — not a re-run, not an unrelated resource, not `--adopt`.
+ */
+export declare const settle: (runner: HostRunner, props: SystemdUnitProps, step: Settle) => Promise<SystemdUnitAttributes>;
+//# sourceMappingURL=unit-settle.d.ts.map

package/dist/linux/unit-settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-settle.d.ts","sourceRoot":"","sources":["../../src/linux/unit-settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAGtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,UAAU,EAQhB,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,MAAM,SAAU,MAAM,WAAW,MAAM,KAAG,KACR,CAAC;AAEhD,eAAO,MAAM,YAAY,UAChB,gBAAgB,cACX,MAAM,UACV,UAAU,KACjB,qBAUD,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,MAAM,WACT,UAAU,SACX,gBAAgB,QACjB,MAAM,KACX,OAAO,CAAC,qBAAqB,CA2C/B,CAAC"}

package/dist/linux/unit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `Systemd.Unit` and `Systemd.Timer` — one systemd unit file and systemd's view of it, declared.
+ *
+ * - create / update — write the unit file atomically, `daemon-reload`, enable or disable, then
+ *   start, stop, or RESTART ONLY when something actually changed (unit-lifecycle.ts settle).
+ * - read — the unit file's SHA-256 plus `systemctl show` (load state, active state, enablement).
+ * - diff — the rendered digest against the stored AND the on-disk one, the declared enablement and
+ *   running state against systemd's, and systemd's own `NeedDaemonReload`.
+ * - replace — only when the unit's name or directory changes, and DELETE FIRST: two unit files for
+ *   one name cannot both be the one systemd reads.
+ * - delete — stop, disable, remove the file, reload.
+ *
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS — see the ⛔ at the top of unit-lifecycle.ts. It is the property
+ *   that lets this family reach a host holding a vault, a clock or a UPS handler.
+ * ⛔ THE UNIT FILE IS NEVER A SECRET (unit-form.ts): it is 0644 and its props sit in state.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`. A unit already on the host reads as `Unowned`; adopting
+ *   one that already matches the declaration does not restart it.
+ * ★ TWO RESOURCES, ONE LIFECYCLE. A timer is a unit whose file ends `.timer` and carries a
+ *   `[Timer]` section; splitting the TYPE rather than the code means a plan says which of the two
+ *   a row is, and a `.service` declared as a timer is a refusal instead of a puzzle.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
+export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
+export interface SystemdUnit extends Resource<'Systemd.Unit', SystemdUnitProps, SystemdUnitAttributes> {
+}
+export interface SystemdTimer extends Resource<'Systemd.Timer', SystemdUnitProps, SystemdUnitAttributes> {
+}
+export declare const SystemdUnit: import("alchemy").ResourceClass<SystemdUnit>;
+export declare const SystemdTimer: import("alchemy").ResourceClass<SystemdTimer>;
+export declare const SystemdUnitProvider: () => import("effect/Layer").Layer<Provider.Provider<SystemdUnit>, never, HostRunnerService>;
+export declare const SystemdTimerProvider: () => import("effect/Layer").Layer<Provider.Provider<SystemdTimer>, never, HostRunnerService>;
+//# sourceMappingURL=unit.d.ts.map

package/dist/linux/unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit.d.ts","sourceRoot":"","sources":["../../src/linux/unit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE3F,MAAM,WAAW,WAAY,SAAQ,QAAQ,CAC3C,cAAc,EACd,gBAAgB,EAChB,qBAAqB,CACtB;CAAG;AAEJ,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAC5C,eAAe,EACf,gBAAgB,EAChB,qBAAqB,CACtB;CAAG;AAEJ,eAAO,MAAM,WAAW,8CAAwC,CAAC;AACjE,eAAO,MAAM,YAAY,+CAA0C,CAAC;AAEpE,eAAO,MAAM,mBAAmB,8FAkB7B,CAAC;AAEJ,eAAO,MAAM,oBAAoB,+FAe9B,CAAC"}