@primafuture/systemd-tasks 1.0.0 → 1.1.0

package/dist/runtime.d.cts

@@ -0,0 +1,467 @@
+import * as util from 'node:util';
+
+/** A deliberately small allowlist of properties that cannot replace task lifecycle policy. */
+interface SystemdProperty {
+    /** The resource weight to pass to the transient service. */
+    readonly name: 'CPUWeight' | 'IOWeight';
+    /** The systemd D-Bus signature, independent of the transport implementation. */
+    readonly signature: 't';
+    /** An integer resource weight from 1 through 10000. */
+    readonly value: number;
+}
+/** A command specification suitable for serialization before any attempt to execute it. */
+interface TaskSpec {
+    /** Absolute executable path; no PATH lookup or shell is performed. */
+    readonly executable: string;
+    /** Literal arguments excluding argv[0], which is the executable path. */
+    readonly argv: readonly string[];
+    /** Absolute working directory, which must already exist at execution time. */
+    readonly cwd: string;
+    /** Explicit environment entries; systemd may add its own execution metadata. */
+    readonly env: Readonly<Record<string, string>>;
+    /** Positive integer milliseconds, or null to explicitly disable the runtime limit. */
+    readonly runtimeLimitMs: number | null;
+    /** Positive integer milliseconds before manager-owned SIGKILL escalation. */
+    readonly stopGraceMs: number;
+    /** Optional resource weights; all other low-level properties are reserved. */
+    readonly systemdProperties?: readonly SystemdProperty[];
+}
+/** Common serializable ownership evidence, without environment or command arguments. */
+interface TaskIdentity {
+    /** Serialization version understood by this library. */
+    readonly version: 1;
+    /** Random UUID generated before submission. */
+    readonly id: string;
+    /** Unique transient service name derived from the ID. */
+    readonly unitName: string;
+    /** Unique auxiliary service name derived from the same ID. */
+    readonly retentionUnitName: string;
+    /** V1 supports the local user manager only. */
+    readonly managerScope: 'user';
+    /** SHA-256 fingerprint of the normalized task specification. */
+    readonly fingerprint: string;
+}
+/** A prepared intention; saving it does not imply that execution was attempted. */
+interface TaskIntent extends TaskIdentity {
+    /** Absence of the observed discriminator keeps both serialized intent families disjoint. */
+    readonly kind?: never;
+    /** Execution configuration, potentially containing secrets; store accordingly. */
+    readonly spec: TaskSpec;
+}
+/** Identity of the specific environment in which a task was observed. */
+interface ManagerIdentity {
+    /** Manager privilege scope; system-manager references are not supported in V1. */
+    readonly scope: 'user';
+    /** Effective local UID whose user bus owns the task. */
+    readonly uid: number;
+    /** Machine identity reported by the manager's D-Bus peer. */
+    readonly machineId: string;
+    /** Local kernel boot identity, preventing cross-boot adoption. */
+    readonly bootId: string;
+    /** Unique identity of the user message bus. */
+    readonly busId: string;
+    /** Unique bus owner of org.freedesktop.systemd1 at connection time. */
+    readonly owner: string;
+}
+/** An observed pair of unit instances; null IDs explicitly mean incomplete evidence. */
+interface TaskReference extends TaskIdentity {
+    /** Absence of the observed discriminator prevents cross-topology client calls. */
+    readonly kind?: never;
+    /** The manager in which the reference was obtained. */
+    readonly manager: ManagerIdentity;
+    /** Main service invocation, or null if no invocation was observed. */
+    readonly invocationId: string | null;
+    /** Auxiliary invocation, or null if it was absent or never invoked. */
+    readonly retentionInvocationId: string | null;
+}
+/** Input from /dev/null, an existing file, or a caller-owned descriptor. */
+type TaskInput = {
+    readonly type: 'null';
+} | {
+    readonly type: 'file'; /** Absolute existing input path. */
+    readonly path: string;
+} | {
+    readonly type: 'fd'; /** Nonnegative Unix descriptor, held open until start settles. */
+    readonly fd: number;
+};
+/** Output without decoding, in-memory capture, or automatic directory creation. */
+type TaskOutput = {
+    readonly type: 'null';
+} | {
+    readonly type: 'file'; /** Absolute output path. */
+    readonly path: string; /** Explicit append or truncate semantics. */
+    readonly mode: 'append' | 'truncate';
+} | {
+    readonly type: 'fd'; /** Nonnegative Unix descriptor, held open until start settles. */
+    readonly fd: number;
+};
+/** All standard descriptors are explicit and excluded from persistent task identities. */
+interface TaskIO {
+    /** Input source; this library does not create an interactive terminal. */
+    readonly stdin: TaskInput;
+    /** Binary standard output destination. */
+    readonly stdout: TaskOutput;
+    /** Binary standard error destination. */
+    readonly stderr: TaskOutput;
+}
+/** Explicit discard configuration for tasks whose output is not needed. */
+declare const nullIO: TaskIO;
+/** Whether the manager and cgroup provide evidence of finished descendant cleanup. */
+type CleanupState = 'pending' | 'complete' | 'incomplete' | 'unknown';
+/** Raw evidence retained by the specific service, with 64-bit values serialized as decimals. */
+interface TaskEvidence {
+    /** Raw systemd Unit.ActiveState. */
+    readonly activeState: string;
+    /** Raw systemd Unit.SubState. */
+    readonly subState: string;
+    /** Raw systemd Service.Result, without inferred stop intent. */
+    readonly systemdResult: string;
+    /** CLD_* wait-status category reported by systemd. */
+    readonly execMainCode: number;
+    /** Exit code or signal number according to execMainCode. */
+    readonly execMainStatus: number;
+    /** Monotonic main-process start timestamp in microseconds; zero means absent. */
+    readonly execMainStartUsec: string;
+    /** Monotonic main-process exit timestamp in microseconds; zero means absent. */
+    readonly execMainExitUsec: string;
+    /** Retained active-entry evidence under Type=exec. */
+    readonly activeEnterUsec: string;
+    /** Current job ID, or zero when no job is pending. */
+    readonly jobId: number;
+    /** Manager-reported cgroup path, possibly empty after cleanup. */
+    readonly controlGroup: string;
+    /** Hierarchical cgroup population evidence; null when unavailable or unnecessary. */
+    readonly cgroupPopulated: boolean | null;
+}
+/** A program failure is a normal result, distinct from a transport or observation error. */
+interface TaskResult {
+    /** Classification based on execution and exit evidence, never just the numeric status. */
+    readonly kind: 'exited' | 'signaled' | 'execution-failed' | 'not-executed' | 'unknown';
+    /** Program or systemd execution status, present only for CLD_EXITED. */
+    readonly exitCode: number | null;
+    /** Signal number, present only for CLD_KILLED or CLD_DUMPED. */
+    readonly signal: number | null;
+    /** Whether Type=exec activation was confirmed by retained manager evidence. */
+    readonly execution: 'confirmed' | 'not-confirmed';
+    /** Raw systemd result; timeout can describe runtime, stop, or cleanup escalation. */
+    readonly systemdResult: string;
+    /** Cleanup must be checked independently of a successful main-process exit. */
+    readonly cleanup: CleanupState;
+}
+/** A current state observation, not a durable event history. */
+interface TaskSnapshot {
+    /** Reference captured from this observation. */
+    readonly reference: TaskReference;
+    /** Complete requires observed InvocationIDs for both task and retention service. */
+    readonly identity: 'complete' | 'incomplete';
+    /** Process phase; completed always requires confirmed cleanup. */
+    readonly phase: 'starting' | 'running' | 'cleaning' | 'completed';
+    /** Main PID is diagnostic only and never used as task identity. */
+    readonly mainPid: number;
+    /** True only for inactive/failed state without a pending job. */
+    readonly managerTerminal: boolean;
+    /** Current cleanup evidence. */
+    readonly cleanup: CleanupState;
+    /** Available main-exit or terminal evidence, possibly before cleanup finishes. */
+    readonly result: TaskResult | null;
+    /** Minimal raw properties needed to audit the classification. */
+    readonly evidence: TaskEvidence;
+}
+/** Absence does not prove that a task never ran; incomplete retention is also explicit. */
+type LookupResult = {
+    readonly status: 'found'; /** Reference from this read. */
+    readonly reference: TaskReference; /** Current task state. */
+    readonly snapshot: TaskSnapshot;
+} | {
+    readonly status: 'not-found'; /** Requested identity without secrets. */
+    readonly identity: TaskIdentity;
+} | {
+    readonly status: 'incomplete'; /** Partial identity, safe to inspect and conservatively release. */
+    readonly reference: TaskReference;
+};
+/** Start acceptance means the manager queued the creation transaction, not successful exec. */
+interface StartReceipt {
+    /** Acknowledged by the manager; subsequent program failure is a separate result. */
+    readonly outcome: 'accepted';
+    /** Requested identity, which is already known before the call. */
+    readonly identity: TaskIdentity;
+    /** Manager that accepted the request. */
+    readonly manager: ManagerIdentity;
+    /** Diagnostic path of the accepted job; jobs are not durable identities. */
+    readonly jobPath: string;
+}
+/** Local waiting controls; neither option changes manager-owned execution limits. */
+interface WaitOptions {
+    /** Aborting affects this caller's wait only. */
+    readonly signal?: AbortSignal;
+    /** Positive integer local deadline, at most 2147483647 milliseconds. */
+    readonly timeoutMs?: number;
+}
+/** Stop acceptance and optional completion waiting are separate stages. */
+interface StopOptions extends WaitOptions {
+    /** When true, await terminal cleanup after manager acceptance. Defaults to false. */
+    readonly wait?: boolean;
+}
+/** Local controls for the complete release sequence, independent of each D-Bus call. */
+interface ReleaseOptions extends WaitOptions {
+    /** Total local release deadline including queueing; defaults to 5000 milliseconds. */
+    readonly timeoutMs?: number;
+}
+/** Successful stop submission or an already-completed instance. */
+interface StopReceipt {
+    /** Already-completed does not submit any stop request. */
+    readonly outcome: 'accepted' | 'already-completed';
+    /** The exact reference checked before stopping. */
+    readonly reference: TaskReference;
+    /** Accepted stop job, or null for an already-completed instance. */
+    readonly jobPath: string | null;
+    /** Present when completion was awaited or already known. */
+    readonly completion: TaskSnapshot | null;
+}
+/** Explicit release affects manager retention, never application log files. */
+interface ReleaseReceipt {
+    /** The auxiliary retention is no longer active. */
+    readonly released: true;
+    /** Both identities were already absent when release began. */
+    readonly alreadyReleased: boolean;
+    /** Whether both records were already garbage-collected at the final observation. */
+    readonly collected: boolean;
+}
+/** Stable categories for callers making recovery decisions. */
+type ErrorCode = 'INVALID_INPUT' | 'UNSUPPORTED_ENVIRONMENT' | 'PERMISSION_DENIED' | 'MANAGER_UNAVAILABLE' | 'IDENTITY_CONFLICT' | 'START_REJECTED' | 'UNKNOWN_MUTATION_OUTCOME' | 'RESULT_UNAVAILABLE' | 'TASK_RUNNING' | 'WAIT_ABORTED' | 'WAIT_TIMEOUT' | 'DISCONNECTED' | 'OBSERVATION_FAILED';
+/** Metadata safe for default error formatting and diagnostic output. */
+interface ErrorDetails {
+    /** Public or transport operation where the failure was observed. */
+    readonly operation?: string;
+    /** Known delivery state; an unknown result must never authorize automatic retry. */
+    readonly mutationOutcome?: 'not-submitted' | 'rejected' | 'accepted' | 'unknown';
+    /** Acknowledged cleanup calls before a release error; may be positive even when a later call is unknown. */
+    readonly acceptedCleanupMutations?: number;
+    /** Stable detail such as unit-not-found or incomplete-identity. */
+    readonly reason?: string;
+    /** Random task ID only, never the serialized intent. */
+    readonly taskId?: string;
+}
+/** A redacted event correlated centrally with a task or connection flow. */
+interface DiagnosticEvent {
+    /** Stable event name; no command, environment, or output content. */
+    readonly event: string;
+    /** Immutable correlation context captured at emission time. */
+    readonly context: {
+        /** Connection flow shared by this client's operations. */
+        readonly connection: {
+            readonly id: string;
+        };
+        /** Task scope, present for task operations. */
+        readonly task?: {
+            readonly id: string; /** Derived unit name. */
+            readonly unitName: string;
+        };
+    };
+    /** Stable failure category, when applicable. */
+    readonly code?: ErrorCode;
+}
+/** Explicit user-manager connection options; no automatic provisioning is performed. */
+interface ConnectOptions {
+    /** Positive local D-Bus call deadline, at most 2147483647 ms; defaults to 5000. */
+    readonly requestTimeoutMs?: number;
+    /** Optional redacted event sink; sync throws and async rejections are isolated, never awaited. */
+    readonly onDiagnostic?: (event: DiagnosticEvent) => void;
+}
+/** The local client owns observation resources; systemd owns the task processes. */
+interface TaskClient {
+    /** Bound manager identity for persistence and diagnosis. */
+    readonly manager: ManagerIdentity;
+    /** Submit exactly one creation attempt for a locally validated intention. */
+    start(intent: TaskIntent, io: TaskIO): Promise<StartReceipt>;
+    /** Read existing ownership evidence without starting or retrying anything. */
+    lookup(target: TaskIntent | TaskReference): Promise<LookupResult>;
+    /** Read the exact referenced instance or fail with explicit observation unavailability. */
+    inspect(reference: TaskReference): Promise<TaskSnapshot>;
+    /** Wait for cleanup, or return explicit incomplete cleanup on terminal manager failure. */
+    wait(target: TaskIntent | TaskReference, options?: WaitOptions): Promise<TaskSnapshot>;
+    /** Ask the manager to stop the referenced cgroup, optionally awaiting cleanup. */
+    stop(reference: TaskReference, options?: StopOptions): Promise<StopReceipt>;
+    /** Release only completed owned retention, preserving application files. */
+    release(reference: TaskReference, options?: ReleaseOptions): Promise<ReleaseReceipt>;
+    /** Close local connections and observers without stopping any task. */
+    disconnect(): Promise<void>;
+}
+
+/** Vstupní specifikace observed tasku rozšiřuje běžný příkaz o konečný stdin snapshot. */
+interface ObservedTaskSpec extends TaskSpec {
+    /** Text se kóduje jako UTF-8, bytes se kopírují a null znamená explicitní /dev/null. */
+    readonly stdin: string | Uint8Array | null;
+}
+/** Serializovatelná identita tří jednotek, která neobsahuje příkaz ani vstupní data. */
+interface ObservedTaskIdentity extends TaskIdentity {
+    /** Rozlišuje observed intent od základního dvoujednotkového kontraktu. */
+    readonly kind: 'observed';
+    /** Verze jednosměrného guardian framingu očekávaná tímto intentem. */
+    readonly protocolVersion: 1;
+    /** Odvozené jméno guardian služby, které caller nemůže zvolit. */
+    readonly guardianUnitName: string;
+}
+/** Připravený observed intent je bezpečný pro JSON round-trip, nikoliv automaticky pro logování. */
+interface ObservedTaskIntent extends ObservedTaskIdentity {
+    /** Normalizovaný příkaz bez standardních descriptorů. */
+    readonly spec: TaskSpec;
+    /** Canonical base64 snapshot stdin; prázdný řetězec je prázdný input a null je /dev/null. */
+    readonly stdinBase64: string | null;
+}
+/** Přesná instance tří transient units svázaná s jedním systemd managerem. */
+interface ObservedTaskReference extends ObservedTaskIdentity {
+    /** Manager, ze kterého pochází invocation evidence. */
+    readonly manager: ManagerIdentity;
+    /** Invocation ID payload služby, nebo null při neúplné topologii. */
+    readonly invocationId: string | null;
+    /** Invocation ID retention služby, nebo null při neúplné topologii. */
+    readonly retentionInvocationId: string | null;
+    /** Invocation ID guardian služby, nebo null při neúplné topologii. */
+    readonly guardianInvocationId: string | null;
+}
+/** Stav jedné procesní služby bez předstírání společného exit výsledku payloadu a guardianu. */
+interface ObservedProcessSnapshot {
+    /** Main PID je pouze diagnostika a nikdy instance identity. */
+    readonly mainPid: number;
+    /** Terminální manager state vyžaduje inactive/failed bez čekajícího jobu. */
+    readonly managerTerminal: boolean;
+    /** Samostatný stav vyprázdnění cgroup této služby. */
+    readonly cleanup: CleanupState;
+    /** Exit evidence, jakmile ji manager skutečně poskytuje. */
+    readonly result: TaskResult | null;
+    /** Minimální raw evidence potřebná pro audit klasifikace. */
+    readonly evidence: TaskEvidence;
+}
+/** Současný snapshot payloadu i guardianu; nejde o historii událostí. */
+interface ObservedTaskSnapshot {
+    /** Reference zachycená stejným čtením jako procesní evidence. */
+    readonly reference: ObservedTaskReference;
+    /** Complete vyžaduje neprázdná invocation ID všech tří jednotek. */
+    readonly identity: 'complete' | 'incomplete';
+    /** Completed vyžaduje terminální a vyčištěný payload i guardian. */
+    readonly phase: 'starting' | 'running' | 'cleaning' | 'completed';
+    /** Konzervativní agregace cleanup evidence obou procesních jednotek. */
+    readonly cleanup: CleanupState;
+    /** Výsledek uživatelského procesu zůstává oddělený od infrastruktury. */
+    readonly payload: ObservedProcessSnapshot;
+    /** Výsledek guardianu odhaluje fail-closed infrastrukturní selhání. */
+    readonly guardian: ObservedProcessSnapshot;
+}
+/** Lookup nikdy nedoplňuje chybějící jednotku ani neopakuje start. */
+type ObservedLookupResult = {
+    readonly status: 'found'; /** Exact reference z tohoto čtení. */
+    readonly reference: ObservedTaskReference; /** Současný společný stav. */
+    readonly snapshot: ObservedTaskSnapshot;
+} | {
+    readonly status: 'not-found'; /** Identita bez příkazu a stdin. */
+    readonly identity: ObservedTaskIdentity;
+} | {
+    readonly status: 'incomplete'; /** Exact dostupná invocation evidence. */
+    readonly reference: ObservedTaskReference;
+};
+/** Jeden binární chunk doručený ze sekvenční bounded fronty guardianu. */
+interface ObservedOutputEvent {
+    /** Původní payload descriptor bez slučování obou kanálů. */
+    readonly stream: 'stdout' | 'stderr';
+    /** Stabilní buffer, který už knihovna po callbacku nemění ani znovu nepoužije. */
+    readonly data: Uint8Array;
+}
+/** Callback je zároveň backpressure hranice; další frame čeká na jeho settlement. */
+interface ObservedStartOptions {
+    /** Přijme každý output chunk přesně jednou během tohoto lokálního připojení. */
+    readonly onOutput: (event: ObservedOutputEvent) => void | Promise<void>;
+}
+/** Lokální připojení k živému outputu, které nevlastní manager task lifecycle. */
+interface ObservedTaskObservation {
+    /** Settluje po čistém complete+EOF, explicitním detach, nebo observation chybě. */
+    readonly completion: Promise<{
+        readonly outcome: 'complete' | 'detached';
+    }>;
+    /** Idempotentně odpojí klienta; guardian dál drainuje a payload se nezastaví. */
+    detach(): Promise<void>;
+}
+/** Manager přijal jediný pokus a guardian zároveň potvrdil připravený output kanál. */
+interface ObservedStartReceipt {
+    /** Přijetí není tvrzení o úspěšném exec nebo exit statusu payloadu. */
+    readonly outcome: 'accepted';
+    /** Veřejná identita bez spec a stdin. */
+    readonly identity: ObservedTaskIdentity;
+    /** Manager, který přijal atomickou tříjednotkovou transakci. */
+    readonly manager: ManagerIdentity;
+    /** Diagnostická cesta manager jobu, nikoliv durable identita. */
+    readonly jobPath: string;
+}
+/** Úspěšný start vrací zvlášť manager receipt a lokální output observation. */
+interface ObservedStartResult {
+    /** Důkaz přijetí transakce a guardian readiness. */
+    readonly receipt: ObservedStartReceipt;
+    /** Klientem vlastněný stream, který lze kdykoliv lokálně odpojit. */
+    readonly observation: ObservedTaskObservation;
+}
+/** Lifecycle observed tasků sdílí manager a mutation pravidla se základním klientem. */
+interface ObservedTaskClient {
+    /** Manager identity pevná po celou dobu tohoto spojení. */
+    readonly manager: ManagerIdentity;
+    /** Odešle jednu transakci a čeká na bounded guardian readiness. */
+    startObserved(intent: ObservedTaskIntent, options: ObservedStartOptions): Promise<ObservedStartResult>;
+    /** Čte všechny tři jednotky bez startu, retry nebo output adopce. */
+    lookup(target: ObservedTaskIntent | ObservedTaskReference): Promise<ObservedLookupResult>;
+    /** Čte přesnou referenced instanci nebo skončí explicitní chybou. */
+    inspect(reference: ObservedTaskReference): Promise<ObservedTaskSnapshot>;
+    /** Čeká na terminální manager stav obou služeb a vrátí samostatnou cleanup evidenci. */
+    wait(target: ObservedTaskIntent | ObservedTaskReference, options?: WaitOptions): Promise<ObservedTaskSnapshot>;
+    /** Zastaví payload cgroup; guardian dostane prostor dokončit drain. */
+    stop(reference: ObservedTaskReference, options?: StopOptions): Promise<ObservedStopReceipt>;
+    /** Uvolní retention až po potvrzeném cleanupu obou procesních služeb. */
+    release(reference: ObservedTaskReference, options?: ReleaseOptions): Promise<ReleaseReceipt>;
+    /** Odpojí všechny output observations a D-Bus bez zastavení tasků. */
+    disconnect(): Promise<void>;
+}
+/** Stop receipt zachovává observed snapshot místo dvoujednotkového výsledku. */
+interface ObservedStopReceipt {
+    /** Already-completed nevytváří další manager mutation. */
+    readonly outcome: 'accepted' | 'already-completed';
+    /** Exact reference ověřená před zastavením. */
+    readonly reference: ObservedTaskReference;
+    /** Přijatý stop job, nebo null při již dokončeném tasku. */
+    readonly jobPath: string | null;
+    /** Snapshot je přítomný při wait:true nebo already-completed. */
+    readonly completion: ObservedTaskSnapshot | null;
+}
+
+/** Connect explicitly to the local user manager; package import has no connection side effects. */
+declare function connect(options?: ConnectOptions): Promise<TaskClient>;
+/** Připojí stejný runtime až po guardian a systemd prerequisites preflightu. */
+declare function connectObserved(options?: ConnectOptions): Promise<ObservedTaskClient>;
+
+/** A recoverable API error with stable categories and redacted default formatting. */
+declare class TaskError extends Error {
+    /** Stable category used by applications instead of parsing human-readable messages. */
+    readonly code: ErrorCode;
+    /** Safe delivery and identity metadata; never contains a command specification. */
+    readonly details: ErrorDetails;
+    /** Preserve the original cause for explicit access while keeping default output redacted. */
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails, cause?: unknown);
+    /** Serialization deliberately excludes raw causes, stack contents, and request payloads. */
+    toJSON(): {
+        /** Stable error class name for serialized consumers. */
+        name: string;
+        /** Public recovery category. */
+        code: ErrorCode;
+        /** Redacted explanation safe for default logs. */
+        message: string;
+        /** Safe delivery evidence without raw causes. */
+        details: ErrorDetails;
+    };
+    /** Console and util.inspect must not expand a transport cause containing request data. */
+    [util.inspect.custom](): string;
+}
+
+/** Připraví úplný observed intent lokálně a zkopíruje mutable Uint8Array vstup. */
+declare function prepareObserved(spec: ObservedTaskSpec): ObservedTaskIntent;
+
+/** Prepare an intention locally; no connection, file opening, or process start occurs. */
+declare function prepare(spec: TaskSpec): TaskIntent;
+
+export { type CleanupState, type ConnectOptions, type DiagnosticEvent, type ErrorCode, type ErrorDetails, type LookupResult, type ManagerIdentity, type ObservedLookupResult, type ObservedOutputEvent, type ObservedProcessSnapshot, type ObservedStartOptions, type ObservedStartReceipt, type ObservedStartResult, type ObservedStopReceipt, type ObservedTaskClient, type ObservedTaskIdentity, type ObservedTaskIntent, type ObservedTaskObservation, type ObservedTaskReference, type ObservedTaskSnapshot, type ObservedTaskSpec, type ReleaseOptions, type ReleaseReceipt, type StartReceipt, type StopOptions, type StopReceipt, type SystemdProperty, type TaskClient, TaskError, type TaskEvidence, type TaskIO, type TaskIdentity, type TaskInput, type TaskIntent, type TaskOutput, type TaskReference, type TaskResult, type TaskSnapshot, type TaskSpec, type WaitOptions, connect, connectObserved, nullIO, prepare, prepareObserved };

package/docs/implementation-decisions.md

@@ -321,3 +321,140 @@ 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.
+
+## Observed-task feasibility checkpoint — 2026-09-17
+
+The opt-in observed-task design passed its pre-API feasibility gate without
+wrapping the payload process. One `StartTransientUnit` request created the existing
+task and retention services plus a `Type=notify` guardian auxiliary service. The
+task received stdout and stderr through the standard FD properties. The guardian
+received the opposite stream endpoints and a client transport through the
+`ExtraFileDescriptors` `a(hs)` property in the same auxiliary property array.
+`LISTEN_PID`, `LISTEN_FDS`, and `LISTEN_FDNAMES` delivered the three descriptors as
+`task-stdout`, `task-stderr`, and `observer` starting at descriptor 3.
+
+The task uses `BindsTo=` and `After=` on the guardian. The guardian validates and
+connects every descriptor before synchronously sending `READY=1` through
+`systemd-notify`; a task held behind that readiness barrier did not execute early,
+and a guardian exiting before readiness left the task unexecuted. A runtime
+guardian SIGKILL stopped the task and its TERM-resistant detached descendant. The
+feasibility prototype deliberately had no reverse stop propagation: after normal
+task exit, explicit stop, or runtime timeout, the guardian drained buffered output
+through EOF before exiting. The production implementation below later added
+ordered stop propagation to cover payload cancellation before exec.
+
+The feasibility checkpoint was originally recorded against the published
+`@primafuture/socket-fdx@1.0.0`. A small development-only native helper created
+three real Unix stream socket pairs and sent their six endpoints to the harness
+over the existing bounded SCM_RIGHTS API. This avoided adding a speculative public
+socket-pair contract before the systemd topology was proven. The helper and the
+probe framing remain historical test fixtures, not runtime or public protocol
+designs. The runnable harness now verifies the active development dependency
+version and is retained as a regression gate alongside the production API tests.
+
+The following real-manager scenarios passed:
+
+- exact binary stdout/stderr routing, manager FD duplication, guardian evidence,
+  and retention of all three unit identities;
+- deterministic readiness hold and pre-readiness guardian failure;
+- guardian crash with fail-closed task and descendant cleanup;
+- explicit observer detach and submitting-client SIGKILL followed by 32 MiB on
+  each output channel, with successful payload completion and no `EPIPE`;
+- explicit task stop and manager runtime timeout with complete cgroup cleanup;
+- a foreign guardian-name collision rejecting the transaction without executing
+  the payload.
+
+One diagnostic pass completed all seven scenarios. The authoritative stress run
+then completed ten consecutive rounds, 70 scenario executions, without retry,
+descriptor-baseline drift, or a remaining `pf-systemd-tasks-observed-proof-*`
+unit. It ran on Node 24.13.0, Linux x86-64 kernel 6.17.0-14-generic, glibc 2.42,
+systemd user manager 257.9, and socket-fdx 1.0.0. Reproduce it with:
+
+```sh
+npm run feasibility:observed
+npm run feasibility:observed -- --repeat 10
+```
+
+This result proves the topology on the recorded host only. It does not yet define
+the public observed-task API, the final framing, a reconnect protocol, or support
+for other systemd and Node versions. The next implementation dependency is an
+explicitly owned socket-pair/adoption contract in `socket-fdx`; no package version
+or runtime behavior changed at this checkpoint.
+
+## Observed-task implementation — 2026-09-17
+
+Version 1.1.0 implements the opt-in design under the separate
+`@primafuture/systemd-tasks/observed` export. The original root export retains the
+same four runtime values. Both thin ESM/CommonJS facades load one package-internal
+runtime module, so errors from either API share the exact `TaskError` constructor.
+Importing either facade remains side-effect free and does not load the native addon;
+socket-fdx is dynamically loaded only when an observed start creates socket pairs
+or the D-Bus adapter establishes a connection.
+
+Observed intents use a distinct unit namespace and carry payload, retention, and
+guardian names plus protocol version 1. Text stdin is copied as UTF-8, byte input is
+copied directly, null remains `/dev/null`, and empty data remains distinct from null.
+The canonical base64 value is fingerprinted and capped at 512 KiB so its expanded
+manager-state representation remains safely below systemd's one-line serialization
+boundary. Non-null data is
+passed through systemd's `StandardInput=data` and `StandardInputData=ay`; there is
+no input feeder or payload wrapper. Manager state can retain these sensitive bytes
+until release.
+
+The production guardian uses the already-proven three-unit topology and the public
+socket-fdx socket-pair/adoption ownership contract. Its private stream protocol has
+a ten-byte `SDTO`, version, kind, uint32be-length header, 64 KiB data frames, and a
+256 KiB client receive budget. Exactly one empty ready frame precedes binary output,
+and exactly one empty complete frame precedes clean EOF. The client rejects unknown,
+out-of-order, partial, oversized, ancillary, or trailing data. Output callbacks are
+awaited sequentially. Their failures are local observation failures and never become
+implicit task-stop requests or diagnostic payloads.
+
+JavaScript cannot cancel a callback promise that application code has already
+started. Explicit detach therefore closes and unregisters the local socket and
+settles the public observation immediately, without awaiting that promise. The
+in-flight callback may settle later, but cannot change the detached outcome, invoke
+another callback, delay `disconnect()`, or restore the output connection.
+
+Guardian readiness has a fixed five-second budget. The guardian validates its three
+named inherited sockets, establishes drain handlers, successfully invokes
+`systemd-notify`, and only then emits the protocol ready frame. The payload starts
+after and `BindsTo` the guardian. Payload stop requests use systemd's
+`PropagatesStopTo=` and reverse ordering, so the payload is terminal before the
+guardian receives SIGTERM. An invoked payload retains strict socket EOF as the only
+drain-completion signal, including while a slow callback applies backpressure. For
+a cancelled pre-exec payload, the guardian confirms the still-empty `InvocationID`
+through `/usr/bin/systemctl` before closing manager-owned write endpoints that can
+never produce data. Client detach or connection loss switches both inputs to
+flowing discard mode, removing observer backpressure while retaining real EOF as
+the process-lifecycle boundary. There is no reconnect, replay, or live-stream adoption.
+
+The original D-Bus adapter now accepts one primary service and an ordered auxiliary
+list, while retaining a single request, collision mode `fail`, descriptor lifetime,
+and mutation-outcome rules. One client core owns the transport, manager identity,
+in-flight read deduplication, per-identity mutation queues, notification hub,
+diagnostics, and local output handles. The two-unit and three-unit codecs share that
+core. Observed lookup treats every partial permutation as incomplete, references
+all three invocation IDs, and never fabricates a missing role. Completion and
+release require terminal empty cgroups for both payload and guardian.
+
+Development is pinned to the exact published
+`npm:@primafuture/socket-fdx@1.1.0` release. The lockfile records its registry
+tarball and SRI integrity. The installed-package smoke uses no consumer override
+and verifies that one canonical socket-fdx instance is loaded. No npm publication
+of this package is part of this changeset.
+
+The post-review local acceptance run completed 67 deterministic unit tests, 43 real
+systemd integration scenarios, and installed ESM/CommonJS runtime and TypeScript
+consumer smoke tests. The earlier historical feasibility stress run remains ten
+rounds (70 scenarios), as recorded above. The installed consumer verified the
+unchanged root runtime export set, the separate observed entrypoint, canonical `TaskError` identity across both
+entrypoints and mixed ESM/CommonJS loading, lazy native loading, and exactly one
+socket-fdx 1.1.0 runtime instance. Real-manager coverage includes binary, empty,
+and exact maximum-size stdin, retention-start failure, separate binary streams, async
+callback backpressure, explicit detach, submitting-client SIGKILL with 32 MiB per
+channel, drain-preserving explicit stop, cross-client cancellation before payload
+exec, guardian fail-closed behavior, collision and incomplete topology handling,
+unknown mutation outcomes, exact invocation ownership, release, and empty cgroups.
+No output bytes, stdin bytes, or callback error payloads are emitted by library
+diagnostics.