sortie-dogs 0.8.2 → 0.8.3

package/dist/core/adaptive-remediation-runtime.js

@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+import { compareAdaptiveSignal } from "./adaptive-signal-comparison.js";
+import { selectAdaptiveRemediation } from "./adaptive-eligibility.js";
+/** Shared RunFlightLedger adapter: probe iterations charge the existing cumulative recovery authority. */
+export class AdaptiveRunFlightLineage {
+    options;
+    predecessor;
+    reservations = new Set();
+    constructor(options) {
+        this.options = options;
+        this.predecessor = options.predecessor_attempt_id;
+    }
+    async reserveProbe() {
+        const attemptID = randomUUID();
+        await this.options.ledger.append({ kind: "attempt.started", at: new Date().toISOString(), attempt_id: attemptID,
+            predecessor_attempt_id: this.predecessor, unit_id: this.options.unit_id, candidate_id: this.options.candidate_id,
+            route_id: this.options.route_id, role: "implementation", selected_model: this.options.selected_model,
+            selected_variant: this.options.selected_variant, child_id: null, call_id: randomUUID(),
+            budget_charge: { kind: "adaptive_probe", recovery_actions: 1, probe_iterations: 1,
+                model_attempts: this.options.model_attempt_per_patch ? 1 : 0 } });
+        this.reservations.add(attemptID);
+        this.predecessor = attemptID;
+        return attemptID;
+    }
+    async finishProbe(input) {
+        if (!this.reservations.delete(input.reservation_id))
+            throw new Error("adaptive-lineage-reservation-invalid");
+        await this.options.ledger.append({ kind: "attempt.finished", at: new Date().toISOString(), attempt_id: input.reservation_id,
+            observed_model: this.options.model_attempt_per_patch ? this.options.selected_model : null,
+            observed_variant: this.options.model_attempt_per_patch ? this.options.selected_variant : null,
+            failure: null, disposition: "succeeded", observation: { stage: "recovery", duration_ms: input.duration_ms,
+                usage: { input_tokens: null, cache_read_tokens: null, output_tokens: null, provenance: "unknown" },
+                estimated_cost: { usd: null, provenance: "unknown" } },
+            references: { capsule_ids: [], artifact_ids: [`sha256:${input.patch.patch_fingerprint}`] } });
+    }
+    async failProbe(input) {
+        if (!this.reservations.delete(input.reservation_id))
+            throw new Error("adaptive-lineage-reservation-invalid");
+        await this.options.ledger.append({ kind: "attempt.finished", at: new Date().toISOString(), attempt_id: input.reservation_id,
+            observed_model: this.options.model_attempt_per_patch ? this.options.selected_model : null,
+            observed_variant: this.options.model_attempt_per_patch ? this.options.selected_variant : null,
+            failure: { category: "implementation", code: input.code }, disposition: "failed",
+            observation: { stage: "recovery", duration_ms: input.duration_ms,
+                usage: { input_tokens: null, cache_read_tokens: null, output_tokens: null, provenance: "unknown" },
+                estimated_cost: { usd: null, provenance: "unknown" } }, references: { capsule_ids: [], artifact_ids: [] } });
+    }
+}
+const pending = (command) => ({
+    command: [command.executable, ...(command.args ?? [])], status: "pending", exit_code: null, fingerprint: null,
+});
+const goalMet = (signal, value) => value !== null &&
+    (signal.goal.operator === "at-least" ? value >= signal.goal.value : value <= signal.goal.value);
+const failure = (code, detail) => ({ code, fallback: "stop", detail });
+/** Executes the bounded state machine. Hosts own process/worktree mechanics; evidence cannot skip a stage. */
+export class AdaptiveRemediationRuntime {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    async execute(request) {
+        const started = Date.now();
+        const selected = selectAdaptiveRemediation(request.eligibility);
+        if (selected.status !== "selected")
+            throw new Error(`adaptive-admission-${selected.reason}`);
+        const target = await this.host.snapshotTarget(request.target_ref);
+        const contract = {
+            version: "0.1.0", task_id: request.task_id, selection: selected.selection, state: "ADMITTED",
+            target: { ref: request.target_ref, base_head: target.head, base_tree: target.tree },
+            allowed_paths: { read: [...request.allowed_paths.read], write: [...request.allowed_paths.write] },
+            limits: { iteration_budget: request.iteration_budget, max_changed_paths: request.max_changed_paths, cleanup_timeout_ms: request.cleanup_timeout_ms },
+            probe_validation: request.probe_validation, canonical_validation: request.canonical_validation,
+            improvement_signals: [request.improvement_signal], risk_class: request.risk_class,
+            post_merge_validation: request.post_merge_validation, baseline_probe: null, iterations: [], converged: false,
+            full_validation: pending(request.canonical_validation), review: { status: "pending", fingerprint: null, remediation_attempts: 0 },
+            promotion: { status: "pending", expected_target_head: target.head, observed_target_head: null, candidate_head: null },
+            post_merge: pending(request.post_merge_validation), failure: null,
+            metrics: { mode: selected.selection.mode, reason: selected.selection.reason, activation_reason: selected.selection.activation_reason,
+                iteration_count: 0, probe_count: 0, full_validation_count: 0, post_merge_validation_count: 0,
+                discarded_patch_count: 0, time_to_first_signal_ms: null, duration_ms: 0, total_tokens: null,
+                estimated_cost_usd: null, sol_demotions: 0, cas_conflicts: 0, post_merge_failures: 0 },
+        };
+        if (selected.selection.mode === "standard")
+            return { ...contract, metrics: { ...contract.metrics, duration_ms: Date.now() - started } };
+        const candidates = [];
+        let currentHead = target.head;
+        let baseline;
+        try {
+            for (let number = 1; number <= request.iteration_budget; number += 1) {
+                const iteration = number;
+                const candidate = await this.host.openCandidate(currentHead, iteration);
+                candidates.push(candidate);
+                if (baseline === undefined) {
+                    contract.state = "PROBING";
+                    baseline = await this.host.runBaselineProbe(candidate, request.probe_validation);
+                    contract.metrics.probe_count += 1;
+                    if (baseline.exit_code !== 0 || baseline.signal_id !== request.improvement_signal.signal_id) {
+                        contract.state = "ABANDONED";
+                        contract.failure = failure("PROBE_FAILED", "Baseline probe did not return the declared typed signal.");
+                        break;
+                    }
+                    contract.baseline_probe = { signal_id: baseline.signal_id, value: baseline.value, artifact_fingerprint: baseline.fingerprint };
+                    contract.metrics.time_to_first_signal_ms = Date.now() - started;
+                }
+                const before = await this.host.snapshotTarget(request.target_ref);
+                if (before.head !== target.head || before.tree !== target.tree) {
+                    contract.state = "REINTEGRATE_REQUIRED";
+                    contract.failure = failure("CAS_DRIFT", "Target changed before candidate promotion.");
+                    contract.metrics.cas_conflicts += 1;
+                    break;
+                }
+                let reservation = "";
+                const iterationStarted = Date.now();
+                try {
+                    reservation = await this.host.reserveProbe?.({ task_id: request.task_id, iteration, parent_candidate: currentHead }) ?? "";
+                }
+                catch (error) {
+                    if (error !== null && typeof error === "object" && "code" in error && error.code === "budget") {
+                        contract.state = "SOL_DEMOTED";
+                        contract.failure = failure("ITERATION_BUDGET_EXHAUSTED", "Shared recovery budget denied the probe iteration.");
+                        contract.metrics.sol_demotions += 1;
+                        break;
+                    }
+                    throw error;
+                }
+                let patch;
+                try {
+                    patch = await this.host.producePatch({ candidate, iteration, acceptance: request.acceptance,
+                        allowed_paths: request.allowed_paths, probe_validation: request.probe_validation });
+                }
+                catch (error) {
+                    if (reservation !== "")
+                        await this.host.failProbe?.({ reservation_id: reservation,
+                            duration_ms: Date.now() - iterationStarted, code: "PROBE_FAILED" });
+                    contract.state = "ABANDONED";
+                    contract.failure = failure("PROBE_FAILED", error instanceof Error ? error.message : "Probe failed.");
+                    break;
+                }
+                contract.metrics.probe_count += 1;
+                if (reservation !== "")
+                    await this.host.finishProbe?.({ reservation_id: reservation, patch, duration_ms: Date.now() - iterationStarted });
+                const outside = patch.changed_paths.filter((path) => !request.allowed_paths.write.includes(path));
+                if (patch.candidate.parent_head !== currentHead || patch.changed_paths.length === 0 ||
+                    patch.changed_paths.length > request.max_changed_paths || outside.length > 0) {
+                    contract.state = "REJECTED";
+                    contract.failure = failure("SCOPE_EXPANSION_REQUIRED", "Patch changed paths outside its bounded unit.");
+                    break;
+                }
+                const compared = compareAdaptiveSignal({ signal: { signal_id: request.improvement_signal.signal_id,
+                        improvement_direction: request.improvement_signal.improvement_direction,
+                        absolute_improvement_threshold: request.improvement_signal.absolute_improvement_threshold },
+                    baseline: { signal_id: baseline.signal_id, value: baseline.value },
+                    current: { signal_id: patch.probe.signal_id, value: patch.probe.value } });
+                const outcome = compared.status === "compared" ? compared.outcome : "inconclusive";
+                const cleanup = await this.host.inspectCleanup(candidate, request.cleanup_timeout_ms);
+                const evidence = { iteration, parent_candidate: currentHead,
+                    candidate_head: patch.candidate_head, hypothesis: patch.hypothesis, patch_fingerprint: patch.patch_fingerprint,
+                    changed_paths: [...patch.changed_paths], measured_probe: { signal_id: patch.probe.signal_id,
+                        baseline_value: baseline.value, current_value: patch.probe.value, outcome,
+                        artifact_fingerprint: patch.probe.fingerprint }, cleanup: { status: cleanup.ok ? "pass" : "fail", remaining_paths: [...cleanup.remaining_paths] } };
+                contract.iterations = [...contract.iterations, evidence];
+                contract.metrics.iteration_count += 1;
+                if (!cleanup.ok) {
+                    contract.state = "ABANDONED";
+                    contract.failure = failure("CLEANUP_FAILED", "Iteration cleanup did not close all residue or processes.");
+                    break;
+                }
+                if (patch.probe.exit_code !== 0) {
+                    contract.state = "ABANDONED";
+                    contract.failure = failure("PROBE_FAILED", "Patch probe exited unsuccessfully.");
+                    break;
+                }
+                if (outcome !== "improved") {
+                    contract.metrics.discarded_patch_count += 1;
+                    contract.state = "ABANDONED";
+                    contract.failure = failure("NO_IMPROVEMENT", `Measured signal outcome was ${outcome}.`);
+                    break;
+                }
+                contract.state = "PROMISING";
+                currentHead = patch.candidate_head;
+                baseline = patch.probe;
+                if (goalMet(request.improvement_signal, patch.probe.value)) {
+                    contract.converged = true;
+                    contract.state = "CONVERGED";
+                    break;
+                }
+                if (number === request.iteration_budget) {
+                    contract.state = "SOL_DEMOTED";
+                    contract.failure = failure("ITERATION_BUDGET_EXHAUSTED", "Declared convergence goal was not reached within the shared iteration budget.");
+                    contract.metrics.sol_demotions += 1;
+                    break;
+                }
+                contract.state = "REFINING";
+            }
+            if (!contract.converged || contract.failure !== null)
+                return contract;
+            const finalCandidate = candidates.at(-1);
+            contract.full_validation = await this.host.runCanonical(finalCandidate, request.canonical_validation);
+            contract.metrics.full_validation_count = 1;
+            if (contract.full_validation.status !== "pass") {
+                contract.state = "ABANDONED";
+                contract.failure = failure("FULL_VALIDATION_FAILED", "Canonical candidate validation failed.");
+                return contract;
+            }
+            contract.state = "FULL_VALIDATED";
+            const review = await this.host.review({ candidate: finalCandidate, candidate_head: currentHead, risk_class: request.risk_class });
+            contract.review = { status: review.status, fingerprint: review.fingerprint, remediation_attempts: review.status === "remediation-required" ? 1 : 0 };
+            if (review.status !== "pass") {
+                contract.state = "REJECTED";
+                contract.failure = failure("REVIEW_REMEDIATION_REQUIRED", "Risk-based review did not approve this candidate.");
+                return contract;
+            }
+            contract.state = "REVIEWED";
+            const beforeCas = await this.host.snapshotTarget(request.target_ref);
+            if (beforeCas.head !== target.head || beforeCas.tree !== target.tree) {
+                contract.state = "REINTEGRATE_REQUIRED";
+                contract.failure = failure("CAS_DRIFT", "Expected target base changed before CAS.");
+                contract.metrics.cas_conflicts += 1;
+                return contract;
+            }
+            const promotion = await this.host.promote({ target_ref: request.target_ref, expected_head: target.head, candidate_head: currentHead });
+            contract.promotion = { status: promotion.status, expected_target_head: target.head,
+                observed_target_head: promotion.observed_head, candidate_head: currentHead };
+            if (promotion.status !== "promoted") {
+                contract.state = "REINTEGRATE_REQUIRED";
+                contract.failure = failure("CAS_DRIFT", "Target CAS lost; target was not changed by this attempt.");
+                contract.metrics.cas_conflicts += 1;
+                return contract;
+            }
+            contract.state = "MERGED";
+            contract.post_merge = await this.host.runPostMerge(request.post_merge_validation);
+            contract.metrics.post_merge_validation_count = 1;
+            if (contract.post_merge.status !== "pass") {
+                contract.failure = failure("POST_MERGE_VERIFICATION_FAILED", "Post-merge verification failed; a new repair candidate is required.");
+                contract.metrics.post_merge_failures += 1;
+                return contract;
+            }
+            contract.state = "VERIFIED";
+            return contract;
+        }
+        finally {
+            const released = await this.host.release(candidates).catch(() => ({ ok: false, remaining_paths: candidates.map(({ path }) => path) }));
+            if (!released.ok && contract.failure === null) {
+                contract.state = "ABANDONED";
+                contract.failure = failure("CLEANUP_FAILED", "Final candidate cleanup failed.");
+            }
+            contract.metrics.duration_ms = Date.now() - started;
+        }
+    }
+}

package/dist/core/adaptive-signal-comparison.d.ts

@@ -0,0 +1,29 @@
+export type AdaptiveSignalImprovementDirection = "increase" | "decrease";
+export interface AdaptiveSignalDefinition {
+    readonly signal_id: string;
+    readonly improvement_direction: AdaptiveSignalImprovementDirection;
+    readonly absolute_improvement_threshold: number;
+}
+export interface AdaptiveSignalObservation {
+    readonly signal_id: string;
+    readonly value: number | null;
+}
+export interface AdaptiveSignalComparisonInput {
+    readonly signal: AdaptiveSignalDefinition;
+    readonly baseline: AdaptiveSignalObservation;
+    readonly current: AdaptiveSignalObservation;
+}
+export type AdaptiveSignalComparisonOutcome = "improved" | "unchanged" | "worse" | "inconclusive";
+export type AdaptiveSignalComparisonRejectionReason = "invalid-input" | "invalid-signal-identity" | "invalid-improvement-direction" | "invalid-improvement-threshold" | "invalid-observation" | "numeric-overflow";
+export type AdaptiveSignalComparisonResult = {
+    readonly status: "compared";
+    readonly outcome: AdaptiveSignalComparisonOutcome;
+} | {
+    readonly status: "rejected";
+    readonly reason: AdaptiveSignalComparisonRejectionReason;
+};
+/**
+ * Compares two declared observations without probing, validation, or runtime side effects.
+ * The result is evidence classification only; it does not establish convergence or authorize promotion.
+ */
+export declare function compareAdaptiveSignal(input: unknown): AdaptiveSignalComparisonResult;

package/dist/core/adaptive-signal-comparison.js

@@ -0,0 +1,64 @@
+const INPUT_KEYS = ["signal", "baseline", "current"];
+const SIGNAL_KEYS = [
+    "signal_id",
+    "improvement_direction",
+    "absolute_improvement_threshold",
+];
+const OBSERVATION_KEYS = ["signal_id", "value"];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasOnlyKeys = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+const isSignalId = (value) => typeof value === "string" && value.length > 0 && value.trim() === value;
+const reject = (reason) => ({ status: "rejected", reason });
+/**
+ * Compares two declared observations without probing, validation, or runtime side effects.
+ * The result is evidence classification only; it does not establish convergence or authorize promotion.
+ */
+export function compareAdaptiveSignal(input) {
+    if (!isObject(input) || !hasOnlyKeys(input, INPUT_KEYS)
+        || !Object.hasOwn(input, "signal") || !isObject(input.signal)
+        || !Object.hasOwn(input, "baseline") || !isObject(input.baseline)
+        || !Object.hasOwn(input, "current") || !isObject(input.current)
+        || !hasOnlyKeys(input.signal, SIGNAL_KEYS)
+        || !hasOnlyKeys(input.baseline, OBSERVATION_KEYS)
+        || !hasOnlyKeys(input.current, OBSERVATION_KEYS)) {
+        return reject("invalid-input");
+    }
+    const { signal, baseline, current } = input;
+    if (!Object.hasOwn(signal, "signal_id") || !isSignalId(signal.signal_id)
+        || !Object.hasOwn(baseline, "signal_id") || !isSignalId(baseline.signal_id)
+        || !Object.hasOwn(current, "signal_id") || !isSignalId(current.signal_id)
+        || signal.signal_id !== baseline.signal_id || signal.signal_id !== current.signal_id) {
+        return reject("invalid-signal-identity");
+    }
+    if (!Object.hasOwn(signal, "improvement_direction")
+        || (signal.improvement_direction !== "increase" && signal.improvement_direction !== "decrease")) {
+        return reject("invalid-improvement-direction");
+    }
+    if (!Object.hasOwn(signal, "absolute_improvement_threshold")
+        || typeof signal.absolute_improvement_threshold !== "number"
+        || !Number.isFinite(signal.absolute_improvement_threshold)
+        || signal.absolute_improvement_threshold < 0) {
+        return reject("invalid-improvement-threshold");
+    }
+    if (!Object.hasOwn(baseline, "value") || !Object.hasOwn(current, "value")
+        || (baseline.value !== null
+            && (typeof baseline.value !== "number" || !Number.isFinite(baseline.value)))
+        || (current.value !== null
+            && (typeof current.value !== "number" || !Number.isFinite(current.value)))) {
+        return reject("invalid-observation");
+    }
+    if (baseline.value === null || current.value === null) {
+        return { status: "compared", outcome: "inconclusive" };
+    }
+    const directedDifference = signal.improvement_direction === "increase"
+        ? current.value - baseline.value
+        : baseline.value - current.value;
+    if (!Number.isFinite(directedDifference))
+        return reject("numeric-overflow");
+    if (directedDifference < 0)
+        return { status: "compared", outcome: "worse" };
+    if (directedDifference === 0 || directedDifference < signal.absolute_improvement_threshold) {
+        return { status: "compared", outcome: "unchanged" };
+    }
+    return { status: "compared", outcome: "improved" };
+}

package/dist/core/child-cancellation-plan.d.ts

@@ -0,0 +1,45 @@
+import { type ChildTerminalEvidence, type ChildTerminalIdentity, type ChildTerminalObservation, type ChildTerminalReconciliationReason } from "./child-terminal-reconciliation.js";
+export interface ChildCancellationPlanInput {
+    readonly current: ChildTerminalIdentity;
+    readonly observation: ChildTerminalObservation;
+    readonly evidence: ChildTerminalEvidence;
+    readonly settled_fingerprint?: string | null;
+    /** Caller-supplied monotonic or wall-clock milliseconds. Must share a clock domain with now_ms. */
+    readonly deadline_ms: number;
+    /** Caller-supplied current time; this planner never reads a clock. */
+    readonly now_ms: number;
+    readonly cancellation_requested: boolean;
+    /** Durable stop-request history. Exact identity matching provides replay suppression. */
+    readonly prior_stop_requests: readonly ChildTerminalIdentity[];
+}
+export type ChildCancellationTrigger = "deadline_expired" | "explicit_cancellation";
+export interface ChildCancellationStopProposal {
+    readonly identity: ChildTerminalIdentity;
+    readonly trigger: ChildCancellationTrigger;
+    readonly runtime_responsibilities: {
+        readonly persist_stop_request_for_idempotency: true;
+        readonly stop_normal_process_tree: true;
+        readonly verify_actual_cancellation_and_no_leaks: true;
+    };
+}
+export type ChildCancellationNonProposalReason = "artifact_window_open" | "artifact_window_unknown" | "terminal_unknown" | "terminal_already_observed" | "cancellation_not_requested" | "stop_already_requested";
+export type ChildCancellationPlanOutcome = {
+    readonly status: "not_proposed";
+    readonly reason: ChildCancellationNonProposalReason;
+} | {
+    readonly status: "rejected";
+    readonly reason: "invalid_input" | "invalid_time";
+} | {
+    readonly status: "rejected";
+    readonly reason: "terminal_reconciliation_rejected";
+    readonly reconciliation_reason: ChildTerminalReconciliationReason;
+} | {
+    readonly status: "proposed";
+    readonly proposal: ChildCancellationStopProposal;
+};
+/**
+ * Produces an inert stop proposal. It performs no I/O, clock read, process stop, release,
+ * ledger append, writer admission, or target mutation. A satisfied terminal observation only
+ * makes stopping unnecessary; it does not independently assert that every resource is released.
+ */
+export declare function planChildCancellation(input: unknown): ChildCancellationPlanOutcome;

package/dist/core/child-cancellation-plan.js

@@ -0,0 +1,87 @@
+import { reconcileChildTerminal, } from "./child-terminal-reconciliation.js";
+const INPUT_KEYS = [
+    "current",
+    "observation",
+    "evidence",
+    "settled_fingerprint",
+    "deadline_ms",
+    "now_ms",
+    "cancellation_requested",
+    "prior_stop_requests",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyInputKeys(value) {
+    return Object.keys(value).every((key) => INPUT_KEYS.includes(key));
+}
+function isTime(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function sameIdentity(left, right) {
+    if (!isRecord(left))
+        return false;
+    return left.run_id === right.run_id && left.unit_id === right.unit_id &&
+        left.attempt_id === right.attempt_id && left.predecessor_attempt_id === right.predecessor_attempt_id &&
+        left.candidate_id === right.candidate_id && left.route_id === right.route_id &&
+        left.child_id === right.child_id && left.call_id === right.call_id;
+}
+/**
+ * Produces an inert stop proposal. It performs no I/O, clock read, process stop, release,
+ * ledger append, writer admission, or target mutation. A satisfied terminal observation only
+ * makes stopping unnecessary; it does not independently assert that every resource is released.
+ */
+export function planChildCancellation(input) {
+    if (!isRecord(input) || !hasOnlyInputKeys(input) || typeof input.cancellation_requested !== "boolean" ||
+        !Array.isArray(input.prior_stop_requests)) {
+        return { status: "rejected", reason: "invalid_input" };
+    }
+    if (!isTime(input.deadline_ms) || !isTime(input.now_ms)) {
+        return { status: "rejected", reason: "invalid_time" };
+    }
+    const reconciliation = reconcileChildTerminal({
+        current: input.current,
+        observation: input.observation,
+        evidence: input.evidence,
+        settled_fingerprint: input.settled_fingerprint,
+    });
+    if (reconciliation.status === "rejected") {
+        return {
+            status: "rejected",
+            reason: "terminal_reconciliation_rejected",
+            reconciliation_reason: reconciliation.reason,
+        };
+    }
+    const current = input.current;
+    const evidence = input.evidence;
+    if (evidence.artifact_window_closed === "unsatisfied") {
+        return { status: "not_proposed", reason: "artifact_window_open" };
+    }
+    if (evidence.artifact_window_closed === "unknown") {
+        return { status: "not_proposed", reason: "artifact_window_unknown" };
+    }
+    if (evidence.terminal === "unknown")
+        return { status: "not_proposed", reason: "terminal_unknown" };
+    if (evidence.terminal === "satisfied") {
+        return { status: "not_proposed", reason: "terminal_already_observed" };
+    }
+    const expired = input.now_ms >= input.deadline_ms;
+    if (!expired && !input.cancellation_requested) {
+        return { status: "not_proposed", reason: "cancellation_not_requested" };
+    }
+    if (input.prior_stop_requests.some((identity) => sameIdentity(identity, current))) {
+        return { status: "not_proposed", reason: "stop_already_requested" };
+    }
+    return {
+        status: "proposed",
+        proposal: {
+            identity: { ...current },
+            trigger: input.cancellation_requested ? "explicit_cancellation" : "deadline_expired",
+            runtime_responsibilities: {
+                persist_stop_request_for_idempotency: true,
+                stop_normal_process_tree: true,
+                verify_actual_cancellation_and_no_leaks: true,
+            },
+        },
+    };
+}

package/dist/core/child-lifecycle-runtime.d.ts

@@ -0,0 +1,46 @@
+import { RunFlightLedger, type ChildFlightState } from "./run-flight-ledger.js";
+import { type ChildTerminalIdentity, type ChildTerminalObservation, type ChildTerminalEvidence } from "./child-terminal-reconciliation.js";
+export declare const DEFAULT_CHILD_DEADLINE_MS: number;
+export declare const DEFAULT_CHILD_CHECK_WAIT_MS = 5000;
+export interface ChildLifecycleDescriptor {
+    readonly identity: ChildTerminalIdentity;
+    readonly deadline_ms: number;
+}
+export interface ChildLifecycleRuntime {
+    observe(): Promise<{
+        observation: ChildTerminalObservation;
+        evidence: ChildTerminalEvidence;
+    }>;
+    /** Optional host policy entry. A terminal result means the same lifecycle completed a live takeover. */
+    takeover?(): Promise<ChildLifecycleResult | undefined>;
+    /** Resolves only after the host's normal process-tree stop request has completed. */
+    stop(): Promise<void>;
+    release(): Promise<void>;
+    terminal(state: ChildFlightState): Promise<void>;
+}
+export type ChildLifecycleResult = {
+    status: "terminal";
+    state: ChildFlightState;
+} | {
+    status: "waiting";
+    reason: string;
+};
+export interface ChildLifecycleOptions {
+    readonly checkWaitMs?: number;
+}
+/** One lifecycle for implementation, diagnosis, and escalation; the host retains process ownership. */
+export declare class CancellableChildLifecycle {
+    #private;
+    readonly descriptor: ChildLifecycleDescriptor;
+    readonly ledger: RunFlightLedger;
+    readonly runtime: ChildLifecycleRuntime;
+    readonly checkWaitMs: number;
+    private constructor();
+    static open(descriptor: ChildLifecycleDescriptor, ledger: RunFlightLedger, runtime: ChildLifecycleRuntime, options?: ChildLifecycleOptions): Promise<CancellableChildLifecycle>;
+    get stopping(): boolean;
+    arm(): void;
+    dispose(): void;
+    check(explicitCancellation?: boolean): Promise<ChildLifecycleResult>;
+    /** Live takeover uses the same bounded stop/release path, but must name the currently registered attempt. */
+    stopForTakeover(identity: ChildTerminalIdentity): Promise<ChildLifecycleResult>;
+}