@agentxm/extension-publish 0.28.4-bootstrap.0

package/dist/src/lint-gate.d.ts

@@ -0,0 +1,47 @@
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Path from "effect/Path";
+import { PublishFailed } from "./errors.js";
+interface PublishLintPlatform {
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+}
+export type PublishLintArgs = {
+    readonly type: "skill";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "pack";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "subagent";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "mcp-server";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "hook";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "rule";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+} | {
+    readonly type: "knowledge";
+    readonly extensionDir: string;
+    readonly manifestJson: unknown;
+    readonly platform: PublishLintPlatform;
+};
+export declare const runPublishLintGate: (args: PublishLintArgs) => Effect.Effect<void, PublishFailed>;
+export {};
+//# sourceMappingURL=lint-gate.d.ts.map

package/dist/src/lint-gate.js

@@ -0,0 +1,136 @@
+import * as Effect from "effect/Effect";
+import { PublishFailed } from "./errors.js";
+import { makePlatformPackFileAccessor } from "@agentxm/extension-workspace";
+import { makePlatformSkillFileAccessor } from "@agentxm/extension-workspace";
+import { platformCanonicalLintConfig } from "@agentxm/registry-protocol/unstable/lint/config";
+import { composePath } from "@agentxm/registry-protocol/unstable/lint/compose-path";
+import { evaluateContexts } from "@agentxm/registry-protocol/unstable/lint/evaluate";
+import { hookRules, knowledgeRules, mcpServerRules, packRules, skillRules, ruleRules, subagentRules, } from "@agentxm/registry-protocol/unstable/lint/publish";
+const manifestName = (manifestJson) => {
+    if (manifestJson === null || typeof manifestJson !== "object" || Array.isArray(manifestJson)) {
+        return undefined;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(manifestJson, "name");
+    return typeof descriptor?.value === "string" ? descriptor.value : undefined;
+};
+export const runPublishLintGate = (args) => {
+    switch (args.type) {
+        case "skill":
+            return evaluateSkill(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "pack":
+            return evaluatePack(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "subagent":
+            return evaluateSubagent(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "mcp-server":
+            return evaluateMcpServer(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "hook":
+            return evaluateHook(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "knowledge":
+            return evaluateKnowledge(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+        case "rule":
+            return evaluateRule(args).pipe(Effect.flatMap(failOnErrorFindings(args.type)));
+    }
+};
+const evaluateSkill = (args) => {
+    const packageFiles = makePlatformSkillFileAccessor(args.platform, args.extensionDir);
+    const files = makePlatformSkillFileAccessor(args.platform, args.platform.path.join(args.extensionDir, "src"));
+    const expectedName = manifestName(args.manifestJson);
+    const context = {
+        subject: {
+            isNative: true,
+            skillJson: args.manifestJson,
+            ...(expectedName === undefined ? {} : { expectedName }),
+        },
+        files,
+        packageFiles,
+        displayRoot: "",
+    };
+    return evaluateContexts(skillRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluatePack = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { packJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(packRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluateSubagent = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { subagentJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(subagentRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluateMcpServer = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { mcpServerJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(mcpServerRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluateHook = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { hookJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(hookRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluateRule = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { ruleJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(ruleRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const evaluateKnowledge = (args) => {
+    const files = makePlatformPackFileAccessor(args.platform, args.extensionDir);
+    const context = {
+        subject: { knowledgeJson: args.manifestJson },
+        files,
+        displayRoot: "",
+    };
+    return evaluateContexts(knowledgeRules, [context], platformCanonicalLintConfig).pipe(Effect.map((evaluated) => collectErrors(evaluated, (ctx) => ctx.displayRoot)));
+};
+const collectErrors = (evaluated, displayRoot) => {
+    const out = [];
+    for (const entry of evaluated) {
+        for (const finding of entry.findings) {
+            if (finding.severity !== "error") {
+                continue;
+            }
+            out.push({
+                path: composePath(displayRoot(entry.context), finding.location),
+                finding,
+            });
+        }
+    }
+    return out;
+};
+const failOnErrorFindings = (type) => (findings) => {
+    if (findings.length === 0) {
+        return Effect.void;
+    }
+    return Effect.fail(new PublishFailed({
+        category: "validation",
+        detail: renderPublishLintFailure(type, findings),
+    }));
+};
+const renderPublishLintFailure = (type, findings) => {
+    const noun = type === "mcp-server" ? "MCP server" : type;
+    const lines = findings.map(({ path, finding }) => `- ${path} [${finding.ruleId}]: ${finding.message}`);
+    return [
+        `Publish lint failed for ${noun} manifest with ${findings.length} error${findings.length === 1 ? "" : "s"}.`,
+        ...lines,
+    ].join("\n");
+};
+//# sourceMappingURL=lint-gate.js.map

package/dist/src/preflight.d.ts

@@ -0,0 +1,46 @@
+import * as Effect from "effect/Effect";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { Version } from "@agentxm/extension-model/unstable/version-constraints";
+import { type ExtensionConstraintInvariantFact, type PackDependencyReachability } from "@agentxm/extension-workspace";
+import type { PublicationPackResult } from "@agentxm/registry-protocol/unstable/registry";
+import type { RegistryClient, RegistryClientFailure } from "@agentxm/registry-client";
+import { PublishFailed } from "./errors.js";
+import type { PublishableType } from "./publishable-types.js";
+export declare const alreadyPublishedVersionConflict: (args: {
+    readonly fqn: string;
+    readonly version: Version;
+}) => PublishFailed;
+export declare const nonMonotonicVersionConflict: (args: {
+    readonly fqn: string;
+    readonly version: Version;
+    readonly highestPublished: Version;
+}) => PublishFailed;
+/** Every publish owner must already exist before any candidate uploads. */
+export declare const validatePublishOwners: (owners: ReadonlyArray<Handle>, client: Pick<RegistryClient, "ownerExists">) => Effect.Effect<void, PublishFailed | RegistryClientFailure>;
+/** One suggested follow-up carried by a publish advisory finding. */
+export interface PublishAdvisorySuggestion {
+    readonly description: string;
+    readonly cmd?: string;
+    readonly url?: string;
+}
+/** A non-gating structured warning observed during publication. */
+export interface PublishAdvisoryFinding {
+    readonly ruleId: string;
+    readonly severity: "warning";
+    readonly message: string;
+    readonly suggestions: ReadonlyArray<PublishAdvisorySuggestion>;
+}
+/** The local constraint facts one selected candidate contributes. */
+export interface LocalPackConstraintCandidate {
+    readonly fqn: string;
+    readonly type: PublishableType;
+    readonly authored: boolean;
+}
+export declare const findPackPublishDivergenceFindings: (args: {
+    readonly candidates: ReadonlyArray<LocalPackConstraintCandidate>;
+    readonly reachability: ReadonlyArray<PackDependencyReachability>;
+    readonly packs: ReadonlyArray<PublicationPackResult>;
+}) => ReadonlyMap<string, ReadonlyArray<PublishAdvisoryFinding>>;
+/** Local Pack-constraint exclusions that block a member's publication. */
+export declare const localPackConstraintFailures: (facts: ReadonlyArray<ExtensionConstraintInvariantFact>) => ReadonlyMap<string, PublishFailed>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/src/preflight.js

@@ -0,0 +1,125 @@
+import * as Effect from "effect/Effect";
+import { formatFqn } from "@agentxm/extension-model/unstable/extensions";
+import { extensionConstraintFactText, } from "@agentxm/extension-workspace";
+import { PublishFailed } from "./errors.js";
+export const alreadyPublishedVersionConflict = (args) => new PublishFailed({
+    category: "conflict",
+    detail: `Cannot publish: version ${args.version} is already published for ${args.fqn}. Published versions are immutable.`,
+    suggestions: [
+        {
+            description: "Bump the manifest version.",
+            cmd: `axm version ${args.fqn} patch`,
+        },
+        {
+            description: "Re-run with --on-existing verify only when the local archive should be byte-equivalent to the published version.",
+        },
+    ],
+});
+export const nonMonotonicVersionConflict = (args) => new PublishFailed({
+    category: "conflict",
+    detail: `Cannot publish: version ${args.version} is lower than the highest published version ${args.highestPublished} for ${args.fqn}.`,
+    suggestions: [
+        {
+            description: "Bump the manifest version.",
+            cmd: `axm version ${args.fqn} patch`,
+        },
+        {
+            description: "Re-run with --backfill only if publishing an older unpublished version is intentional.",
+        },
+    ],
+});
+/** Every publish owner must already exist before any candidate uploads. */
+export const validatePublishOwners = (owners, client) => Effect.forEach([...new Set(owners)], (owner) => client.ownerExists(owner).pipe(Effect.flatMap(({ exists }) => exists
+    ? Effect.void
+    : new PublishFailed({
+        category: "not_found",
+        detail: `Publish owner ${owner} does not exist.`,
+        suggestions: [
+            {
+                description: "Create the organization in AgentXM before publishing.",
+                url: "https://agentxm.ai/orgs/new",
+            },
+        ],
+    }))), { concurrency: 4, discard: true });
+export const findPackPublishDivergenceFindings = (args) => {
+    const authoredPacks = new Set(args.candidates
+        .filter((candidate) => candidate.authored && candidate.type === "pack")
+        .map((candidate) => candidate.fqn));
+    const localByPair = new Map(args.reachability.map((record) => [`${record.packFqn}\u0000${record.memberFqn}`, record]));
+    const findings = new Map();
+    for (const pack of args.packs) {
+        if (pack.status !== "admitted")
+            continue;
+        const packFqn = formatFqn(pack.target);
+        if (!authoredPacks.has(packFqn))
+            continue;
+        for (const resolution of pack.resolutions) {
+            const memberFqn = formatFqn(resolution.dependency);
+            const local = localByPair.get(`${packFqn}\u0000${memberFqn}`);
+            if (local?.classification !== "satisfying" ||
+                local.memberVersion === undefined ||
+                local.memberVersion === resolution.effectiveVersion) {
+                continue;
+            }
+            const finding = {
+                ruleId: "pack/publish-resolution-divergence",
+                severity: "warning",
+                message: `${packFqn} resolves ${memberFqn}@${local.memberVersion} in this workspace, while Registry consumers resolve ${memberFqn}@${resolution.effectiveVersion} within ${resolution.dependency.range}.`,
+                suggestions: [
+                    local.memberAuthority === "workspace"
+                        ? {
+                            description: `Publish ${memberFqn} before publishing the pack if consumers should receive the workspace version`,
+                            cmd: `axm publish ${memberFqn}`,
+                        }
+                        : {
+                            description: `Update ${memberFqn} if this workspace should match Registry consumers`,
+                            cmd: `axm update ${memberFqn}`,
+                        },
+                ],
+            };
+            const current = findings.get(packFqn);
+            if (current === undefined)
+                findings.set(packFqn, [finding]);
+            else
+                current.push(finding);
+        }
+    }
+    return new Map([...findings.entries()].map(([packFqn, values]) => [
+        packFqn,
+        [...values].sort((left, right) => left.message.localeCompare(right.message)),
+    ]));
+};
+/** Local Pack-constraint exclusions that block a member's publication. */
+export const localPackConstraintFailures = (facts) => {
+    return new Map(facts.map((fact) => {
+        const memberFqn = fact.subject.identity;
+        const memberVersion = fact.observation.candidateVersion ?? "unknown";
+        const violations = fact.observation.violations ?? [];
+        return [
+            memberFqn,
+            new PublishFailed({
+                category: "validation",
+                detail: `${extensionConstraintFactText(fact)}; ${memberFqn}@${memberVersion} is excluded by the current workspace Pack constraints: ${violations
+                    .map((constraint) => `${constraint.dependingPack ?? "unknown Pack"} declares ${constraint.range}`)
+                    .join("; ")}`,
+                suggestions: violations.flatMap((constraint) => constraint.authority === "workspace"
+                    ? [
+                        {
+                            description: `Replace ${constraint.dependingPack ?? "the Pack"}'s constraint with the selected version, then publish the member and pack together`,
+                            cmd: `axm packs add ${constraint.dependingPack ?? "<name>"} ${memberFqn}`,
+                        },
+                    ]
+                    : [
+                        {
+                            description: `Update ${constraint.dependingPack ?? "the Pack"} if its owner has published a compatible constraint`,
+                            cmd: `axm update ${constraint.dependingPack ?? "<extension[@version]>"}`,
+                        },
+                        {
+                            description: `Otherwise stop workspace authority from shadowing ${memberFqn}`,
+                        },
+                    ]),
+            }),
+        ];
+    }));
+};
+//# sourceMappingURL=preflight.js.map

package/dist/src/publish-ignore.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Publish ignore resolution.
+ *
+ * A manifest may declare `publish.ignore` to keep development-only files out of
+ * the archive. AXM also excludes its reserved canonical completion marker so
+ * installed packages can be republished without leaking workspace metadata.
+ *
+ * Some paths can never be ignored. Dropping the manifest would produce an
+ * archive the registry cannot identify, and the failure would surface as a
+ * confusing "manifest missing" error far from the pattern that caused it. This
+ * module rejects such a pattern at its source instead.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import { PublishFailed } from "./errors.js";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { BuildZipArchiveOptions } from "./archive.js";
+declare const PublishIgnoreError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PublishIgnoreError";
+} & Readonly<A>;
+/** @experimental This API is unstable and may change without notice. */
+export declare class PublishIgnoreError extends PublishIgnoreError_base<{
+    readonly detail: string;
+    readonly pattern: string;
+    readonly path: string;
+}> {
+}
+/**
+ * Archive-relative paths a publish ignore list may never remove.
+ *
+ * Only the manifest is protected here. Required body files (a skill's
+ * `SKILL.md`, a hook's entrypoint, a knowledge bundle's root index) are
+ * enforced by filtered-package validation on the built archive, which reports
+ * the missing file by name at both the client and Registry ingestion boundary.
+ */
+export declare const protectedPublishPaths: (type: ExtensionType) => ReadonlyArray<string>;
+/**
+ * Effective ignore patterns for a publish, or the first pattern that would drop
+ * a protected path.
+ */
+export declare const resolvePublishIgnore: (type: ExtensionType, declared: ReadonlyArray<string> | undefined) => Result.Result<ReadonlyArray<string>, PublishIgnoreError>;
+/**
+ * Archive options for one publish, as an Effect the per-type publish operations
+ * can yield directly.
+ */
+export declare const publishArchiveOptions: (type: ExtensionType, declared: ReadonlyArray<string> | undefined) => Effect.Effect<BuildZipArchiveOptions, PublishFailed>;
+export {};
+//# sourceMappingURL=publish-ignore.d.ts.map

package/dist/src/publish-ignore.js

@@ -0,0 +1,61 @@
+/**
+ * Publish ignore resolution.
+ *
+ * A manifest may declare `publish.ignore` to keep development-only files out of
+ * the archive. AXM also excludes its reserved canonical completion marker so
+ * installed packages can be republished without leaking workspace metadata.
+ *
+ * Some paths can never be ignored. Dropping the manifest would produce an
+ * archive the registry cannot identify, and the failure would surface as a
+ * confusing "manifest missing" error far from the pattern that caused it. This
+ * module rejects such a pattern at its source instead.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import { PublishFailed } from "./errors.js";
+import { expandGlobs } from "./internal/glob.js";
+import { manifestFilenameForType } from "@agentxm/registry-protocol/unstable/publish/manifest-policy";
+/** @experimental This API is unstable and may change without notice. */
+export class PublishIgnoreError extends Data.TaggedError("PublishIgnoreError") {
+}
+/**
+ * Archive-relative paths a publish ignore list may never remove.
+ *
+ * Only the manifest is protected here. Required body files (a skill's
+ * `SKILL.md`, a hook's entrypoint, a knowledge bundle's root index) are
+ * enforced by filtered-package validation on the built archive, which reports
+ * the missing file by name at both the client and Registry ingestion boundary.
+ */
+export const protectedPublishPaths = (type) => [
+    manifestFilenameForType(type),
+];
+/**
+ * Effective ignore patterns for a publish, or the first pattern that would drop
+ * a protected path.
+ */
+export const resolvePublishIgnore = (type, declared) => {
+    if (declared === undefined || declared.length === 0) {
+        return Result.succeed([]);
+    }
+    const protectedPaths = protectedPublishPaths(type);
+    for (const pattern of declared) {
+        const [blocked] = expandGlobs([pattern], protectedPaths);
+        if (blocked !== undefined) {
+            return Result.fail(new PublishIgnoreError({
+                detail: `publish.ignore pattern "${pattern}" would leave "${blocked}" out of the archive, and a ${type} package cannot be published without it.`,
+                pattern,
+                path: blocked,
+            }));
+        }
+    }
+    return Result.succeed(declared);
+};
+/**
+ * Archive options for one publish, as an Effect the per-type publish operations
+ * can yield directly.
+ */
+export const publishArchiveOptions = (type, declared) => Effect.fromResult(resolvePublishIgnore(type, declared)).pipe(Effect.map((ignore) => ({ ignore })), Effect.mapError((cause) => new PublishFailed({ category: "validation", detail: cause.detail, cause })));
+//# sourceMappingURL=publish-ignore.js.map

package/dist/src/publishable-types.d.ts

@@ -0,0 +1,21 @@
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+/**
+ * Publish policy, total over every extension type: a new type cannot be added
+ * without deciding whether it publishes.
+ */
+export declare const PUBLISHABLE_TYPES: {
+    readonly skill: true;
+    readonly "mcp-server": true;
+    readonly subagent: true;
+    readonly rule: true;
+    readonly hook: true;
+    readonly knowledge: true;
+    readonly pack: true;
+};
+type TruthyKeys<T> = {
+    [K in keyof T]: T[K] extends true ? K : never;
+}[keyof T];
+export type PublishableType = TruthyKeys<typeof PUBLISHABLE_TYPES>;
+export declare const isPublishableType: (type: ExtensionType) => type is PublishableType;
+export {};
+//# sourceMappingURL=publishable-types.d.ts.map

package/dist/src/publishable-types.js

@@ -0,0 +1,15 @@
+/**
+ * Publish policy, total over every extension type: a new type cannot be added
+ * without deciding whether it publishes.
+ */
+export const PUBLISHABLE_TYPES = {
+    skill: true,
+    "mcp-server": true,
+    subagent: true,
+    rule: true,
+    hook: true,
+    knowledge: true,
+    pack: true,
+};
+export const isPublishableType = (type) => PUBLISHABLE_TYPES[type];
+//# sourceMappingURL=publishable-types.js.map

package/dist/src/recovery.d.ts

@@ -0,0 +1,11 @@
+/** The per-item outcome facts recovery selection reads. */
+export interface PublishRecoveryItem {
+    readonly id: string;
+    readonly status: string;
+    readonly reason?: string;
+}
+export declare const publishRecoverySelection: (results: ReadonlyArray<PublishRecoveryItem>) => {
+    readonly remainingItems: ReadonlyArray<string>;
+    readonly blockedDependents: ReadonlyArray<string>;
+};
+//# sourceMappingURL=recovery.d.ts.map

package/dist/src/recovery.js

@@ -0,0 +1,15 @@
+export const publishRecoverySelection = (results) => ({
+    // The continuation set covers everything not definitively published:
+    // failures, blocked dependents, indeterminate uploads (the re-run verifies
+    // byte-identical versions before retrying), and interrupted pending items.
+    remainingItems: results
+        .filter((result) => result.status === "failed" ||
+        result.status === "blocked" ||
+        result.status === "unknown" ||
+        (result.status === "pending" && result.reason === "interrupted"))
+        .map((result) => result.id),
+    blockedDependents: results
+        .filter((result) => result.status === "blocked")
+        .map((result) => result.id),
+});
+//# sourceMappingURL=recovery.js.map

package/dist/src/settlement.d.ts

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import { type PublishExtensionArgs, type PublishExtensionResponse, type RegistryClient, type RegistryClientFailure } from "@agentxm/registry-client";
+import { PublishFailed } from "./errors.js";
+/** Every failure a publish settlement can surface. */
+export type PublishSettlementFailure = PublishFailed | RegistryClientFailure;
+export type PublishSettlement = "response" | "readback" | "replay" | "unresolved";
+export type SettledPublish = {
+    readonly status: "published";
+    readonly settlement: Exclude<PublishSettlement, "unresolved">;
+    readonly response?: PublishExtensionResponse;
+} | {
+    readonly status: "unknown";
+    readonly settlement: "unresolved";
+    readonly reason: "settlement_unresolved" | "authorization_expired";
+    readonly error: PublishSettlementFailure;
+};
+/** Settle one exact immutable publish with bounded readback and one replay. */
+export declare const settlePublish: (client: Pick<RegistryClient, "publishExtension" | "getExactExtensionVersion">, args: PublishExtensionArgs) => Effect.Effect<SettledPublish, PublishSettlementFailure>;
+//# sourceMappingURL=settlement.d.ts.map

package/dist/src/settlement.js

@@ -0,0 +1,70 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { isRegistryClientFailure, } from "@agentxm/registry-client";
+import { PublishFailed } from "./errors.js";
+const isAmbiguousDispatch = (error) => error.category === "timeout" || error.metadata?.requestPolicy?.retryable === true;
+const readback = (client, args, remaining, lastError) => client
+    .getExactExtensionVersion({
+    owner: args.owner,
+    type: args.type,
+    name: args.name,
+    version: args.version,
+    ...(args.accessToken === undefined ? {} : { accessToken: args.accessToken }),
+})
+    .pipe(Effect.matchEffect({
+    onFailure: (error) => remaining <= 1
+        ? Effect.succeed({ kind: "absent", error })
+        : Effect.sleep("500 millis").pipe(Effect.andThen(readback(client, args, remaining - 1, error))),
+    onSuccess: (version) => {
+        if (Option.isSome(version)) {
+            return version.value.integrity === args.metadata.integrity
+                ? Effect.succeed({ kind: "matching" })
+                : Effect.fail(new PublishFailed({
+                    category: "conflict",
+                    detail: `Registry version ${args.owner}/${args.type}/${args.name}@${args.version} has different content.`,
+                }));
+        }
+        return remaining <= 1
+            ? Effect.succeed({
+                kind: "absent",
+                ...(lastError === undefined ? {} : { error: lastError }),
+            })
+            : Effect.sleep("500 millis").pipe(Effect.andThen(readback(client, args, remaining - 1, lastError)));
+    },
+}));
+const unresolved = (initialError, laterError) => {
+    const error = laterError ?? initialError;
+    return {
+        status: "unknown",
+        settlement: "unresolved",
+        reason: isRegistryClientFailure(error) && error.category === "auth"
+            ? "authorization_expired"
+            : "settlement_unresolved",
+        error,
+    };
+};
+/** Settle one exact immutable publish with bounded readback and one replay. */
+export const settlePublish = (client, args) => client.publishExtension(args).pipe(Effect.map((response) => ({
+    status: "published",
+    settlement: "response",
+    response,
+})), Effect.catch((initialError) => {
+    if (!isAmbiguousDispatch(initialError))
+        return Effect.fail(initialError);
+    return readback(client, args, 3).pipe(Effect.flatMap((firstReadback) => {
+        if (firstReadback.kind === "matching") {
+            const settled = { status: "published", settlement: "readback" };
+            return Effect.succeed(settled);
+        }
+        return client.publishExtension(args).pipe(Effect.map((response) => ({
+            status: "published",
+            settlement: "replay",
+            response,
+        })), Effect.catch((replayError) => replayError.category === "conflict"
+            ? Effect.fail(replayError)
+            : readback(client, args, 3).pipe(Effect.map((finalReadback) => finalReadback.kind === "matching"
+                ? { status: "published", settlement: "readback" }
+                : unresolved(initialError, finalReadback.error ?? replayError)))));
+    }));
+}));
+//# sourceMappingURL=settlement.js.map