@astrosheep/keiyaku 4.0.0 → 4.0.1

package/build/src/protocol/placement.js

@@ -0,0 +1,114 @@
+import { SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { contractState } from "../core/facts/observation.js";
+import { decidePlacement } from "../core/verbs/placement.js";
+import { reconcileEffectFailure } from "../git/reconcile.js";
+import { GitPlumbingError } from "../git/repository.js";
+import { acquireTargetPlacementFence, followTargetPlacement, prepareTargetPlacement, observeTargetHead, } from "../git/target-placement.js";
+import { admitDecidedOffer, mintAttempts } from "./attempt.js";
+import { prepareProtocolAttempt, runProtocol, } from "./run.js";
+function placementFailure(error) {
+    return { kind: "placement-failed", diagnostic: error instanceof Error ? error.message : String(error) };
+}
+function expectedPlacementFailure(error) {
+    if (error instanceof GitPlumbingError || error instanceof SqliteTransactionLockError)
+        return placementFailure(error);
+    throw error;
+}
+async function runFencedPlacement(repository, input, protocol) {
+    for (let index = 0; index < protocol.attempts.length; index += 1) {
+        const prepared = await prepareProtocolAttempt(protocol, protocol.attempts[index]);
+        if (prepared.kind === "refused")
+            return prepared;
+        const state = contractState(prepared.observation.decision, input.contractId);
+        if (state === null)
+            throw new Error("placement offer has no contract state");
+        if (prepared.offer.target === undefined)
+            throw new Error("targeted placement offer is missing its target movement");
+        const observed = observeTargetHead(repository, prepared.offer.target.target);
+        if (observed !== prepared.offer.target.expectedOid) {
+            return {
+                kind: "target-moved",
+                contractId: input.contractId,
+                target: prepared.offer.target.target,
+                expected: prepared.offer.target.expectedOid,
+                observed,
+            };
+        }
+        const physical = prepareTargetPlacement(repository, state, prepared.offer.target);
+        if (physical.kind === "refused")
+            return physical;
+        const result = await admitDecidedOffer({
+            channel: protocol.channel,
+            repository,
+            decisionObservation: prepared.observation,
+            attempt: prepared.attempt,
+            offer: prepared.offer,
+            primaryContract: input.contractId,
+        });
+        if (result.kind === "accepted") {
+            return { ...result, physical: followTargetPlacement(repository, physical.placement) };
+        }
+        if (result.kind === "publication-failed")
+            return result;
+        if (result.kind === "collision" && index + 1 === protocol.attempts.length)
+            return result;
+    }
+    return { kind: "exhausted" };
+}
+/** Run the sole placement adjudicator inside the target's physical fence. */
+export async function admitPlacement(channel, repository, target, input) {
+    const attempts = mintAttempts({ entryCount: 1 });
+    const protocol = {
+        input,
+        channel,
+        repository,
+        contracts: [input.contractId],
+        attempts,
+        decide: decidePlacement,
+    };
+    const run = () => runProtocol(protocol);
+    if (target === undefined)
+        return await run();
+    let held;
+    try {
+        held = await acquireTargetPlacementFence(repository, target);
+    }
+    catch (error) {
+        return placementFailure(error);
+    }
+    let result;
+    let exceptional;
+    try {
+        result = await runFencedPlacement(repository, input, protocol);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            exceptional = error;
+        else {
+            try {
+                result = expectedPlacementFailure(error);
+            }
+            catch (unexpected) {
+                exceptional = unexpected;
+            }
+        }
+    }
+    let releaseFailure;
+    try {
+        held.close();
+    }
+    catch (error) {
+        releaseFailure = error;
+    }
+    if (exceptional !== undefined)
+        throw exceptional;
+    if (result === undefined)
+        throw new Error("placement produced no result");
+    if (releaseFailure !== undefined) {
+        return result.kind === "accepted"
+            ? { ...result, physical: reconcileEffectFailure(releaseFailure, result.physical) }
+            : placementFailure(releaseFailure);
+    }
+    return result;
+}

package/build/src/protocol/read/audit.d.ts

@@ -1,5 +1,6 @@
+import { type GitDecodeChannel } from "../../git/read-observation.js";
 import type { GitRepository } from "../../git/repository.js";
-import type { ContractId, ContractState, FactKind, Gate, JournalEntry } from "../../core/facts/types.js";
+import type { ContractId, ContractState, DeliverData, FactKind, Gate, JournalEntry, SnapshotId } from "../../core/facts/types.js";
 export type { FactKind } from "../../core/facts/types.js";
 export type TimelineEntry = Readonly<{
     kind: FactKind;
@@ -15,11 +16,16 @@ export type AuditReport = Readonly<{
     reworks: number;
     reviews: number;
     timeline: readonly TimelineEntry[];
+    delivery?: DeliverData;
+    targetObservation?: Readonly<{
+        head: SnapshotId | null;
+        drift: boolean;
+    }>;
 }>;
 type AuditRead = Readonly<{
     state: ContractState | null;
     entries: readonly JournalEntry[];
     report: AuditReport;
 }>;
-export declare function auditReport(entries: readonly JournalEntry[], reviewed: Gate): AuditReport;
-export declare function readAudit(repository: GitRepository, contract: ContractId, reviewed: Gate): AuditRead;
+export declare function auditReport(entries: readonly JournalEntry[], reviewed: Gate, state?: ContractState, targetObservation?: AuditReport["targetObservation"]): AuditReport;
+export declare function readAuditAt(repository: GitRepository, channel: GitDecodeChannel, contract: ContractId, reviewed: Gate): Promise<AuditRead>;

package/build/src/protocol/read/audit.js

@@ -1,4 +1,5 @@
-import { observeContract } from "../../git/observe.js";
+import { observeContractWorld, observeDeliveryTargetAt } from "../../git/observe.js";
+import { withGitReadObservation } from "../../git/read-observation.js";
 function elapsedSince(prior, current) {
     if (prior === undefined)
         return null;
@@ -6,7 +7,7 @@ function elapsedSince(prior, current) {
     const currentMs = Date.parse(current);
     return currentMs - priorMs;
 }
-export function auditReport(entries, reviewed) {
+export function auditReport(entries, reviewed, state, targetObservation) {
     let reworks = 0;
     let reviews = 0;
     const timeline = entries.map((entry, index) => {
@@ -27,13 +28,28 @@ export function auditReport(entries, reviewed) {
             } : {}),
         };
     });
-    return { reworks, reviews, timeline };
-}
-export function readAudit(repository, contract, reviewed) {
-    const observation = observeContract(repository, contract);
+    const delivery = state?.delivery?.data;
     return {
-        state: observation.state,
-        entries: observation.entries,
-        report: auditReport(observation.entries, reviewed),
+        reworks,
+        reviews,
+        timeline,
+        ...(delivery === undefined ? {} : { delivery }),
+        ...(targetObservation === undefined ? {} : { targetObservation }),
     };
 }
+export async function readAuditAt(repository, channel, contract, reviewed) {
+    return withGitReadObservation(repository, channel, async (observation) => {
+        const world = await observeContractWorld(observation, [contract]);
+        const record = world.contracts.get(contract);
+        if (record === undefined)
+            throw new Error(`missing requested contract observation: ${contract}`);
+        const targetObservation = record.state === null
+            ? undefined
+            : await observeDeliveryTargetAt(observation, record.state) ?? undefined;
+        return {
+            state: record.state,
+            entries: record.entries,
+            report: auditReport(record.entries, reviewed, record.state ?? undefined, targetObservation),
+        };
+    });
+}

package/build/src/protocol/read/documents.d.ts

@@ -1,8 +1,8 @@
-import type { GitRepository } from "../../git/repository.js";
+import type { GitReadObservation } from "../../git/read-observation.js";
 import type { ContractId } from "../../core/facts/types.js";
 export type ContractDocumentProjection = Readonly<{
     contract: ContractId;
     documentBytes: string;
 }>;
 /** Read every live contract document from one immutable Git snapshot. */
-export declare function readDocuments(repository: GitRepository): readonly ContractDocumentProjection[];
+export declare function readDocuments(observation: GitReadObservation): Promise<readonly ContractDocumentProjection[]>;

package/build/src/protocol/read/documents.js

@@ -1,11 +1,11 @@
-import { observeGit } from "../../git/observe.js";
+import { observeActiveContractWorld } from "../../git/observe.js";
 /** Read every live contract document from one immutable Git snapshot. */
-export function readDocuments(repository) {
-    const observed = observeGit(repository);
+export async function readDocuments(observation) {
+    const observed = await observeActiveContractWorld(observation);
     const documents = [];
     for (const [contract, observation] of observed.contracts) {
         const state = observation.state;
-        if (state === null || state.terminal !== null)
+        if (state === null)
             continue;
         documents.push({
             contract,

package/build/src/protocol/read/status.d.ts

@@ -1,6 +1,7 @@
 import type { GitRepository } from "../../git/repository.js";
+import type { GitDecodeChannel, GitReadObservation } from "../../git/read-observation.js";
 import { type GateCurrent } from "../../core/facts/gate.js";
-import type { ContractId, SnapshotId } from "../../core/facts/types.js";
+import type { ContractId, DeliverData, SnapshotId } from "../../core/facts/types.js";
 export type ContractPhase = "waiting" | "bound" | "pending-delivery" | "claimed" | "abandoned";
 export type ContractDisposition = "active" | "terminal";
 export type ContractGateCurrent = GateCurrent;
@@ -15,7 +16,11 @@ export type ContractRow = Readonly<{
     workspace: "worktree" | "here";
     worktreePath: string | null;
     target: string | null;
-    candidate: SnapshotId | null;
+    delivery: DeliverData | null;
+    targetObservation: Readonly<{
+        head: SnapshotId | null;
+        drift: boolean;
+    }> | null;
     gates: Readonly<{
         reports: readonly ContractGateReport[];
         satisfied: boolean;
@@ -23,6 +28,7 @@ export type ContractRow = Readonly<{
 }>;
 export type ContractBoard = Readonly<{
     root: string;
+    state: SnapshotId | null;
     rows: readonly ContractRow[];
 }>;
 export type ContractObservation = Readonly<{
@@ -33,6 +39,6 @@ export type ContractObservation = Readonly<{
     row: ContractRow;
 }>;
 /** Build the Contract board from one immutable git observation. */
-export declare function readContractBoard(repository: GitRepository): ContractBoard;
-/** Observe one Contract without enumerating the Contract world. */
-export declare function readContractObservation(repository: GitRepository, id: ContractId): ContractObservation;
+export declare function readContractBoard(observation: GitReadObservation): Promise<ContractBoard>;
+/** Observe one Contract and its target from one fresh ref epoch. */
+export declare function readContractObservationAt(repository: GitRepository, channel: GitDecodeChannel, id: ContractId): Promise<ContractObservation>;

package/build/src/protocol/read/status.js

@@ -1,28 +1,30 @@
-import { observeGit, observeContract } from "../../git/observe.js";
-import { deliveryWorktreePath } from "../../git/reconcile.js";
+import { extendContractsForAdmissionAt, observeActiveContractWorld, observeContractsForAdmissionInObservationAt, observeDeliveryTargetAt, withContractReadObservationAt, } from "../../git/observe.js";
+import { deliveryWorktreePath } from "../../git/workspace.js";
 import { gateReports } from "../../core/facts/gate.js";
-function phaseFor(state) {
+import { prerequisiteStatus } from "../../core/facts/observation.js";
+function phaseFor(state, eligible) {
     if (state.terminal?.kind === "claimed")
         return "claimed";
     if (state.terminal?.kind === "abandoned")
         return "abandoned";
     if (state.delivery !== null)
         return "pending-delivery";
-    if (state.bound !== null)
+    if (state.bound !== null || eligible)
         return "bound";
     return "waiting";
 }
-function rowFor(repository, state) {
+function rowFor(repository, state, targetObservation, eligible) {
     const workspace = state.coordinates.workspace;
     const gates = gateReports(state);
     return {
         id: state.id,
-        phase: phaseFor(state),
+        phase: phaseFor(state, eligible),
         disposition: state.terminal === null ? "active" : "terminal",
         workspace,
         worktreePath: workspace === "worktree" ? deliveryWorktreePath(repository, state.id) : null,
         target: state.coordinates.target ?? null,
-        candidate: state.delivery?.data.candidate ?? null,
+        delivery: state.delivery?.data ?? null,
+        targetObservation,
         gates: {
             reports: gates.reports.map((report) => ({ gate: report.gate, current: report.current })),
             satisfied: gates.satisfied,
@@ -30,18 +32,29 @@ function rowFor(repository, state) {
     };
 }
 /** Build the Contract board from one immutable git observation. */
-export function readContractBoard(repository) {
-    const observed = observeGit(repository);
+export async function readContractBoard(observation) {
+    const observed = await observeActiveContractWorld(observation);
     const rows = [];
     for (const value of observed.contracts.values()) {
         if (value.state === null)
             continue;
-        rows.push(rowFor(repository, value.state));
+        const state = value.state;
+        rows.push(observeDeliveryTargetAt(observation, state).then((target) => rowFor(observation.repository, state, target, prerequisiteStatus(state.terms.after, observed.eligibility) === "claimed")));
     }
-    return { root: repository.primaryWorktree, rows };
+    return { root: observation.repository.primaryWorktree, state: observed.snapshot, rows: await Promise.all(rows) };
 }
-/** Observe one Contract without enumerating the Contract world. */
-export function readContractObservation(repository, id) {
-    const state = observeContract(repository, id).state;
-    return state === null ? { kind: "missing", id } : { kind: "present", row: rowFor(repository, state) };
+/** Observe one Contract and its target from one fresh ref epoch. */
+export async function readContractObservationAt(repository, channel, id) {
+    return withContractReadObservationAt(repository, channel, id, async (observation) => {
+        let observed = await observeContractsForAdmissionInObservationAt(observation, [id]);
+        const state = observed.decision.get(id) ?? null;
+        if (state !== null)
+            observed = await extendContractsForAdmissionAt(channel, observed, state.terms.after);
+        return state === null
+            ? { kind: "missing", id }
+            : {
+                kind: "present",
+                row: rowFor(observation.repository, state, await observeDeliveryTargetAt(observation, state), prerequisiteStatus(state.terms.after, observed.decision) === "claimed"),
+            };
+    });
 }

package/build/src/protocol/run.d.ts

@@ -1,5 +1,7 @@
 import { type GitDecisionObservation } from "../git/observe.js";
+import type { GitDecodeChannel, GitTreeSelection } from "../git/read-observation.js";
 import type { GitRepository } from "../git/repository.js";
+import type { GitRefAssertion } from "../git/repository.js";
 import type { AttemptContext, DecideInput, OfferDecision } from "../core/decide.js";
 import type { Offer, TreeUpdate } from "../core/facts/offer.js";
 import { type ContractId } from "../core/facts/types.js";
@@ -16,24 +18,64 @@ export type CompanionDecorator = (input: Readonly<{
     observation: GitDecisionObservation;
     contractId: ContractId;
     offer: Offer;
-}>) => readonly TreeUpdate[];
-type RunProtocolInput<Input extends Readonly<{
+}>) => readonly TreeUpdate[] | Promise<readonly TreeUpdate[]>;
+export type RunProtocolInput<Input extends Readonly<{
     contractId: ContractId;
-}>, Refusal> = Readonly<{
-    input: Input;
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}> = Input> = Readonly<{
+    channel: GitDecodeChannel;
     repository: GitRepository;
     contracts: readonly ContractId[];
     attempts: readonly AttemptContext[];
     decide: (input: DecideInput<Input>) => OfferDecision<Refusal>;
     /** Override the targeted observer only for intents that need a full snapshot. */
-    observe?: (repository: GitRepository, contracts: readonly ContractId[]) => GitDecisionObservation;
+    observe?: (repository: GitRepository, channel: GitDecodeChannel, contracts: readonly ContractId[]) => Promise<GitDecisionObservation>;
     /** Mint verb-owned entries from the exact size of this attempt's observation. */
     extendAttempt?: (attempt: AttemptContext, observedContractCount: number) => AttemptContext;
     /** Add opaque companions from the exact immutable observation for this attempt. */
     decorateOffer?: CompanionDecorator;
+    observationSelection?: GitTreeSelection;
+}> & (Readonly<{
+    input: Input;
+    prepareInput?: never;
+}> | Readonly<{
+    input: Seed;
+    prepareInput: (observation: GitDecisionObservation, input: Seed) => Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }> | Promise<Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }>>;
+}>);
+export type PreparedProtocolAttempt<Refusal> = Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}> | Readonly<{
+    kind: "offered";
+    observation: GitDecisionObservation;
+    attempt: AttemptContext;
+    offer: Offer;
+    assertions: readonly GitRefAssertion[];
 }>;
+/** Form one decided offer without admitting or reinterpreting it. */
+export declare function prepareProtocolAttempt<Input extends Readonly<{
+    contractId: ContractId;
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}> = Input>(input: RunProtocolInput<Input, Refusal, Seed>, baseAttempt: AttemptContext): Promise<PreparedProtocolAttempt<Refusal>>;
 /** Run bounded, verb-neutral attempts and return one real admission on acceptance. */
 export declare function runProtocol<Input extends Readonly<{
     contractId: ContractId;
-}>, Refusal>(input: RunProtocolInput<Input, Refusal>): ProtocolResult<Refusal>;
-export {};
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}> = Input>(input: RunProtocolInput<Input, Refusal, Seed>): Promise<ProtocolResult<Refusal>>;

package/build/src/protocol/run.js

@@ -1,32 +1,60 @@
-import { observeContractsForAdmission } from "../git/observe.js";
+import { extendAdmissionPathsAt, observeContractsForAdmissionAt, } from "../git/observe.js";
 import { admitDecidedOffer } from "./attempt.js";
+/** Form one decided offer without admitting or reinterpreting it. */
+export async function prepareProtocolAttempt(input, baseAttempt) {
+    const decisionObservation = input.observe === undefined
+        ? await observeContractsForAdmissionAt(input.repository, input.channel, input.contracts, input.observationSelection)
+        : await input.observe(input.repository, input.channel, input.contracts);
+    const observation = decisionObservation.decision;
+    const preparedInput = "prepareInput" in input && input.prepareInput !== undefined
+        ? await input.prepareInput(decisionObservation, input.input)
+        : { kind: "prepared", input: input.input, assertions: [] };
+    if (preparedInput.kind === "refused")
+        return preparedInput;
+    const attempt = input.extendAttempt === undefined
+        ? baseAttempt
+        : input.extendAttempt(baseAttempt, observation.size);
+    const decision = input.decide({ input: preparedInput.input, attempt, observation });
+    if (decision.kind === "refused")
+        return decision;
+    const companions = input.decorateOffer === undefined
+        ? []
+        : await input.decorateOffer({
+            repository: input.repository,
+            observation: decisionObservation,
+            contractId: input.input.contractId,
+            offer: decision.offer,
+        });
+    const offer = companions.length === 0
+        ? decision.offer
+        : { ...decision.offer, companions: [...(decision.offer.companions ?? []), ...companions] };
+    const admissionObservation = companions.length === 0
+        ? decisionObservation
+        : await extendAdmissionPathsAt(input.channel, decisionObservation, companions.map(({ path }) => path));
+    return {
+        kind: "offered",
+        observation: admissionObservation,
+        attempt,
+        offer,
+        assertions: preparedInput.assertions ?? [],
+    };
+}
 /** Run bounded, verb-neutral attempts and return one real admission on acceptance. */
-export function runProtocol(input) {
+export async function runProtocol(input) {
     const attempts = input.attempts;
-    const contracts = input.contracts;
-    const observe = input.observe ?? observeContractsForAdmission;
     for (let index = 0; index < attempts.length; index += 1) {
-        const baseAttempt = attempts[index];
-        const decisionObservation = observe(input.repository, contracts);
-        const observation = decisionObservation.decision;
-        const attempt = input.extendAttempt === undefined
-            ? baseAttempt
-            : input.extendAttempt(baseAttempt, observation.size);
-        const decision = input.decide({ input: input.input, attempt, observation });
-        if (decision.kind === "refused")
-            return { kind: "refused", refusal: decision.refusal };
-        const companions = input.decorateOffer === undefined
-            ? []
-            : input.decorateOffer({
-                repository: input.repository,
-                observation: decisionObservation,
-                contractId: input.input.contractId,
-                offer: decision.offer,
-            });
-        const offer = companions.length === 0
-            ? decision.offer
-            : { ...decision.offer, companions: [...(decision.offer.companions ?? []), ...companions] };
-        const result = admitDecidedOffer(input.repository, decisionObservation, attempt, offer, input.input.contractId);
+        const prepared = await prepareProtocolAttempt(input, attempts[index]);
+        if (prepared.kind === "refused")
+            return prepared;
+        const result = await admitDecidedOffer({
+            channel: input.channel,
+            repository: input.repository,
+            decisionObservation: prepared.observation,
+            attempt: prepared.attempt,
+            offer: prepared.offer,
+            primaryContract: input.input.contractId,
+            assertions: prepared.assertions,
+        });
         if (result.kind === "accepted" || result.kind === "publication-failed")
             return result;
         if (result.kind === "collision" && index + 1 === attempts.length)

package/build/src/runtime/proc/line-rpc.d.ts

@@ -33,5 +33,6 @@ export declare class LineRpcProcess {
     private fail;
     request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
     notify(method: string): void;
+    endInputAndDrain(timeoutMs?: number): Promise<void>;
     close(force?: boolean): Promise<void>;
 }

package/build/src/runtime/proc/line-rpc.js

@@ -1,5 +1,12 @@
 import { spawn } from "node:child_process";
 import { terminateProcessTree } from "./run.js";
+const DEFAULT_DRAIN_TIMEOUT_MS = 1_000;
+function bounded(promise, milliseconds) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), milliseconds);
+        void promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -110,6 +117,20 @@ export class LineRpcProcess {
         if (!this.closed)
             this.child.stdin.write(`${JSON.stringify({ method })}\n`);
     }
+    async endInputAndDrain(timeoutMs = DEFAULT_DRAIN_TIMEOUT_MS) {
+        if (this.closed) {
+            await this.exited;
+            return;
+        }
+        this.closed = true;
+        this.fail(new Error("line RPC process is closed"));
+        this.child.stdin.end();
+        const drained = await bounded(this.exited, timeoutMs);
+        if (drained === undefined) {
+            await terminateProcessTree(this.child.pid, true);
+            await this.exited;
+        }
+    }
     async close(force = false) {
         if (this.closed) {
             await this.exited;

package/build/src/runtime/proc/run.d.ts

@@ -2,9 +2,10 @@ type ProcessLaunch = Readonly<{
     readonly argv: readonly string[];
     readonly cwd?: string;
     readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
 }>;
 export type ProcessInput = ProcessLaunch & Readonly<{
-    readonly timeoutMs: number;
+    readonly timeoutMs?: number;
 }>;
 type ProcessTerminal = Readonly<{
     readonly kind: "terminal";
@@ -23,7 +24,20 @@ type ProcessSpawnError = Readonly<{
 type ProcessUnknownExit = Readonly<{
     readonly kind: "unknown-exit";
 }>;
-export type ProcessOutcome = ProcessTerminal | ProcessTimeout | ProcessSpawnError | ProcessUnknownExit;
+type ProcessCancelled = Readonly<{
+    readonly kind: "cancelled";
+}>;
+export type ProcessOutcome = ProcessTerminal | ProcessTimeout | ProcessSpawnError | ProcessUnknownExit | ProcessCancelled;
+export type ProcessIdentity = Readonly<{
+    pid: number;
+    spawnedAt: string;
+}>;
+export type ProcessIdentityProbe = Readonly<{
+    kind: "gone" | "alive" | "replaced";
+}> | Readonly<{
+    kind: "unverifiable";
+    diagnostic: string;
+}>;
 export type ProcessCollar = Readonly<{
     pid: number;
     processGroup: number;
@@ -46,6 +60,8 @@ export type DetachedProcessInput = Readonly<{
 }>;
 export declare function terminateProcessTree(pid: number | undefined, force?: boolean): Promise<void>;
 export declare function currentProcessCollar(): ProcessCollar;
+export declare function currentProcessIdentity(): ProcessIdentity;
+export declare function probeProcessIdentity(identity: ProcessIdentity): ProcessIdentityProbe;
 export declare function spawnDetachedProcess(input: DetachedProcessInput): Promise<ProcessCollar>;
 export declare function probeProcessTree(collar: ProcessCollar): ProcessTreeProbe;
 export declare function putDownProcessTree(collar: ProcessCollar): Promise<PutDownEvidence>;