@agentxm/registry-client 0.28.4-bootstrap.0

package/dist/src/admin-client.d.ts

@@ -0,0 +1,181 @@
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import { type RegistryClientFailure } from "./errors.js";
+import { RegistryUrl } from "./registry-url.js";
+import { type RegistryRequestPolicy } from "./request-policy.js";
+import * as GeneratedRegistryClient from "./__generated__/registry-client.js";
+import type { DeprecationReplacementIntent } from "@agentxm/registry-protocol/unstable/registry/schema";
+import type { DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
+export interface RegistryExtensionReference {
+    readonly owner: string;
+    readonly type: string;
+    readonly name: string;
+}
+export interface RegistryExtensionVersionReference extends RegistryExtensionReference {
+    readonly version: string;
+}
+export type YankCategory = "broken" | "security" | "accidental" | "other";
+export interface RegistryLifecycleCallOptions {
+    readonly stepUpRequestId?: string;
+    readonly requestPolicy?: RegistryRequestPolicy;
+}
+export interface PutExtensionDeprecationInput {
+    readonly revision: string;
+    readonly message: string | null;
+    readonly replacement: DeprecationReplacementIntent;
+}
+export declare const normalizeRegistryDeprecation: (value: GeneratedRegistryClient.DeprecationView | null) => Effect.Effect<DeprecationView | null, RegistryClientFailure>;
+export declare const yankExtensionVersion: (ref: RegistryExtensionVersionReference, input: {
+    readonly category?: YankCategory;
+    readonly notice?: string;
+}, options?: RegistryLifecycleCallOptions) => Effect.Effect<{
+    readonly owner: string;
+    readonly type: "skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack";
+    readonly name: string;
+    readonly version: string;
+    readonly yankedAt: import("effect/DateTime").Utc | null;
+    readonly yankCategory: string | null;
+    readonly yankNotice: string | null;
+    readonly links: {
+        readonly html: string;
+    };
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+export declare const yankAvailableExtensionVersions: (ref: RegistryExtensionReference, input: {
+    readonly category?: YankCategory;
+    readonly notice?: string;
+}, options?: RegistryLifecycleCallOptions) => Effect.Effect<{
+    readonly selection: "all-available";
+    readonly affectedVersions: readonly string[];
+    readonly futureVersionsAffected: false;
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+export declare const unyankExtensionVersion: (ref: RegistryExtensionVersionReference, options?: RegistryLifecycleCallOptions) => Effect.Effect<{
+    readonly owner: string;
+    readonly type: "skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack";
+    readonly name: string;
+    readonly version: string;
+    readonly yankedAt: null;
+    readonly yankCategory: null;
+    readonly yankNotice: null;
+    readonly links: {
+        readonly html: string;
+    };
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+export declare const getExtensionDeprecation: (ref: RegistryExtensionReference) => Effect.Effect<{
+    deprecation: {
+        readonly message: string;
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly replacement?: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        } | undefined;
+    } | {
+        readonly replacement: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        };
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly message?: string | undefined;
+    } | null;
+    revision: string;
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+export declare const deprecateExtension: (ref: RegistryExtensionReference, input: PutExtensionDeprecationInput) => Effect.Effect<{
+    target: string;
+    before: {
+        readonly message: string;
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly replacement?: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        } | undefined;
+    } | {
+        readonly replacement: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        };
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly message?: string | undefined;
+    } | null;
+    after: {
+        readonly message: string;
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly replacement?: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        } | undefined;
+    } | {
+        readonly replacement: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        };
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly message?: string | undefined;
+    } | null;
+    disposition: "created" | "edited" | "restored" | "unchanged";
+    revision: string;
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+export declare const undeprecateExtension: (ref: RegistryExtensionReference, revision: string) => Effect.Effect<{
+    target: string;
+    before: {
+        readonly message: string;
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly replacement?: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        } | undefined;
+    } | {
+        readonly replacement: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        };
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly message?: string | undefined;
+    } | null;
+    after: {
+        readonly message: string;
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly replacement?: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        } | undefined;
+    } | {
+        readonly replacement: {
+            readonly status: "available";
+            readonly fqn: string;
+        } | {
+            readonly status: "unavailable";
+            readonly fqn?: string | undefined;
+        };
+        readonly deprecatedAt: import("effect/DateTime").Utc;
+        readonly message?: string | undefined;
+    } | null;
+    disposition: "created" | "edited" | "restored" | "unchanged";
+    revision: string;
+}, RegistryClientFailure, RegistryUrl | HttpClient.HttpClient>;
+//# sourceMappingURL=admin-client.d.ts.map

package/dist/src/admin-client.js

@@ -0,0 +1,165 @@
+// @effect-diagnostics anyUnknownInErrorContext:off — generated HTTP response errors are normalized by this registry adapter
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import { RegistryRequestFailed } from "./errors.js";
+import { RegistryUrl } from "./registry-url.js";
+import { captureRegistryErrorResponseBodies, mapRegistryFailure } from "./failure-mapping.js";
+import { executeRegistryRequest, } from "./request-policy.js";
+import * as GeneratedRegistryClient from "./__generated__/registry-client.js";
+export const normalizeRegistryDeprecation = (value) => {
+    if (value === null)
+        return Effect.succeed(null);
+    const replacement = value.replacement === undefined || value.replacement === null
+        ? undefined
+        : value.replacement.status === "available"
+            ? value.replacement
+            : {
+                status: "unavailable",
+                ...(value.replacement.fqn === undefined || value.replacement.fqn === null
+                    ? {}
+                    : { fqn: value.replacement.fqn }),
+            };
+    if (value.message !== undefined && value.message !== null) {
+        return Effect.succeed({
+            deprecatedAt: value.deprecatedAt,
+            message: value.message,
+            ...(replacement === undefined ? {} : { replacement }),
+        });
+    }
+    if (replacement !== undefined) {
+        return Effect.succeed({ deprecatedAt: value.deprecatedAt, replacement });
+    }
+    return Effect.fail(new RegistryRequestFailed({
+        category: "internal",
+        detail: "Registry response did not contain required deprecation guidance.",
+    }));
+};
+const normalizeManagementView = (value) => Effect.map(normalizeRegistryDeprecation(value.deprecation), (deprecation) => ({
+    deprecation,
+    revision: value.revision,
+}));
+const normalizeTransition = (value) => Effect.all({
+    before: normalizeRegistryDeprecation(value.before),
+    after: normalizeRegistryDeprecation(value.after),
+}).pipe(Effect.map(({ before, after }) => ({
+    target: value.target,
+    before,
+    after,
+    disposition: value.disposition,
+    revision: value.revision,
+})));
+const mapAdminClientError = (registryUrl) => (error) => mapRegistryFailure(error, {
+    baseUrl: registryUrl,
+    networkDetail: "Registry request failed.",
+    incompatibleDetail: "Registry response did not match the expected schema.",
+    requestConstructionDetail: "Could not construct the Registry request.",
+    fallbackDetail: "Unexpected registry client failure.",
+});
+const makeLifecycleClient = (options) => Effect.gen(function* () {
+    const registryUrl = yield* RegistryUrl;
+    const httpClient = yield* HttpClient.HttpClient;
+    const remoteHttpClient = captureRegistryErrorResponseBodies(httpClient.pipe(HttpClient.mapRequest((request) => {
+        const withUrl = HttpClientRequest.prependUrl(request, registryUrl);
+        return options?.stepUpRequestId === undefined
+            ? withUrl
+            : HttpClientRequest.setHeaders(withUrl, {
+                "x-axm-step-up-request": options.stepUpRequestId,
+            });
+    })));
+    return {
+        registryUrl,
+        client: GeneratedRegistryClient.make(remoteHttpClient),
+        requestPolicy: options?.requestPolicy,
+    };
+});
+const runAdminCall = (registryUrl, effect, args) => executeRegistryRequest(effect, {
+    operation: args.operation,
+    request: {
+        service: "registry",
+        method: args.method,
+        url: new URL(args.path, registryUrl).href,
+    },
+    replaySafety: args.replaySafety,
+    mapError: mapAdminClientError(registryUrl),
+    ...(args.requestPolicy === undefined ? {} : { policy: args.requestPolicy }),
+});
+const safe = { kind: "safe" };
+const mutation = { kind: "mutation" };
+export const yankExtensionVersion = (ref, input, options) => Effect.gen(function* () {
+    const { client, registryUrl, requestPolicy } = yield* makeLifecycleClient(options);
+    return yield* runAdminCall(registryUrl, client.ExtensionsYankVersion(ref.owner, ref.type, ref.name, ref.version, {
+        payload: {
+            ...(input.category === undefined ? {} : { category: input.category }),
+            ...(input.notice === undefined ? {} : { notice: input.notice }),
+        },
+    }), {
+        operation: "yank extension version",
+        method: "POST",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/${ref.version}/yank`,
+        replaySafety: mutation,
+        ...(requestPolicy === undefined ? {} : { requestPolicy }),
+    });
+});
+export const yankAvailableExtensionVersions = (ref, input, options) => Effect.gen(function* () {
+    const { client, registryUrl, requestPolicy } = yield* makeLifecycleClient(options);
+    return yield* runAdminCall(registryUrl, client.ExtensionsYankAvailableVersions(ref.owner, ref.type, ref.name, {
+        payload: {
+            selection: "all-available",
+            ...(input.category === undefined ? {} : { category: input.category }),
+            ...(input.notice === undefined ? {} : { notice: input.notice }),
+        },
+    }), {
+        operation: "yank available extension versions",
+        method: "POST",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/versions/yank`,
+        replaySafety: mutation,
+        ...(requestPolicy === undefined ? {} : { requestPolicy }),
+    });
+});
+export const unyankExtensionVersion = (ref, options) => Effect.gen(function* () {
+    const { client, registryUrl, requestPolicy } = yield* makeLifecycleClient(options);
+    return yield* runAdminCall(registryUrl, client.ExtensionsUnyankVersion(ref.owner, ref.type, ref.name, ref.version, undefined), {
+        operation: "unyank extension version",
+        method: "DELETE",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/${ref.version}/yank`,
+        replaySafety: mutation,
+        ...(requestPolicy === undefined ? {} : { requestPolicy }),
+    });
+});
+export const getExtensionDeprecation = (ref) => Effect.gen(function* () {
+    const { client, registryUrl } = yield* makeLifecycleClient();
+    const result = yield* runAdminCall(registryUrl, client.ExtensionsGetDeprecation(ref.owner, ref.type, ref.name, undefined), {
+        operation: "get extension deprecation",
+        method: "GET",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/deprecation`,
+        replaySafety: safe,
+    });
+    return yield* normalizeManagementView(result);
+});
+export const deprecateExtension = (ref, input) => Effect.gen(function* () {
+    const { client, registryUrl } = yield* makeLifecycleClient();
+    const result = yield* runAdminCall(registryUrl, client.ExtensionsPutDeprecation(ref.owner, ref.type, ref.name, {
+        params: { "if-match": input.revision },
+        payload: { message: input.message, replacement: input.replacement },
+    }), {
+        operation: "deprecate extension",
+        method: "PUT",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/deprecation`,
+        replaySafety: mutation,
+    });
+    return yield* normalizeTransition(result);
+});
+export const undeprecateExtension = (ref, revision) => Effect.gen(function* () {
+    const { client, registryUrl } = yield* makeLifecycleClient();
+    const result = yield* runAdminCall(registryUrl, client.ExtensionsDeleteDeprecation(ref.owner, ref.type, ref.name, {
+        params: { "if-match": revision },
+    }), {
+        operation: "undeprecate extension",
+        method: "DELETE",
+        path: `/v1/extensions/${ref.owner}/${ref.type}/${ref.name}/deprecation`,
+        replaySafety: mutation,
+    });
+    return yield* normalizeTransition(result);
+});
+//# sourceMappingURL=admin-client.js.map

package/dist/src/archive-cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Verified, content-addressed cache for registry ZIP archives.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Duration from "effect/Duration";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type RegistryClientFailure } from "./errors.js";
+export declare const ARCHIVE_CACHE_MAX_BYTES: number;
+export declare const ARCHIVE_CACHE_MAX_AGE: Duration.Duration;
+export interface ArchiveCacheOptions {
+    readonly maxBytes?: number;
+    readonly maxAge?: Duration.Duration;
+}
+export interface ArchiveCacheStatus {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly maxBytes: number;
+    readonly maxAgeDays: number;
+}
+export interface ArchiveCacheVerifyResult {
+    readonly checked: number;
+    readonly valid: number;
+    readonly corruptRemoved: number;
+}
+export interface ArchiveCachePruneResult {
+    readonly removed: number;
+    readonly bytesFreed: number;
+    readonly remaining: number;
+    readonly remainingBytes: number;
+}
+export interface ArchiveCache {
+    readonly read: (integrity: string) => Effect.Effect<Option.Option<Uint8Array>, RegistryClientFailure>;
+    readonly write: (integrity: string, archive: Uint8Array, options?: {
+        readonly prune?: boolean;
+    }) => Effect.Effect<void, RegistryClientFailure>;
+    readonly status: () => Effect.Effect<ArchiveCacheStatus, RegistryClientFailure>;
+    readonly verify: () => Effect.Effect<ArchiveCacheVerifyResult, RegistryClientFailure>;
+    readonly prune: () => Effect.Effect<ArchiveCachePruneResult, RegistryClientFailure>;
+}
+export declare const makeArchiveCache: (fs: FileSystem.FileSystem, path: Path.Path, root: string, options?: ArchiveCacheOptions) => ArchiveCache;
+export declare const makeUserArchiveCache: () => Effect.Effect<ArchiveCache, never, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=archive-cache.d.ts.map

package/dist/src/archive-cache.js

@@ -0,0 +1,179 @@
+/**
+ * Verified, content-addressed cache for registry ZIP archives.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { RegistryOperationFailed } from "./errors.js";
+import { computeIntegrity } from "./integrity.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { resolveAxmCacheRoot } from "./cache-root.js";
+export const ARCHIVE_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+export const ARCHIVE_CACHE_MAX_AGE = Duration.days(90);
+const cacheError = (detail, cause) => new RegistryOperationFailed({
+    category: "internal",
+    detail,
+    ...(cause === undefined ? {} : { cause }),
+});
+const cacheFileName = (integrity) => {
+    if (!integrity.startsWith("sha512-") || integrity.length === "sha512-".length)
+        return undefined;
+    const base64Url = integrity
+        .slice("sha512-".length)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
+    return `${base64Url}.zip`;
+};
+const integrityFromFileName = (fileName) => {
+    if (!fileName.endsWith(".zip"))
+        return undefined;
+    const base64Url = fileName.slice(0, -".zip".length);
+    if (base64Url.length === 0 || !/^[A-Za-z0-9_-]+$/.test(base64Url))
+        return undefined;
+    const remainder = base64Url.length % 4;
+    const padding = remainder === 0 ? "" : "=".repeat(4 - remainder);
+    return `sha512-${base64Url.replaceAll("-", "+").replaceAll("_", "/")}${padding}`;
+};
+export const makeArchiveCache = (fs, path, root, options = {}) => {
+    const maxBytes = options.maxBytes ?? ARCHIVE_CACHE_MAX_BYTES;
+    const maxAge = options.maxAge ?? ARCHIVE_CACHE_MAX_AGE;
+    const pathForIntegrity = (integrity) => {
+        const fileName = cacheFileName(integrity);
+        return fileName === undefined
+            ? Effect.fail(cacheError(`Unsupported archive integrity value: ${integrity}`))
+            : Effect.succeed(path.join(root, fileName));
+    };
+    const listEntries = () => Effect.gen(function* () {
+        const exists = yield* fs.exists(root).pipe(Effect.orElseSucceed(() => false));
+        if (!exists)
+            return [];
+        const names = yield* fs
+            .readDirectory(root)
+            .pipe(Effect.mapError((cause) => cacheError(`Failed to inspect archive cache: ${root}`, cause)));
+        return yield* Effect.forEach(names.filter((name) => name.endsWith(".zip")), (name) => Effect.gen(function* () {
+            const entryPath = path.join(root, name);
+            const info = yield* fs
+                .stat(entryPath)
+                .pipe(Effect.mapError((cause) => cacheError(`Failed to inspect cache entry: ${entryPath}`, cause)));
+            return {
+                path: entryPath,
+                integrity: integrityFromFileName(name),
+                size: Number(info.size),
+                accessedAt: Option.match(info.mtime, {
+                    onNone: () => DateTime.makeUnsafe(0),
+                    onSome: (mtime) => DateTime.makeUnsafe(mtime),
+                }),
+            };
+        }), { concurrency: 16 });
+    });
+    const removeEntry = (entryPath) => fs
+        .remove(entryPath)
+        .pipe(Effect.mapError((cause) => cacheError(`Failed to remove cache entry: ${entryPath}`, cause)));
+    const prune = () => Effect.gen(function* () {
+        const now = yield* DateTime.now;
+        const entries = [...(yield* listEntries())].sort((a, b) => DateTime.Order(a.accessedAt, b.accessedAt));
+        const expired = entries.filter((entry) => Duration.isGreaterThan(DateTime.distance(entry.accessedAt, now), maxAge));
+        yield* Effect.forEach(expired, (entry) => removeEntry(entry.path), { concurrency: 8 });
+        const expiredPaths = new Set(expired.map((entry) => entry.path));
+        const retained = entries.filter((entry) => !expiredPaths.has(entry.path));
+        let retainedBytes = retained.reduce((total, entry) => total + entry.size, 0);
+        const removedForSize = [];
+        for (const entry of retained) {
+            if (retainedBytes <= maxBytes)
+                break;
+            yield* removeEntry(entry.path);
+            removedForSize.push(entry);
+            retainedBytes -= entry.size;
+        }
+        const removed = [...expired, ...removedForSize];
+        return {
+            removed: removed.length,
+            bytesFreed: removed.reduce((total, entry) => total + entry.size, 0),
+            remaining: entries.length - removed.length,
+            remainingBytes: retainedBytes,
+        };
+    });
+    const read = (integrity) => Effect.gen(function* () {
+        const entryPath = yield* pathForIntegrity(integrity);
+        const exists = yield* fs.exists(entryPath).pipe(Effect.orElseSucceed(() => false));
+        if (!exists)
+            return Option.none();
+        const archive = yield* fs
+            .readFile(entryPath)
+            .pipe(Effect.mapError((cause) => cacheError(`Failed to read cache entry: ${entryPath}`, cause)));
+        const actualIntegrity = yield* computeIntegrity(archive);
+        if (actualIntegrity !== integrity) {
+            yield* removeEntry(entryPath);
+            return Option.none();
+        }
+        const now = DateTime.toDateUtc(yield* DateTime.now);
+        yield* fs.utimes(entryPath, now, now).pipe(Effect.ignore);
+        return Option.some(archive);
+    });
+    const write = (integrity, archive, writeOptions = {}) => Effect.gen(function* () {
+        const actualIntegrity = yield* computeIntegrity(archive);
+        if (actualIntegrity !== integrity) {
+            return yield* new RegistryOperationFailed({
+                category: "validation",
+                detail: "Downloaded registry archive did not match its published integrity.",
+            });
+        }
+        const entryPath = yield* pathForIntegrity(integrity);
+        yield* fs
+            .makeDirectory(root, { recursive: true })
+            .pipe(Effect.mapError((cause) => cacheError(`Failed to create archive cache: ${root}`, cause)));
+        yield* writeFileAtomic(fs, {
+            targetPath: entryPath,
+            content: archive,
+            removeTargetBeforeRename: true,
+            mapError: (failure) => failure.step === "rename"
+                ? cacheError(`Failed to commit cache entry: ${entryPath}`, failure.cause)
+                : cacheError("Failed to write archive cache temp file", failure.cause),
+        });
+        if (writeOptions.prune !== false)
+            yield* prune();
+    });
+    const status = () => Effect.map(listEntries(), (entries) => ({
+        entries: entries.length,
+        bytes: entries.reduce((total, entry) => total + entry.size, 0),
+        maxBytes,
+        maxAgeDays: Duration.toDays(maxAge),
+    }));
+    const verify = () => Effect.gen(function* () {
+        const entries = yield* listEntries();
+        const results = yield* Effect.forEach(entries, (entry) => Effect.gen(function* () {
+            if (entry.integrity === undefined) {
+                yield* removeEntry(entry.path);
+                return false;
+            }
+            const archive = yield* fs
+                .readFile(entry.path)
+                .pipe(Effect.mapError((cause) => cacheError(`Failed to read cache entry: ${entry.path}`, cause)));
+            const actualIntegrity = yield* computeIntegrity(archive);
+            if (actualIntegrity === entry.integrity)
+                return true;
+            yield* removeEntry(entry.path);
+            return false;
+        }), { concurrency: 8 });
+        const valid = results.filter(Boolean).length;
+        return {
+            checked: results.length,
+            valid,
+            corruptRemoved: results.length - valid,
+        };
+    });
+    return { read, write, status, verify, prune };
+};
+export const makeUserArchiveCache = () => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const root = path.join(yield* resolveAxmCacheRoot(), "archives");
+    return makeArchiveCache(fs, path, root);
+});
+//# sourceMappingURL=archive-cache.js.map

package/dist/src/atomic-write.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * Deliberately duplicated from the workspace-state kernel: an integration
+ * may not depend on a kernel, and this helper is within the sanctioned
+ * duplication budget for small pure functions. The registry consumers never
+ * sweep stale temps, so that half of the original stays behind.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type { PlatformError } from "effect/PlatformError";
+/**
+ * Step at which an atomic write failed. `check-target` and `read-target` can
+ * only occur with `skipIfUnchanged: "fail-on-read-error"`.
+ */
+export type AtomicWriteStep = "check-target" | "read-target" | "write-temp" | "rename";
+/** Failure passed to `mapError` so each call site keeps its own error shape. */
+export interface AtomicWriteFailure {
+    readonly step: AtomicWriteStep;
+    readonly targetPath: string;
+    readonly tempPath: string;
+    readonly cause: PlatformError;
+}
+/**
+ * Content-equality short-circuit mode: `fail-on-read-error` surfaces
+ * check/read failures via `mapError`; `ignore-read-errors` treats an
+ * unreadable target as changed and proceeds to write.
+ */
+export type SkipIfUnchanged = "fail-on-read-error" | "ignore-read-errors";
+/** Options for `writeFileAtomic`. */
+export interface WriteFileAtomicOptions<E> {
+    readonly targetPath: string;
+    readonly content: string | Uint8Array;
+    /** When set, leave the target untouched if it already has this content. */
+    readonly skipIfUnchanged?: SkipIfUnchanged;
+    /** Best-effort remove of the target before rename (Windows cannot always rename over an existing file). */
+    readonly removeTargetBeforeRename?: boolean;
+    readonly mapError: (failure: AtomicWriteFailure) => E;
+}
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * categories, details, and suggestions stay call-site specific.
+ */
+export declare const writeFileAtomic: <E>(fs: FileSystem.FileSystem, options: WriteFileAtomicOptions<E>) => Effect.Effect<"written" | "skipped", E>;
+//# sourceMappingURL=atomic-write.d.ts.map