@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/infra/owned-process-group.d.ts

@@ -0,0 +1,173 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+interface StopOptions {
+    termMs?: number;
+    killMs?: number;
+    pollMs?: number;
+}
+export declare class OwnedGroupRefusal extends Error {
+    readonly code: string;
+    readonly detail: string | null;
+    constructor(code: string, detail?: string | null);
+}
+/** Members of this exact owned group, or null when the host cannot observe process tables. */
+export declare function observeGroup(handle: unknown): {
+    pid: number;
+    pgid: number;
+    state: string;
+    start_identity: string;
+}[] | null;
+/**
+ * Spawn one child in its own detached process group and keep the exact incarnation of the
+ * group leader in private state. Only the returned frozen token can later stop that group.
+ */
+export declare function spawnOwnedGroup(command: string, args?: string[], options?: SpawnOptions): object;
+/**
+ * Genuine-handle-only accessor: returns the ChildProcess created by this exact handle. The
+ * handle remains a frozen opaque token, so a caller can never pass an arbitrary pid/pgid as
+ * authority for signalling.
+ */
+export declare function ownedChild(handle: unknown): ChildProcess;
+/** Observes only this handle's own group: parent exit is not group exit. */
+export declare function groupState(handle: unknown): {
+    observable: boolean;
+    pgid: number;
+    parent_exited: boolean;
+    members: {
+        pid: number;
+        pgid: number;
+        state: string;
+        start_identity: string;
+    }[];
+    live_members: number[];
+    group_live: boolean;
+};
+/**
+ * Bounded TERM then KILL against this handle's own group. Refuses when the group leader was
+ * replaced by a different incarnation, and reports `stopped: false` while any member lives.
+ */
+export declare function stopOwnedGroup(handle: unknown, options?: StopOptions): Promise<{
+    stopped: boolean;
+    already_stopped: boolean;
+    term_sent: boolean;
+    kill_sent: boolean;
+    remaining: {
+        pid: number;
+        state: string;
+        start_identity: string;
+    }[];
+}>;
+/**
+ * Read-only snapshot of the genuine owned root and the processes that are actually its
+ * descendants (tree traversal from the private root pid), keeping exact PID + start identities
+ * and the members of every group those processes belong to. The snapshot is a frozen opaque
+ * token backed by private state; no caller-supplied PID/PGID ever becomes authority, and the
+ * caller's groups are captured before any native interrupt so orphaned groups remain targeted.
+ *
+ * A group is only captured when its leader is the owned root or a captured descendant AND every
+ * current member of that group is itself a proven descendant of the owned root. A group leader
+ * alone can never grant authority over an unrelated process that merely joined the group, so a
+ * contaminated tree is refused wholesale instead of being stopped.
+ */
+export declare function snapshotOwnedTree(handle: unknown): Readonly<{
+    scope: "owned-descendant-tree-snapshot";
+    captured_at: string;
+    original_pgid: number;
+    root: {
+        pid: number;
+        pgid: number;
+        start_identity: string;
+    };
+    descendants: {
+        pid: number;
+        ppid: number;
+        pgid: number;
+        start_identity: string;
+    }[];
+    groups: {
+        pgid: number;
+        member_count: number;
+    }[];
+}>;
+/**
+ * Bounded global TERM then KILL across the snapshotted groups (one shared budget, never
+ * multiplied by group count). Only the runtime whose owned group captured the snapshot may stop
+ * it. Signalling happens after every current live member of every captured group matches a
+ * snapshotted PID + start identity and the same captured PGID, and every still-live captured PID
+ * is still in its captured group; an uncaptured joiner, a reused id, a moved captured member or an
+ * observation failure refuses unproven and signals nothing. Immediately before escalation the
+ * same verdict is recomputed, so a group whose membership or incarnation changed during TERM is
+ * never SIGKILLed; a `stopped: true` result requires that same positive verdict on the final
+ * observation.
+ */
+export declare function stopSnapshottedTree(snapshot: unknown, options?: StopOptions & {
+    handle?: object;
+}): Promise<{
+    scope: string;
+    original_pgid: number;
+    root_pid: number;
+    groups: number[];
+    targeted_groups: number[];
+    stopped: boolean;
+    already_stopped: boolean;
+    term_sent: boolean;
+    kill_sent: boolean;
+    group_observed: boolean;
+    escalation_refused: string;
+    remaining: never[];
+} | {
+    scope: string;
+    original_pgid: number;
+    root_pid: number;
+    groups: number[];
+    targeted_groups: number[];
+    stopped: boolean;
+    already_stopped: boolean;
+    term_sent: boolean;
+    kill_sent: boolean;
+    group_observed: boolean;
+    escalation_refused: string;
+    escalation_detail: string;
+    remaining: {
+        pid: number;
+        pgid: number;
+        state: string;
+        start_identity: string;
+    }[];
+} | {
+    scope: string;
+    original_pgid: number;
+    root_pid: number;
+    groups: number[];
+    targeted_groups: number[];
+    stopped: boolean;
+    already_stopped: boolean;
+    term_sent: boolean;
+    kill_sent: boolean;
+    group_observed: boolean;
+    final_proof_refused: string;
+    final_proof_detail: string;
+    remaining: {
+        pid: number;
+        pgid: number;
+        state: string;
+        start_identity: string;
+    }[];
+} | {
+    scope: string;
+    original_pgid: number;
+    root_pid: number;
+    groups: number[];
+    targeted_groups: number[];
+    stopped: boolean;
+    already_stopped: boolean;
+    term_sent: boolean;
+    kill_sent: boolean;
+    remaining: {
+        pid: number;
+        pgid: number;
+        state: string;
+        start_identity: string;
+    }[];
+    group_observed: boolean;
+}>;
+export {};