@spacefast/common 0.0.24 → 0.2.1

package/dist/utils/publish-policy.d.ts

@@ -11,20 +11,16 @@ export declare const STATIC_RUNTIME_CONTROL_PATHS: string[];
 export declare const STATIC_RUNTIME_CONTROL_PREFIXES: string[];
 export declare function normalizePublishPath(relativePath: string): string;
 /**
- * The one subtree inside the runtime control prefix that a publish may write.
+ * The one subtree inside the runtime control prefix a publish may write, so a
+ * compiled worker bundle travels the ordinary manifest and upload path while
+ * staying unservable as static content.
  *
- * `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.
+ * Scoped to `bundles/`, not the whole `__spacefast/functions/` directory: the
+ * sibling `config.json` holds the key its signatures are minted with.
  */
 export declare const PUBLISHABLE_BUILD_ARTIFACT_PREFIX = "__spacefast/functions/bundles/";
+/** The same carve-out for the Next-cache seed document. */
+export declare const PUBLISHABLE_SEED_ARTIFACT_PREFIX = "__spacefast/functions/seeds/";
 export declare function publishPathIgnored(relativePath: string): boolean;
 export declare function publishPathIsConvention(relativePath: string): boolean;
 export declare function providerRuntimeFeatureWarnings(paths: readonly string[]): PublishManifestWarning[];
@@ -89,12 +85,10 @@ export type PublishRouteOwnership = {
  */
 export declare function canonicalizePublishRequestedRoute(route: string): string;
 /**
- * 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.
+ * Expands artifact paths into the request routes they can serve: literal
+ * files, directory indexes and clean `.html` aliases. Two artifacts owning one
+ * route is rejected at publish rather than left to lookup order.
+ * `routeOwnership` restates the expansion in canonical access-route form.
  */
 export declare function analyzePublishRoutes(paths: readonly string[], options?: {
     index?: string | false;

package/dist/utils/publish-policy.fixtures.json

@@ -146,6 +146,16 @@
         "path": "__spacefast/functions/bundlesX/evil.json",
         "expected": "static_runtime_control_path_not_supported"
     },
+    {
+        "path": "__spacefast/functions/seeds/abc123/seed.json",
+        "expected": null,
+        "why": "the Next-cache seed document, the bundle carve-out's sibling"
+    },
+    {
+        "path": "__spacefast/functions/seeds.json",
+        "expected": "static_runtime_control_path_not_supported",
+        "why": "the carve-out is the seeds/ prefix, not anything starting with seeds"
+    },
     {
         "path": "__spacefast/zero/deploy.json",
         "expected": null,
@@ -201,10 +211,6 @@
         "path": "engine-manifest.json",
         "expected": "static_runtime_control_path_not_supported"
     },
-    {
-        "path": "entrypoint-shim.php",
-        "expected": "static_runtime_control_path_not_supported"
-    },
     {
         "path": "nested/custom-redirects.php",
         "expected": null,
@@ -213,7 +219,7 @@
     {
         "path": "init.php",
         "expected": null,
-        "why": "engine/init.php installs under .stattic/engine/, not the docroot"
+        "why": "engine/init.php installs inside an immutable release, not the docroot"
     },
     {
         "path": ".spacefast/storage/routes/current.php",

package/dist/utils/publish-policy.js

@@ -2,21 +2,17 @@ import { BRAND } from "../brand.js";
 import { WORST_CASE_QUOTAS } from "../contracts/quotas.js";
 import { SPACE_CONFIG_PRIVATE_FILES } from "../contracts/space-config.js";
 import { ZERO_RUNTIME_DEPLOY_PATH } from "../contracts/zero.js";
-// The ONE static publish policy (internal-docs/platform.md "Upload Contract"):
-// path denials, manifest scale caps, plan caps, duplicate detection, and the
-// free-plan content rules live here. Consumed by API manifest validation, CLI
-// local preflight, inline archive extraction, and the runtime parity fixtures
-// (the PHP twin is runtime/engine/admin/upload-policy.php).
+// The ONE static publish policy (spec "Upload Contract"), shared by API
+// manifest validation, CLI preflight and archive extraction. The PHP twin is
+// runtime/engine/admin/upload-policy.php.
 import { canonicalizeVersionPath, normalizeVersionPath } from "./version-path.js";
-// Manifest scale caps (spec "Upload Contract"): the hard contract ceiling is
-// 100,000 files per version; plan policy may LOWER it (Free 20,000), never
-// raise it. Canonical paths cap at 1,024 bytes; manifest request bodies at
-// 16 MB, enforced fail-early before any upload session exists.
+// Manifest scale caps (spec "Upload Contract"). Plan policy may LOWER the
+// file-count ceiling (Free 20,000), never raise it. All are enforced before
+// any upload session exists.
 export const MANIFEST_MAX_FILES_CEILING = 100_000;
 export const MANIFEST_MAX_PATH_BYTES = 1024;
 export const MANIFEST_MAX_BODY_BYTES = 16 * 1024 * 1024;
 export const MAX_VERSION_FILE_SIZE_BYTES = 64 * 1024 * 1024;
-// Worst-case artifact ceiling lives in the named raise-only quota table.
 export const MAX_VERSION_TOTAL_BYTES = WORST_CASE_QUOTAS.maxArtifactBytes;
 const IGNORED_EXACT_PATHS = new Set([
     ".DS_Store",
@@ -28,8 +24,7 @@ const IGNORED_EXACT_PATHS = new Set([
     ".env.test",
     ".npmrc",
     ".netrc",
-    // CLI checkout state (current dir name plus the legacy pre-rename one —
-    // user archives may contain either; both stay out of every publish).
+    // CLI checkout state. Both spellings appear in user archives.
     ".spacefast/state.json",
     ".stattic/state.json",
     "_routes.json",
@@ -57,33 +52,22 @@ const SENSITIVE_FILE_PATTERNS = [
 // Denied runtime private/control paths (spec "Static path policy").
 // Every list below is generated verbatim into runtime/engine/admin/upload-policy.php
 // by apps/control-plane/src/scripts/codegen-php-policy.ts, so the two enforcers
-// cannot hold different literals. Lowercase only — both sides fold the path first.
+// cannot hold different literals. Lowercase only; both sides fold the path first.
 export const STATIC_EXECUTION_CONTROL_FILES = [".htaccess", ".user.ini"];
-// Reserved runtime namespace segments are matched by PREFIX: the runtime owns
-// `/__spacefast/*` plus `__spacefast_generated/`, and the `__stattic` spelling
-// (`/__stattic_probe` today, more `/__stattic/*` routes planned) stays
-// reserved the same way. Mid-segment occurrences are ordinary content.
+// Matched by PREFIX, so the runtime owns `__spacefast_generated/` as well as
+// `/__spacefast/*`. Mid-segment occurrences are ordinary content.
 export const STATIC_RUNTIME_CONTROL_SEGMENT_PREFIXES = ["__spacefast", "__stattic"];
-// Reserved as WHOLE root segments. In runtime/engine/shared/context.php the
-// control table gives `/__sf` and `/__span` `match => 'namespace', fold => true`
-// rows, and `_stattic_control_path_row()` reads `namespace` as `=== '/__sf' ||
-// starts_with('/__sf/')`, so `/__sfx/...` and `/__spanish/page` are ordinary
-// tenant paths. Reserving more than the front door claims would refuse a publish
-// of content the front door then happily serves as tenant content.
+// Reserved as WHOLE root segments, so `/__sfx/...` and `/__spanish/page` are
+// ordinary tenant paths. Reserving more than the front door claims would refuse
+// a publish of content the front door then serves anyway.
 //
-// This is a SUBSET of what the control table reserves, not a mirror of it: the
-// table also reserves the nested exact path `/__/collab` (the review link),
-// while the `/__/` prefix around it is tenant-publishable. Publish deliberately
-// does not claim that one — the reservation that matters is enforced at request
-// time, where serve.php refuses to let either a published file or a routing rule
-// answer a reserved route, and that refusal is what runtime/tests/collab-frame.test.ts
-// exercises by publishing a file at `__/collab` on purpose. The control table is
-// the authority; this list is a publish-time convenience, so keep it a subset
-// and never let it contradict the table.
+// A SUBSET of what the control table in runtime/engine/shared/context.php
+// reserves, never a mirror: the table also reserves `/__/collab`, enforced at
+// request time by serve.php. The table is the authority; keep this list a
+// subset of it.
 export const STATIC_RUNTIME_ROOT_SEGMENTS = ["__sf", "__span"];
-// 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.
+// Both spellings stay denied: spaces published before the `.stattic` →
+// `.spacefast` rename still serve from the legacy on-disk layout.
 export const STATIC_RUNTIME_CONTROL_PATHS = [
     ".well-known/spacefast-runtime",
     ".well-known/stattic-runtime",
@@ -98,43 +82,34 @@ export function normalizePublishPath(relativePath) {
     return relativePath.replace(/\\/g, "/").replace(/^\/+/g, "");
 }
 /**
- * The one subtree inside the runtime control prefix that a publish may write.
+ * The one subtree inside the runtime control prefix a publish may write, so a
+ * compiled worker bundle travels the ordinary manifest and upload path while
+ * staying unservable as static content.
  *
- * `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.
+ * Scoped to `bundles/`, not the whole `__spacefast/functions/` directory: the
+ * sibling `config.json` holds the key its signatures are minted with.
  */
 export const PUBLISHABLE_BUILD_ARTIFACT_PREFIX = "__spacefast/functions/bundles/";
+/** The same carve-out for the Next-cache seed document. */
+export const PUBLISHABLE_SEED_ARTIFACT_PREFIX = "__spacefast/functions/seeds/";
 /**
- * The one FILE inside the control prefix a publish may write.
- *
- * A Zero capsule's compiled server travels as version metadata, not content, so
- * a server-only change ships a byte-identical app shell and the version intent's
- * manifest comparison reads it as "no changes". `sf publish` writes the deploy's
- * digest here so the manifest moves whenever the deploy does — same reasoning as
- * the Functions bundle above, same channel.
- *
- * One exact path, not a prefix: its siblings under `__spacefast/zero/` are the
- * runtime's own artifact, config and binary, and a publish that could overwrite
- * those would be a publish that could replace the runtime.
+ * ZERO_RUNTIME_DEPLOY_PATH is the one FILE a publish may write inside the
+ * control prefix. A Zero capsule's server travels as version metadata, so a
+ * server-only change would otherwise ship a byte-identical shell that the
+ * manifest comparison reads as "no changes"; the deploy digest moves it. One
+ * exact path, not a prefix: its siblings under `__spacefast/zero/` are the
+ * runtime's own artifact, config and binary.
  */
 function isPublishableBuildArtifactPath(normalizedPath, lowerPath) {
     return (lowerPath.startsWith(PUBLISHABLE_BUILD_ARTIFACT_PREFIX) ||
+        lowerPath.startsWith(PUBLISHABLE_SEED_ARTIFACT_PREFIX) ||
         normalizedPath === ZERO_RUNTIME_DEPLOY_PATH);
 }
 export function publishPathIgnored(relativePath) {
     const path = normalizePublishPath(relativePath);
-    // The agent state dirs hold one secret (state.json) plus committable tooling
-    // (space.json). Drop only those files at any depth so a checkout archived one
-    // level too high never ships a claim token — but keep serving legitimate
-    // content in the same dirs (e.g. the legacy .stattic/routes.json convention).
+    // Drop these files at any depth so a checkout archived one level too high
+    // never ships a claim token, while other content in the same dirs still
+    // publishes (e.g. the legacy .stattic/routes.json convention).
     if (/(?:^|\/)\.(?:spacefast|stattic)\/(?:state|space)\.json$/.test(path) ||
         /(?:^|\/)\.spacefast-(?:[0-9a-f-]{36}\.(?:tmp|rollback|retired)|[0-9a-f]{24}\.lock)$/.test(path)) {
         return true;
@@ -151,11 +126,9 @@ export function publishPathIgnored(relativePath) {
 export function publishPathIsConvention(relativePath) {
     return RESERVED_CONVENTION_PATHS.has(normalizePublishPath(relativePath));
 }
-// Provider runtime features that have no Spacefast equivalent (spec "Routing And
-// Headers", migration diagnostics): Cloudflare Pages `_worker.js`/`_routes.json`
-// and Netlify's provider-specific function directory publish as inert content
-// with a warning so migrations are never silent. A root `functions/` directory
-// is Spacefast's own file-router convention and must never reach this warning.
+// Provider runtime features with no Spacefast equivalent publish as inert
+// content with a warning, so migrations are never silent. A root `functions/`
+// directory is Spacefast's own convention and must never reach this warning.
 function providerRuntimeFeatureForPath(path) {
     if (path === "_worker.js") {
         return "Cloudflare Pages _worker.js";
@@ -210,9 +183,8 @@ export function staticUploadPathViolation(path, options = {}) {
         return pathViolation("invalid_file_path", "File path is invalid.", rawPath);
     }
     if (normalizedPath !== rawPath) {
-        // The path the caller sent, not the normal form it missed: echoing a
-        // rewritten path suggests the rewrite was accepted, and it is the one place
-        // this policy used to report a different string than the runtime's copy.
+        // Echo the path the caller sent; a rewritten one would suggest the
+        // rewrite was accepted.
         return pathViolation("invalid_file_path", "File path is invalid.", rawPath);
     }
     if (new TextEncoder().encode(normalizedPath).length > MANIFEST_MAX_PATH_BYTES) {
@@ -280,12 +252,10 @@ export function canonicalizePublishRequestedRoute(route) {
     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.
+ * Expands artifact paths into the request routes they can serve: literal
+ * files, directory indexes and clean `.html` aliases. Two artifacts owning one
+ * route is rejected at publish rather than left to lookup order.
+ * `routeOwnership` restates the expansion in canonical access-route form.
  */
 export function analyzePublishRoutes(paths, options = {}) {
     const index = options.index === undefined ? "index.html" : options.index;
@@ -354,12 +324,10 @@ export function analyzePublishRoutes(paths, options = {}) {
 export function resolveManifestFileCap(maxFiles) {
     return Math.min(MANIFEST_MAX_FILES_CEILING, maxFiles && maxFiles > 0 ? maxFiles : MANIFEST_MAX_FILES_CEILING);
 }
-// The shared manifest validator (spec "Upload Contract"): canonicalizes every
-// path (decode-once + NFC), enforces the static path policy, the scale caps,
-// and plan caps, rejects post-canonicalization duplicates, and emits the
-// case-collision warning. Runs BEFORE any upload session is created; archive
-// extraction routes through the same checks. Returns the manifest with
-// canonical paths — callers use the returned files, never the input.
+// The shared manifest validator (spec "Upload Contract"). Runs BEFORE any
+// upload session is created; archive extraction routes through the same
+// checks. Returns canonical paths, so callers use the returned files, never
+// the input.
 export function validatePublishManifest(files, caps = {}) {
     const maxFiles = resolveManifestFileCap(caps.maxFiles);
     if (files.length > maxFiles) {
@@ -416,15 +384,13 @@ export function validatePublishManifest(files, caps = {}) {
                 warnings: [],
             };
         }
-        // Checkout state and credential paths (.spacefast/, .git/, .env*, …) are
-        // silently dropped rather than rejected: agents that archive one level too
-        // high must never publish a claim token to the live site, and failing the
-        // whole manifest for it would punish the common accident.
+        // Dropped rather than rejected: failing a whole manifest over a stray
+        // .env or .spacefast/ would punish the common accident.
         if (publishPathIgnored(canonicalPath)) {
             continue;
         }
-        // Case-only-differing paths are distinct (paths are byte-exact and
-        // case-sensitive) but cannot round-trip case-insensitive filesystems.
+        // Distinct paths here, but they cannot round-trip a case-insensitive
+        // filesystem.
         const lowercase = canonicalPath.toLowerCase();
         const caseSibling = lowercasePaths.get(lowercase);
         if (caseSibling !== undefined && caseSibling !== canonicalPath) {
@@ -486,8 +452,7 @@ const FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS = new Set([
     ".txt",
     ".md",
     ".csv",
-    // Opaque static payloads used by migration fixtures and served as
-    // application/octet-stream by the runtime.
+    // Migration fixtures, served as application/octet-stream.
     ".customtype",
     ".xml",
     ".svg",
@@ -503,13 +468,10 @@ const FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS = new Set([
     ".ttf",
     ".otf",
 ]);
-// THE anonymous content enforcement (accept-and-scan posture): uploads are
-// accepted like any free publish, but until the space is claimed the runtime
-// only serves these content types, pushed as the generic route-config
-// `content_types` allowlist (exact types or `prefix/*` wildcards; the engine
-// enforces the list without knowing it means "anonymous"). Web-page content
-// only — no opaque octet-streams, archives (except scanned gzip, which
-// pagefind search indexes depend on), documents, or media containers.
+// THE anonymous content enforcement: uploads are accepted like any free
+// publish, but until the space is claimed the runtime serves only these types,
+// pushed as the route-config `content_types` allowlist. Web-page content only.
+// Gzip is the one archive, because pagefind search indexes need it.
 export const ANONYMOUS_SERVE_CONTENT_TYPES = [
     "text/*",
     "image/*",
@@ -534,20 +496,14 @@ function freePlanDeniedExecutablePath(filePath) {
         .split("/")
         .some((segment) => segment === "bin");
 }
-// Acceptance is deliberately identical for claimed-free and unclaimed
-// anonymous spaces (accept-and-scan posture): rejecting file types at upload
-// adds no safety — the bytes reach us before any scan either way — so
-// publishes are accepted, every file goes through the scan pipeline, and the
-// SERVE-time content-type allowlist (ANONYMOUS_SERVE_CONTENT_TYPES via the
-// route-config `content_types` policy) is what keeps opaque binaries dark
-// until the space is claimed.
+// Acceptance is deliberately identical for claimed-free and unclaimed spaces:
+// rejecting types at upload adds no safety, since the bytes reach us before
+// any scan either way. ANONYMOUS_SERVE_CONTENT_TYPES is what keeps opaque
+// binaries dark until the space is claimed.
 export function freePlanCanUploadPath(filePath, options) {
     const path = normalizePublishPath(filePath);
-    // Root Spacefast config files are platform machinery, not user content (spec "Space
-    // Configuration Files": ships in the manifest, same lifecycle as
-    // `_redirects`/`_headers`) — the plan's content-extension gate must never
-    // eat it (e2e checkpoint 4: it was silently dropped on free publishes,
-    // disabling fallback/meta/templates/theme for every free space).
+    // Platform machinery, not user content: same lifecycle as
+    // `_redirects`/`_headers`, so the content-extension gate must never eat them.
     if (SPACE_CONFIG_PRIVATE_FILES.includes(path)) {
         return true;
     }
@@ -571,8 +527,7 @@ export function freePlanCanUploadContentType(contentType) {
         normalized === "application/javascript" ||
         normalized === "application/json" ||
         normalized === "application/manifest+json" ||
-        // Gzip stays allowed for anonymous spaces too: pagefind search indexes
-        // ship as gzip fragments, and ClamAV decompresses gzip when scanning.
+        // pagefind ships gzip fragments, and ClamAV decompresses gzip when scanning.
         normalized === "application/gzip" ||
         normalized === "image/svg+xml" ||
         normalized === "application/xml" ||

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

@@ -4,4 +4,6 @@ export type ApiErrorLike = {
 };
 export declare function createSpacefastQueryClient(options?: {
     isClientError?: (error: unknown) => error is ApiErrorLike;
+    /** Default freshness window for every query, in milliseconds. */
+    staleTime?: number;
 }): QueryClient;

package/dist/utils/query-client.js

@@ -1,4 +1,13 @@
 import { QueryClient } from "@tanstack/react-query";
+/**
+ * Freshness for a caller that has not adopted a tiered caching policy.
+ *
+ * The tiers themselves (`STALE_TIME_MS`) live in `@spacefast/sdk/query`, which
+ * depends on this package — so they cannot be imported here and arrive as an
+ * argument instead. The dashboard passes `STALE_TIME_MS.normal`; superadmin
+ * still runs on this default.
+ */
+const UNTIERED_STALE_TIME_MS = 60_000;
 export function createSpacefastQueryClient(options) {
     return new QueryClient({
         defaultOptions: {
@@ -12,7 +21,7 @@ export function createSpacefastQueryClient(options) {
                     }
                     return failureCount < 2;
                 },
-                staleTime: 60_000,
+                staleTime: options?.staleTime ?? UNTIERED_STALE_TIME_MS,
                 refetchOnWindowFocus: true,
                 refetchOnReconnect: true,
             },

package/dist/utils/runtime-paths.d.ts

@@ -2,13 +2,13 @@ export declare const SPACEFAST_RUNTIME_NAMESPACE: "/__spacefast";
 export declare const RUNTIME_MANAGEMENT_API_PATH: "/__spacefast/api.php";
 export declare const RUNTIME_UPLOAD_API_PATH: "/__spacefast/upload.php";
 export declare const RUNTIME_HEALTH_PATH: "/__spacefast/health.php";
+export declare const RUNTIME_CONTENT_API_PATH: "/__spacefast/content.php";
 export declare const RUNTIME_COMMENTS_CONFIG_PATH: "/__spacefast/comments/config";
 export declare const RUNTIME_COMMENTS_TICKET_PATH: "/__spacefast/comments/ticket";
 export declare const RUNTIME_COMMENTS_VERSION_URLS_PATH: "/__spacefast/comments/version-urls";
-/** The review workspace the orb expands into — a reserved control path on the
- *  Space's own origin (collab-frame-plan §4), not part of the `/__spacefast`
- *  exchange namespace because people paste this one into Slack.
- *  The PHP mirror is SPACEFAST_COLLAB_FRAME_PATH in runtime/engine/shared/context.php. */
+/** The review workspace, on the Space's own origin and outside the
+ *  `/__spacefast` exchange namespace because people paste it into Slack.
+ *  The PHP mirror is SPACEFAST_COLLAB_FRAME_PATH in shared/context.php. */
 export declare const RUNTIME_COLLAB_FRAME_PATH: "/__/collab";
 export declare function runtimeManagementPath(suffix: string): string;
 export declare function runtimeUploadPath(params: URLSearchParams | Record<string, string>): string;

package/dist/utils/runtime-paths.js

@@ -2,17 +2,15 @@ export const SPACEFAST_RUNTIME_NAMESPACE = "/__spacefast";
 export const RUNTIME_MANAGEMENT_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/api.php`;
 export const RUNTIME_UPLOAD_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/upload.php`;
 export const RUNTIME_HEALTH_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/health.php`;
-// Same-origin Comments exchange paths served on every published host. The PHP
-// mirror is SPACEFAST_COMMENTS_*_PATH in runtime/engine/shared/context.php;
-// runtime/tests/spacefast-sdk.test.ts pins the PHP side and
-// packages/collab-sdk/test/entry.test.ts pins the SDK side to these literals.
+export const RUNTIME_CONTENT_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/content.php`;
+// Same-origin Comments exchange paths. The PHP mirror is
+// SPACEFAST_COMMENTS_*_PATH in runtime/engine/shared/context.php.
 export const RUNTIME_COMMENTS_CONFIG_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/config`;
 export const RUNTIME_COMMENTS_TICKET_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/ticket`;
 export const RUNTIME_COMMENTS_VERSION_URLS_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/version-urls`;
-/** The review workspace the orb expands into — a reserved control path on the
- *  Space's own origin (collab-frame-plan §4), not part of the `/__spacefast`
- *  exchange namespace because people paste this one into Slack.
- *  The PHP mirror is SPACEFAST_COLLAB_FRAME_PATH in runtime/engine/shared/context.php. */
+/** The review workspace, on the Space's own origin and outside the
+ *  `/__spacefast` exchange namespace because people paste it into Slack.
+ *  The PHP mirror is SPACEFAST_COLLAB_FRAME_PATH in shared/context.php. */
 export const RUNTIME_COLLAB_FRAME_PATH = "/__/collab";
 export function runtimeManagementPath(suffix) {
     const route = normalizeRuntimeRoute(suffix);

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

@@ -4,6 +4,15 @@ export declare function runtimeUploadFetchUrl(input: {
     uploadId: string;
     path: string;
 }): string;
+export declare function runtimeUploadFileUrl(input: {
+    baseUrl: string;
+    uploadId: string;
+    path: string;
+}): string;
+export declare function runtimeUploadBlobsHaveUrl(input: {
+    baseUrl: string;
+    spaceId: string;
+}): string;
 export declare function runtimeUploadBlobUrl(input: {
     baseUrl: string;
     spaceId: string;

package/dist/utils/runtime-upload.js

@@ -15,6 +15,18 @@ export function runtimeUploadFetchUrl(input) {
         path: runtimeUploadCanonicalPath(input.path),
     }), input.baseUrl).toString();
 }
+export function runtimeUploadFileUrl(input) {
+    return new URL(runtimeUploadPath({
+        op: "file",
+        upload_id: input.uploadId,
+        path: runtimeUploadCanonicalPath(input.path),
+    }), input.baseUrl).toString();
+}
+export function runtimeUploadBlobsHaveUrl(input) {
+    return new URL(runtimeUploadPath({
+        route: `/spaces/${encodeURIComponent(input.spaceId)}/blobs/have`,
+    }), input.baseUrl).toString();
+}
 export function runtimeUploadBlobUrl(input) {
     return new URL(runtimeUploadPath({
         route: `/spaces/${encodeURIComponent(input.spaceId)}/blobs/${encodeURIComponent(input.sha256)}`,

package/dist/utils/secure-local-file.d.ts

@@ -51,9 +51,9 @@ export declare function secureOutputLocation(trustedPath: string, outputPath: st
 };
 /**
  * Writes beneath an explicitly trusted root without following output-tree
- * symlinks. Linux uses descriptor-relative operations; other supported
- * platforms use exclusive staging plus before-and-after ancestor identity
- * validation and fail closed if any binding changes.
+ * symlinks. Linux uses descriptor-relative operations; other platforms use
+ * exclusive staging plus before-and-after ancestor identity validation, and
+ * fail closed if any binding changes.
  */
 export declare function secureWriteFile(options: SecureWriteOptions): Promise<void>;
 export declare function secureReadFile(options: SecureReadOptions & {