@rehearsal-db/core 0.1.0-rc.4 → 0.1.0-rc.8

package/BENCHMARKS.md

@@ -55,6 +55,24 @@ the same proof remains required in GitHub Actions before public release.
 
 ## Regression policy
 
+The installed PostgreSQL scenario also demonstrates a data-specific failure:
+the exact same `SET NOT NULL` migration succeeds on an empty table and fails on a
+synthetic table containing a known null. It then reviews a changed candidate that
+backfills the synthetic value, verifies the corrected constraint through the
+application's HTTP proof, and checks immutable baselines and resource cleanup.
+This is a correctness control, not a timing benchmark or a claim about production
+traffic. The synthetic backfill is not a recommendation for real business data.
+
+Maintainers can repeat it with one exact artifact:
+
+```bash
+REHEARSAL_CANDIDATE_ARTIFACT=/absolute/path/to/candidate.tgz npm run test:fixture:postgresql
+```
+
+The result records the artifact and candidate hashes, empty/populated outcomes,
+baseline preservation and cleanup. Do not attribute a candidate's result to a
+different registry artifact merely because both have the same version number.
+
 Record a new equivalent sample before a beta release or after changing baseline format,
 streaming, restore, migration application, verification, or local-runtime lifecycle.
 Investigate a repeatable increase greater than 25% in a phase. Do not weaken checks to

package/CHANGELOG.md

@@ -3,7 +3,112 @@
 All notable Rehearsal package changes will be documented here. The format follows Keep
 a Changelog, and versions will follow Semantic Versioning after the package exists.
 
-## Unreleased
+## [Unreleased]
+
+## [0.1.0-rc.8] - Unreleased candidate
+
+### Added
+
+- Optional interactive update reminders, with explicit network consent, daily
+  opening-session checks, defer/skip/disable choices and exact-version guidance.
+  Machine commands remain network-free, custom installations stay manual-only,
+  and no update installs automatically.
+
+### Fixed
+
+- Invalid positive-integer configuration settings and rejected configuration proposals
+  report configuration failures rather than baseline or internal failures. Review
+  remains non-writing, and unexpected faults retain their original failure category.
+
+### Documentation
+
+- Separate released VSIX installation, dashboard access, and updates from contributor
+  setup and separately approved commercial launch requirements.
+- Clarify that configured database and Storage data remain persistent and that no
+  separate temporary Docker-helper ownership or cleanup capability exists today.
+- Explain profile startup and resource measurements without equating cached-image
+  container checks with a cold VM or whole-machine memory benchmark.
+
+## [0.1.0-rc.7] - 2026-10-15
+
+### Fixed
+
+- Release approval checks accept GitHub form line endings without changing the exact
+  owner, environment, operation, run, attempt, source or checksum bindings. Other text
+  changes and stale or ambiguous approvals remain refused.
+
+rc.6's tag and failed GitHub publication history are preserved; it was not published
+to npm. rc.7 does not add or change database, application or environment behavior.
+
+### Documentation
+
+- The shared GitHub/npm README visibly links to both the source repository and npm
+  package page.
+
+## [0.1.0-rc.6] - 2026-10-15
+
+### Fixed
+
+- Release ancestry verification no longer requests a paginated comparison when the
+  immutable source tag already points to the exact verified main commit. Older source
+  commits still require bounded, unpaged ancestry evidence; incomplete responses remain
+  refused. Human approval, provenance and immutable-tag protections are unchanged.
+
+rc.5's GitHub candidate and tag are retained, but its npm publication stopped at the
+read-only preflight. rc.6 carries the same product features and a new tested artifact;
+no runtime or environment behavior was added during this publisher correction.
+
+## [0.1.0-rc.5] - 2026-10-15
+
+### Added
+
+- Project-owned resource inventory, exact long-running-environment stop review, and
+  individually selected unused-image cleanup. Volumes remain tied to reviewed runtime
+  discard; other projects and the shared engine are protected.
+- Friendly environment labels, protection, named display profiles, resource quotas and
+  review schedules, with validated configuration metadata and fingerprint-bound proposals.
+- Ordered migration review, baseline/privacy/authentication summaries, and bounded
+  operation stages and recent receipts through public JSON contracts.
+- Optional target-local resource provenance reports recorded baseline and migration
+  digests, restore-writer version, and configured ports without claiming fresh
+  verification, listening services or activity. Legacy receipts remain explicitly unknown.
+- Environment classification separately reports ownership-proven creation, recorded
+  format/provider compatibility, and age-based review due status. Missing verification
+  does not mean a database was never created; differing writer versions do not imply
+  incompatible data. Configured sandbox volumes remain persistent after workload stop.
+- Opt-in, bounded graph sampling and measured distribution goals, with immutable
+  post-sanitization fidelity evidence and required-goal refusal before activation.
+- Lightweight Supabase service profiles and explicit required-service checks.
+- Opt-in foreground sandbox idle shutdown using an explicit application-owned activity
+  contract. Unknown or busy activity preserves workloads; no background daemon is added.
+- A disposable PostgreSQL regression demo showing an empty-database migration pass,
+  populated-data refusal, and verified recovery with a reviewed backfill.
+
+### Fixed
+
+- Partial startup and interrupted work clean up only workloads proved owned by the
+  operation, preserving existing running environments, data and shared engines.
+- Opted-in owned-engine shutdown checks for newly appeared workloads immediately before
+  stopping and preserves a replacement ownership receipt from a later operation.
+- Application startup refuses occupied local ports without replacing another process.
+- Application and profile ports are checked across the complete configured topology;
+  configuration proposals can explicitly bind a dependent edit to its parent graph.
+- Application teardown retires its owned process group even after the launcher exits.
+- Supabase startup diagnostics preserve safe service/health categories while withholding
+  logs, credentials, URLs and private paths. Unknown causes stay unknown.
+- Public JSON retains strictly false privacy attestations without exposing credentials;
+  normalized shape policies can be safely validated repeatedly.
+- Failed migrations retain their baseline/candidate phase instead of inferring it from
+  earlier progress; summaries omit Node source excerpts and provider SQL output.
+- Release preparation, publication and tag repair now refuse missing or ambiguous live
+  repository/environment controls; prereleases preserve a stable `latest` version even
+  when that version has build metadata.
+- Read-only release CI drift-checks an owner-observed settings record when GitHub hides
+  bypass metadata. Publication still requires an actual owner deployment review bound
+  to the exact run, attempt, source, artifact and settings-record checksums.
+
+These changes belong to rc.5, not the existing rc.4 artifact. Scheduled review is
+not unattended cleanup, and container age is not proof of user inactivity.
 
 ## [0.1.0-rc.4] - 2026-10-11
 

package/COMPATIBILITY.md

@@ -17,7 +17,7 @@ A change to any of those requires either a compatible extension or a deliberate
 transition. Rehearsal must never silently reinterpret an old config, baseline, digest,
 or successful verification receipt.
 
-The first stable `1.0.0` requires external beta evidence, a support policy, and a settled
+The first `1.0.0` release requires external beta evidence, a support policy, and a settled
 public API. Supporting additional database families, package managers, or operating
 systems is not implied by the 0.x contract.
 

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="https://ddupasquier.github.io/rehearsal-db/">Read the documentation</a> ·
   <a href="https://www.npmjs.com/package/@rehearsal-db/core">View on npm</a> ·
+  <a href="https://github.com/Ddupasquier/rehearsal-db">Source on GitHub</a> ·
   <a href="https://github.com/Ddupasquier/rehearsal-db/issues">Report a problem</a>
 </p>
 
@@ -129,6 +130,15 @@ When local disk space gets tight, choose **Clean up disk space** in the guide. R
 previews old baseline generations first and keeps runtime or shared-image removal
 explicit.
 
+Run `npx rehearsal environments` for a read-only view of this project's owned runtimes,
+container state, current owned-container CPU and memory, Docker resource totals, and
+measurable Colima disk capacity. Rehearsal
+warns before the disk becomes critical and refuses expensive startup without configured
+headroom. PostgreSQL uses one container for SQL-only proofs; Supabase's default
+`application` profile keeps application services while omitting development-only extras.
+Optional idle shutdown can stop only a Colima boot Rehearsal proves it started, and only
+after every container on the shared engine is already stopped.
+
 Press `Ctrl+Z` at any guided prompt to exit the whole session. Choose **Get help**, or run
 `npx rehearsal support`, to create a privacy-safe diagnostic report.
 

package/SECURITY.md

@@ -4,9 +4,10 @@ Rehearsal handles sensitive database topology and may process sanitized derivati
 production data. Do not include credentials, connection strings, raw data, or a real
 baseline in a public report.
 
-Report suspected vulnerabilities through GitHub's private vulnerability reporting for
-this repository. Do not open a public issue containing an exploit, secret, hosted
-target, or source record.
+Report suspected vulnerabilities through the
+[private security form](https://github.com/Ddupasquier/rehearsal-db/security/advisories/new)
+in this repository. A GitHub account is required. Do not open a
+public issue containing an exploit, secret, hosted target, or source record.
 
 Supported security updates cover the latest released 0.x minor during beta. A security
 fix may deliberately tighten configuration or refuse a workflow that an earlier beta

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "0.1.0-rc.4",
+    "version": "0.1.0-rc.8",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -23,7 +23,12 @@
         "rehearsal": "dist/src/cli/rehearsal.mjs"
     },
     "rehearsalContracts": {
-        "projectDiscovery": 1
+        "projectDiscovery": 1,
+        "resourceInventory": 1,
+        "resourceManager": 1,
+        "migrationReview": 1,
+        "configurationReview": 1,
+        "baselineShape": 1
     },
     "exports": {
         ".": {
@@ -38,7 +43,8 @@
         "./privacy": "./dist/src/baseline/privacy_engine.mjs",
         "./schema": "./dist/src/baseline/schema_snapshot.mjs",
         "./service-environment": "./dist/src/runtime/service_environment.mjs",
-        "./source-access": "./dist/src/source/access.mjs"
+        "./source-access": "./dist/src/source/access.mjs",
+        "./shape": "./dist/src/source/shape.mjs"
     },
     "files": [
         "dist",
@@ -69,6 +75,7 @@
         "test:fixture:typescript": "npm run build && node scripts/verification/run_scenario.mjs typescript",
         "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
         "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
+        "test:fixture:resources": "npm run build && node scripts/verification/run_scenario.mjs resources",
         "release:verify": "node scripts/verification/release_gate.mjs",
         "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
         "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",

package/dist/scripts/runtime/manage_database.mjs

@@ -7,15 +7,25 @@ import { loadRehearsalConfig } from "../../src/project/configuration.mjs";
 import { parseRuntimeInvocation } from "../../src/targets/target.mjs";
 import { runRuntimeTarget } from "../../src/targets/driver.mjs";
 import { runWithOperationCancellation } from "../../src/shared/cancellation.mjs";
+import { withRuntimeStartupCleanup } from "../../src/runtime/runtime_startup_ownership.mjs";
+import { guardRuntimeManagerAction } from "../../src/runtime/runtime_manager_guards.mjs";
 const run = async () => {
     const invocation = parseRuntimeInvocation();
-    const { config } = await loadRehearsalConfig({
+    const loaded = await loadRehearsalConfig({
         projectRoot: process.cwd(),
         ...(invocation.configPath === undefined
             ? {}
             : { configPath: invocation.configPath }),
     });
-    await runRuntimeTarget(config.runtime.target);
+    await guardRuntimeManagerAction(loaded, invocation.action);
+    await withRuntimeStartupCleanup({
+        projectRoot: loaded.projectRoot,
+        configPath: loaded.configPath,
+        config: loaded.config,
+        action: invocation.action,
+        ownerOperationId: process.env.REHEARSAL_OWNER_OPERATION_ID,
+        task: () => runRuntimeTarget(loaded.config.runtime.target),
+    });
 };
 if (process.env.REHEARSAL_CANCELLABLE_OPERATION === "1") {
     await runWithOperationCancellation({ task: run });

package/dist/src/application/activity_contract.d.mts

@@ -0,0 +1,28 @@
+/** Explicit application-owned activity; never infer use from container or editor age. */
+export interface ApplicationActivity {
+    readonly url: string;
+}
+export interface ApplicationActivitySample {
+    readonly schemaVersion: 1;
+    readonly busy: boolean;
+    readonly activitySequence: number;
+}
+export interface ApplicationIdleWindow {
+    readonly sequence: number | null;
+    readonly quietSince: number | null;
+    readonly lastObservedAt: number | null;
+    readonly validSamples: number;
+}
+export declare const emptyApplicationIdleWindow: () => ApplicationIdleWindow;
+export declare const validateApplicationActivityUrl: (value: unknown, readinessUrl: string | null) => string;
+export declare const parseApplicationActivitySample: (value: unknown) => ApplicationActivitySample | null;
+/** `now` is a monotonic clock; missing evidence cannot carry a previous quiet window. */
+export declare const observeApplicationActivity: ({ previous, sample, now, timeoutMs, }: {
+    readonly previous: ApplicationIdleWindow;
+    readonly sample: ApplicationActivitySample | null;
+    readonly now: number;
+    readonly timeoutMs: number;
+}) => {
+    readonly window: ApplicationIdleWindow;
+    readonly idle: boolean;
+};

package/dist/src/application/activity_contract.mjs

@@ -0,0 +1,84 @@
+export const emptyApplicationIdleWindow = () => ({
+    sequence: null,
+    quietSince: null,
+    lastObservedAt: null,
+    validSamples: 0,
+});
+export const validateApplicationActivityUrl = (value, readinessUrl) => {
+    const message = "Application activity requires a bounded credential-free loopback HTTP(S) URL on the exact readiness origin, with an explicit non-privileged port and no query or fragment.";
+    if (typeof value !== "string" ||
+        value.length > 500 ||
+        /[\x00-\x20\x7f]/u.test(value))
+        throw new Error(message);
+    let url;
+    let readiness;
+    try {
+        url = new URL(value);
+        readiness = new URL(readinessUrl ?? "");
+    }
+    catch {
+        throw new Error(message);
+    }
+    if (!/^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):[0-9]+(?:\/|$)/iu.test(value) ||
+        !["http:", "https:"].includes(url.protocol) ||
+        !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        Number(url.port) < 1024 ||
+        Number(url.port) > 65535 ||
+        readiness.username ||
+        readiness.password ||
+        url.origin !== readiness.origin)
+        throw new Error(message);
+    return url.href;
+};
+export const parseApplicationActivitySample = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const sample = value;
+    if (Object.keys(sample).length !== 3 ||
+        Object.keys(sample).some((key) => !["schemaVersion", "busy", "activitySequence"].includes(key)) ||
+        sample.schemaVersion !== 1 ||
+        typeof sample.busy !== "boolean" ||
+        typeof sample.activitySequence !== "number" ||
+        !Number.isSafeInteger(sample.activitySequence) ||
+        sample.activitySequence < 0)
+        return null;
+    return {
+        schemaVersion: 1,
+        busy: sample.busy,
+        activitySequence: sample.activitySequence,
+    };
+};
+/** `now` is a monotonic clock; missing evidence cannot carry a previous quiet window. */
+export const observeApplicationActivity = ({ previous, sample, now, timeoutMs, }) => {
+    if (!Number.isFinite(now) ||
+        !Number.isFinite(timeoutMs) ||
+        timeoutMs <= 0 ||
+        (previous.lastObservedAt !== null && now < previous.lastObservedAt) ||
+        !sample ||
+        (previous.sequence !== null && sample.activitySequence < previous.sequence))
+        return {
+            window: { ...previous, quietSince: null, validSamples: 0 },
+            idle: false,
+        };
+    const changed = previous.sequence === null || sample.activitySequence > previous.sequence;
+    const reset = changed || sample.busy || previous.quietSince === null;
+    const quietSince = sample.busy ? null : reset ? now : previous.quietSince;
+    const validSamples = sample.busy
+        ? 0
+        : reset
+            ? 1
+            : Math.min(previous.validSamples + 1, 2);
+    return {
+        window: {
+            sequence: sample.activitySequence,
+            quietSince,
+            validSamples,
+            lastObservedAt: now,
+        },
+        idle: quietSince !== null && validSamples >= 2 && now - quietSince >= timeoutMs,
+    };
+};

package/dist/src/application/activity_monitor.d.mts

@@ -0,0 +1,20 @@
+import { type ApplicationActivitySample } from "./activity_contract.mjs";
+export declare const readApplicationActivity: ({ url, signal, fetchImplementation, timeoutMs, }: {
+    readonly url: string;
+    readonly signal: AbortSignal;
+    readonly fetchImplementation?: typeof fetch;
+    readonly timeoutMs?: number;
+}) => Promise<ApplicationActivitySample | null>;
+export declare const waitForApplicationIdle: ({ url, readinessUrl, timeoutSeconds, signal, fetchImplementation, now, pollIntervalMs, requestTimeoutMs, onAvailability, }: {
+    readonly url: string;
+    readonly readinessUrl: string;
+    readonly timeoutSeconds: number;
+    readonly signal: AbortSignal;
+    readonly fetchImplementation?: typeof fetch;
+    readonly now?: () => number;
+    readonly pollIntervalMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly onAvailability?: (available: boolean) => void;
+}) => Promise<Readonly<{
+    reason: "idle-timeout";
+}>>;

package/dist/src/application/activity_monitor.mjs

@@ -0,0 +1,191 @@
+/** Foreground-only serial polling of an explicitly declared application activity route. */
+import { performance } from "node:perf_hooks";
+import { emptyApplicationIdleWindow, observeApplicationActivity, parseApplicationActivitySample, validateApplicationActivityUrl, } from "./activity_contract.mjs";
+const MAXIMUM_ACTIVITY_BYTES = 4096;
+const aborted = () => Object.assign(new Error("Application activity monitoring stopped."), {
+    name: "AbortError",
+});
+class ActivityTransportUnresponsive extends Error {
+    constructor() {
+        super("Application activity transport did not stop within its bound; idle shutdown is disabled for this foreground session.");
+    }
+}
+const settleWithin = async (promise, milliseconds) => {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.then(() => true, () => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+};
+const wait = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted) {
+        reject(aborted());
+        return;
+    }
+    const finish = (cancelled) => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+        if (cancelled)
+            reject(aborted());
+        else
+            resolve();
+    };
+    const onAbort = () => finish(true);
+    const timer = setTimeout(() => finish(false), milliseconds);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+export const readApplicationActivity = async ({ url, signal, fetchImplementation = fetch, timeoutMs = 2000, }) => {
+    if (signal.aborted)
+        throw aborted();
+    const started = performance.now();
+    const budget = Math.min(Math.max(timeoutMs, 1), 2000);
+    const request = new AbortController();
+    let rejectOwner = () => undefined;
+    const ownerAborted = new Promise((_resolve, reject) => {
+        rejectOwner = reject;
+    });
+    const onAbort = () => {
+        request.abort();
+        rejectOwner(aborted());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    const abortTimer = setTimeout(() => request.abort(), Math.max(1, budget - 50));
+    let deadlineTimer;
+    const deadline = new Promise((_resolve, reject) => {
+        deadlineTimer = setTimeout(() => {
+            request.abort();
+            reject(new ActivityTransportUnresponsive());
+        }, budget);
+    });
+    let reader;
+    const read = async () => {
+        try {
+            const response = await fetchImplementation(url, {
+                signal: request.signal,
+                method: "GET",
+                redirect: "error",
+                headers: { accept: "application/json", "cache-control": "no-store" },
+            });
+            if (request.signal.aborted)
+                return null;
+            if (response.status !== 200 ||
+                response.redirected ||
+                !/^application\/json(?:\s*;|$)/iu.test(response.headers.get("content-type") ?? "") ||
+                !response.body)
+                return null;
+            const declared = response.headers.get("content-length");
+            if (declared !== null &&
+                (!/^[0-9]+$/u.test(declared) ||
+                    Number(declared) > MAXIMUM_ACTIVITY_BYTES))
+                return null;
+            reader = response.body.getReader();
+            const chunks = [];
+            let length = 0;
+            while (true) {
+                if (request.signal.aborted)
+                    return null;
+                const result = await reader.read();
+                if (request.signal.aborted)
+                    return null;
+                if (result.done)
+                    break;
+                length += result.value.byteLength;
+                if (length > MAXIMUM_ACTIVITY_BYTES)
+                    return null;
+                chunks.push(result.value);
+            }
+            const bytes = Buffer.concat(chunks, length);
+            return parseApplicationActivitySample(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+        }
+        catch {
+            return null;
+        }
+    };
+    try {
+        return await Promise.race([read(), deadline, ownerAborted]);
+    }
+    finally {
+        clearTimeout(abortTimer);
+        if (deadlineTimer)
+            clearTimeout(deadlineTimer);
+        signal.removeEventListener("abort", onAbort);
+        request.abort();
+        const cancelled = reader?.cancel().catch(() => undefined);
+        const cancellationFinished = cancelled === undefined ||
+            (await settleWithin(cancelled, Math.max(1, Math.min(50, budget - (performance.now() - started)))));
+        try {
+            reader?.releaseLock();
+        }
+        catch {
+            /* A stuck transport is disabled below. */
+        }
+        if (signal.aborted)
+            throw aborted();
+        if (!cancellationFinished)
+            throw new ActivityTransportUnresponsive();
+    }
+};
+export const waitForApplicationIdle = async ({ url, readinessUrl, timeoutSeconds, signal, fetchImplementation = fetch, now = () => performance.now(), pollIntervalMs = 5000, requestTimeoutMs = 2000, onAvailability = () => undefined, }) => {
+    const endpoint = validateApplicationActivityUrl(url, readinessUrl);
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)
+        throw new Error("Application idle monitoring requires an explicit positive timeout.");
+    let window = emptyApplicationIdleWindow();
+    let available;
+    while (!signal.aborted) {
+        let sample;
+        try {
+            sample = await readApplicationActivity({
+                url: endpoint,
+                signal,
+                fetchImplementation,
+                timeoutMs: requestTimeoutMs,
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw aborted();
+            if (!(error instanceof ActivityTransportUnresponsive))
+                throw error;
+            onAvailability(false);
+            // Do not accumulate new requests behind a transport that ignored abort/cancel.
+            await new Promise((_resolve, reject) => {
+                const stop = () => reject(aborted());
+                signal.addEventListener("abort", stop, { once: true });
+                if (signal.aborted) {
+                    signal.removeEventListener("abort", stop);
+                    stop();
+                }
+            });
+            throw aborted();
+        }
+        if (signal.aborted)
+            throw aborted();
+        const current = observeApplicationActivity({
+            previous: window,
+            sample,
+            now: now(),
+            timeoutMs: timeoutSeconds * 1000,
+        });
+        window = current.window;
+        const nextAvailable = sample !== null &&
+            (window.sequence === null ||
+                sample.activitySequence >= window.sequence) &&
+            window.lastObservedAt !== null;
+        if (available !== nextAvailable) {
+            available = nextAvailable;
+            onAvailability(available);
+        }
+        if (current.idle)
+            return { reason: "idle-timeout" };
+        await wait(Math.max(1, pollIntervalMs), signal);
+    }
+    throw aborted();
+};

package/dist/src/application/port_preflight.d.mts

@@ -0,0 +1,12 @@
+export interface LocalApplicationEndpoint {
+    readonly host: "localhost" | "127.0.0.1" | "::1";
+    readonly port: number;
+}
+type ProbeState = "free" | "occupied" | "unavailable" | "unsupported";
+export type ApplicationPortProbe = (host: "127.0.0.1" | "::1", port: number) => Promise<ProbeState>;
+export declare const parseLocalApplicationEndpoint: (value: unknown) => LocalApplicationEndpoint;
+export declare const assertApplicationPortAvailable: ({ url, probe, }: {
+    readonly url: unknown;
+    readonly probe?: ApplicationPortProbe;
+}) => Promise<void>;
+export {};

package/dist/src/application/port_preflight.mjs

@@ -0,0 +1,71 @@
+/** Startup-only, bounded loopback listener check; never touches an existing process. */
+import { createConnection } from "node:net";
+export const parseLocalApplicationEndpoint = (value) => {
+    let parsed;
+    try {
+        if (typeof value !== "string")
+            throw new Error();
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("Application readiness requires a valid local HTTP or HTTPS endpoint.");
+    }
+    const host = parsed.hostname === "[::1]" ? "::1" : parsed.hostname;
+    const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+    if (!["http:", "https:"].includes(parsed.protocol) ||
+        !["localhost", "127.0.0.1", "::1"].includes(host) ||
+        parsed.username ||
+        parsed.password ||
+        !Number.isSafeInteger(port) ||
+        port < 1 ||
+        port > 65535)
+        throw new Error("Application readiness requires a credential-free loopback HTTP or HTTPS endpoint.");
+    return Object.freeze({
+        host: host,
+        port,
+    });
+};
+const probeLoopbackPort = (host, port) => new Promise((resolve) => {
+    const socket = createConnection({
+        host,
+        port,
+        family: host === "::1" ? 6 : 4,
+    });
+    let settled = false;
+    const finish = (state) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(state);
+    };
+    const timer = setTimeout(() => finish("unavailable"), 750);
+    socket.once("connect", () => finish("occupied"));
+    socket.once("error", (error) => finish(error.code === "ECONNREFUSED"
+        ? "free"
+        : [
+            "EAFNOSUPPORT",
+            "EPROTONOSUPPORT",
+            "ENETUNREACH",
+            "EHOSTUNREACH",
+        ].includes(error.code ?? "") && host === "::1"
+            ? "unsupported"
+            : "unavailable"));
+});
+export const assertApplicationPortAvailable = async ({ url, probe = probeLoopbackPort, }) => {
+    const endpoint = parseLocalApplicationEndpoint(url);
+    const hosts = endpoint.host === "localhost" ? ["127.0.0.1", "::1"] : [endpoint.host];
+    let results;
+    try {
+        results = await Promise.all(hosts.map((host) => probe(host, endpoint.port)));
+    }
+    catch {
+        throw new Error("Application port availability could not be proved. No application was started; diagnose the local endpoint before retrying.");
+    }
+    if (results.includes("occupied"))
+        throw new Error(`Application port ${endpoint.port} is already in use. No application was started or stopped. Stop the existing application yourself, or choose a different reviewed local port and update its start command.`);
+    if (results.some((state) => !["free", "unsupported"].includes(state)) ||
+        !results.includes("free"))
+        throw new Error("Application port availability could not be proved. No application was started; diagnose the local endpoint before retrying.");
+};