@ricsam/r5d-worker 0.0.136 → 0.0.138

package/dist/types/runtime/releases/manager.d.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { OwnershipFence, RuntimeHello } from "@ricsam/r5d-api/runtime-protocol";
+import { HostExecutorClient } from "../client";
+import { AdapterConfig, AdapterGrant, ExecutorCommand, type AdapterRegistration } from "../protocol";
+import { AdapterManifest, ImmutableAdapterArtifacts } from "./artifacts";
+import { AdapterRetirementCompletion } from "./retirement";
+import type { DeliveryReceipt } from "./rpc-protocol";
+export declare const ReleaseManagerConfig: z.ZodObject<{
+    installationId: z.ZodString;
+    workerId: z.ZodString;
+    stateDir: z.ZodString;
+    artifactsDir: z.ZodString;
+    workspaceRoots: z.ZodArray<z.ZodString>;
+    runtimePath: z.ZodString;
+    runtimeSha256: z.ZodString;
+    controller: z.ZodObject<{
+        socketPath: z.ZodString;
+        principalId: z.ZodString;
+        token: z.ZodString;
+        hello: z.ZodObject<{
+            installationId: z.ZodString;
+            instanceId: z.ZodString;
+            releaseId: z.ZodString;
+            role: z.ZodEnum<{
+                web: "web";
+                scheduler: "scheduler";
+                runner: "runner";
+                gateway: "gateway";
+                "worker-adapter": "worker-adapter";
+                "browser-adapter": "browser-adapter";
+                executor: "executor";
+                keeper: "keeper";
+                storage: "storage";
+            }>;
+            protocol: z.ZodObject<{
+                min: z.ZodNumber;
+                max: z.ZodNumber;
+            }, z.core.$strict>;
+            capabilities: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ReleaseManagerConfig = z.input<typeof ReleaseManagerConfig>;
+export type ReleaseRecord = {
+    principalId: string;
+    manifest: AdapterManifest;
+    artifactDigest: string;
+    grant: AdapterGrant;
+    phase: "staged" | "ready" | "active" | "retained" | "retired";
+    retirementCompletion?: AdapterRetirementCompletion;
+};
+type KeeperStatus = {
+    hello: RuntimeHello;
+    workerId: string;
+    authority: {
+        fence: OwnershipFence;
+        validUntil: number;
+    } | null;
+    degraded: boolean;
+    adapters: AdapterRegistration[];
+};
+type Call = {
+    id: string;
+    principal: string;
+    hash: string;
+    state: "pending" | "completed" | "unknown";
+    acknowledged: number;
+};
+/** Local installation agent, independently supervised from the keeper. Its controller token is never passed to adapters. */
+export declare class WorkerAdapterReleases {
+    readonly invocation: `${string}-${string}-${string}-${string}-${string}`;
+    readonly config: z.output<typeof ReleaseManagerConfig>;
+    readonly artifacts: ImmutableAdapterArtifacts;
+    readonly controller: HostExecutorClient;
+    private readonly db;
+    private readonly lock;
+    private readonly ackKey;
+    private readonly children;
+    private readonly deliveries;
+    private probes;
+    private readonly retiring;
+    private serial;
+    private closing;
+    private closed?;
+    constructor(input: ReleaseManagerConfig);
+    private verifyRuntime;
+    private exclusive;
+    list(): ReleaseRecord[];
+    calls(): Call[];
+    transitions(): unknown[];
+    private get;
+    private put;
+    private configPath;
+    private keeper;
+    /** Approval digest must come from the authenticated release ledger, not the source directory itself. */
+    stage(input: {
+        source: string;
+        manifest: AdapterManifest;
+        approvalDigest: string;
+        grant: AdapterGrant;
+        adapter: AdapterConfig;
+    }): Promise<ReleaseRecord>;
+    launch(id: string): Promise<{
+        pid: number;
+    }>;
+    /** Fence/lease are the committed DB grant from the separately authenticated controller, not a locally invented epoch. */
+    promote(id: string, inputFence: OwnershipFence, validUntil: number): Promise<void>;
+    private recordAuthority;
+    /** Recovery reads the keeper, never replays a promotion or kills a remembered PID. */
+    reconcile(): Promise<KeeperStatus>;
+    bindRpcPrincipals(principals: unknown): void;
+    /** Actual child request, independent of the delivery/admin queues; never substitutes direct executor status. */
+    probe(id: string, hello: RuntimeHello): Promise<KeeperStatus & {
+        adapterPid: number;
+    }>;
+    delivery(callId: string): DeliveryReceipt | null;
+    private ackToken;
+    private saveDelivery;
+    /** Stable transport ID: persisted completed outcomes replay exactly; unknown never redispatches. */
+    deliver(callId: string, id: string, hello: RuntimeHello, requesterId: string, command: ExecutorCommand): Promise<DeliveryReceipt>;
+    observe(id: string, hello: RuntimeHello, requesterId: string, command: ExecutorCommand): Promise<DeliveryReceipt>;
+    private dispatchDelivery;
+    acknowledgeDelivery(callId: string, responseDigest: string, ackToken: string, requesterId: string): {
+        callId: string;
+        responseDigest: string;
+        acknowledged: true;
+    };
+    /** Admin-only attestation to independently durable reconciliation. Never replays or changes the unknown outcome. */
+    settleUnknownDelivery(callId: string, evidenceDigest: string): DeliveryReceipt;
+    deliveryDrain(id: string): {
+        unsettled: number;
+        unknown: number;
+    };
+    /** Stable callId journals delivery; reusing it never dispatches twice. Explicit retry uses reconcileCall. */
+    request<T = unknown>(callId: string, id: string, command: ExecutorCommand): Promise<T>;
+    reconcileCall<T = unknown>(callId: string, id: string, command: ExecutorCommand): Promise<T>;
+    private dispatch;
+    /** Called only after the controller's durable inbox/outbox has recorded the result OR explicit unknown reconciliation. */
+    acknowledge(callId: string): Promise<void>;
+    retire(id: string, retirementIntentDigest?: string): Promise<void>;
+    stopAdapter(id: string): Promise<void>;
+    close(): Promise<void>;
+}
+export {};

package/dist/types/runtime/releases/process.d.ts

@@ -0,0 +1,14 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { type ExecutorCommand } from "../protocol";
+/** Owns only a translation process. Never starts, signals, supervises or adopts the executor. */
+export declare class AdapterChild {
+    private readonly timeoutMs;
+    readonly process: ChildProcessWithoutNullStreams;
+    private readonly pending;
+    private gone;
+    constructor(runtimePath: string, entrypoint: string, configPath: string, home: string, timeoutMs?: number);
+    private fail;
+    get alive(): boolean;
+    request<T = unknown>(command: ExecutorCommand): Promise<T>;
+    close(): Promise<void>;
+}

package/dist/types/runtime/releases/retirement.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** Written only after closing a known owned child. Not inferred from process absence. */
+export declare const AdapterRetirementCompletion: z.ZodObject<{
+    format: z.ZodLiteral<1>;
+    installationId: z.ZodString;
+    workerId: z.ZodString;
+    adapterId: z.ZodString;
+    manifestDigest: z.ZodString;
+    grantDigest: z.ZodString;
+    retirementIntentDigest: z.ZodString;
+    managerInvocation: z.ZodString;
+    childPid: z.ZodNumber;
+    completionId: z.ZodString;
+}, z.core.$strict>;
+export type AdapterRetirementCompletion = z.infer<typeof AdapterRetirementCompletion>;

package/dist/types/runtime/releases/rpc-client.d.ts

@@ -0,0 +1,52 @@
+import type { OperationEnvelope } from "@ricsam/r5d-api/runtime-protocol";
+import { ExecutorCommand, type RunIdentity, type RunReceipt, type PollResult, type ActionReceipt } from "../protocol";
+import { DeliveryReceipt, ManagerRpcClientConfig, type ManagerCommand } from "./rpc-protocol";
+export type DeliveryReceiptSink = (receipt: DeliveryReceipt) => Promise<void>;
+export declare class ManagerRpcClient {
+    readonly config: ReturnType<typeof ManagerRpcClientConfig.parse>;
+    constructor(config: ManagerRpcClientConfig);
+    request<T = unknown>(command: ManagerCommand): Promise<T>;
+    probe(): Promise<unknown>;
+    execute(callId: string, command: ExecutorCommand): Promise<DeliveryReceipt>;
+    observe(command: ExecutorCommand): Promise<DeliveryReceipt>;
+    receipt(callId: string): Promise<DeliveryReceipt>;
+    acknowledge(callId: string, responseDigest: string, ackToken: string): Promise<{
+        callId: string;
+        responseDigest: string;
+        acknowledged: true;
+    }>;
+}
+/** Workspace facade: every resource method traverses manager -> actual child -> executor. No executor token/socket available. */
+export declare class ManagedExecutorClient {
+    private readonly receiptSink?;
+    private readonly onAcknowledged?;
+    readonly rpc: ManagerRpcClient;
+    constructor(config: ManagerRpcClientConfig, receiptSink?: DeliveryReceiptSink | undefined, onAcknowledged?: DeliveryReceiptSink | undefined);
+    get config(): {
+        socketPath: string;
+        installationId: string;
+        workerId: string;
+        principalId: string;
+        token: string;
+        adapterId: string;
+        hello: {
+            installationId: string;
+            instanceId: string;
+            releaseId: string;
+            role: "web" | "scheduler" | "runner" | "gateway" | "worker-adapter" | "browser-adapter" | "executor" | "keeper" | "storage";
+            protocol: {
+                min: number;
+                max: number;
+            };
+            capabilities: string[];
+        };
+        timeoutMs: number;
+    };
+    status(): Promise<unknown>;
+    request<T = unknown>(command: ExecutorCommand): Promise<T>;
+    start(operation: OperationEnvelope): Promise<RunReceipt>;
+    poll(run: RunIdentity, stdoutOffset?: number, stderrOffset?: number, maxBytes?: number): Promise<PollResult>;
+    write(run: RunIdentity, actionId: string, data: string, eof?: boolean): Promise<ActionReceipt>;
+    resize(run: RunIdentity, actionId: string, cols: number, rows: number): Promise<ActionReceipt>;
+    cancel(run: RunIdentity, actionId: string): Promise<ActionReceipt>;
+}

package/dist/types/runtime/releases/rpc-main.d.ts

@@ -0,0 +1,10 @@
+import { WorkerAdapterReleases } from "./manager";
+import { ManagerRpcConfig } from "./rpc-protocol";
+export declare function readManagerPrivateJson(path: string): unknown;
+/** Independently supervised Unix service; callers never receive grants, adapter tokens or admin authority. */
+export declare function startManagerRpc(input: ManagerRpcConfig): Promise<{
+    manager: WorkerAdapterReleases;
+    socketPath: string;
+    readonly pending: number;
+    close(): Promise<void>;
+}>;