@primafuture/systemd-tasks 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.2.0 — 2026-10-10
+
+- Add observed `finalizeAfterCompletion(reference, { afterRelease, timeoutMs })`:
+  an opt-in transient systemd-owned finalizer survives caller detach and death,
+  confirms payload/guardian cleanup, releases existing retention, and executes
+  one bounded native after-release command with finite stdin.
+- Bind repeated registrations to the exact reference and callback, preserve
+  truthful registration outcomes, and collect the finalizer itself after exit.
+- Cover post-payload reads with the same finalization deadline and honor native
+  callback stop grace through manager-owned cgroup termination.
+- Keep default retention, existing intent/reference formats, manual lifecycle,
+  and output ownership unchanged.
+
+## 1.1.0 — 2026-09-17 (local candidate)
+
+- Add the `@primafuture/systemd-tasks/observed` entrypoint with immutable
+  JSON-safe intents, finite manager-owned stdin, live binary stdout/stderr, and
+  separate payload/guardian lifecycle evidence.
+- Create payload, retention, and `Type=notify` guardian services in one atomic
+  transaction. Both process services require successful retention initialization;
+  payload stop propagates to a drain-aware guardian even when exec was cancelled.
+  Fail closed when the guardian dies, while allowing it to drain output after
+  payload exit, stop, timeout, client detach, or client death.
+- Add a versioned bounded guardian protocol, sequential asynchronous callback
+  backpressure, explicit local detach, and stable `OBSERVATION_FAILED` errors.
+  Reconnect, replay, and stream adoption remain deliberately unsupported.
+- Generalize the existing D-Bus adapter to an ordered auxiliary-unit topology and
+  share transport ownership, mutation serialization, notification routing,
+  cleanup, diagnostics, and `TaskError` identity across root/observed APIs and
+  mixed ESM/CommonJS loading.
+- Upgrade the external native transport to the exact published
+  `@primafuture/socket-fdx@1.1.0` release and use its owned `socketPair()` and
+  `adoptSocket()` primitives.
+- Extend deterministic, real-systemd, installed ESM/CommonJS, and TypeScript
+  consumer tests, including the real 512 KiB stdin boundary, partial socket
+  allocation rollback, pre-readiness detach, cross-client pre-exec stop, final
+  output under slow-callback backpressure during explicit stop, 32 MiB per-channel draining, and guardian
+  fail-closed behavior. Detach also settles independently of an already-pending
+  application callback. No npm publish was performed.
+
 ## 1.0.0 — 2026-09-07
 
 - Add explicit preparation, single-attempt submission, lookup, inspection, waiting,

package/README.md

@@ -4,7 +4,7 @@ Run one-shot Linux processes owned by the **systemd user manager**, with literal
 arguments, binary file-descriptor I/O, manager-owned timeouts, and recoverable
 results after the Node client exits or crashes.
 
-Version 1.0.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
+Version 1.2.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
 and cgroup v2. The verified environment
 is Node 24.13.0, systemd 257.9-0ubuntu2.4, Linux 6.17.0-14-generic, x86-64.
 Other versions satisfying those minimums are not independently verified.
@@ -15,11 +15,12 @@ Other versions satisfying those minimums are not independently verified.
 npm install @primafuture/systemd-tasks
 ```
 
-The pinned native dependency `@primafuture/socket-fdx@1.0.0` is installed under
-the npm alias `usocket` and supplies its compatible `USocket` adapter. It ships a
-prebuilt native binary: ordinary installation needs no compiler, Python, or install
-scripts. Consumers do not need `overrides`. The dependency is pinned to its stable release;
-musl Linux and other architectures are outside its current support. The JavaScript D-Bus stack
+The native dependency `@primafuture/socket-fdx@1.1.0` is installed under the npm
+alias `usocket` and supplies both the D-Bus adapter and explicitly owned Unix
+socket-pair primitives. It is pinned to the exact published release and ships a
+prebuilt native binary, so ordinary installation needs no compiler, Python, install
+scripts, or consumer override. Musl Linux and other architectures remain unsupported.
+The JavaScript D-Bus stack
 (`dbus-next@0.10.2` and its dependencies) is bundled; licenses are recorded in
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
@@ -29,6 +30,9 @@ that the retention executable resolves to a regular executable file before openi
 the bus, then verifies the manager environment. It fails explicitly; the library does not provision a manager,
 enable linger, request elevated privileges, or fall back to child_process.
 Importing either the ESM or CommonJS entrypoint does not connect or start a process.
+Observed tasks additionally require `/usr/bin/systemd-notify`, `/usr/bin/systemctl`,
+and the packaged guardian bundle; `connectObserved()` verifies them before opening
+the bus.
 
 ## Basic execution
 
@@ -70,6 +74,133 @@ environment that are absent from this map, using a snapshot immediately before
 submission. Systemd may add execution metadata such as `INVOCATION_ID`. Concurrent
 external changes to manager configuration are outside this guarantee.
 
+## Observed execution
+
+The separate `@primafuture/systemd-tasks/observed` entrypoint adds live binary
+stdout/stderr delivery without wrapping the payload process:
+
+```ts
+import * as observed from '@primafuture/systemd-tasks/observed';
+
+const intent = observed.prepareObserved({
+	executable: '/usr/bin/sort',
+	argv: [],
+	cwd: '/tmp',
+	env: {},
+	runtimeLimitMs: 5000,
+	stopGraceMs: 500,
+	stdin: 'second\nfirst\n',
+});
+
+const client = await observed.connectObserved();
+try {
+	const started = await client.startObserved(intent, {
+		async onOutput(event) {
+			// Awaiting here applies bounded backpressure to both output channels.
+			await consume(event.stream, event.data);
+		},
+	});
+	await started.observation.completion;
+	const completed = await client.wait(intent, { timeoutMs: 10000 });
+	await client.release(completed.reference);
+} finally {
+	await client.disconnect();
+}
+```
+
+`stdin` is mandatory. A string is snapshotted as UTF-8, a `Uint8Array` is copied,
+an empty value remains an explicit empty data input, and `null` selects `/dev/null`.
+The fixed limit is 512 KiB, chosen to remain below systemd's manager-state line
+serialization boundary after base64 expansion. The canonical base64 snapshot is
+part of the serialized intent and its fingerprint. Systemd owns `StandardInputData` after submission and
+may retain those bytes in manager state until release, so treat the intent and
+manager access as sensitive when stdin contains secrets.
+
+Each observed task consists of payload, retention, and `Type=notify` guardian
+services created by one `StartTransientUnit` transaction. The payload is ordered
+after and `BindsTo` the guardian; both process services require successful
+retention initialization. `startObserved()` returns only after manager
+acceptance and guardian readiness, with a fixed five-second readiness budget. A
+failure after manager acceptance reports `mutationOutcome: 'accepted'`; it is not
+permission to retry.
+
+Output callbacks are sequential and their returned promises provide real bounded
+backpressure. Callback failure rejects `observation.completion` with
+`OBSERVATION_FAILED` and detaches locally; it does not stop the payload. `detach()`
+and `disconnect()` likewise close only the local observer. The guardian continues
+to drain and discard both channels so the payload does not receive `EPIPE` merely
+because the client left. There is deliberately no reconnect, replay, or adoption
+of another client's live stream. Use ordinary durable file I/O instead when output
+must survive observation loss.
+
+An already-invoked callback is application code and cannot be cancelled. Explicit
+detach closes the socket and settles `completion` as `detached` without waiting for
+that callback promise; no later callback is invoked, and a later settlement of the
+detached callback cannot change the observation outcome or block `disconnect()`.
+
+The guardian emits a private versioned binary protocol with separate stdout and
+stderr frames. Payload bytes and callback causes are never included in diagnostics.
+`wait()` reports payload and guardian results independently and reaches `completed`
+only after both services are terminal with confirmed empty cgroups. `stop()` targets
+the payload; systemd propagates that stop to the guardian in reverse dependency
+order, so it drains bytes already written before completing. This also closes a
+guardian whose payload start was cancelled before exec. `release()` refuses until
+both process services are clean, then removes retention.
+
+### Automatic finalization of a background task
+
+Observed clients can explicitly hand completion to the user manager:
+
+```ts
+const found = await client.lookup(intent);
+if (found.status === 'found' && found.snapshot.identity === 'complete') {
+	await client.finalizeAfterCompletion(found.reference, {
+		timeoutMs: 30000,
+		afterRelease: {
+			executable: '/absolute/path/to/node',
+			argv: ['/absolute/path/to/application.mjs', '--finish-owned-record'],
+			cwd: '/absolute/application/directory',
+			env: {},
+			runtimeLimitMs: 10000,
+			stopGraceMs: 1000,
+			stdin: JSON.stringify({ generation: 'application-owned-generation' }),
+		},
+	});
+}
+```
+
+Register after persisting the exact reference and before advertising the background
+task as ready. A separate transient finalizer survives observer detach, CLI exit,
+and death of the original client. It does not stop the original task. It waits for
+payload termination and confirmed payload/guardian cleanup, uses the existing
+`release()` checks, and then executes the finite native command once, without a
+shell, inherited environment, or output replay. The command runs in the finalizer's
+own systemd control group; its output is discarded. The finalizer is collected
+after it exits, including failure. Safe error metadata remains in the journal.
+
+`timeoutMs` is one shared deadline for lookup, cleanup, release, and the
+after-release command once the finalizer confirms payload termination. It does
+not bound the task's active lifetime or restart for each phase. Callback runtime
+is also limited by its non-null `runtimeLimitMs`, when supplied. On timeout the
+finalizer exits; systemd stops its remaining command processes with `SIGTERM`,
+allows `stopGraceMs`, and escalates to `SIGKILL` only if necessary. Stop grace is
+a separate bounded cleanup interval, not additional execution time. The callback
+may not be a resident service. A timed-out read or release never starts the callback.
+
+The receipt says `accepted` or `already-registered`, not `completed`. An identical
+registration while the finalizer exists does not create another callback. A
+different callback for the same task is a conflict. An unknown registration outcome
+must be reconciled before proceeding; never blindly submit a replacement task.
+Failed cleanup does not execute the callback. Callback failure does not restore
+released task results or automatically retry the callback.
+
+This is deliberately opt-in and does not change the default retention policy.
+After handing finalization off, do not rely on a late `wait()` retaining an exit
+result: release can win that race. Applications should confirm their own cleanup
+effect plus absence of the exact task rather than fabricate an exit status. The
+callback must condition its own changes on its persisted generation. Recovery is
+still required for a client death before registration and for manager restart.
+
 ## Lifecycle and recovery
 
 | Operation | Contract |
@@ -83,6 +214,7 @@ external changes to manager configuration are outside this guarantee.
 | `stop(reference, options?)` | Request manager stop; `wait: true` additionally waits for cleanup. |
 | `release(reference, options?)` | Refuse live tasks, then discard owned result retention. Never deletes logs. |
 | `disconnect()` | Release local socket/listeners only; tasks keep running. Idempotent. |
+| Observed `finalizeAfterCompletion(reference, options)` | Register exact manager-owned cleanup followed by one finite native command. Opt-in, not a completion receipt. |
 
 Save the **intent before calling start**, then save an observed reference and final
 result as they become available. Intents contain the command and environment,
@@ -206,7 +338,7 @@ service manipulation can invalidate evidence. The library does not enable linger
 recreate missing tasks, implement a daemon, or promise survival when the manager
 itself stops. Connection failure is distinct from missing units.
 
-The only advanced properties allowed in 1.0.0 are `CPUWeight` and `IOWeight`, each
+The only advanced properties allowed in 1.x are `CPUWeight` and `IOWeight`, each
 with signature `'t'` and an integer value from 1 to 10000. Duplicates, unknown
 properties, and lifecycle overrides are rejected before mutation. Kernel/controller
 configuration determines the practical scheduling effect of those weights.
@@ -228,7 +360,8 @@ npm run check
 `check` runs strict typechecking, unit tests, real systemd integration tests, dual
 ESM/CJS build, and tarball runtime/type smoke tests. `prepublishOnly` invokes the
 same chain. Integration tests fail explicitly when prerequisites are missing.
-Tests create unique identities and clean only their recorded task/retention pairs.
+Tests create unique identities and clean only their recorded task/retention pairs,
+plus the exact guardian identity for observed tests.
 They do not restart the user manager or change host configuration.
 
 Runnable repository examples after `npm run build`:

package/THIRD_PARTY_NOTICES.md

@@ -25,7 +25,7 @@ This file is generated by `scripts/licenses.ts` from the distributed source map.
 
 ## External native dependency
 
-`@primafuture/socket-fdx` 1.0.0 (ISC) is installed separately under the npm alias `usocket`. It ships its native binary, license, and third-party notices, has no runtime dependencies, and is not embedded in this JavaScript bundle. The direct pinned alias applies in consumer installations without root overrides.
+`@primafuture/socket-fdx` 1.1.0 (ISC) is installed separately under the npm alias `usocket`. It ships its native binary, license, and third-party notices, has no runtime dependencies, and is not embedded in this JavaScript bundle. The direct pinned alias applies in consumer installations without root overrides.
 
 ## @nornagon/put 0.0.8