primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/document-ingest.js

@@ -0,0 +1,384 @@
+/**
+ * Driving one bulk-load session: create, upload, commit, poll.
+ *
+ * The artifact is already built and checked by the time anything here runs
+ * (`document-ingest-artifact`), so every refusal this module reports comes
+ * from the server. What it decides is what to do about one:
+ *
+ * - a create the server refuses uploads nothing;
+ * - an upload that fails ABORTS the session rather than retrying a slot whose
+ *   reservation this side cannot see — the artifact is deterministic and a
+ *   re-run is cheap;
+ * - Ctrl-C during the uploads aborts too, because the session it was filling
+ *   is not going to be committed; Ctrl-C while POLLING leaves the session
+ *   alone, because by then the document is already being changed and giving up
+ *   on watching is not giving up on the load;
+ * - a session READ that fails while polling is retried on a bounded schedule
+ *   (#3597), for the same reason: the read failing says nothing about the load,
+ *   and a multi-hour load will meet transient reads. When the bound is spent
+ *   the wait stops and says the session is still running — it never reports it
+ *   as cancelled or failed.
+ *
+ * Exit codes follow `functions runs wait`/`invoke`, as `docs/cli-design.md`
+ * records them: 0 completed, 1 failed or refused, 124 a wait that gave up,
+ * 130 Ctrl-C. Both ways of giving up on the WATCHING are 124 and both say the
+ * session keeps running; only the load itself failing is 1.
+ */
+import fs from "fs";
+/** A plan the operator did not confirm, or cannot be asked about. */
+export class IngestRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IngestRefusedError";
+    }
+}
+const POLL_FAST_MS = 2_000;
+const POLL_SLOW_MS = 5_000;
+const POLL_SLOWS_AFTER_MS = 60_000;
+/**
+ * How long CONSECUTIVE failed session reads may run before the wait gives up
+ * (#3597), and the backoff between them.
+ *
+ * A bound measured in attempts would have been wrong for the load this is for:
+ * the 2026-09-18 2 GB validation attempts met reads that failed for MINUTES
+ * together through the same route while the session stayed alive and
+ * advancing. So the bound is a wall-clock window, and any successful read
+ * resets it — an isolated blip costs a multi-hour load nothing at all, and
+ * only an outage that never lifts ends the watching.
+ *
+ * Module constants like the poll cadence above, deliberately: there is no flag
+ * for them. The backoff caps rather than doubling forever, because a backoff
+ * that silently stops backing off is a poll storm (`function-run.ts`).
+ */
+const POLL_READ_RETRY_WINDOW_MS = 10 * 60_000;
+const POLL_READ_BACKOFF_MS = 1_000;
+const POLL_READ_BACKOFF_CAP_MS = 15_000;
+/**
+ * Whether a thrown session read is worth retrying.
+ *
+ * `ApiClient.request` throws an `ApiError` carrying `statusCode` on any
+ * non-2xx, and the fetch under it rejects with no status at all on a dropped
+ * connection — so a transport failure, a 5xx, a 408 and a 429 all describe a
+ * server that may well answer the next read, and the session goes on either
+ * way. Any OTHER 4xx is definitive: the session is gone, or unreadable to this
+ * caller, and retrying it only to call it "still running" would misstate it.
+ */
+function isTransientReadError(error) {
+    const status = error?.statusCode ?? error?.status;
+    if (typeof status !== "number")
+        return true;
+    if (status >= 500)
+        return true;
+    return status === 408 || status === 429;
+}
+/** The capped doubling between consecutive failed reads. */
+function readBackoffMs(failures) {
+    return Math.min(POLL_READ_BACKOFF_MS * 2 ** (failures - 1), POLL_READ_BACKOFF_CAP_MS);
+}
+/** The plan summary an operator confirms, one line per row. */
+export function summariseIngestPlan(plan) {
+    const lines = plan.models.map((model) => `  ${model.model}: ${model.rows} rows, ${model.chunks} chunks, ` +
+        `${model.bytes} bytes` +
+        (model.deletes > 0 ? `, ${model.deletes} deletes` : ""));
+    return [
+        `${plan.rows} rows across ${plan.models.length} model(s), ` +
+            `${plan.chunks.length} chunks, ${plan.bytes} bytes` +
+            (plan.deletes > 0 ? `, ${plan.deletes} deletes` : ""),
+        ...lines,
+    ];
+}
+/**
+ * Refuse a run that cannot ask, before it asks the server anything.
+ *
+ * A bulk load deletes and overwrites a live document's records with no undo,
+ * which is what the CLI design's destructive default is for. A pipeline that
+ * meant to run one says so with `-y`.
+ */
+export function assertIngestConfirmable(options) {
+    if (options.yes || options.isTTY)
+        return;
+    throw new IngestRefusedError("A bulk load replaces records in a live document and cannot be undone. " +
+        "Re-run with -y to confirm it without a prompt.");
+}
+export async function driveDocumentIngest(options) {
+    const { client, documentId, plan, concurrency = 4, wait = true, timeoutMs = null, signal, onProgress = () => { }, readChunk = async (chunk) => fs.readFileSync(chunk.file), now = () => Date.now(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), } = options;
+    // A phase appears only once it has FINISHED (#3598). A create that threw
+    // cost time, but not a measurable amount of anything an operator can act
+    // on; half an upload has no rate; and a phase the run never reached has
+    // nothing to say rather than a zero to say it with.
+    const timings = {};
+    /** A whole number of milliseconds, never negative. */
+    const since = (at) => Math.max(0, now() - at);
+    // ── create ──
+    let session;
+    const createdAt = now();
+    try {
+        session = await client.createIngest(documentId);
+    }
+    catch (error) {
+        if (error?.code === "DOCUMENT_INGEST_ACTIVE") {
+            const active = (error.details && error.details.sessionId) ?? "the active session";
+            return {
+                exitCode: 1,
+                sessionId: null,
+                session: null,
+                timings,
+                message: `${error.message}\nThis document already has bulk load ${active}. ` +
+                    `Watch it with \`primitive documents ingests get ${documentId} ${active}\`, ` +
+                    `or give it up with \`primitive documents ingests abort\`.`,
+            };
+        }
+        return {
+            exitCode: 1,
+            sessionId: null,
+            session: null,
+            timings,
+            message: String(error?.message ?? error),
+        };
+    }
+    timings.createMs = since(createdAt);
+    const sessionId = String(session.sessionId);
+    onProgress(`Session ${sessionId} opened.`);
+    const giveUp = async (message, exitCode) => {
+        try {
+            await client.abortIngest(documentId, sessionId);
+            onProgress(`Session ${sessionId} aborted; nothing was applied.`);
+        }
+        catch (error) {
+            onProgress(`Session ${sessionId} could not be aborted: ${error?.message ?? error}`);
+        }
+        return { exitCode, sessionId, session: null, timings, message };
+    };
+    // ── upload ──
+    const uploadStartedAt = now();
+    const queue = [...plan.chunks];
+    let uploaded = 0;
+    let failure = null;
+    const worker = async () => {
+        for (;;) {
+            if (failure !== null || signal?.aborted)
+                return;
+            const chunk = queue.shift();
+            if (!chunk)
+                return;
+            try {
+                const body = await readChunk(chunk);
+                await client.uploadIngestChunk(documentId, sessionId, { ...chunk, body });
+                uploaded += 1;
+                onProgress(`Uploaded ${uploaded}/${plan.chunks.length} chunks ` +
+                    `(${chunk.model} ${chunk.index}).`);
+            }
+            catch (error) {
+                // The first failure wins: the others are the same session going away.
+                if (failure === null)
+                    failure = String(error?.message ?? error);
+                return;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, queue.length || 1)) }, worker));
+    if (failure !== null)
+        return giveUp(failure, 1);
+    if (signal?.aborted) {
+        return giveUp("Interrupted while uploading; the session was aborted and nothing was applied.", 130);
+    }
+    // Every chunk is up, so there is a rate to state. It is measured over the
+    // PLAN's stored chunk sizes — what actually went over the wire — rather
+    // than over the decompressed total, which is not what was sent.
+    const uploadMs = since(uploadStartedAt);
+    const uploadedBytes = plan.chunks.reduce((sum, chunk) => sum + chunk.bytes, 0);
+    timings.uploadMs = uploadMs;
+    timings.uploadedBytes = uploadedBytes;
+    onProgress(`Uploaded ${plan.chunks.length} chunks (${uploadedBytes} bytes) in ` +
+        `${seconds(uploadMs)}` +
+        (uploadMs > 0 ? ` (${megabytesPerSecond(uploadedBytes, uploadMs)}).` : "."));
+    // ── commit ──
+    const committedAt = now();
+    try {
+        session = await client.commitIngest(documentId, sessionId);
+    }
+    catch (error) {
+        return giveUp(String(error?.message ?? error), 1);
+    }
+    const commitMs = since(committedAt);
+    timings.commitMs = commitMs;
+    onProgress(`Session ${sessionId} committed.`);
+    onProgress(`Committed in ${seconds(commitMs)}.`);
+    if (!wait) {
+        // Nothing was waited for, so the wait is zero rather than unknown: the
+        // session keeps running and `ingests get` is where its own time is.
+        timings.waitMs = 0;
+        return { exitCode: 0, sessionId, session, timings, message: undefined };
+    }
+    // ── poll ──
+    //
+    // Past this point the session is the server's business: the copy has begun
+    // and the document's tables will be swapped whatever this process does. So
+    // neither a timeout nor a Ctrl-C nor a read that keeps failing aborts it —
+    // each says so and leaves.
+    const started = now();
+    let reported = null;
+    let reportedProgress = "";
+    // The current run of consecutive failed reads: how many, when it started on
+    // the injected clock, and the last thing the server said. All three reset on
+    // any read that answers.
+    let readFailures = 0;
+    let failingSince = 0;
+    let lastReadError = "";
+    const stillRunning = () => `The bulk load is still running on the server; read it with ` +
+        `\`primitive documents ingests get ${documentId} ${sessionId}\`.`;
+    // Every door out of the WATCHING records the wait it is ending (#3598): the
+    // time was really spent on the server whichever way the watching stopped,
+    // and a load that gave up is exactly when somebody needs that number.
+    const interrupted = (view) => {
+        timings.waitMs = since(started);
+        return {
+            exitCode: 130,
+            sessionId,
+            session: view,
+            timings,
+            message: `Interrupted. The session keeps running; watch it with ` +
+                `\`primitive documents ingests get ${documentId} ${sessionId}\`.`,
+        };
+    };
+    const timedOut = (view, elapsed) => {
+        timings.waitMs = elapsed;
+        return {
+            exitCode: 124,
+            sessionId,
+            session: view,
+            timings,
+            message: `Gave up waiting after ${Math.round(elapsed / 1000)}s. The session ` +
+                `keeps running; watch it with \`primitive documents ingests get ` +
+                `${documentId} ${sessionId}\`.`,
+        };
+    };
+    for (;;) {
+        let view;
+        try {
+            view = await client.getIngest(documentId, sessionId);
+            if (readFailures > 0) {
+                onProgress(`Session ${sessionId} answered again after ${readFailures} ` +
+                    `unanswered read(s); polling resumed.`);
+                readFailures = 0;
+                lastReadError = "";
+            }
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            // A refusal is a refusal: it is reported now, exactly as before — and
+            // it still carries the wait that preceded it (finding 3598-FROZEN-01),
+            // because a load that polled for minutes before the reads stopped
+            // answering really did spend those minutes waiting on the server.
+            if (!isTransientReadError(error)) {
+                timings.waitMs = since(started);
+                return { exitCode: 1, sessionId, session: null, timings, message };
+            }
+            if (readFailures === 0)
+                failingSince = now();
+            readFailures += 1;
+            lastReadError = message;
+            const failingFor = now() - failingSince;
+            if (failingFor >= POLL_READ_RETRY_WINDOW_MS) {
+                // 124, the documented "a wait that gave up" code — never 1. Giving up
+                // on the watching is not the load failing, and the operator has to be
+                // able to tell them apart by the exit code alone.
+                timings.waitMs = since(started);
+                return {
+                    exitCode: 124,
+                    sessionId,
+                    session: null,
+                    timings,
+                    message: `Stopped watching after ${Math.round(failingFor / 1000)}s of ` +
+                        `unanswered session reads (${readFailures} attempts). ` +
+                        `${stillRunning()} Last read error: ${lastReadError}`,
+                };
+            }
+            onProgress(`Session ${sessionId} did not answer (attempt ${readFailures}, ` +
+                `unanswered for ${Math.round(failingFor / 1000)}s); retrying` +
+                (readFailures === 1 ? `: ${message}` : "."));
+            await sleep(readBackoffMs(readFailures));
+            // The backoff sleep is part of the wait, so it honours the same two
+            // doors the success path does and with the same words: neither aborts.
+            if (signal?.aborted)
+                return interrupted(null);
+            const waited = now() - started;
+            if (timeoutMs !== null && waited >= timeoutMs)
+                return timedOut(null, waited);
+            continue;
+        }
+        if (view?.state !== reported) {
+            reported = view?.state ?? null;
+            onProgress(`Session ${sessionId} is ${reported}.`);
+        }
+        const progress = describeProgress(view?.progress);
+        if (progress && progress !== reportedProgress) {
+            reportedProgress = progress;
+            onProgress(`  ${progress}`);
+        }
+        if (view?.state === "complete") {
+            const waitMs = since(started);
+            timings.waitMs = waitMs;
+            // What the PLATFORM spent, separable from what this side did. The
+            // session's own `timings` say where inside the platform it went.
+            onProgress(`Server finished in ${seconds(waitMs)}.`);
+            return { exitCode: 0, sessionId, session: view, timings };
+        }
+        if (view?.state === "failed" || view?.state === "aborted") {
+            const waitMs = since(started);
+            timings.waitMs = waitMs;
+            onProgress(`Server finished in ${seconds(waitMs)}.`);
+            return {
+                exitCode: 1,
+                sessionId,
+                session: view,
+                timings,
+                message: describeFailure(view),
+            };
+        }
+        const elapsed = now() - started;
+        if (timeoutMs !== null && elapsed >= timeoutMs)
+            return timedOut(view, elapsed);
+        await sleep(elapsed >= POLL_SLOWS_AFTER_MS ? POLL_SLOW_MS : POLL_FAST_MS);
+        if (signal?.aborted)
+            return interrupted(view);
+    }
+}
+/** A duration an operator reads at a glance, never a bare millisecond count. */
+function seconds(ms) {
+    return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/** The unit a bulk load's speed is discussed in. */
+function megabytesPerSecond(bytes, ms) {
+    return `${((bytes / 1_000_000 / ms) * 1000).toFixed(2)} MB/s`;
+}
+/** The session's own words for why it stopped. */
+function describeFailure(view) {
+    if (view?.state === "aborted")
+        return "The session was aborted.";
+    const failure = view?.failure;
+    if (!failure)
+        return "The session failed.";
+    // A failure's rows are `{ model, id }` on the wire, and a bounded sample of
+    // them; a string is accepted too so a stub or an older server still reads.
+    const rows = Array.isArray(failure.rows) && failure.rows.length > 0
+        ? `\n  ${failure.rows
+            .map((row) => typeof row === "string" ? row : `${row?.model} ${row?.id}`)
+            .join("\n  ")}`
+        : "";
+    return `${failure.code}: ${failure.reason}${rows}`;
+}
+/** One line of counters, or nothing while they are all still zero. */
+function describeProgress(progress) {
+    if (!progress)
+        return "";
+    const copied = progress.rowsCopied ?? 0;
+    const chunks = progress.chunksApplied ?? 0;
+    const rows = progress.rowsApplied ?? 0;
+    const reconciled = progress.recordsReconciled ?? 0;
+    if (copied + chunks + rows + reconciled === 0)
+        return "";
+    return (`copied ${copied} rows, applied ${chunks} chunks / ${rows} rows, ` +
+        `reconciled ${reconciled} records`);
+}
+//# sourceMappingURL=document-ingest.js.map

package/dist/src/lib/document-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-ingest.js","sourceRoot":"","sources":["../../../src/lib/document-ingest.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/env-resolver-core.d.ts

@@ -0,0 +1,258 @@
+/**
+ * The shared Primitive environment resolver (#2873).
+ *
+ * Three surfaces have to agree on which backend/app a project is pointed at:
+ * the CLI, the Vue build (`primitive-app`'s `primitiveEnv()` plugin), and the
+ * Swift template's pre-build script. This module is the single algorithm they
+ * share. The CLI owns it; `packages/primitive-app` carries a byte-identical
+ * GENERATED copy (`cli/scripts/gen-primitive-env-resolver.mjs`, checked for
+ * freshness by `cli/tests/unit/env-resolver-copy-drift-guard.test.ts`); the
+ * Swift script is an independent bash+python3 port pinned by a parity test.
+ *
+ * ── COPYABILITY (load-bearing) ────────────────────────────────────────────
+ * This file MUST stay self-contained: node builtins only, ZERO relative
+ * imports. The generator copies it verbatim into a package that cannot depend
+ * on the CLI, so any `./x.js` import here would break that copy at runtime.
+ * The drift guard asserts this.
+ *
+ * Scope: config discovery, the schema `version` check, structural validation,
+ * the local selection, the precedence, and the http→ws scheme swap. It
+ * deliberately does NOT duplicate the CLI's full field-level validation
+ * (`validateProjectConfig` in `project-config.ts`) — the CLI wrapper runs that
+ * first, and the other readers only need "version understood, shape sane, fail
+ * loudly otherwise".
+ *
+ * Precedence (one order, everywhere):
+ *   1. an explicit name (`--env` / `--primitive-env`)
+ *   2. PRIMITIVE_ENV                (per-invocation intent, keeps CI working)
+ *   3. .primitive/local.json        (this machine's `primitive env use`)
+ *   4. defaultEnvironment           (the committed team default)
+ *   5. the sole environment, if there is exactly one
+ */
+/** Schema version of `primitive/config.json` this core understands. */
+export declare const PRIMITIVE_CONFIG_VERSION = 1;
+/** Schema version of `.primitive/local.json` this core writes and reads. */
+export declare const PRIMITIVE_LOCAL_STATE_VERSION = 1;
+/**
+ * The two directories, split apart by #3153 so one name never means two
+ * things: `primitive/` is the COMMITTED tree (the config and every
+ * environment's TOML), `.primitive/` is MACHINE-LOCAL state (credentials, this
+ * machine's selection, snapshot backups) and is gitignored whole.
+ */
+export declare const PROJECT_TREE_DIR = "primitive";
+export declare const PROJECT_LOCAL_STATE_DIR = ".primitive";
+export declare const PROJECT_CONFIG_FILENAME = "config.json";
+export declare const LOCAL_STATE_FILENAME = "local.json";
+export declare const PROJECT_CONFIG_DISPLAY_NAME = "primitive/config.json";
+export declare const LOCAL_STATE_DISPLAY_NAME = ".primitive/local.json";
+/**
+ * The one refusal for a project that never migrated off the pre-#3153 layout:
+ * a `.primitive/config.json` with no `primitive/config.json` beside it.
+ *
+ * That shape is refused rather than walked past because the walk's next stop
+ * is the parent directory, and in a nested checkout the parent may be a
+ * DIFFERENT project — a command run in the unmigrated one would silently act
+ * on the other's app. Nothing else is refused (#3392): anything left under
+ * `.primitive/` beside a migrated tree is machine-local junk, not signal.
+ *
+ * One sentence, naming both halves — the file that was found and the file
+ * that is expected — and no document. The migration page this once pointed
+ * at was never published (#3155, won't-fix), and every reader that shares
+ * this refusal — this core, the generated Vite-plugin copy, the Swift
+ * pre-build script, the Vue template's deploy script — says the same thing.
+ */
+export declare function unmigratedProjectMessage(found: string, expected: string): string;
+/**
+ * The one refusal for a command run outside a Primitive project (#3154,
+ * intent criterion 5).
+ *
+ * There is exactly one way to resolve the configuration tree, the credentials
+ * and the app: the environment named by `primitive/config.json`. Outside a
+ * project there is no such thing, and the CLI says so once, in these words,
+ * wherever the question is asked — the resolver core, the CLI's
+ * `requireCurrentEnvironment()`, and the credentials store.
+ *
+ * Two constraints on the wording, both test-asserted:
+ *
+ *   - it names `primitive init`, the one command that creates what is missing;
+ *   - it never names `primitive env add`, which after this change also fails
+ *     outside a project — an error may only offer an invocation it does not
+ *     itself block.
+ */
+export declare function missingConfigMessage(where: string): string;
+/**
+ * Error kinds callers branch on. Every failure is one of these — no reader is
+ * ever left guessing what a broken config meant.
+ */
+export type PrimitiveEnvErrorKind = "missing-config" | "malformed-config" | "unsupported-version" | "corrupt-local-state" | "unknown-environment" | "no-selection" | "missing-app-id" | "stale-layout";
+export declare class PrimitiveEnvError extends Error {
+    readonly kind: PrimitiveEnvErrorKind;
+    readonly path?: string;
+    constructor(kind: PrimitiveEnvErrorKind, message: string, path?: string);
+}
+export interface CoreEnvironmentEntry {
+    apiUrl: string;
+    /**
+     * The one app this environment names (#3152). Required: selecting an
+     * environment selects exactly one app, so there is no per-machine "current
+     * app" for a second reader to disagree with.
+     */
+    appId: string;
+    appName?: string;
+    /**
+     * The app's web counterpart for this environment, as a normalized origin
+     * (#2982). Read through `normalizeWebOrigin`, so a value this reader carries
+     * is always an origin — see that function for why the typed read other
+     * fields get is not enough here.
+     */
+    webUrl?: string;
+    description?: string;
+}
+/**
+ * The app's web counterpart as a normalized ORIGIN, or undefined when the
+ * value cannot be one (#2982).
+ *
+ * Unlike `appId`/`appName`, a typed read is not enough. This value is not
+ * merely carried: the Swift app points its emailed sign-in link at
+ * `<webUrl>/oauth/callback` and trusts incoming universal links from the same
+ * origin, and BOTH jobs need an origin —
+ *
+ *   - https except loopback, the rule the server applies to every redirect URI
+ *     (`src/auth/redirect-uri.ts`): an origin that cannot be allow-listed turns
+ *     every sign-in request into a 400, and a plain-http link would carry the
+ *     magic token in clear;
+ *   - no path, query or fragment: the web client serves its callback on its own
+ *     origin plus `/oauth/callback`, which is also the exact path the
+ *     `apple-app-site-association` component claims;
+ *   - no credentials, which have no business in a link that goes out by email.
+ *
+ * `primitive env add --web-url` and the project-config validation reject those
+ * shapes with a field-named error, but neither is on the path from a
+ * hand-edited `primitive/config.json` to an Xcode build: the Swift template's
+ * pre-build script reads the file directly. So every reader that feeds
+ * `primitive.json` applies the contract, and a value that misses it is read as
+ * "this environment has no web counterpart" — code-only email, no trusted
+ * origin, nothing silently pointed at the wrong URL.
+ *
+ * The message-producing twin of this rule lives in `cli/src/lib/web-url.ts`;
+ * this file cannot import it (see COPYABILITY above), and a test pins that the
+ * two agree.
+ */
+export declare function normalizeWebOrigin(value: unknown): string | undefined;
+/**
+ * The one remedy for an environment that names no app (#3152), shared by every
+ * reader that can hit it: this core, the CLI's `validateProjectConfig`, the
+ * Swift template's pre-build script, and the Vue template's cf-deploy.
+ *
+ * Two constraints on the wording, both test-asserted:
+ *
+ *   - it never says `primitive env add <name>`, which REFUSES an environment
+ *     name that already exists — the shape this error is always about;
+ *   - it names no command the failure itself blocks. The CLI validates the
+ *     project config before any command parses, so every `primitive` command
+ *     run inside the broken project fails with this same error. The only
+ *     invocation it may offer is one it says out loud to run elsewhere.
+ */
+export declare function missingAppIdMessage(name: string, configPath?: string): string;
+export interface CoreProjectConfig {
+    version: number;
+    defaultEnvironment?: string;
+    environments: Record<string, CoreEnvironmentEntry>;
+}
+/** Which precedence step picked the environment. Printed in the build banner. */
+export type PrimitiveEnvSource = "explicit" | "env-var" | "local" | "default" | "sole";
+export interface ResolvedPrimitiveEnv {
+    name: string;
+    apiUrl: string;
+    /** Derived from apiUrl by scheme swap — never authored separately. */
+    wsUrl: string;
+    /** The app this environment names. Always present — see #3152. */
+    appId: string;
+    appName?: string;
+    /** The app's web counterpart for the SELECTED environment, if it has one. */
+    webUrl?: string;
+    description?: string;
+    source: PrimitiveEnvSource;
+    configPath: string;
+    localStatePath: string;
+    projectRoot: string;
+}
+export interface ResolveOptions {
+    /** Directory to start the upward walk from. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Environment variables to read. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** An explicit `--env` / `--primitive-env` value, if the caller has one. */
+    explicitEnvName?: string | null;
+    /** Use this config file instead of discovering one. */
+    configPath?: string;
+}
+/**
+ * Derives the WebSocket URL from the API URL. Every apiUrl/wsUrl pair in
+ * practice is the same host with the scheme swapped, so it is derived rather
+ * than authored — one less thing to get out of sync.
+ */
+export declare function deriveWsUrl(apiUrl: string): string;
+/**
+ * Finds `primitive/config.json` by walking up from `cwd`, or returns the
+ * PRIMITIVE_PROJECT_CONFIG override when it is set (and exists).
+ *
+ * The override is checked for provenance BEFORE the file is read (#3153, F2):
+ * it bypasses the walk, so without this an old-layout config could be handed
+ * straight to a reader and defeat the cutover. An override that points inside
+ * a `.primitive/` directory IS the old layout, named explicitly.
+ *
+ * This is the one function every reader goes through — `resolvePrimitiveEnv`
+ * and the CLI's own `loadProjectConfig`/`findProjectRoot` alike — so the
+ * unmigrated-project refusal lives HERE, in the walk, or the commands that
+ * never call `resolvePrimitiveEnv` would walk past the old anchor into the
+ * parent directory's project.
+ */
+export declare function findPrimitiveConfigPath(options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): string | null;
+/**
+ * The project root for a config path: the parent of `primitive/`, or the
+ * containing directory when the config was pointed at directly (a fixture via
+ * PRIMITIVE_PROJECT_CONFIG, which is not inside a `primitive/` directory).
+ */
+export declare function projectRootForConfigPath(configPath: string): string;
+/**
+ * Machine-local state lives under the project root's `.primitive/`, not beside
+ * the config — the config is committed now, and the two must not share a
+ * directory. A fixture-pointed bare config still gets its own `.primitive/`
+ * in its own directory, so it never picks up a real project's selection.
+ */
+export declare function localStatePathForConfigPath(configPath: string): string;
+/**
+ * Reads and structurally validates `primitive/config.json`. Throws rather
+ * than guessing: a config that cannot be understood is always louder than a
+ * silent fallback to the wrong backend.
+ */
+export declare function readCoreProjectConfig(configPath: string): CoreProjectConfig;
+/**
+ * Reads this machine's selection from `.primitive/local.json`. Returns null
+ * when there is no file or no selection in it; throws when the file exists but
+ * cannot be read as the shape `primitive env use` writes.
+ */
+export declare function readLocalSelection(configPath: string): string | null;
+/**
+ * Applies the precedence to an already-loaded config. Exposed separately so
+ * the CLI wrapper can run its own field-level validation first and still share
+ * one ordering with every other reader.
+ */
+export declare function selectEnvironmentName(config: CoreProjectConfig, options: {
+    explicitEnvName?: string | null;
+    envVarName?: string | null;
+    localSelection?: string | null;
+    configPath?: string;
+}): {
+    name: string;
+    source: PrimitiveEnvSource;
+};
+/**
+ * The whole algorithm end to end: discover the config, read the selection,
+ * apply the precedence, derive the WebSocket URL.
+ */
+export declare function resolvePrimitiveEnv(options?: ResolveOptions): ResolvedPrimitiveEnv;