@primafuture/systemd-tasks 1.0.0

package/docs/implementation-decisions.md

@@ -0,0 +1,323 @@
+# Implementation decisions and evidence
+
+## Maintainer-approved platform amendment
+
+During the published socket-fdx migration, the maintainer explicitly selected
+**Node 24.13.0+, Linux x64, glibc 2.28+** as this version's supported runtime.
+This decision supersedes the original broader Node 24+/Linux wording for platform
+support only. The original `IMPLEMENTATION.md` and `specification.md` were used
+unchanged during implementation and independent review, then removed at the
+maintainer's request when preparing version 1.0.0. All other requirements, including systemd 257+,
+cgroup v2, lifecycle guarantees, and T01–T18, remain applicable.
+
+## Feasibility checkpoint
+
+The initial Node experiments ran on 2026-09-07 with Node 24.13.0, npm 11.16.0,
+systemd 257.9-0ubuntu2.4, Linux 6.17.0-14-generic, and the existing user manager.
+The manager reported `degraded`; it was reachable and the isolated task scenarios
+worked. No manager configuration, linger, permissions, or existing service was changed.
+
+Reproduction commands from the project directory:
+
+```sh
+node scripts/probe.mjs
+node scripts/feasibility.mjs
+node scripts/recovery-probe.mjs
+```
+
+Each experiment creates unique `pf-systemd-tasks-*` identities. Its cleanup is
+restricted to those exact task/retention pairs. Generated output stays inside the
+project. `feasibility.mjs` launches separate Node clients and observers and sends
+SIGKILL to the client after creation or stop acceptance. This is actual Node/D-Bus
+integration, not a `systemd-run` wrapper test.
+
+Observed before implementing the public API:
+
+| Scenario | Observation |
+| --- | --- |
+| Literal argv, cwd, environment | Empty arguments, spaces, Unicode, quotes, `$`, and `%` survived direct `ExecStartEx` with `no-env-expand`. |
+| Unix FD and binary output | Bytes `00 ff 80 0a` survived; the caller's FD remained open after acceptance and could then be closed. |
+| Client death with file output | A service finished and wrote output after its Node client was SIGKILLed; a fresh Node observer recovered the result. |
+| Success and application failure | Exit 0 and 7 remained observable after client death, with raw `success` and `exit-code` respectively. |
+| Execution failure | Missing executable produced status 203 without entering the active state; an application deliberately returning 203 did enter it. Missing cwd produced status 200 without entering active. |
+| Signal and runtime deadline | SIGKILL produced raw `signal`; a TERM-resistant task reached SIGKILL through the manager's runtime/stop timers and produced raw `timeout`. |
+| Accepted stop followed by client death | The manager completed escalation without the requesting client. |
+| Main exit and descendant cleanup | A detached (`setsid`) TERM-resistant descendant was gone before completion; main exit 0 remained available even though cleanup escalation produced raw `timeout`. |
+| Lost application reply | A client abandoned its start promise and was killed after submission; lookup recovered the run, and an explicit colliding start was rejected. This is loss at the application boundary; precise wire loss is covered separately by injected transport tests. |
+| Release and replacement | Releasing the pair allowed collection; an explicitly authorized experiment reusing the name received a different InvocationID. |
+| Retention initialization failure | A missing retention executable prevented execution of the user command. The task had no InvocationID and no main exit evidence. |
+
+An inactive unit with a pending start job is **not** complete. The experiment caught
+this race; completion must also inspect the job and cgroup state. `Result=timeout`
+alone cannot identify a runtime deadline: it can also describe stop or descendant
+cleanup escalation. The API must preserve these distinctions without inventing causes.
+
+## Retention mechanism
+
+Create the task and auxiliary service in one `StartTransientUnit` request, using
+job mode `fail`. The task has `Requires` and `After` dependencies on its uniquely
+named retention service. The auxiliary service runs `/usr/bin/true` with
+`Type=oneshot`, `RemainAfterExit=yes`, and `Before` referencing the task. Therefore
+retention activation precedes task execution, and the active auxiliary service
+keeps the task referenced after termination without a living helper process.
+
+The task uses `Type=exec`, `ExitType=main`, `KillMode=control-group`, `Restart=no`,
+and manager-owned stop/runtime timers. It does not use `RemainAfterExit` itself.
+Release checks both identities and completion before removing retention. Failed
+states must also be reset to permit garbage collection. Stop may replace pending
+jobs to cancel a queued start; creation never uses replacement or restart.
+
+This relies on the [systemd 257 dependency-based garbage collection contract](https://github.com/systemd/systemd/blob/v257/man/systemd.unit.xml)
+and the [257 service lifecycle](https://github.com/systemd/systemd/blob/v257/src/core/service.c).
+It does not provide persistence across manager restart or reboot, or protection
+against another equally privileged process changing these units.
+
+## Transport and native installation
+
+The current transport is `dbus-next` 0.10.2 (MIT) with the published
+`@primafuture/socket-fdx` 1.0.0 (ISC), installed under the direct npm alias
+`usocket`. Its root export provides the compatible `USocket` constructor. No
+installed dependency files or global prototypes are patched.
+
+The following records the superseded feasibility candidates, not the current
+runtime dependencies.
+The originally requested `usocket` 0.3.0 failed to build: its node-gyp 7.1.2 reported
+`Completion callback never invoked!` with Node 24.13.0 and Python 3.13.7. Because
+that dependency is optional upstream, an apparently successful npm installation
+silently omitted FD support. Connection must explicitly reject that condition.
+
+`usocket` 1.0.3 built and transmitted descriptors using NAN 2.25.0 and node-gyp
+12.4.0, with the host's Python 3.13.7, make, and C++ compiler. Python is a native
+build prerequisite, not a runtime dependency of task execution. Version 1.1.0
+also built, but its node-gyp 13 dependency declares a newer Node minimum than the
+tested 24.13.0; it was not selected.
+
+The build bundles the pinned JavaScript D-Bus implementation and its resolved
+JavaScript dependencies, while leaving `usocket` as a pinned external runtime
+dependency. This makes the selected native version effective in consumer projects:
+npm overrides in a published dependency do not control the consumer's resolution.
+The development override also selects xml2js 0.6.2 instead of the vulnerable older
+release. Licensing notices accompany bundled dependencies. No D-Bus wire protocol
+is implemented by this library.
+
+The transport adapter must bound pending calls and explicitly destroy the native
+socket at disconnect. It uses a small, documented set of pinned transport internals
+for FD capability checks and abandoned-call cleanup. Upstream maintenance age,
+native compatibility, and these internal hooks are maintenance risks. Connection
+preflight awaits non-FD D-Bus replies before returning a usable client, so the
+first FD-bearing request follows the daemon's completed Hello exchange.
+
+The replacement ships a Linux x64/glibc 2.28+ prebuild and requires Node 24.13.0+.
+It has no runtime dependencies or install hook. Its Node-API boundary also uses
+libuv, so arbitrary future ABI compatibility is not assumed. This project's
+consumer smoke installs with `--ignore-scripts` and no overrides, checks the actual
+aliased package identity and loaded `.node` binary, and executes tasks using FDs.
+
+## Environment and execution evidence
+
+Before submission, read the manager environment and place inherited names absent
+from the explicit map in `UnsetEnvironment`. Do not change the manager environment.
+Systemd still supplies its own execution metadata. The experiment observed
+`MANAGERPID`, `INVOCATION_ID`, `SYSTEMD_EXEC_PID`, `MEMORY_PRESSURE_WATCH`, and
+`MEMORY_PRESSURE_WRITE`. This is not a byte-for-byte promise for the whole environment.
+Concurrent external changes to manager configuration are outside the isolation
+guarantee and must be documented.
+
+Retained active-entry timestamps under `Type=exec`, main-exit fields, and raw
+systemd results form the execution evidence. Numeric status 203 alone is not an
+execution-failure classifier. If the manager never executed the main process,
+the absence of an invocation and exit evidence remains explicit.
+
+## Supported baseline
+
+V1 requires Node 24.13.0+ on Linux x64 with glibc 2.28+,
+a local user manager with systemd 257 or newer,
+Unix FD negotiation, and a cgroup v2 hierarchy. Version 257 is a conservative
+baseline for the experimentally verified mapping; older releases are not claimed.
+Only the concrete versions recorded above have been exercised at this checkpoint.
+
+## Final API and packaged verification
+
+The frozen format is version 1. Intents include the normalized specification and
+its SHA-256 fingerprint; references omit the specification and bind local UID,
+machine ID, boot ID, bus ID, manager bus owner, and both service InvocationIDs.
+An unavailable ID is null, never a wildcard for a later invocation. Manager changes
+invalidate the connection; there is no implicit reconnect. Equal-privilege external
+unit replacement remains a read/check/mutate race because the systemd methods
+accept a unit name rather than an InvocationID precondition.
+
+The build bundles 16 JavaScript packages and generates full attribution from the
+actual source map. The pinned `socket-fdx` alias remains external. Both conditional
+declaration branches are tested with strict NodeNext TypeScript consumers.
+Installation is performed with scripts disabled. The smoke consumer has its own manifest and
+node_modules under a fresh `.artifacts/package-smoke-*` directory, separate from
+`src`, and imports only the installed tarball. A test-only CommonJS resolver guard
+rejects absolute resolutions outside that consumer to exclude ancestor packages
+(including optional `debug`/`supports-color` probes). Runtime require-cache checks
+also reject dependency leakage. This is dependency isolation within the authorized
+workspace, not a container or a second physical host.
+
+The runtime artifacts import without a native connection. The unsupported-platform
+smoke uses an injected `process.platform` value; no macOS or Windows execution is
+claimed. The native package has no transitive runtime dependencies. Native ABI,
+upstream maintenance, and reliance on pinned dbus-next internals require continued
+maintenance and fresh packaged verification when upgrading.
+
+Reproduce the final checks with:
+
+```sh
+npm run check
+npm run test:integration
+```
+
+The second command repeats the real lifecycle suite, including the crash matrix,
+retention, immediate exits, and descriptor leak checks. The following table maps
+all acceptance scenarios to concrete evidence. `unit/` and `integration/` paths
+are relative to `__tests__` in the repository; those sources are not published.
+
+| ID | Evidence | Boundary |
+| --- | --- | --- |
+| T01 | `integration/execution.test.ts`, `unit/validation.test.ts`: literal argv, cwd, explicit env, immutable serializable preparation | Real executable and local validation |
+| T02 | `integration/execution.test.ts`: binary input/output, separate channels, 32 MiB direct file output; crash matrix exits 0 and 7 | Real FDs and bounded observed RSS; not an arbitrary-volume benchmark |
+| T03 | `integration/execution.test.ts`, `unit/io.test.ts`, `integration/faults.test.ts`: missing exec/cwd, executable permissions, I/O failures, status 203 distinction | Real OS errors; explicit D-Bus permission rejection injected |
+| T04 | `integration/execution.test.ts`, `unit/evidence.test.ts`: signal, runtime escalation, raw result classification | Real manager timers plus deterministic evidence classification |
+| T05 | `integration/execution.test.ts`, `unit/evidence.test.ts`: setsid TERM-resistant descendant disappears before completion; unreadable/populated cleanup never reports complete | Real descendant/cgroup behavior; incomplete evidence injected |
+| T06 | `integration/crash.test.ts`: submitting Node process SIGKILL, fresh Node observer, retained file output | Real processes, two rounds per retained outcome |
+| T07 | `integration/crash.test.ts`, `unit/lifecycle.test.ts`: accepted stop followed by stopping-client SIGKILL; cancellation delivery stages | Real escalation; precise cancellation timing injected |
+| T08 | `integration/crash.test.ts`, `integration/lifecycle.test.ts`: runtime deadline without client, local abort/timeout leaves task and other waiter alive | Real manager and concurrent clients |
+| T09 | `integration/faults.test.ts`, `unit/lifecycle.test.ts`, `scripts/feasibility.mjs`: lost reply, late recovery, missing unit, auxiliary collision and initialization failure | Actual accepted task with reply loss injected at adapter boundary; real collisions/failure; absent-after-unknown simulated |
+| T10 | `integration/crash.test.ts`: success, exit 7, exec failure, signal, timeout, stop retained until explicit release | Real client deaths and fresh observers; repeated matrix |
+| T11 | `integration/lifecycle.test.ts`, `integration/faults.test.ts`, `unit/lifecycle.test.ts`, `unit/evidence.test.ts`: recreated name, stale IDs, collisions, manager mismatch, incomplete reference | Real replacement/collision; alternate manager identity injected |
+| T12 | `integration/lifecycle.test.ts`, `unit/lifecycle.test.ts`: 25 FD-bearing tasks with multiple waiters, abort, snapshot race, pending job, actual overlapping stop/release and deferred stop acknowledgment/cancellation | Real repetition and overlapping calls plus deterministic event ordering |
+| T13 | `integration/faults.test.ts`, `unit/lifecycle.test.ts`: lost reads/mutations, permission vs NoReply, disconnect with pending waits | Adapter failures injected around real calls and fake transport; no manager shutdown |
+| T14 | `integration/execution.test.ts`, `integration/lifecycle.test.ts`, `integration/faults.test.ts`, `integration/pipes.test.ts`, `unit/io.test.ts`: borrowed ownership, repeated FD-bearing execution and manager rejection counts, partial-open leaks, descriptor cleanup after disconnect | Real descriptors, native transport, Linux /proc measurements |
+| T15 | `integration/pipes.test.ts`, `integration/lifecycle.test.ts`, `unit/io.test.ts`: append/truncate, hard-link coalescing, error side effects, EPIPE and EOF | Real files, FIFO-backed Unix pipes, and execution failures |
+| T16 | `integration/lifecycle.test.ts`, `integration/crash.test.ts`, `unit/lifecycle.test.ts`: refuse live release, repeat release, preserve logs, independent total deadline, preserve reset/stop acknowledgment across timeout | Real retention and deterministic delayed observations |
+| T17 | `unit/validation.test.ts`, `unit/environment.test.ts`, `scripts/smoke.ts`: invalid inputs, retention prerequisites, native architecture/libc rejection, simulated unsupported platform | Pure validation, isolated filesystem/native-loader faults through public connect, and installed import/connect check |
+| T18 | `scripts/smoke.ts`: npm tarball install without scripts or overrides, published alias/native binary identity, ESM/CJS binary execution and release, .mts/.cts consumer types, artifact allowlist | Real installed artifact with ancestor-module isolation |
+
+The runnable examples also exercise basic execution, fsynced intent before start,
+a separate recovery process, fsynced result before release, local wait timeout,
+manager runtime timeout, and explicit stop escalation. Their task IDs and output
+records are saved under `.artifacts/examples`.
+
+## Explicit limitations of the evidence
+
+Only Node 24.13.0 on Linux x86-64 and systemd 257.9 were run. Other Node minors,
+architectures, distributions, kernel/controller combinations, newer systemd,
+containers, restricted buses, and alternative native build toolchains are unverified.
+The suite does not deliberately reboot the machine, stop/restart the user's manager,
+change its environment, change linger, or change access policy. Manager restart,
+bus loss, exact lost replies, and permission categories are represented by injected
+boundaries where indicated above. Retention across actual manager shutdown is not
+part of the contract. Cgroup escape by privileged code and hostile external changes
+to owned units or I/O paths are outside the guarantee.
+
+## Acceptance result — 2026-09-07
+
+All T01–T18 scenarios above passed within their stated evidence boundaries.
+`npm run check` completed with 28 unit tests and 30 real integration tests passing,
+zero skipped tests, a successful dual-format build, and all packaged runtime/type
+smoke checks passing. A separate repeat of the integration suite passed all 30 tests
+again. All four runnable example entrypoints completed successfully. After cleanup,
+no `pf-systemd-tasks-*` units remained loaded in the user manager. The complete
+locked dependency audit reported zero known vulnerabilities at verification time;
+that is a dated registry result, not a guarantee of absence of vulnerabilities.
+
+## Independent review follow-up
+
+The fresh review `2026-09-07_09-34-45` requested changes despite the passing baseline
+suite. The original acceptance result above describes that baseline, not final
+review approval. Two issues were confirmed:
+
+- Connection preflight did not verify its fixed retention executable. `connect()`
+  now checks that `/usr/bin/true` resolves to a regular file with execute access,
+  reporting `UNSUPPORTED_ENVIRONMENT` before opening the bus. Three isolated
+  filesystem-fault tests exercise missing, non-regular, and non-executable cases
+  through the public `connect()` API without changing the host executable.
+- Upstream `usocket@1.0.3` loses its FD array after a zero-byte native write. A
+  deterministic reproduction with two queued messages confirmed the missing FDs
+  on repeated drain attempts. The native loop also retains `msghdr.msg_control`
+  after clearing its local FD vector, permitting duplicate control payloads if a
+  single native call performs multiple successful partial sends.
+
+The upstream dependency is now replaced by the independently implemented,
+published `@primafuture/socket-fdx@1.0.0`. Its shipped
+`docs/architecture-and-evidence.md` records F04/F05 native regressions: repeated
+EAGAIN preserves descriptors, positive partial sends deliver them once, and an
+independent receiver detects deliberately broken ancillary reuse as a negative
+control. These are the dependency's recorded evidence, not tests rerun by this
+consumer. This project verifies the published adapter through its own real systemd
+integration and installed-package checks. The earlier patch draft is historical
+only; no vendored patch or node_modules mutation is used.
+
+The unused internal transport-version field was removed. Test callback comments
+now describe their fixture boundary or the reason for an assertion, rather than
+repeating the adjacent test title.
+
+## Published socket-fdx migration verification
+
+The initial migration used registry package `@primafuture/socket-fdx@0.1.0-rc.0` with integrity
+`sha512-9BjkqES7Jx/SQvk8Gzpj0BRcKhJPh0kQHNi9SsAPr7vM3LuVIH8hsYLcHQihxRExi+AEQrM07buq0lWn4TNVQA==`.
+`npm ls usocket --all` resolves both the direct runtime dependency and development
+dbus-next dependency to that single alias. The old NAN/node-gyp runtime dependency
+closure is removed. The package remains external to the D-Bus JavaScript bundle.
+
+`npm run check` passed 31 unit tests and 30 integration tests, followed by the
+dual-format build and installed runtime/type smoke. A preceding separate integration
+run also passed all 30 tests. Consumer installation used no overrides and disabled
+install scripts; both module formats loaded the shipped socket-fdx native binary
+and completed real binary FD output and release. The production dependency audit
+reported zero known vulnerabilities. These results use the host environment
+recorded above; the dependency's wider build matrix is not a downstream verification
+claim for this project. Independent review is a separate gate from these checks.
+
+The continuation review identified native environment error misclassification and
+gaps in T12/T14 coverage. Native platform, ABI, and missing-binary codes now map to
+`UNSUPPORTED_ENVIRONMENT`; public connection tests inject architecture and libc
+capabilities without modifying the host. Two deferred-reply tests overlap stop
+and release through completion and cancellation, and a real manager test overlaps
+stop-with-wait and release. The 25-iteration loop now sends real output descriptors
+and checks output plus per-iteration FD counts, including execution failures.
+Eight real FD-bearing requests rejected by the manager also return to the original
+FD count; disconnect checks confirm release of each connection's bus socket.
+The revised `npm run check` passed 36 unit tests, 32 integration tests, both builds,
+and all isolated package smoke checks, with no skipped tests.
+
+The maintainer then requested the stable published `@primafuture/socket-fdx@1.0.0`.
+The direct alias and installed-artifact identity assertion now pin that version;
+its registry integrity is
+`sha512-ASACXfVCDTUV2UQYh/mjTJ0HEbFjEZYkmZSV9HxMJ1YGmWVRcflwNlS2q83ucWypSzDIfG+HgbE2pxzU6XI+fA==`.
+The installed native binary and both JavaScript runtime entrypoints have identical
+SHA-256 hashes to the reviewed release candidate. The native SHA-256 is
+`9ca53cde1620155c96e91a836f450ee43a6d8dcb339050c39107c5a87ccd7ae1`.
+Both development and runtime dependency branches resolve to the stable alias.
+The full aggregate check was rerun against 1.0.0 and passed the same 36 unit and
+32 integration tests, dual-format build, and all installed-artifact smoke checks.
+The full locked dependency audit reported zero known vulnerabilities at that check.
+
+A subsequent independent review found two additional defects. Release no longer
+reuses a single-request transport budget for the entire multi-request sequence.
+Its optional `ReleaseOptions` provide an independent total timeout (5000 ms by
+default) and abort signal. Acknowledged reset and stop mutations retain accepted
+delivery evidence if later observation times out; explicit absence remains a no-op.
+Tests exercise individually timely reads whose sum exceeds the transport budget,
+timeouts after reset/stop acknowledgment, and pre-submission cancellation.
+
+Diagnostics now consume returned promises and thenables without awaiting them.
+A separate child process under `--unhandled-rejections=strict` verifies delayed
+sink rejection, rejecting thenables, and a never-settling observer, while accepted
+task submission and disconnect still complete and no global rejection escapes.
+The aggregate check after these fixes passed 41 unit tests, 32 real integration
+tests, type checking, both distribution formats, and the isolated package smoke
+with `ReleaseOptions` checked through both declaration branches.
+
+Mixed release outcomes now retain a separate `acceptedCleanupMutations` count.
+A later rejected/not-submitted step cannot overwrite earlier confirmed effects as
+though the entire release were rejected. Later unknown delivery remains unknown,
+while the count preserves preceding acknowledgments. Nine deterministic cases
+cover rejection, non-submission, and uncertain delivery at each of the main reset,
+retention reset, and retention stop boundaries. The unused raw object-path field
+was removed; transport paths remain local to the D-Bus request that needs them.
+The aggregate check passed 50 unit tests, 32 real integration tests, both builds,
+and installed runtime/type verification including partial-cleanup error metadata.

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "@primafuture/systemd-tasks",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "One-shot process tasks owned by the systemd user manager.",
+	"author": "PrimaFuture.cz s.r.o. <dev@primafuture.cz>",
+	"license": "ISC",
+	"engines": {
+		"node": ">=24.13.0"
+	},
+	"dependencies": {
+		"usocket": "npm:@primafuture/socket-fdx@1.0.0"
+	},
+	"overrides": {
+		"dbus-next": {
+			"usocket": "$usocket",
+			"xml2js": "0.6.2"
+		}
+	},
+	"devDependencies": {
+		"@types/node": "24.13.3",
+		"tsup": "8.5.0",
+		"tsx": "4.20.6",
+		"typescript": "5.9.3",
+		"dbus-next": "0.10.2"
+	},
+	"sideEffects": false,
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD_PARTY_NOTICES.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup && tsx scripts/licenses.ts",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.dev.json --noEmit",
+		"test": "node --import tsx --test --test-timeout=15000 __tests__/unit/*.test.ts",
+		"test:integration": "node --import tsx --test --test-concurrency=1 __tests__/integration/*.test.ts",
+		"smoke": "tsx scripts/smoke.ts",
+		"check": "npm run typecheck && npm test && npm run test:integration && npm run build && npm run smoke",
+		"prepublishOnly": "npm run check"
+	}
+}