@spacefast/common 0.0.12 → 0.0.17

package/dist/utils/content-type.d.ts

@@ -2,9 +2,9 @@
  * Map a file extension to a Content-Type header value. Returns
  * `application/octet-stream` when the extension is not recognized.
  *
- * This is the superset of the extensions handled by the control-plane
- * runtime service and the spacefast-cli uploader, so both sides agree on the
- * same content types when uploading and serving version files.
+ * MIME extension coverage comes from the maintained `mime` database. The
+ * small overrides above preserve intentional existing policy; this module
+ * does not carry a second partial extension registry.
  */
 export declare function contentTypeForPath(filePath: string): string;
 export declare function textTypeForPath(filePath: string): string | null;

package/dist/utils/content-type.js

@@ -1,71 +1,41 @@
+import mime from "mime";
+const CONTENT_TYPE_OVERRIDES = {
+    // Preserve the public uploader/runtime policy where the database's preferred
+    // server-oriented type differs from the established browser-facing type.
+    ".cjs": "text/javascript",
+    ".cts": "text/plain",
+    ".d.ts": "text/plain",
+    ".ico": "image/x-icon",
+    ".mts": "text/plain",
+    ".rs": "text/plain",
+    ".sh": "text/plain",
+    ".tgz": "application/gzip",
+    ".ts": "text/plain",
+};
+const UTF8_APPLICATION_TYPES = new Set([
+    "application/json",
+    "application/manifest+json",
+    "application/xml",
+]);
 /**
  * Map a file extension to a Content-Type header value. Returns
  * `application/octet-stream` when the extension is not recognized.
  *
- * This is the superset of the extensions handled by the control-plane
- * runtime service and the spacefast-cli uploader, so both sides agree on the
- * same content types when uploading and serving version files.
+ * MIME extension coverage comes from the maintained `mime` database. The
+ * small overrides above preserve intentional existing policy; this module
+ * does not carry a second partial extension registry.
  */
 export function contentTypeForPath(filePath) {
-    const extensionIndex = filePath.lastIndexOf(".");
-    const extension = extensionIndex >= 0 ? filePath.slice(extensionIndex).toLowerCase() : "";
-    switch (extension) {
-        case ".html":
-        case ".htm":
-            return "text/html; charset=utf-8";
-        case ".css":
-            return "text/css; charset=utf-8";
-        case ".js":
-        case ".mjs":
-        case ".cjs":
-            return "text/javascript; charset=utf-8";
-        case ".json":
-        case ".map":
-            return "application/json; charset=utf-8";
-        case ".webmanifest":
-            return "application/manifest+json; charset=utf-8";
-        case ".gz":
-        case ".tgz":
-            return "application/gzip";
-        case ".txt":
-        case ".sh":
-            return "text/plain; charset=utf-8";
-        case ".md":
-            return "text/markdown; charset=utf-8";
-        case ".csv":
-            return "text/csv; charset=utf-8";
-        case ".xml":
-            return "application/xml; charset=utf-8";
-        case ".svg":
-            return "image/svg+xml";
-        case ".png":
-            return "image/png";
-        case ".jpg":
-        case ".jpeg":
-            return "image/jpeg";
-        case ".gif":
-            return "image/gif";
-        case ".webp":
-            return "image/webp";
-        case ".avif":
-            return "image/avif";
-        case ".ico":
-            return "image/x-icon";
-        case ".pdf":
-            return "application/pdf";
-        case ".woff":
-            return "font/woff";
-        case ".woff2":
-            return "font/woff2";
-        case ".ttf":
-            return "font/ttf";
-        case ".otf":
-            return "font/otf";
-        case ".wasm":
-            return "application/wasm";
-        default:
-            return "application/octet-stream";
+    const normalizedPath = filePath.toLowerCase();
+    const override = Object.entries(CONTENT_TYPE_OVERRIDES).find(([suffix]) => normalizedPath.endsWith(suffix))?.[1];
+    const type = override ?? mime.getType(filePath);
+    if (!type) {
+        return "application/octet-stream";
     }
+    if (type.startsWith("text/") || UTF8_APPLICATION_TYPES.has(type)) {
+        return `${type}; charset=utf-8`;
+    }
+    return type;
 }
 function hasPrefix(bytes, prefix) {
     return prefix.every((value, index) => bytes[index] === value);
@@ -141,5 +111,12 @@ export function contentTypeForBytes(filePath, bytes) {
     if (textType && bytesLookTextual(bytes)) {
         return textType;
     }
+    // Container signatures such as ISO-BMFF, WebM, and Ogg are shared by audio
+    // and video variants. The extension is the reliable discriminator for the
+    // manifest declaration, while unknown binary extensions remain generic.
+    const pathType = contentTypeForPath(filePath);
+    if (pathType.startsWith("audio/") || pathType.startsWith("video/")) {
+        return pathType;
+    }
     return "application/octet-stream";
 }

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

@@ -16,7 +16,7 @@ export type PolicyAuthorizeInput = {
     resource: string | readonly string[];
     conditions?: RequestCondition;
 };
-export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:create" | "spaces:publish" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:create")[];
+export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:create" | "spaces:publish" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:trigger" | "builds:create")[];
 export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): ApiCredentialPolicy;
 /** Expand a named API-key preset into the finite permissions sent on the public wire contract. */
 export declare function apiKeyPresetPermissions(preset: ApiKeyPreset): StatticAction[];

package/dist/utils/credential-policy.js

@@ -8,10 +8,12 @@ export const publishActions = [
     "versions:promote",
     "versions:download",
     "builds:read",
+    "builds:trigger",
     "builds:create",
 ];
 const spaceAdminActions = [
     ...publishActions,
+    "spaces:rename",
     "spaces:delete",
     "spaces:transfer",
     "spaces:export",
@@ -81,12 +83,14 @@ export function compileTeamRolePolicy(input) {
                 "spaces:read",
                 "spaces:create",
                 "spaces:write",
+                "spaces:rename",
                 "spaces:publish",
                 "versions:read",
                 "versions:promote",
                 "versions:download",
                 "domains:read",
                 "builds:read",
+                "builds:trigger",
                 "builds:create",
                 "teams:read",
                 "billing:read",

package/dist/utils/domain-diagnostics.d.ts

@@ -1,15 +1,15 @@
 export type HostnameDiagnosticsForActions = {
     hostname: string;
-    providerIps: string[];
-    dnsInstructions: unknown[];
+    providerIps?: string[] | undefined;
+    dnsInstructions?: unknown[] | undefined;
     dns: {
         pointsToProvider: boolean;
         txtVerified: boolean | null;
         expectedTxtValue: string | null;
         records?: {
-            a: string[];
-            aaaa: string[];
-        };
+            a?: string[] | undefined;
+            aaaa?: string[] | undefined;
+        } | undefined;
     };
     ssl: {
         status: string;

package/dist/utils/domain-diagnostics.js

@@ -3,8 +3,20 @@ import { addressDnsInstructionIsObserved, addressDnsInstructionsForHostname, uns
 export function domainRequiredActions(hostnameDiagnostics) {
     const actions = [];
     for (const entry of hostnameDiagnostics) {
-        const unsupportedRecords = entry.dns.records
-            ? unsupportedAddressDnsRecordsForHostname({ ...entry, records: entry.dns.records })
+        const records = entry.dns.records
+            ? {
+                a: entry.dns.records.a ?? [],
+                aaaa: entry.dns.records.aaaa ?? [],
+            }
+            : undefined;
+        const dnsInstructions = entry.dnsInstructions ?? [];
+        const providerIps = entry.providerIps ?? [];
+        const unsupportedRecords = records
+            ? unsupportedAddressDnsRecordsForHostname({
+                hostname: entry.hostname,
+                dnsInstructions,
+                records,
+            })
             : [];
         actions.push(...unsupportedRecords.map((record) => ({
             code: "dns_unaccepted_address",
@@ -12,13 +24,12 @@ export function domainRequiredActions(hostnameDiagnostics) {
             message: `Remove the ${record.type} record on ${record.name} with value ${record.value}; it does not match a Spacefast target for this hostname.`,
         })));
         if (!entry.dns.pointsToProvider) {
-            const routingInstructions = addressDnsInstructionsForHostname(entry);
-            const observedAddressRecords = entry.dns.records;
-            const missingRoutingInstructions = observedAddressRecords
-                ? routingInstructions.filter((instruction) => !addressDnsInstructionIsObserved({
-                    instruction,
-                    records: observedAddressRecords,
-                }))
+            const routingInstructions = addressDnsInstructionsForHostname({
+                hostname: entry.hostname,
+                dnsInstructions,
+            });
+            const missingRoutingInstructions = records
+                ? routingInstructions.filter((instruction) => !addressDnsInstructionIsObserved({ instruction, records }))
                 : routingInstructions;
             if (missingRoutingInstructions.length > 0) {
                 actions.push(...missingRoutingInstructions.map((instruction) => ({
@@ -28,7 +39,7 @@ export function domainRequiredActions(hostnameDiagnostics) {
                 })));
             }
             else if (routingInstructions.length === 0) {
-                const targets = entry.providerIps.length > 0 ? entry.providerIps.join(", ") : "Spacefast";
+                const targets = providerIps.length > 0 ? providerIps.join(", ") : "Spacefast";
                 actions.push({
                     code: "dns_not_pointing",
                     hostname: entry.hostname,

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

@@ -1,5 +1,5 @@
 {
-    "comment": "Shared egress-policy corpus (spec: one proxy-egress-safety invariant). Exercised by BOTH enforcers: apps/control-plane/src/http/egress-guard.ts (control-plane SSRF guard) and runtime/engine/shared/egress.php (runtime proxy egress). Every case must produce the same verdict in TypeScript and PHP; parity is asserted by apps/control-plane/src/runtime/php-policy-parity.test.ts and src/http/egress-guard.test.ts.",
+    "comment": "Shared egress-policy corpus (spec: one proxy-egress-safety invariant). Exercised by THREE enforcers: apps/control-plane/src/http/egress-guard.ts (control-plane SSRF guard), runtime/engine/shared/egress.php (runtime proxy egress), and crates/stattic-runtime-core (Rust finalizer policy). Every case must produce the same verdict in TypeScript, PHP, and Rust; parity is asserted by apps/control-plane/src/runtime/php-policy-parity.test.ts, src/http/egress-guard.test.ts, and crates/stattic-runtime-core/src/policy.rs::proxy_destinations_match_the_shared_egress_corpus.",
     "ips": [
         { "ip": "127.0.0.1", "public": false, "reason": "loopback" },
         { "ip": "127.8.9.10", "public": false, "reason": "loopback /8" },

package/dist/utils/grants.d.ts

@@ -0,0 +1,53 @@
+import { type Grant, type GrantCapability, type GrantCheckFailure, type GrantSource } from "../contracts/grants.js";
+export type GrantPrincipal = {
+    teamIds?: readonly string[];
+    personIds?: readonly string[];
+    linkIds?: readonly string[];
+    passwordCredentialIds?: readonly string[];
+    machineIds?: readonly string[];
+    externalIdentities?: readonly {
+        issuer: string;
+        subject: string;
+    }[];
+    verifiedEmail?: boolean;
+    ipAddress?: string;
+    country?: string;
+    userAgent?: string;
+};
+export type GrantEvaluationTarget = {
+    kind: "live";
+} | {
+    kind: "version";
+    versionId: string;
+} | {
+    kind: "branch";
+    branch: string;
+};
+export type GrantEvaluationInput = {
+    grants: readonly Grant[];
+    resource: string;
+    resourceKind?: "route" | "artifact";
+    target: GrantEvaluationTarget;
+    principal?: GrantPrincipal;
+    spaceClaimed: boolean;
+    now?: Date;
+    useCounts?: Readonly<Record<string, number>>;
+    acquiredGrantIds?: readonly string[];
+};
+export type GrantMatch = {
+    grantId: string;
+    capabilities: GrantCapability[];
+    source: GrantSource;
+};
+export type GrantEvaluation = {
+    capabilities: GrantCapability[];
+    matches: GrantMatch[];
+};
+export declare function grantResourcePatternMatches(pattern: string, resource: string, resourceKind?: "route" | "artifact"): boolean;
+export type GrantEvaluationExplanation = {
+    grantId: string;
+    failures: GrantCheckFailure[];
+};
+export declare function explainGrants(input: GrantEvaluationInput): GrantEvaluationExplanation[];
+export declare function evaluateGrants(input: GrantEvaluationInput): GrantEvaluation;
+export declare function grantAllows(input: GrantEvaluationInput, capability: GrantCapability): boolean;

package/dist/utils/grants.js

@@ -0,0 +1,160 @@
+import { normalizeAccessScopePath } from "../contracts/access.js";
+import { GRANT_CAPABILITIES, grantNetworkCidrMatches, normalizeGrantResourcePattern, } from "../contracts/grants.js";
+function audienceMatches(audience, principal) {
+    switch (audience.kind) {
+        case "public":
+            return true;
+        case "team":
+            return principal.teamIds?.includes(audience.teamId) ?? false;
+        case "person":
+            return principal.personIds?.includes(audience.personId) ?? false;
+        case "link":
+            return principal.linkIds?.includes(audience.linkId) ?? false;
+        case "password":
+            return principal.passwordCredentialIds?.includes(audience.credentialId) ?? false;
+        case "machine":
+            return principal.machineIds?.includes(audience.machineId) ?? false;
+        case "external":
+            return (principal.externalIdentities?.some((identity) => identity.issuer === audience.issuer && identity.subject === audience.subject) ?? false);
+    }
+    throw new Error("Unsupported Grant audience.");
+}
+function targetMatches(selector, target) {
+    switch (selector.kind) {
+        case "live":
+            return target.kind === "live";
+        case "version":
+            return target.kind === "version" && target.versionId === selector.versionId;
+        case "branch":
+            return target.kind === "branch" && target.branch === selector.branch;
+        case "all_versions":
+            return target.kind === "version";
+    }
+    throw new Error("Unsupported Grant target.");
+}
+function normalizeGrantEvaluationResource(resource, resourceKind) {
+    if (resourceKind === "route")
+        return normalizeAccessScopePath(resource);
+    if (!resource.startsWith("/")) {
+        throw new TypeError("artifact resource must be an absolute path");
+    }
+    const canonical = normalizeGrantResourcePattern(resource);
+    if (canonical.includes("*")) {
+        throw new TypeError("artifact resource cannot contain wildcards");
+    }
+    return canonical;
+}
+export function grantResourcePatternMatches(pattern, resource, resourceKind = "route") {
+    const canonicalPattern = normalizeGrantResourcePattern(pattern);
+    const canonicalResource = normalizeGrantEvaluationResource(resource, resourceKind);
+    const patternSegments = canonicalPattern === "/" ? [] : canonicalPattern.slice(1).split("/");
+    const resourceSegments = canonicalResource === "/" ? [] : canonicalResource.slice(1).split("/");
+    const matches = (patternIndex, resourceIndex) => {
+        const patternSegment = patternSegments[patternIndex];
+        if (patternSegment === undefined)
+            return resourceIndex === resourceSegments.length;
+        if (patternSegment === "**") {
+            if (patternIndex === patternSegments.length - 1)
+                return true;
+            for (let next = resourceIndex; next <= resourceSegments.length; next++) {
+                if (matches(patternIndex + 1, next))
+                    return true;
+            }
+            return false;
+        }
+        if (resourceIndex >= resourceSegments.length)
+            return false;
+        if (patternSegment !== "*" && patternSegment !== resourceSegments[resourceIndex])
+            return false;
+        return matches(patternIndex + 1, resourceIndex + 1);
+    };
+    return matches(0, 0);
+}
+function grantCheckFailures(grant, input, principal, now) {
+    const failures = [];
+    if (grant.source.kind === "config" && !input.spaceClaimed) {
+        failures.push("space_unclaimed_config");
+    }
+    if (!audienceMatches(grant.audience, principal))
+        failures.push("audience");
+    if (!targetMatches(grant.target, input.target))
+        failures.push("target");
+    const timestamp = now.getTime();
+    if (!Number.isFinite(timestamp)) {
+        failures.push("invalid_time");
+    }
+    else {
+        const notBefore = grant.constraints.notBefore;
+        if (notBefore !== undefined && timestamp < Date.parse(notBefore))
+            failures.push("not_before");
+        const expiresAt = grant.constraints.expiresAt;
+        if (expiresAt !== undefined && timestamp >= Date.parse(expiresAt))
+            failures.push("expired");
+    }
+    const maxUses = grant.constraints.maxUses;
+    if (maxUses !== undefined && !input.acquiredGrantIds?.includes(grant.id)) {
+        const uses = input.useCounts?.[grant.id];
+        if (!Number.isInteger(uses) || (uses ?? 0) < 0 || (uses ?? 0) >= maxUses) {
+            failures.push("max_uses");
+        }
+    }
+    if (grant.constraints.requireVerifiedEmail && principal.verifiedEmail !== true) {
+        failures.push("verified_email");
+    }
+    if (grant.constraints.network &&
+        ((grant.constraints.network.ipCidrs !== undefined &&
+            (!principal.ipAddress ||
+                !grant.constraints.network.ipCidrs.some((cidr) => grantNetworkCidrMatches(cidr, principal.ipAddress ?? "")))) ||
+            (grant.constraints.network.countries !== undefined &&
+                (!principal.country ||
+                    !grant.constraints.network.countries.includes(principal.country.toUpperCase()))) ||
+            (grant.constraints.network.excludedCountries !== undefined &&
+                (!principal.country ||
+                    grant.constraints.network.excludedCountries.includes(principal.country.toUpperCase()))) ||
+            (grant.constraints.network.excludedUserAgentSubstrings !== undefined &&
+                (!principal.userAgent ||
+                    grant.constraints.network.excludedUserAgentSubstrings.some((needle) => principal.userAgent?.toLowerCase().includes(needle.toLowerCase())))))) {
+        failures.push("network");
+    }
+    const included = grant.resources.include.some((pattern) => grantResourcePatternMatches(pattern, input.resource, input.resourceKind));
+    if (!included) {
+        failures.push("resource_not_included");
+    }
+    else if (grant.resources.exclude.some((pattern) => grantResourcePatternMatches(pattern, input.resource, input.resourceKind))) {
+        failures.push("resource_excluded");
+    }
+    return failures;
+}
+export function explainGrants(input) {
+    const principal = input.principal ?? {};
+    const now = input.now ?? new Date();
+    return input.grants.map((grant) => ({
+        grantId: grant.id,
+        failures: grantCheckFailures(grant, input, principal, now),
+    }));
+}
+export function evaluateGrants(input) {
+    const principal = input.principal ?? {};
+    const now = input.now ?? new Date();
+    const matches = [];
+    const capabilities = new Set();
+    for (const grant of input.grants) {
+        if (grantCheckFailures(grant, input, principal, now).length > 0)
+            continue;
+        const matchedCapabilities = [...grant.capabilities];
+        matches.push({
+            grantId: grant.id,
+            capabilities: matchedCapabilities,
+            source: grant.source,
+        });
+        for (const capability of matchedCapabilities)
+            capabilities.add(capability);
+    }
+    return {
+        capabilities: GRANT_CAPABILITIES.filter((capability) => capabilities.has(capability)),
+        matches,
+    };
+}
+export function grantAllows(input, capability) {
+    return evaluateGrants(input).capabilities.includes(capability);
+}

package/dist/utils/local-space-state.d.ts

@@ -13,15 +13,18 @@ export declare const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
  * `.spacefast/state.json` is the local credential/cache axis: it records the
  * resolved `spaceId`, provider `apiUrl`, anonymous `claimToken` before claim,
  * durable `accessToken` after continuation, and small publish caches such as
- * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written
- * so newer tools preserve unknown fields from older/newer tools.
+ * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written.
+ * The strict versioned schema fails closed instead of letting an older tool
+ * reinterpret fields written under a contract it does not understand.
  */
 export declare const localSpaceLinkSchema: z.ZodObject<{
     team: z.ZodOptional<z.ZodString>;
     space: z.ZodString;
     apiBaseUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
+export declare const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
 export declare const localSpaceStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
     spaceId: z.ZodOptional<z.ZodString>;
     apiUrl: z.ZodOptional<z.ZodString>;
     teamSlug: z.ZodOptional<z.ZodString>;
@@ -30,11 +33,52 @@ export declare const localSpaceStateSchema: z.ZodObject<{
     expiresAt: z.ZodOptional<z.ZodString>;
     accessToken: z.ZodOptional<z.ZodString>;
     lastVersionId: z.ZodOptional<z.ZodString>;
+    pendingOperationId: z.ZodOptional<z.ZodString>;
     lastVersionUrl: z.ZodOptional<z.ZodString>;
     lastSpaceUrl: z.ZodOptional<z.ZodString>;
-}, z.core.$loose>;
+    /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
+    anonymousPublishNonce: z.ZodOptional<z.ZodString>;
+    /** Unsettled first-publish mutation. Retries must reuse this exact key. */
+    pendingPublish: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        principal: z.ZodString;
+        kind: z.ZodEnum<{
+            anonymous: "anonymous";
+            authenticated: "authenticated";
+        }>;
+        intent: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    /** Settled creation receipt identity retained for invocations that began before its commit. */
+    creationReplay: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        principal: z.ZodString;
+        kind: z.ZodEnum<{
+            anonymous: "anonymous";
+            authenticated: "authenticated";
+        }>;
+        intent: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    /** Random replay capability reserved before consuming a claim credential. */
+    pendingCredentialReplay: z.ZodOptional<z.ZodObject<{
+        operation: z.ZodEnum<{
+            "claim-rotate": "claim-rotate";
+            "claim-exchange": "claim-exchange";
+        }>;
+        credentialFingerprint: z.ZodString;
+        key: z.ZodString;
+        principal: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export type LocalSpaceLink = z.infer<typeof localSpaceLinkSchema>;
 export type LocalSpaceStateFile = z.infer<typeof localSpaceStateSchema>;
+export type LocalSpaceStateWrite = Omit<LocalSpaceStateFile, "schemaVersion"> & {
+    schemaVersion?: typeof LOCAL_SPACE_STATE_SCHEMA_VERSION;
+};
+export type LocalCredentialReplay = NonNullable<LocalSpaceStateFile["pendingCredentialReplay"]>;
+export type LocalCredentialReplayOperation = LocalCredentialReplay["operation"];
 export type DiscoveredLocalSpaceState = {
     root: string;
     statePath: string | null;
@@ -48,6 +92,7 @@ export type DiscoveredLocalSpaceState = {
     claimUrl: string | undefined;
     expiresAt: string | undefined;
     lastVersionId: string | undefined;
+    pendingOperationId: string | undefined;
 };
 export type SaveLocalSpaceStateInput = {
     spaceId: string;
@@ -58,9 +103,26 @@ export type SaveLocalSpaceStateInput = {
     expiresAt?: string | undefined;
     accessToken?: string | undefined;
     lastVersionId?: string | undefined;
+    pendingOperationId?: string | undefined;
     lastVersionUrl?: string | undefined;
     lastSpaceUrl?: string | undefined;
+    /** Required when replacing one shown-once credential with another. */
+    expectedCredential?: {
+        claimToken?: string | undefined;
+        accessToken?: string | undefined;
+    };
+    /** Replay reservation completed by this shown-once credential replacement. */
+    credentialReplay?: LocalCredentialReplay | undefined;
+    /** Explicit relinks may replace another Space; ordinary cache writes may not. */
+    replaceSpace?: boolean | undefined;
 };
+export declare class LocalSpaceStateConflictError extends Error {
+    name: string;
+}
+export declare class LocalSpaceStateError extends Error {
+    readonly path: string;
+    constructor(filePath: string, cause?: unknown);
+}
 export declare function localSpaceStateDir(root: string): string;
 export declare function localSpaceStatePath(root: string): string;
 export declare function localSpaceLinkPath(root: string): string;
@@ -83,7 +145,19 @@ export declare function readLocalSpaceStateAt(root: string): Promise<DiscoveredL
 export declare function findUpward<T>(probe: (dir: string) => Promise<T | null>, startDir?: string, boundary?: string): Promise<T | null>;
 export declare function discoverLocalSpaceState(startDir?: string, boundary?: string): Promise<DiscoveredLocalSpaceState | null>;
 export declare function writeLocalSpaceLink(root: string, link: LocalSpaceLink): Promise<string>;
-export declare function writeLocalSpaceState(root: string, state: LocalSpaceStateFile): Promise<string>;
+export declare function mutateLocalSpaceState(root: string, mutate: (current: LocalSpaceStateFile) => LocalSpaceStateWrite, options?: {
+    beforeCommit?: (() => void | Promise<void>) | undefined;
+    afterBackup?: (() => void | Promise<void>) | undefined;
+    /** Fault-injection observer used to synchronize concurrency tests. */
+    onConflict?: (() => void | Promise<void>) | undefined;
+}): Promise<LocalSpaceStateFile>;
+export declare function writeLocalSpaceState(root: string, state: LocalSpaceStateWrite): Promise<string>;
+/** Reserve random replay custody before a claim token can be consumed. */
+export declare function reserveLocalCredentialReplay(root: string, input: {
+    operation: LocalCredentialReplayOperation;
+    claimToken: string;
+    allowUnstoredClaimToken?: boolean | undefined;
+}): Promise<LocalCredentialReplay>;
 export declare function saveLocalSpaceState(root: string, input: SaveLocalSpaceStateInput): Promise<{
     statePath: string;
     linkPath: string;