@primafuture/systemd-tasks 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,316 +1 @@
-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 {
-    /** 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 {
-    /** 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';
-/** 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>;
-}
-
-/** Connect explicitly to the local user manager; package import has no connection side effects. */
-declare function connect(options?: ConnectOptions): Promise<TaskClient>;
-
-/** Prepare an intention locally; no connection, file opening, or process start occurs. */
-declare function prepare(spec: TaskSpec): TaskIntent;
-
-/** 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;
-}
-
-export { type CleanupState, type ConnectOptions, type DiagnosticEvent, type ErrorCode, type ErrorDetails, type LookupResult, type ManagerIdentity, 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, nullIO, prepare };
+export { CleanupState, ConnectOptions, DiagnosticEvent, ErrorCode, ErrorDetails, LookupResult, ManagerIdentity, ReleaseOptions, ReleaseReceipt, StartReceipt, StopOptions, StopReceipt, SystemdProperty, TaskClient, TaskError, TaskEvidence, TaskIO, TaskIdentity, TaskInput, TaskIntent, TaskOutput, TaskReference, TaskResult, TaskSnapshot, TaskSpec, WaitOptions, connect, nullIO, prepare } from '#runtime';

package/dist/index.d.ts

@@ -1,316 +1 @@
-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 {
-    /** 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 {
-    /** 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';
-/** 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>;
-}
-
-/** Connect explicitly to the local user manager; package import has no connection side effects. */
-declare function connect(options?: ConnectOptions): Promise<TaskClient>;
-
-/** Prepare an intention locally; no connection, file opening, or process start occurs. */
-declare function prepare(spec: TaskSpec): TaskIntent;
-
-/** 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;
-}
-
-export { type CleanupState, type ConnectOptions, type DiagnosticEvent, type ErrorCode, type ErrorDetails, type LookupResult, type ManagerIdentity, 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, nullIO, prepare };
+export { CleanupState, ConnectOptions, DiagnosticEvent, ErrorCode, ErrorDetails, LookupResult, ManagerIdentity, ReleaseOptions, ReleaseReceipt, StartReceipt, StopOptions, StopReceipt, SystemdProperty, TaskClient, TaskError, TaskEvidence, TaskIO, TaskIdentity, TaskInput, TaskIntent, TaskOutput, TaskReference, TaskResult, TaskSnapshot, TaskSpec, WaitOptions, connect, nullIO, prepare } from '#runtime';