@spacefast/common 0.0.11 → 0.0.13

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

@@ -21,7 +21,6 @@ export declare const qk: {
     teamSpaces: (id: string) => readonly ["teams", string, "spaces"];
     teamDomains: (id: string) => readonly ["teams", string, "domains"];
     teamManagedDomains: (id: string) => readonly ["teams", string, "managed-domains"];
-    domainBindings: () => readonly ["domain-bindings"];
     slugAvailability: (kind: "team" | "space", slug: string, teamId?: string, currentSlug?: string) => readonly ["slugs", "availability", "space" | "team", string, string, string];
     teamVariables: (id: string) => readonly ["teams", string, "variables"];
     teamActivity: (id: string, limit: number) => readonly ["teams", string, "activity", number];
@@ -30,8 +29,8 @@ export declare const qk: {
     spaceVersions: (id: string) => readonly ["spaces", string, "versions"];
     spaceVersionsHistory: (id: string) => readonly ["spaces", string, "versions", "history"];
     spaceCollaboration: (id: string) => readonly ["spaces", string, "collaboration"];
-    spaceCollaborationEmbedConfig: (id: string) => readonly ["spaces", string, "collaboration", "embed-config"];
-    spaceAnnotations: (id: string) => readonly ["spaces", string, "annotations"];
+    spaceComments: (id: string) => readonly ["spaces", string, "comments"];
+    spaceCommentThread: (id: string, threadId: string) => readonly ["spaces", string, "comments", string];
     spaceActivity: (id: string, limit: number) => readonly ["spaces", string, "activity", number];
     spaceDeployments: (id: string) => readonly ["spaces", string, "deployments"];
     spaceTags: (id: string) => readonly ["spaces", string, "tags"];
@@ -39,11 +38,11 @@ export declare const qk: {
     spaceTagDiff: (id: string, versionId: string) => readonly ["spaces", string, "tags", string, "diff"];
     spaceTagReleases: (id: string) => readonly ["spaces", string, "tags", "releases"];
     spaceTagsEffective: (id: string) => readonly ["spaces", string, "tags", "effective"];
-    build: (id: string) => readonly ["builds", string];
-    buildLogs: (id: string, limit?: number) => readonly ["builds", string, "logs"] | readonly ["builds", string, "logs", number];
+    build: (spaceId: string, id: string) => readonly ["spaces", string, "builds", string];
+    buildLogs: (spaceId: string, id: string, limit?: number) => readonly ["spaces", string, "builds", string, "logs"] | readonly ["spaces", string, "builds", string, "logs", number];
     spaceBuilds: (id: string) => readonly ["spaces", string, "builds"];
     spaceRepositoryConnection: (id: string, connectionType?: string) => readonly ["spaces", string, "repository-connection", string];
-    repositoryInstallations: (spaceId: string) => readonly ["repository-connections", "installations", string];
+    repositoryInstallations: (spaceId: string) => readonly ["spaces", string, "repository-installations"];
     repositoryInstallationRepositories: (installationId: string) => readonly ["repository-connections", "installations", string, "repositories"];
     spaceRepositoryAnalyze: (id: string, connectionType?: string, ref?: string, root?: string) => readonly ["spaces", string, "repository-connection", string, "analyze", string, string];
     spaceRepositoryWebhookDeliveries: (id: string, connectionType?: string) => readonly ["spaces", string, "repository-webhook-deliveries", string];
@@ -51,7 +50,7 @@ export declare const qk: {
     webhook: (webhookId: string) => readonly ["webhooks", string];
     webhookDeliveries: (webhookId: string) => readonly ["webhooks", string, "deliveries"];
     spaceVersion: (id: string, versionId: string) => readonly ["spaces", string, "versions", string];
-    spaceVersionAnnotations: (id: string, versionId: string, status?: string) => readonly ["spaces", string, "versions", string, "annotations"] | readonly ["spaces", string, "versions", string, "annotations", string];
+    spaceVersionComments: (id: string, versionId: string, status?: string) => readonly ["spaces", string, "versions", string, "comments"] | readonly ["spaces", string, "versions", string, "comments", string];
     spaceVersionFiles: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "files"];
     spaceVersionFile: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string];
     spaceVersionFileDirectUrl: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string, "direct-url"];
@@ -64,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

@@ -26,7 +26,6 @@ export const qk = {
     teamSpaces: (id) => ["teams", id, "spaces"],
     teamDomains: (id) => ["teams", id, "domains"],
     teamManagedDomains: (id) => ["teams", id, "managed-domains"],
-    domainBindings: () => ["domain-bindings"],
     slugAvailability: (kind, slug, teamId, currentSlug) => ["slugs", "availability", kind, slug, teamId ?? "", currentSlug ?? ""],
     teamVariables: (id) => ["teams", id, "variables"],
     teamActivity: (id, limit) => ["teams", id, "activity", limit],
@@ -38,8 +37,8 @@ export const qk = {
     // `invalidateQueries({ queryKey: qk.spaceVersions(id) })` still reaches it.
     spaceVersionsHistory: (id) => [...qk.spaceVersions(id), "history"],
     spaceCollaboration: (id) => ["spaces", id, "collaboration"],
-    spaceCollaborationEmbedConfig: (id) => ["spaces", id, "collaboration", "embed-config"],
-    spaceAnnotations: (id) => ["spaces", id, "annotations"],
+    spaceComments: (id) => ["spaces", id, "comments"],
+    spaceCommentThread: (id, threadId) => [...qk.spaceComments(id), threadId],
     spaceActivity: (id, limit) => ["spaces", id, "activity", limit],
     spaceDeployments: (id) => ["spaces", id, "deployments"],
     spaceTags: (id) => ["spaces", id, "tags"],
@@ -49,15 +48,15 @@ export const qk = {
     // The merged (system+team+space) read-only view; never a write base — see
     // `fetchSpaceReleasedGraph` in apps/my/src/lib/space-queries.ts.
     spaceTagsEffective: (id) => ["spaces", id, "tags", "effective"],
-    build: (id) => ["builds", id],
+    build: (spaceId, id) => [...qk.spaceBuilds(spaceId), id],
     // Observers with different limits must not share a cache entry; calling with
     // no limit yields the bare prefix for invalidating every limit at once.
-    buildLogs: (id, limit) => limit === undefined
-        ? ["builds", id, "logs"]
-        : ["builds", id, "logs", limit],
+    buildLogs: (spaceId, id, limit) => limit === undefined
+        ? [...qk.build(spaceId, id), "logs"]
+        : [...qk.build(spaceId, id), "logs", limit],
     spaceBuilds: (id) => ["spaces", id, "builds"],
     spaceRepositoryConnection: (id, connectionType = "connected") => ["spaces", id, "repository-connection", connectionType],
-    repositoryInstallations: (spaceId) => ["repository-connections", "installations", spaceId],
+    repositoryInstallations: (spaceId) => [...qk.space(spaceId), "repository-installations"],
     repositoryInstallationRepositories: (installationId) => ["repository-connections", "installations", installationId, "repositories"],
     spaceRepositoryAnalyze: (id, connectionType = "connected", ref = "", root = "") => ["spaces", id, "repository-connection", connectionType, "analyze", ref, root],
     spaceRepositoryWebhookDeliveries: (id, connectionType = "connected") => ["spaces", id, "repository-webhook-deliveries", connectionType],
@@ -66,10 +65,10 @@ export const qk = {
     webhookDeliveries: (webhookId) => ["webhooks", webhookId, "deliveries"],
     spaceVersion: (id, versionId) => ["spaces", id, "versions", versionId],
     // Calling with no status yields the bare prefix, for invalidating every
-    // status-scoped annotations list at once.
-    spaceVersionAnnotations: (id, versionId, status) => status === undefined
-        ? ["spaces", id, "versions", versionId, "annotations"]
-        : ["spaces", id, "versions", versionId, "annotations", status],
+    // status-scoped version comment list at once.
+    spaceVersionComments: (id, versionId, status) => status === undefined
+        ? ["spaces", id, "versions", versionId, "comments"]
+        : ["spaces", id, "versions", versionId, "comments", status],
     spaceVersionFiles: (id, versionId) => ["spaces", id, "versions", versionId, "files"],
     spaceVersionFile: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path],
     spaceVersionFileDirectUrl: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "direct-url"],
@@ -82,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/source-archive-policy.d.ts

@@ -0,0 +1,2 @@
+export declare const SOURCE_ARCHIVE_MAX_EXPANSION_RATIO = 200;
+export declare const SOURCE_ARCHIVE_EXPANSION_RATIO_FLOOR_BYTES: number;

package/dist/utils/source-archive-policy.js

@@ -0,0 +1,2 @@
+export const SOURCE_ARCHIVE_MAX_EXPANSION_RATIO = 200;
+export const SOURCE_ARCHIVE_EXPANSION_RATIO_FLOOR_BYTES = 8 * 1024 * 1024;

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.fixtures.json

@@ -0,0 +1,57 @@
+{
+    "phpLike": [
+        { "path": "index.php", "expected": true },
+        { "path": "nested/app.phtml", "expected": true },
+        { "path": "lib.phar", "expected": true },
+        { "path": "legacy.php5", "expected": true },
+        { "path": "index.html", "expected": false },
+        { "path": "assets/main.js", "expected": false },
+        { "path": ".env", "expected": false }
+    ],
+    "immutable": [
+        { "path": "_next/static/chunks/main-app-4A_iFExJ.js", "expected": true },
+        { "path": "_next/static/chunks/framework-2c1d4f8a.js", "expected": true },
+        { "path": "_next/static/chunks/pages/index-a1b2c3d4e5f6.js", "expected": true },
+        { "path": "_next/static/chunks/oton0Guf.js", "expected": true },
+        { "path": "_next/static/css/app.plainname.css", "expected": true },
+        { "path": "/_next/static/chunks/oton0Guf.js", "expected": true },
+        { "path": "_app/immutable/entry/start.DYyuCeEr.js", "expected": true },
+        { "path": "_nuxt/index.oton0Guf.js", "expected": true },
+        { "path": "_astro/about.DYyuCeEr.css", "expected": true },
+        { "path": "_next/static/index.html", "expected": false },
+        { "path": "_next/static/sitemap.xml", "expected": false },
+        { "path": "_app/immutable/manifest.txt", "expected": false },
+        { "path": "_nextish/chunks/oton0Guf.js", "expected": false },
+        { "path": "nested/_next/static/chunks/oton0Guf.js", "expected": false },
+        { "path": "assets/index-BzeDGMM3.js", "expected": false },
+        { "path": "assets/auth-client-P1Tx-Cyu.js", "expected": false },
+        { "path": "assets/index-DYyuCeEr.js", "expected": false },
+        { "path": "assets/index-9f8e7d6c.js", "expected": false },
+        { "path": "assets/D3GeoMap.js", "expected": false },
+        { "path": "assets/index.js", "expected": false },
+        { "path": "assets/client-widget.js", "expected": false },
+        { "path": "app.1a2b3c4d.css", "expected": false },
+        { "path": "vendor.3f9a2b7e.js", "expected": false },
+        { "path": "static/js/main.d41d8cd98f00b204e9800998.js", "expected": false },
+        { "path": "index.html", "expected": false },
+        { "path": "robots.txt", "expected": false },
+        { "path": "config.xml", "expected": false },
+        { "path": "page.php", "expected": false },
+        { "path": "MyComponent.js", "expected": false },
+        { "path": "image01.png", "expected": false }
+    ],
+    "safeContentType": [
+        {
+            "path": "index.php",
+            "mime": "application/x-httpd-php",
+            "expected": "text/plain; charset=utf-8"
+        },
+        { "path": "lib.phar", "mime": "application/zip", "expected": "application/octet-stream" },
+        {
+            "path": "assets/main.js",
+            "mime": "text/javascript; charset=utf-8",
+            "expected": "text/javascript; charset=utf-8"
+        },
+        { "path": "logo.svg", "mime": "image/svg+xml", "expected": "image/svg+xml" }
+    ]
+}

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 routing 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.11",
+  "version": "0.0.13",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -91,8 +91,10 @@
     }
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.101.1",
-    "smol-toml": "^1.6.1",
-    "zod": "^4.3.6"
+    "@tanstack/react-query": "^5.101.4",
+    "culori": "^4.0.2",
+    "js-yaml": "^4.1.1",
+    "smol-toml": "^1.7.0",
+    "zod": "^4.4.3"
   }
 }