@spacefast/common 0.0.12 → 0.0.13

package/dist/utils/publish-policy.js

@@ -60,6 +60,10 @@ const STATIC_EXECUTION_CONTROL_FILES = new Set([".htaccess", ".user.ini"]);
 // (`/__stattic_probe` today, more `/__stattic/*` routes planned) stays
 // reserved the same way. Mid-segment occurrences are ordinary content.
 const STATIC_RUNTIME_CONTROL_SEGMENT_PREFIXES = ["__spacefast", "__stattic"];
+// Compact platform endpoints live below `/__sf`. Reserve the complete root
+// segment prefix before the first endpoint ships so uploaded content can never
+// shadow a later platform route. Nested `__sf*` directories remain content.
+const STATIC_RUNTIME_ROOT_SEGMENT_PREFIXES = ["__sf"];
 // Both the current and the legacy control-path spellings stay denied: spaces
 // published before the `.stattic` → `.spacefast` rename still serve from the
 // legacy on-disk layout, and user archives may carry either name.
@@ -76,6 +80,24 @@ const STATIC_RUNTIME_CONTROL_PREFIXES = [
 export function normalizePublishPath(relativePath) {
     return relativePath.replace(/\\/g, "/").replace(/^\/+/g, "");
 }
+/**
+ * The one subtree inside the runtime control prefix that a publish may write.
+ *
+ * `sf publish` compiles a version's worker into `__spacefast/functions/bundles/`
+ * so the bundle travels through the ordinary manifest and upload path instead of
+ * needing a parallel one. Keeping it under the control prefix is what makes it
+ * unservable as static content by default — the runtime answers it only behind a
+ * signature.
+ *
+ * Scoped to `bundles/` rather than the whole `__spacefast/functions/` directory
+ * on purpose: the sibling `config.json` holds the key those signatures are
+ * minted with, and a publish that could overwrite it would be a publish that
+ * could mint its own tokens.
+ */
+const PUBLISHABLE_BUILD_ARTIFACT_PREFIX = "__spacefast/functions/bundles/";
+function isPublishableBuildArtifactPath(lowerPath) {
+    return lowerPath.startsWith(PUBLISHABLE_BUILD_ARTIFACT_PREFIX);
+}
 export function publishPathIgnored(relativePath) {
     const path = normalizePublishPath(relativePath);
     // The agent state dirs hold one secret (state.json) plus committable tooling
@@ -101,27 +123,27 @@ export function publishPathIsConvention(relativePath) {
 // Headers", migration diagnostics): Cloudflare Pages `_worker.js`/`_routes.json`
 // and Pages/Netlify function directories publish as inert content with a
 // warning so migrations are never silent.
+function providerRuntimeFeatureForPath(path) {
+    if (path === "_worker.js") {
+        return "Cloudflare Pages _worker.js";
+    }
+    if (path === "_routes.json") {
+        return "Cloudflare Pages _routes.json";
+    }
+    if (path.startsWith("functions/")) {
+        return "Pages Functions (functions/)";
+    }
+    if (path.startsWith("netlify/functions/")) {
+        return "Netlify Functions (netlify/functions/)";
+    }
+    return null;
+}
 export function providerRuntimeFeatureWarnings(paths) {
     const warnings = [];
     const seen = new Set();
-    const featureForPath = (path) => {
-        if (path === "_worker.js") {
-            return "Cloudflare Pages _worker.js";
-        }
-        if (path === "_routes.json") {
-            return "Cloudflare Pages _routes.json";
-        }
-        if (path.startsWith("functions/")) {
-            return "Pages Functions (functions/)";
-        }
-        if (path.startsWith("netlify/functions/")) {
-            return "Netlify Functions (netlify/functions/)";
-        }
-        return null;
-    };
     for (const rawPath of paths) {
         const path = normalizePublishPath(rawPath);
-        const feature = featureForPath(path);
+        const feature = providerRuntimeFeatureForPath(path);
         if (!feature || seen.has(feature)) {
             continue;
         }
@@ -179,11 +201,15 @@ export function staticUploadPathViolation(path, options = {}) {
     if (reservedRuntimeControlFiles?.has(lowerName) && lowerPath === lowerName) {
         return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
     }
+    const lowerRootSegment = segments[0]?.toLowerCase() ?? "";
+    if (STATIC_RUNTIME_ROOT_SEGMENT_PREFIXES.some((prefix) => lowerRootSegment.startsWith(prefix))) {
+        return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
+    }
     const controlSegment = segments.find((segment) => {
         const lowerSegment = segment.toLowerCase();
         return STATIC_RUNTIME_CONTROL_SEGMENT_PREFIXES.some((prefix) => lowerSegment.startsWith(prefix));
     });
-    if (controlSegment) {
+    if (controlSegment && !isPublishableBuildArtifactPath(lowerPath)) {
         return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
     }
     if (STATIC_RUNTIME_CONTROL_PREFIXES.some((prefix) => lowerPath === prefix || lowerPath.startsWith(`${prefix}/`))) {
@@ -203,6 +229,95 @@ export function firstStaticUploadPathViolation(paths, options = {}) {
     }
     return null;
 }
+/**
+ * Canonicalizes a route expanded from an already-canonical manifest path.
+ * Manifest intake has decoded percent escapes exactly once, so this must not
+ * decode again. It applies only the route-identity aliases shared with access.
+ */
+export function canonicalizePublishRequestedRoute(route) {
+    if (!route.startsWith("/")) {
+        throw new TypeError("publish requested routes must be absolute");
+    }
+    const segments = route
+        .split("/")
+        .filter((segment) => segment !== "" && segment !== ".")
+        .map((segment) => segment.normalize("NFC"));
+    if (segments.at(-1) === "index.html")
+        segments.pop();
+    return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+/**
+ * Expands artifact paths into the request routes they can serve. The runtime
+ * resolves literal files, directory indexes, and clean `.html` aliases; two
+ * different artifacts owning one request route is rejected at publish/finalize
+ * instead of depending on lookup order. `routeOwnership` exposes the same
+ * expansion in canonical access-route form so authorization and diagnostics
+ * never have to infer a route from an artifact path.
+ */
+export function analyzePublishRoutes(paths, options = {}) {
+    const index = options.index === undefined ? "index.html" : options.index;
+    const cleanUrls = options.cleanUrls ?? true;
+    const routes = new Map();
+    const add = (route, path) => {
+        const owners = routes.get(route) ?? new Set();
+        owners.add(path);
+        routes.set(route, owners);
+    };
+    for (const path of paths) {
+        add(`/${path}`, path);
+        if (cleanUrls && path.endsWith(".html")) {
+            add(`/${path.slice(0, -".html".length)}`, path);
+        }
+        if (index !== false) {
+            if (path === index) {
+                add("/", path);
+            }
+            else if (path.endsWith(`/${index}`)) {
+                const directory = path.slice(0, -(index.length + 1));
+                add(`/${directory}`, path);
+                add(`/${directory}/`, path);
+            }
+        }
+    }
+    const collisions = [...routes.entries()]
+        .filter(([, owners]) => owners.size > 1)
+        .map(([route, owners]) => ({ route, paths: [...owners].toSorted() }))
+        .toSorted((left, right) => left.route.localeCompare(right.route));
+    const firstByFoldedRoute = new Map();
+    const caseCollisions = [];
+    for (const [route, owners] of routes) {
+        const folded = route.toLowerCase();
+        const pathsForRoute = [...owners].toSorted();
+        const sibling = firstByFoldedRoute.get(folded);
+        if (sibling && sibling.route !== route) {
+            caseCollisions.push({
+                route,
+                siblingRoute: sibling.route,
+                paths: [...new Set([...sibling.paths, ...pathsForRoute])].toSorted(),
+            });
+        }
+        else if (!sibling) {
+            firstByFoldedRoute.set(folded, { route, paths: pathsForRoute });
+        }
+    }
+    const canonicalOwnership = new Map();
+    for (const [route, owners] of routes) {
+        const canonicalRoute = canonicalizePublishRequestedRoute(route);
+        const canonicalOwners = canonicalOwnership.get(canonicalRoute) ?? new Set();
+        for (const owner of owners)
+            canonicalOwners.add(owner);
+        canonicalOwnership.set(canonicalRoute, canonicalOwners);
+    }
+    const routeOwnership = [...canonicalOwnership.entries()]
+        .flatMap(([requestedRoute, owners]) => [...owners].map((artifactPath) => ({ requestedRoute, artifactPath })))
+        .toSorted((left, right) => left.requestedRoute.localeCompare(right.requestedRoute) ||
+        left.artifactPath.localeCompare(right.artifactPath));
+    return {
+        collisions,
+        caseCollisions: caseCollisions.toSorted((left, right) => left.route.localeCompare(right.route)),
+        routeOwnership,
+    };
+}
 export function resolveManifestFileCap(maxFiles) {
     return Math.min(MANIFEST_MAX_FILES_CEILING, maxFiles && maxFiles > 0 ? maxFiles : MANIFEST_MAX_FILES_CEILING);
 }
@@ -374,8 +489,6 @@ export const ANONYMOUS_SERVE_CONTENT_TYPES = [
     "application/rss+xml",
     "application/atom+xml",
 ];
-const LINE_SPLIT_PATTERN = /\r?\n/;
-const BASIC_AUTH_HEADER_PATTERN = /^basic-auth\s*:/i;
 function extensionForPath(filePath) {
     const normalized = normalizePublishPath(filePath).toLowerCase();
     const fileName = normalized.split("/").at(-1) ?? normalized;
@@ -449,45 +562,3 @@ export function filterFreePlanManifest(files, options) {
     }
     return { allowed, ignored };
 }
-// Free-plan `_headers` compile policy (spec "Plans And Limits", amended
-// 2026-06-10): custom response headers stay FREE; the Basic-Auth header
-// MECHANISM is the paid feature. Basic-Auth operations are dropped from free
-// compiles with a `free_headers_basic_auth_disabled` warning; every other
-// header operation passes through untouched.
-export function filterFreePlanHeaders(content) {
-    const output = [];
-    let droppedBasicAuthCount = 0;
-    let pendingMatcher = null;
-    let matcherEmitted = false;
-    const emitOperation = (rawLine) => {
-        if (pendingMatcher !== null && !matcherEmitted) {
-            output.push(pendingMatcher);
-            matcherEmitted = true;
-        }
-        output.push(rawLine);
-    };
-    for (const rawLine of content.split(LINE_SPLIT_PATTERN)) {
-        const trimmed = rawLine.trim();
-        if (!trimmed || trimmed.startsWith("#")) {
-            continue;
-        }
-        if (!rawLine.startsWith(" ") && !rawLine.startsWith("\t")) {
-            pendingMatcher = trimmed;
-            matcherEmitted = false;
-            continue;
-        }
-        if (pendingMatcher === null) {
-            continue;
-        }
-        if (BASIC_AUTH_HEADER_PATTERN.test(trimmed)) {
-            droppedBasicAuthCount += 1;
-        }
-        else {
-            emitOperation(rawLine);
-        }
-    }
-    return {
-        headers: output.length > 0 ? `${output.join("\n")}\n` : undefined,
-        droppedBasicAuthCount,
-    };
-}

package/dist/utils/query-keys.d.ts

@@ -63,20 +63,15 @@ export declare const qk: {
     spaceDomains: (id: string) => readonly ["spaces", string, "domains"];
     spaceRuntimeStatus: (id: string) => readonly ["spaces", string, "runtime"];
     spaceApplyState: (id: string) => readonly ["spaces", string, "apply-state"];
-    spaceZero: (id: string) => readonly ["spaces", string, "zero"];
     spaceZeroDb: (id: string) => readonly ["spaces", string, "zero", "db"];
-    spaceZeroLogs: (id: string, limit: number) => readonly ["spaces", string, "zero", "logs", number];
+    spaceRuntimeLogs: (id: string, limit: number) => readonly ["spaces", string, "logs", "runtime", number];
     spaceZeroRealtimeEvents: (id: string, limit: number) => readonly ["spaces", string, "zero", "realtime", "events", number];
     spaceVariables: (id: string) => readonly ["spaces", string, "variables"];
     spaceCertificates: (id: string) => readonly ["spaces", string, "runtime", "certificates"];
     spaceLogs: (id: string, kind: "build" | "access" | "runtime") => readonly ["spaces", string, "logs", "build" | "runtime" | "access"];
     spaceAnalytics: (id: string, window: string) => readonly ["spaces", string, "analytics", string];
-    spaceFirewall: (id: string) => readonly ["spaces", string, "access", "firewall"];
-    spaceAccessViews: (id: string, since?: string) => readonly ["spaces", string, "access", "views", string];
-    teamServiceTokens: (teamId: string) => readonly ["teams", string, "access", "service-tokens"];
     teamAgentHandoffs: (teamId: string) => readonly ["teams", string, "agent-handoffs"];
     teamAccessDefaults: (teamId: string) => readonly ["teams", string, "access", "defaults"];
-    teamAccessConnections: (teamId: string) => readonly ["teams", string, "access", "connections"];
     domain: (teamId: string, ref: string) => readonly ["teams", string, "domains", string];
     domainDiagnostics: (teamId: string, domainId: string) => readonly ["teams", string, "domains", string, "diagnostics"];
     domainDnsCapabilities: (domainId: string) => readonly ["domains", string, "dns", "capabilities"];

package/dist/utils/query-keys.js

@@ -81,20 +81,15 @@ export const qk = {
     spaceDomains: (id) => ["spaces", id, "domains"],
     spaceRuntimeStatus: (id) => ["spaces", id, "runtime"],
     spaceApplyState: (id) => ["spaces", id, "apply-state"],
-    spaceZero: (id) => ["spaces", id, "zero"],
     spaceZeroDb: (id) => ["spaces", id, "zero", "db"],
-    spaceZeroLogs: (id, limit) => ["spaces", id, "zero", "logs", limit],
+    spaceRuntimeLogs: (id, limit) => ["spaces", id, "logs", "runtime", limit],
     spaceZeroRealtimeEvents: (id, limit) => ["spaces", id, "zero", "realtime", "events", limit],
     spaceVariables: (id) => ["spaces", id, "variables"],
     spaceCertificates: (id) => ["spaces", id, "runtime", "certificates"],
     spaceLogs: (id, kind) => ["spaces", id, "logs", kind],
     spaceAnalytics: (id, window) => ["spaces", id, "analytics", window],
-    spaceFirewall: (id) => ["spaces", id, "access", "firewall"],
-    spaceAccessViews: (id, since) => ["spaces", id, "access", "views", since ?? ""],
-    teamServiceTokens: (teamId) => ["teams", teamId, "access", "service-tokens"],
     teamAgentHandoffs: (teamId) => ["teams", teamId, "agent-handoffs"],
     teamAccessDefaults: (teamId) => ["teams", teamId, "access", "defaults"],
-    teamAccessConnections: (teamId) => ["teams", teamId, "access", "connections"],
     domain: (teamId, ref) => ["teams", teamId, "domains", ref],
     domainDiagnostics: (teamId, domainId) => ["teams", teamId, "domains", domainId, "diagnostics"],
     domainDnsCapabilities: (domainId) => ["domains", domainId, "dns", "capabilities"],

package/dist/utils/space-config.d.ts

@@ -1,3 +1,4 @@
+import { type Grant } from "../contracts/grants.js";
 import { type SpaceConfig, type SpaceConfigFile } from "../contracts/space-config.js";
 export type SpaceConfigBlockingIssueCode = "config_file_too_large" | "config_templates_over_limit" | "config_meta_too_long" | "config_invalid" | "inject_snippet_too_large" | "inject_invalid";
 export type SpaceConfigIssue = {
@@ -8,6 +9,9 @@ export type SpaceConfigIssue = {
     path?: string;
     details?: Record<string, unknown>;
 };
+export declare const CONFIG_PUBLIC_GRANT_COMPILED_ID = "config:access.public";
+/** Compiles the file-only access declaration; activation decides which Version is live. */
+export declare function compileSpaceConfigPublicGrant(fileConfig: Pick<SpaceConfigFile, "access"> | null | undefined): Grant | null;
 type SpaceConfigBlockingIssue = SpaceConfigIssue & {
     code: SpaceConfigBlockingIssueCode;
 };
@@ -16,7 +20,7 @@ type SpaceConfigBlockingIssue = SpaceConfigIssue & {
  * `config`): the 16 KB compiled-overlay cap plus the shared shape caps.
  * Returns the first blocking issue, or null when the overlay is acceptable.
  */
-export declare function spaceConfigOverlayIssue(config: SpaceConfig): SpaceConfigBlockingIssue | null;
+export declare function spaceConfigOverlayIssue(config: SpaceConfig | Record<string, unknown>): SpaceConfigBlockingIssue | null;
 export declare function stripJsonComments(raw: string): string;
 export type ParsedSpaceConfigFile = {
     /** Parsed config (cap- and shape-valid keys only); null when unusable. */

package/dist/utils/space-config.js

@@ -1,8 +1,35 @@
+import { CONFIG_PUBLIC_GRANT_SOURCE_REFERENCE, grantSchema, } from "../contracts/grants.js";
 import { SPACE_CONFIG_CAPS, SPACE_CONFIG_CANONICAL_FILE, SPACE_CONFIG_PRIVATE_FILES, spaceConfigFileSchema, spaceConfigSchema, } from "../contracts/space-config.js";
 const TEXT_BYTES = new TextEncoder();
+export const CONFIG_PUBLIC_GRANT_COMPILED_ID = "config:access.public";
 function byteLength(value) {
     return TEXT_BYTES.encode(value).length;
 }
+/** Compiles the file-only access declaration; activation decides which Version is live. */
+export function compileSpaceConfigPublicGrant(fileConfig) {
+    const patterns = fileConfig?.access?.public ?? [];
+    const include = patterns.filter((pattern) => !pattern.startsWith("!"));
+    if (include.length === 0)
+        return null;
+    return grantSchema.parse({
+        id: CONFIG_PUBLIC_GRANT_COMPILED_ID,
+        name: "Public paths from sf.jsonc",
+        audience: { kind: "public" },
+        resources: {
+            include,
+            exclude: patterns
+                .filter((pattern) => pattern.startsWith("!"))
+                .map((pattern) => pattern.slice(1)),
+        },
+        capabilities: ["page.view"],
+        constraints: {},
+        target: { kind: "live" },
+        source: {
+            kind: "config",
+            reference: CONFIG_PUBLIC_GRANT_SOURCE_REFERENCE,
+        },
+    });
+}
 function capIssues(candidate) {
     const issues = [];
     const templates = candidate.templates;
@@ -102,6 +129,14 @@ function capIssues(candidate) {
  * Returns the first blocking issue, or null when the overlay is acceptable.
  */
 export function spaceConfigOverlayIssue(config) {
+    if (Object.prototype.hasOwnProperty.call(config, "access")) {
+        return {
+            severity: "error",
+            code: "config_invalid",
+            message: "access is only valid in the committed sf.jsonc file.",
+            path: "access",
+        };
+    }
     const encoded = JSON.stringify(config);
     if (byteLength(encoded) > SPACE_CONFIG_CAPS.overlayBytes) {
         return {

package/dist/utils/static-runtime-policy.d.ts

@@ -1,5 +1,10 @@
 export declare const PHP_LIKE_EXTENSIONS: string[];
+export declare const INTERNAL_REDIRECT_RESPONSE_HEADERS: string[];
 export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: string[];
+/** Reserved response-header namespaces owned by the platform's own serving signature. */
+export declare const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES: string[];
+/** True when user rules may neither set nor remove this response header. */
+export declare function isPlatformManagedResponseHeader(name: string): boolean;
 export declare const NON_IMMUTABLE_EXTENSIONS: string[];
 export declare const GUARANTEED_IMMUTABLE_PREFIXES: string[];
 /** Lowercased extension without the leading dot, posix semantics. Dotfiles have no extension. */

package/dist/utils/static-runtime-policy.js

@@ -7,13 +7,47 @@
 // (static-runtime-policy.fixtures.json). Do not add platform/filesystem
 // behavior here.
 export const PHP_LIKE_EXTENSIONS = ["php", "php3", "php4", "php5", "php7", "php8", "phtml", "phar"];
+// The internal-redirect/sendfile family: headers that do not describe a response, they
+// instruct the web server to produce a different one. Under nginx+php-fpm
+// X-Accel-Redirect (and every vendor spelling of it) turns a response into a server-side
+// read of an arbitrary internal path — a private-path disclosure primitive — while
+// X-Accel-Limit-Rate pins the serving worker for the length of the transfer.
+//
+// These are dangerous from ANY origin we do not control, so this family is factored out
+// of the platform-managed list below: a relay lane (runtime/engine/runtime/proxy.php)
+// must drop exactly this set from an untrusted upstream while still relaying the
+// ordinary response headers (location, content-encoding, content-range, allow) that the
+// rest of the managed list contains.
+export const INTERNAL_REDIRECT_RESPONSE_HEADERS = [
+    "x-accel-buffering",
+    "x-accel-charset",
+    "x-accel-expires",
+    "x-accel-limit-rate",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-lighttpd-sendfile",
+    "x-lighttpd-sendfile2",
+    "x-reproxy-url",
+    "x-sendfile",
+];
 // Rejected/platform-managed response headers (internal-docs/platform.md "Routing And
-// Headers"): user `_headers` rules can never set or remove these. The list includes the
-// internal-redirect/sendfile family (X-Accel-Redirect, X-Sendfile, X-LIGHTTPD-send-file,
-// X-Accel-Buffering) because under nginx+php-fpm those headers turn a response into a
-// server-side file read — a private-path disclosure primitive. The native Rust compiler
-// rejects them at publish; the PHP runtime refuses them again at apply time so a compiler
-// gap can never emit one.
+// Headers"): user `_headers` rules can never set or remove these. The
+// internal-redirect/sendfile family above is spread in, so it stays a strict subset —
+// anything the proxy lane refuses to relay is also refused from `_headers`. The rest is
+// the connection and transport surface: hop-by-hop names (Connection, Keep-Alive, TE,
+// Trailer, Transfer-Encoding, Upgrade, Proxy-*), framing, and the edge-cache trio.
+//
+// `isPlatformManagedResponseHeader` — not this list alone — is the policy: the reserved
+// `x-spacefast-*` / `x-stattic-*` namespaces below carry the platform's own response
+// signature (X-Spacefast-Runtime, X-Spacefast-Version, X-Spacefast-Reason, …), so user
+// rules can never forge or clobber them.
+//
+// Every enforcement point derives from here: the `_headers` compiler in
+// @spacefast/routing imports it directly, the PHP runtime maps and prefixes are
+// generated from it into runtime/engine/shared/safety.php, and the Rust authorities
+// (crates/stattic-runtime-core policy.rs, crates/stattic-zero-runner
+// response_headers.rs) are drift-guarded against it by
+// apps/control-plane/src/runtime/php-policy-parity.test.ts.
 export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
     "accept-ranges",
     "age",
@@ -28,21 +62,31 @@ export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
     "cookie",
     "date",
     "host",
+    "keep-alive",
     "location",
     "netlify-cdn-cache-control",
+    "proxy-authenticate",
+    "proxy-authorization",
     "server",
     "set-cookie",
     "strict-transport-security",
     "surrogate-control",
+    "te",
     "trailer",
     "transfer-encoding",
     "upgrade",
     "vary",
-    "x-accel-buffering",
-    "x-accel-redirect",
-    "x-lighttpd-send-file",
-    "x-sendfile",
+    ...INTERNAL_REDIRECT_RESPONSE_HEADERS,
 ];
+/** Reserved response-header namespaces owned by the platform's own serving signature. */
+export const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES = ["x-spacefast-", "x-stattic-"];
+const PLATFORM_MANAGED_RESPONSE_HEADER_SET = new Set(PLATFORM_MANAGED_RESPONSE_HEADERS);
+/** True when user rules may neither set nor remove this response header. */
+export function isPlatformManagedResponseHeader(name) {
+    const lower = name.trim().toLowerCase();
+    return (PLATFORM_MANAGED_RESPONSE_HEADER_SET.has(lower) ||
+        PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES.some((prefix) => lower.startsWith(prefix)));
+}
 export const NON_IMMUTABLE_EXTENSIONS = ["html", "htm", "php", "txt", "xml"];
 const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
 const NON_IMMUTABLE_EXTENSION_SET = new Set(NON_IMMUTABLE_EXTENSIONS);

package/dist/utils/upload-session.d.ts

@@ -24,6 +24,9 @@ export declare class UploadTargetError extends Error {
     readonly status: number;
     constructor(target: UploadTarget, status: number, message: string);
 }
+export declare function uploadPageHasRemainder(page: UploadSession): boolean;
+export declare const UPLOAD_STALLED_RESUME_MAX_ATTEMPTS = 3;
+export declare function uploadQueueAdvanced(before: UploadSession, after: UploadSession | null): boolean;
 export declare function executeUploadSession(input: {
     session: UploadSession;
     targets?: readonly UploadTarget[] | undefined;

package/dist/utils/upload-session.js

@@ -8,6 +8,37 @@ export class UploadTargetError extends Error {
         this.name = "UploadTargetError";
     }
 }
+// Manifest paging policy — ONE definition, shared by every uploader (the CLI
+// and the control plane's inline uploader).
+//
+// `targets` is a single instruction page, bounded by the instruction payload
+// budget; `summary.upload` counts the whole declared manifest. A short page
+// therefore means a remainder that only `resume` hands out, and an uploader
+// that stops at the first page finalizes a version the runtime rejects with
+// `version_upload_incomplete`. A complete page means there is nothing left to
+// ask for — don't re-resume to double-check the uploads, since the runtime
+// verifies size and sha256 on every PUT and finalize independently enumerates
+// anything still missing.
+export function uploadPageHasRemainder(page) {
+    return page.summary.upload > page.targets.length;
+}
+// Resume mints the next page from runtime session truth, so a converging
+// session always hands back different work. A page that repeats the previous
+// one is a session that is not draining; retry it a bounded number of times,
+// then fail loudly rather than page forever.
+export const UPLOAD_STALLED_RESUME_MAX_ATTEMPTS = 3;
+export function uploadQueueAdvanced(before, after) {
+    if (!after || after.targets.length === 0) {
+        return true;
+    }
+    if (after.targets.length < before.targets.length) {
+        return true;
+    }
+    if (after.targets.length > before.targets.length) {
+        return false;
+    }
+    return after.targets.some((target, index) => target.path !== before.targets[index]?.path);
+}
 async function runConcurrent(items, concurrency, fn) {
     let nextIndex = 0;
     const runWorker = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -93,6 +93,7 @@
   "dependencies": {
     "@tanstack/react-query": "^5.101.4",
     "culori": "^4.0.2",
+    "js-yaml": "^4.1.1",
     "smol-toml": "^1.7.0",
     "zod": "^4.4.3"
   }

package/dist/utils/access-grant.d.ts

@@ -1,14 +0,0 @@
-import type { RuntimeRule } from "../contracts/access.js";
-export declare const ACCESS_GRANT_GATE_RULE_ID = "access-grant-gate";
-export declare const ACCESS_GRANT_ADMISSION_RULE_ID = "access-grant-admission";
-export type AccessGrantExposure = {
-    anonymousAccess: "gated" | "gated_with_exceptions" | "partly_public" | "shadowed";
-    earlierAnonymousAllowRules: number;
-    earlierManagedAccessRules: number;
-    precedingTerminalRules: number;
-};
-export declare function withAccessGrantGate(rules: RuntimeRule[], grant: string): RuntimeRule[];
-export declare function withoutAccessGrantRule(rules: RuntimeRule[], selectedIndex: number): RuntimeRule[];
-export declare function isAccessGrantAdmissionRule(rule: RuntimeRule): boolean;
-export declare function isAccessGrantFallbackRule(rule: RuntimeRule): boolean;
-export declare function accessGrantExposure(rules: RuntimeRule[]): AccessGrantExposure;

package/dist/utils/access-grant.js

@@ -1,88 +0,0 @@
-// `sf access grant` and the dashboard's Grant access card share one canonical
-// pair: an authenticated admission allow plus an anonymous fallback challenge.
-// Repeated grants widen both rules' OR-list. The split is essential under
-// first-match evaluation: the admission can pass before managed challenges,
-// while the fallback closes otherwise-public traffic after those challenges.
-export const ACCESS_GRANT_GATE_RULE_ID = "access-grant-gate";
-export const ACCESS_GRANT_ADMISSION_RULE_ID = "access-grant-admission";
-export function withAccessGrantGate(rules, grant) {
-    // Raw access writes replace only the unmanaged lane. GET/PUT responses may
-    // include server-owned managed blocks, but sending those blocks back would
-    // be rejected and could let a client accidentally claim their ownership.
-    // Reserved access-grant rules are rebuilt as one canonical pair below.
-    const unmanagedRules = rules.filter((rule) => rule.managedBy === undefined &&
-        rule.id !== ACCESS_GRANT_ADMISSION_RULE_ID &&
-        rule.id !== ACCESS_GRANT_GATE_RULE_ID);
-    const existingRequiredGrants = rules.find((rule) => rule.id === ACCESS_GRANT_ADMISSION_RULE_ID)
-        ?.auth?.requiredGrants;
-    const fallbackRequiredGrants = rules.find((rule) => rule.id === ACCESS_GRANT_GATE_RULE_ID)?.auth
-        ?.requiredGrants;
-    const requiredGrants = [
-        ...new Set([...(existingRequiredGrants ?? fallbackRequiredGrants ?? []), grant]),
-    ];
-    return [
-        ...unmanagedRules,
-        {
-            id: ACCESS_GRANT_ADMISSION_RULE_ID,
-            match: {},
-            effect: "allow",
-            auth: { requiredGrants },
-            reasonCode: "identity_grant_admitted",
-        },
-        {
-            id: ACCESS_GRANT_GATE_RULE_ID,
-            match: {},
-            effect: "challenge",
-            auth: { requiredGrants },
-            reasonCode: "identity_grant_required",
-            message: "Sign in with an approved identity to continue.",
-        },
-    ];
-}
-export function withoutAccessGrantRule(rules, selectedIndex) {
-    const selectedRule = rules[selectedIndex];
-    const removesAccessGrant = selectedRule?.id === ACCESS_GRANT_ADMISSION_RULE_ID ||
-        selectedRule?.id === ACCESS_GRANT_GATE_RULE_ID;
-    return rules.filter((rule, index) => rule.managedBy === undefined &&
-        (removesAccessGrant
-            ? rule.id !== ACCESS_GRANT_ADMISSION_RULE_ID && rule.id !== ACCESS_GRANT_GATE_RULE_ID
-            : index !== selectedIndex));
-}
-export function isAccessGrantAdmissionRule(rule) {
-    return (rule.id === ACCESS_GRANT_ADMISSION_RULE_ID &&
-        rule.effect === "allow" &&
-        Object.keys(rule.match).length === 0 &&
-        rule.auth !== undefined);
-}
-export function isAccessGrantFallbackRule(rule) {
-    return (rule.id === ACCESS_GRANT_GATE_RULE_ID &&
-        rule.effect === "challenge" &&
-        Object.keys(rule.match).length === 0 &&
-        rule.auth !== undefined);
-}
-// The admission allow protects approved identities without preempting the
-// existing password/share/service challenge. The final fallback gate protects
-// public fallthrough. A terminal rule from an earlier effective lane can still
-// stop evaluation before admission; report that explicitly instead of claiming
-// the space is simply gated.
-export function accessGrantExposure(rules) {
-    const gateIndex = rules.findIndex(isAccessGrantFallbackRule);
-    const admissionIndex = rules.findIndex(isAccessGrantAdmissionRule);
-    const earlierRules = gateIndex === -1 ? rules : rules.slice(0, gateIndex);
-    const rulesBeforeAdmission = admissionIndex === -1 ? earlierRules : rules.slice(0, admissionIndex);
-    const precedingTerminalRules = rulesBeforeAdmission.filter((rule) => rule.effect === "challenge" || (rule.effect === "deny" && rule.auth === undefined)).length;
-    const earlierAnonymousAllowRules = earlierRules.filter((rule) => rule.effect === "allow" && !rule.auth).length;
-    const earlierManagedAccessRules = earlierRules.filter((rule) => rule.managedBy !== undefined && rule.effect === "allow").length;
-    return {
-        anonymousAccess: precedingTerminalRules > 0
-            ? "shadowed"
-            : earlierAnonymousAllowRules > 0
-                ? "partly_public"
-                : earlierManagedAccessRules > 0
-                    ? "gated_with_exceptions"
-                    : "gated",
-        earlierAnonymousAllowRules,
-        earlierManagedAccessRules,
-        precedingTerminalRules,
-    };
-}