@spacefast/common 0.0.26 → 0.2.1

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 (the platform spec "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,39 +82,23 @@ 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 bundle carve-out's sibling for the Next-cache seed document: the same
- * reasoning (travel through the ordinary manifest and upload path, stay
- * unservable by default), the same deliberate narrowness (a prefix of its
- * own, never the whole `functions/` directory — see the bundle comment).
- */
+/** 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) ||
@@ -139,10 +107,9 @@ function isPublishableBuildArtifactPath(normalizedPath, lowerPath) {
 }
 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;
@@ -159,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";
@@ -218,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) {
@@ -288,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;
@@ -362,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) {
@@ -424,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) {
@@ -494,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",
@@ -511,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/*",
@@ -542,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;
     }
@@ -579,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

@@ -9,6 +9,10 @@ export declare function runtimeUploadFileUrl(input: {
     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

@@ -22,6 +22,11 @@ export function runtimeUploadFileUrl(input) {
         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 & {

package/dist/utils/secure-local-file.js

@@ -236,10 +236,9 @@ async function canonicalPortableWriteRoot(rootInput) {
 async function openPortableChildDirectory(identities, visibleParent, component, create) {
     assertSafeComponent(component);
     const childPath = path.join(visibleParent, component);
-    // A missing directory is the normal "file not found" result for secure
-    // reads. Probe before identity capture so callers can handle ENOENT. If the
-    // directory disappears after this probe, visibleDirectoryIdentity still
-    // fails closed because an observed ancestor binding changed mid-read.
+    // A missing directory is the normal "file not found" for secure reads, so
+    // probe before identity capture. A later disappearance still fails closed in
+    // visibleDirectoryIdentity.
     if (!create) {
         await lstat(childPath);
     }
@@ -465,8 +464,7 @@ async function unlinkOwnedLeafLockArtifact(lockPath, artifactPath, nonce) {
         return;
     }
     // The pathname changed after its owner was inspected. Restore the exact inode
-    // when the name is still free; if another lock is already visible, keep this
-    // one displaced so contenders detect it instead of deleting a fresh owner.
+    // when the name is free; otherwise keep it displaced so contenders detect it.
     let restored = false;
     try {
         await link(retiredPath, artifactPath);
@@ -544,14 +542,12 @@ async function acquireLeafLock(lockPath, temporaryPath) {
                 if (released)
                     return;
                 released = true;
-                // Move the canonical name into unique cleanup custody while its inode
-                // is still active. Once that atomic rename happens a new owner may
-                // publish, but cleanup only ever unlinks the retired name it inspected.
+                // Move the canonical name into unique custody while its inode is still
+                // active; cleanup only ever unlinks the retired name it inspected.
                 await unlinkOwnedLeafLockArtifact(lockPath, lockPath, owner.nonce).catch(() => undefined);
                 try {
-                    // A delayed stale reclaimer may already hold this inode at a displaced
-                    // name. Mark it complete through the handle so that artifact can be
-                    // reclaimed even though this process remains alive.
+                    // A delayed stale reclaimer may hold this inode at a displaced name.
+                    // Mark it complete through the handle so it can still be reclaimed.
                     const releasedWrite = await acquiredHandle.write(Buffer.from("R"), 0, 1, 0);
                     if (releasedWrite.bytesWritten === 1)
                         await acquiredHandle.sync();
@@ -598,16 +594,15 @@ async function acquireLeafLock(lockPath, temporaryPath) {
         }
         const displaced = await readLeafLockRecord(displacedPath);
         if (!(await leafLockRecordIsStale(displaced))) {
-            // A fresh owner won between our stale read and rename. Put its exact inode
-            // back when possible; every contender also scans displaced names before
-            // entering, so a live writer is never silently unlocked.
+            // A fresh owner won between our stale read and rename. Put its exact
+            // inode back; contenders scan displaced names before entering, so a live
+            // writer is never silently unlocked.
             try {
                 await link(displacedPath, lockPath);
             }
             catch (error) {
                 if (isMissing(error)) {
-                    // Its owner completed cleanup while we inspected the displaced inode.
-                    // Nothing remains to restore; compete again for the now-current name.
+                    // Its owner finished cleanup; compete again for the current name.
                     await delay(LEAF_LOCK_RETRY_DELAY_MS);
                     continue;
                 }
@@ -857,10 +852,9 @@ async function commitPortableStagedFile(input) {
     }
 }
 async function secureWriteFilePortable(options) {
-    // The caller explicitly trusts the root. Canonicalize that boundary once so
-    // supported system aliases such as macOS `/var -> /private/var` do not look
-    // like attacker-controlled children; every path below it is still walked
-    // component-by-component without following symlinks.
+    // Canonicalize the trusted root once so system aliases like macOS
+    // `/var -> /private/var` don't look like attacker-controlled children.
+    // Everything below it is still walked without following symlinks.
     const root = await canonicalPortableWriteRoot(options.root);
     const relativePath = validateRelativePath(options.relativePath, "write");
     const components = relativePath.split(path.sep);
@@ -923,9 +917,9 @@ async function secureWriteFilePortable(options) {
 }
 /**
  * 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 async function secureWriteFile(options) {
     if ((options.data === undefined) === (options.write === undefined)) {

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

@@ -16,18 +16,15 @@ type SpaceConfigBlockingIssue = SpaceConfigIssue & {
     code: SpaceConfigBlockingIssueCode;
 };
 /**
- * Keys a committed `sf.jsonc` owns outright: they are facts about the content
- * of a version (who may read it, what it is called, what runs it), so they roll
- * forward and back with the version instead of living in the space's mutable
- * overlay. API intake refuses them rather than storing or dropping them.
+ * Keys a committed `sf.jsonc` owns outright. They are facts about a version's
+ * content, so they roll forward and back with it instead of living in the
+ * space's mutable overlay. API intake refuses them.
  */
-export declare const SPACE_CONFIG_FILE_ONLY_KEYS: readonly ["access", "name", "runtime"];
+export declare const SPACE_CONFIG_FILE_ONLY_KEYS: readonly ["access", "name", "runtime", "system"];
 /**
- * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): file-only keys, the 16 KB compiled-overlay cap, plus the shared
- * shape caps. Returns the first blocking issue, or null when the overlay is
- * acceptable. Takes the raw request value, because the overlay schema strips
- * file-only keys and this is what has to see them.
+ * Validates a space `config` overlay at API intake, returning the first
+ * blocking issue or null. Takes the RAW request value: the overlay schema
+ * strips file-only keys, and this is what has to see them.
  */
 export declare function spaceConfigOverlayIssue(config: unknown): SpaceConfigBlockingIssue | null;
 export declare function stripJsonComments(raw: string): string;
@@ -37,16 +34,16 @@ export type ResolvedServingConfig = {
         path: string;
         status: 200 | 404;
     } | null;
-    /** W7.1 clean URLs: serve flat `<name>.html` at its extensionless URL. */
+    /** Serve flat `<name>.html` at its extensionless URL. */
     cleanUrls: boolean;
     listing: boolean;
     viewer: boolean;
     meta: NonNullable<SpaceConfig["meta"]> | null;
-    /** Theme tokens for every Spacefast-authored page; null when unset. */
+    /** Theme tokens for every Spacefast-authored page. */
     pageTheme: NonNullable<SpaceConfig["theme"]> | null;
-    /** Hidden experimental build-pipeline flag; false keeps today's behavior. */
+    /** Hidden experimental build-pipeline flag. */
     experimentalGutenberg: boolean;
-    /** Resolved inject snippets; only honored when experimentalGutenberg is true. */
+    /** Only honored when experimentalGutenberg is true. */
     inject: NonNullable<SpaceConfig["inject"]> | null;
 };
 export type SpaceSettingsPatch = {

package/dist/utils/space-config.js

@@ -42,9 +42,7 @@ function capIssues(candidate) {
             details: { count: templates.length, limit: SPACE_CONFIG_CAPS.templates },
         });
     }
-    // inject snippets (hidden feature, honored only with experimental_gutenberg):
-    // shape and byte caps fail with the stable codes here, before zod, so intake
-    // reports inject_invalid / inject_snippet_too_large instead of shape errors.
+    // inject is a hidden feature, honored only with experimental_gutenberg.
     const inject = candidate.inject;
     if (inject !== undefined) {
         if (typeof inject !== "object" || inject === null || Array.isArray(inject)) {
@@ -126,18 +124,15 @@ function capIssues(candidate) {
     return issues;
 }
 /**
- * Keys a committed `sf.jsonc` owns outright: they are facts about the content
- * of a version (who may read it, what it is called, what runs it), so they roll
- * forward and back with the version instead of living in the space's mutable
- * overlay. API intake refuses them rather than storing or dropping them.
+ * Keys a committed `sf.jsonc` owns outright. They are facts about a version's
+ * content, so they roll forward and back with it instead of living in the
+ * space's mutable overlay. API intake refuses them.
  */
-export const SPACE_CONFIG_FILE_ONLY_KEYS = ["access", "name", "runtime"];
+export const SPACE_CONFIG_FILE_ONLY_KEYS = ["access", "name", "runtime", "system"];
 /**
- * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): file-only keys, the 16 KB compiled-overlay cap, plus the shared
- * shape caps. Returns the first blocking issue, or null when the overlay is
- * acceptable. Takes the raw request value, because the overlay schema strips
- * file-only keys and this is what has to see them.
+ * Validates a space `config` overlay at API intake, returning the first
+ * blocking issue or null. Takes the RAW request value: the overlay schema
+ * strips file-only keys, and this is what has to see them.
  */
 export function spaceConfigOverlayIssue(config) {
     if (config === null || config === undefined || typeof config !== "object") {
@@ -166,9 +161,8 @@ export function spaceConfigOverlayIssue(config) {
     }
     return capIssues(config)[0] ?? null;
 }
-// Strips JSONC comments and trailing commas (string-aware single pass). The
-// config file itself is parsed by the crate; this stays for the OTHER JSONC
-// files the CLI reads (agent configs, exported platform env).
+// The config file itself is parsed by the crate; this stays for the OTHER
+// JSONC files the CLI reads (agent configs, exported platform env).
 export function stripJsonComments(raw) {
     let output = "";
     let inString = false;