@agentxm/registry-protocol 0.30.1 → 0.31.0

package/dist/src/unstable/registry/index.d.ts

@@ -4,6 +4,6 @@
  * @experimental This API is unstable and may change without notice.
  */
 export { type DiscoverPackagesResponse, DiscoverPackagesResponseSchema, type DiscoveryExtensionResult, DiscoveryExtensionResultSchema, type DiscoveryPackageResult, DiscoveryPackageResultSchema, type DiscoveryResolvedExtension, DiscoveryResolvedExtensionSchema, } from "./discover-schema.js";
-export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, type PackDependencyDescriptor, type PackDependencyFinding, PackDependencyFindingSchema, type PreviewPublicationSetRequest, PreviewPublicationSetRequestSchema, type PreviewPublicationSetResponse, PreviewPublicationSetResponseSchema, type ProspectivePackDependencyState, type ProspectivePublicationCandidate, type PublicationCandidateResult, type PublicationDependencySnapshot, type PublicationDependencyVersionSnapshot, type PublicationDescriptor, type PublicationPackResult, type PublicationTarget, type PublicationVisibilityInput, PublicationVisibilityInputSchema, type Sha256Hex, Sha256HexSchema, archiveSha256Hex, comparePublicationTargets, evaluateProspectivePackDependencies, evaluateProspectivePackDependencyState, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
+export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, type PackDependencyDescriptor, type PackDependencyFinding, PackDependencyFindingSchema, type PreviewPublicationSetRequest, PreviewPublicationSetRequestSchema, type PreviewPublicationSetResponse, PreviewPublicationSetResponseSchema, type PublicationCandidateResult, type PublicationDescriptor, type PublicationPackResult, type PublicationTarget, type PublicationVisibilityInput, PublicationVisibilityInputSchema, type Sha256Hex, Sha256HexSchema, archiveSha256Hex, formatPackDependencyFinding, comparePublicationTargets, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
 export { type DeprecationManagementView, DeprecationManagementViewSchema, type DeprecationReplacementIntent, DeprecationReplacementIntentSchema, DeprecationRevisionSchema, type DeprecationTransition, DeprecationTransitionSchema, type ExtensionIndex, ExtensionIndexSchema, type VersionEntry, VersionEntrySchema, packagesToPackageUrlParts, } from "./schema.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/registry/index.js

@@ -4,6 +4,6 @@
  * @experimental This API is unstable and may change without notice.
  */
 export { DiscoverPackagesResponseSchema, DiscoveryExtensionResultSchema, DiscoveryPackageResultSchema, DiscoveryResolvedExtensionSchema, } from "./discover-schema.js";
-export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, PackDependencyFindingSchema, PreviewPublicationSetRequestSchema, PreviewPublicationSetResponseSchema, PublicationVisibilityInputSchema, Sha256HexSchema, archiveSha256Hex, comparePublicationTargets, evaluateProspectivePackDependencies, evaluateProspectivePackDependencyState, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
+export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, PackDependencyFindingSchema, PreviewPublicationSetRequestSchema, PreviewPublicationSetResponseSchema, PublicationVisibilityInputSchema, Sha256HexSchema, archiveSha256Hex, formatPackDependencyFinding, comparePublicationTargets, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
 export { DeprecationManagementViewSchema, DeprecationReplacementIntentSchema, DeprecationRevisionSchema, DeprecationTransitionSchema, ExtensionIndexSchema, VersionEntrySchema, packagesToPackageUrlParts, } from "./schema.js";
 //# sourceMappingURL=index.js.map

package/dist/src/unstable/registry/publication-set.d.ts

@@ -1,9 +1,8 @@
 import * as Schema from "effect/Schema";
-import { type ExtensionName, type ExtensionType, type ExtensionVisibility } from "@agentxm/extension-model/unstable/extensions/common";
+import type { PackDependencyPolicyFinding } from "@agentxm/extension-model/unstable/packs/dependency-policy";
+import { type ExtensionName, type ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
 import { type Handle } from "@agentxm/extension-model/unstable/extensions/handle";
-import { VisibilityEvaluationSchema, VisibilityEvaluationUnavailableSchema } from "../publish/visibility.js";
 import { type Version, type VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
-import { type DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
 export declare const PUBLICATION_SET_CONTRACT: "publication-set-v2";
 export declare const MAX_PUBLICATION_SET_CANDIDATES = 100;
 export declare const Sha256HexSchema: Schema.String;
@@ -117,6 +116,8 @@ export declare const PackDependencyFindingSchema: Schema.Struct<{
     }>>;
 }>;
 export type PackDependencyFinding = typeof PackDependencyFindingSchema.Type;
+/** Encode domain findings without deciding pack admission or version selection. */
+export declare const formatPackDependencyFinding: (finding: PackDependencyPolicyFinding) => PackDependencyFinding;
 export declare const PreviewPublicationSetResponseSchema: Schema.Struct<{
     readonly contract: Schema.Literal<"publication-set-v2">;
     readonly publicationSetDigest: Schema.String;
@@ -248,29 +249,6 @@ export declare const PreviewPublicationSetResponseSchema: Schema.Struct<{
 export type PreviewPublicationSetResponse = typeof PreviewPublicationSetResponseSchema.Type;
 export type PublicationCandidateResult = PreviewPublicationSetResponse["candidates"][number];
 export type PublicationPackResult = PreviewPublicationSetResponse["packs"][number];
-export interface PublicationDependencyVersionSnapshot {
-    readonly version: string;
-    readonly status: string;
-    readonly yanked: boolean;
-    readonly purged: boolean;
-}
-export interface PublicationDependencySnapshot {
-    readonly dependency: PackDependencyDescriptor;
-    readonly exists: boolean;
-    readonly visibility: string | null;
-    readonly lifecycleState: string | null;
-    readonly deprecation: DeprecationView | null;
-    readonly versions: ReadonlyArray<PublicationDependencyVersionSnapshot>;
-}
-export type ProspectivePublicationCandidate = {
-    readonly descriptor: PublicationDescriptor;
-    readonly kind: "resolved";
-    readonly visibility: typeof VisibilityEvaluationSchema.Type;
-} | {
-    readonly descriptor: PublicationDescriptor;
-    readonly kind: "unavailable";
-    readonly visibility: typeof VisibilityEvaluationUnavailableSchema.Type;
-};
 export declare const comparePublicationTargets: (left: PublicationTarget, right: PublicationTarget) => number;
 export declare const normalizePublicationDescriptor: (descriptor: PublicationDescriptor) => PublicationDescriptor;
 export declare const normalizePublicationSet: (descriptors: ReadonlyArray<PublicationDescriptor>) => ReadonlyArray<PublicationDescriptor>;
@@ -279,25 +257,5 @@ export declare const publicationSetDigest: (descriptors: ReadonlyArray<Publicati
 export declare const archiveSha256Hex: (archive: Uint8Array) => Sha256Hex;
 export declare const publicationTargetKey: (target: PublicationTarget) => string;
 export declare const validatePublicationDescriptors: (descriptors: ReadonlyArray<PublicationDescriptor>) => ReadonlyArray<PublicationDescriptor>;
-export declare const evaluateProspectivePackDependencies: (input: {
-    readonly packVisibility: ExtensionVisibility;
-    readonly dependencies: ReadonlyArray<PackDependencyDescriptor>;
-    readonly snapshots: ReadonlyArray<PublicationDependencySnapshot>;
-    readonly candidates: ReadonlyArray<ProspectivePublicationCandidate>;
-}) => ReadonlyArray<PackDependencyFinding>;
-export interface ProspectivePackDependencyState {
-    readonly findings: ReadonlyArray<PackDependencyFinding>;
-    readonly resolutions: PublicationPackResult["resolutions"];
-}
-/**
- * Evaluate dependency admission and expose the exact version an ordinary
- * Registry consumer would resolve from the same prospective snapshot.
- */
-export declare const evaluateProspectivePackDependencyState: (input: {
-    readonly packVisibility: ExtensionVisibility;
-    readonly dependencies: ReadonlyArray<PackDependencyDescriptor>;
-    readonly snapshots: ReadonlyArray<PublicationDependencySnapshot>;
-    readonly candidates: ReadonlyArray<ProspectivePublicationCandidate>;
-}) => ProspectivePackDependencyState;
 export declare const validatePublicationSetResponse: (descriptors: ReadonlyArray<PublicationDescriptor>, response: PreviewPublicationSetResponse) => PreviewPublicationSetResponse;
 //# sourceMappingURL=publication-set.d.ts.map

package/dist/src/unstable/registry/publication-set.js

@@ -7,7 +7,7 @@ import { formatFqn } from "@agentxm/extension-model/unstable/extensions/fqn";
 import { HandleSchema } from "@agentxm/extension-model/unstable/extensions/handle";
 import { VisibilityEvaluationSchema, VisibilityEvaluationUnavailableSchema, VisibilityIntentSchema, } from "../publish/visibility.js";
 import { VersionRangeSchema, VersionSchema, } from "@agentxm/extension-model/unstable/version-constraints";
-import { DeprecationViewSchema, } from "@agentxm/extension-model/unstable/extensions/deprecation";
+import { DeprecationViewSchema } from "@agentxm/extension-model/unstable/extensions/deprecation";
 export const PUBLICATION_SET_CONTRACT = "publication-set-v2";
 export const MAX_PUBLICATION_SET_CANDIDATES = 100;
 export const Sha256HexSchema = Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)).annotate({
@@ -67,6 +67,104 @@ export const PackDependencyFindingSchema = Schema.Struct({
     message: Schema.String,
     suggestions: Schema.Array(SuggestedActionSchema),
 }).annotate({ identifier: "PackDependencyFinding" });
+const packDependencyGuidance = (finding) => {
+    const fqn = formatFqn(finding.dependency);
+    switch (finding.reason) {
+        case "missing":
+            return {
+                explanation: "that extension does not exist in the registry",
+                suggestions: [
+                    {
+                        description: `Publish ${fqn} or correct the dependency identity`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            };
+        case "not-public":
+            return {
+                explanation: "that extension is not public",
+                suggestions: [{ description: `Make ${fqn} public or depend on a public extension` }],
+            };
+        case "selected-unavailable":
+            return {
+                explanation: "that selected target is unavailable",
+                suggestions: [
+                    {
+                        description: `Verify authority and availability for ${fqn}, then preview the complete set again`,
+                    },
+                ],
+            };
+        case "selected-new-private":
+            return {
+                explanation: "the selected dependency will remain private",
+                suggestions: [
+                    {
+                        description: `Publish ${fqn} as public, then preview the complete set again`,
+                        cmd: `axm publish ${fqn} --visibility public`,
+                    },
+                ],
+            };
+        case "selected-existing-private":
+            return {
+                explanation: "the selected dependency will remain private",
+                suggestions: [
+                    { description: `Make ${fqn} public explicitly, then preview the complete set again` },
+                ],
+            };
+        case "lifecycle-unavailable":
+            return {
+                explanation: "that extension is not active",
+                suggestions: [{ description: `Restore ${fqn} to active state or remove it from the pack` }],
+            };
+        case "no-installable-version":
+            return {
+                explanation: "it has no installable versions",
+                suggestions: [
+                    {
+                        description: `Publish an installable version of ${fqn} or remove it from the pack`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            };
+        case "range-unsatisfied":
+            return {
+                explanation: "no installable version satisfies the requested range",
+                suggestions: [
+                    {
+                        description: `Publish a version of ${fqn} satisfying "${finding.dependency.range}" or correct the requested range`,
+                        cmd: `axm publish ${fqn}`,
+                    },
+                ],
+            };
+        case "deprecated":
+            return {
+                explanation: "resolves to a deprecated extension",
+                suggestions: [
+                    { description: `Prefer a supported replacement for ${fqn} when one is available` },
+                ],
+            };
+    }
+};
+/** Encode domain findings without deciding pack admission or version selection. */
+export const formatPackDependencyFinding = (finding) => {
+    const { reason, ...facts } = finding;
+    const guidance = packDependencyGuidance(finding);
+    const subject = `Dependency ${formatFqn(finding.dependency)} requests range "${finding.dependency.range}"`;
+    return {
+        ...facts,
+        kind: "advisory",
+        ruleId: reason === "deprecated" ? "pack/dependency-deprecated" : "pack/dependency-version-resolvable",
+        reason: reason === "missing" || reason === "not-public" || reason === "selected-unavailable"
+            ? "target-unavailable"
+            : reason,
+        location: { file: "pack.json" },
+        path: "./pack.json",
+        message: reason === "deprecated"
+            ? `${subject} and ${guidance.explanation}.`
+            : `${subject}, but ${guidance.explanation}.`,
+        suggestions: guidance.suggestions,
+    };
+};
 const ResolvedPublicationCandidateSchema = Schema.Struct({
     kind: Schema.Literal("resolved"),
     target: PublicationTargetSchema,
@@ -163,267 +261,7 @@ export const validatePublicationDescriptors = (descriptors) => {
     }
     return normalizePublicationSet(descriptors);
 };
-const findingBase = (finding) => ({
-    kind: "advisory",
-    location: { file: "pack.json" },
-    path: "./pack.json",
-    ...finding,
-});
-const dependencyError = (input) => {
-    const fqn = formatFqn(input.snapshot.dependency);
-    return findingBase({
-        ruleId: "pack/dependency-version-resolvable",
-        severity: "error",
-        reason: input.reason,
-        dependency: input.snapshot.dependency,
-        ...(input.discloseState !== true
-            ? {}
-            : {
-                ...(input.snapshot.visibility === "public" || input.snapshot.visibility === "private"
-                    ? { effectiveVisibility: input.snapshot.visibility }
-                    : {}),
-                ...(input.snapshot.lifecycleState === null
-                    ? {}
-                    : { lifecycle: input.snapshot.lifecycleState === "active" ? "active" : "unavailable" }),
-            }),
-        message: `Dependency ${fqn} requests range "${input.snapshot.dependency.range}", but ${input.explanation}.`,
-        suggestions: input.suggestions,
-    });
-};
-const evaluateDependencySnapshot = (snapshot, packVisibility) => {
-    const fqn = formatFqn(snapshot.dependency);
-    if (!snapshot.exists) {
-        return [
-            dependencyError({
-                snapshot,
-                reason: "target-unavailable",
-                explanation: "that extension does not exist in the registry",
-                suggestions: [
-                    {
-                        description: `Publish ${fqn} or correct the dependency identity`,
-                        cmd: `axm publish ${fqn}`,
-                    },
-                ],
-            }),
-        ];
-    }
-    if (packVisibility === "public" && snapshot.visibility !== "public") {
-        return [
-            dependencyError({
-                snapshot,
-                reason: "target-unavailable",
-                explanation: "that extension is not public",
-                suggestions: [{ description: `Make ${fqn} public or depend on a public extension` }],
-            }),
-        ];
-    }
-    if (snapshot.lifecycleState !== "active") {
-        return [
-            dependencyError({
-                snapshot,
-                reason: "lifecycle-unavailable",
-                explanation: "that extension is not active",
-                discloseState: true,
-                suggestions: [{ description: `Restore ${fqn} to active state or remove it from the pack` }],
-            }),
-        ];
-    }
-    const installable = snapshot.versions.filter((version) => version.status === "available" && !version.yanked && !version.purged);
-    if (installable.length === 0) {
-        return [
-            dependencyError({
-                snapshot,
-                reason: "no-installable-version",
-                explanation: "it has no installable versions",
-                discloseState: true,
-                suggestions: [
-                    {
-                        description: `Publish an installable version of ${fqn} or remove it from the pack`,
-                        cmd: `axm publish ${fqn}`,
-                    },
-                ],
-            }),
-        ];
-    }
-    if (!installable.some((candidate) => semver.satisfies(candidate.version, snapshot.dependency.range))) {
-        return [
-            dependencyError({
-                snapshot,
-                reason: "range-unsatisfied",
-                explanation: "no installable version satisfies the requested range",
-                discloseState: true,
-                suggestions: [
-                    {
-                        description: `Publish a version of ${fqn} satisfying "${snapshot.dependency.range}" or correct the requested range`,
-                        cmd: `axm publish ${fqn}`,
-                    },
-                ],
-            }),
-        ];
-    }
-    return snapshot.deprecation !== null
-        ? [
-            findingBase({
-                ruleId: "pack/dependency-deprecated",
-                severity: "warning",
-                reason: "deprecated",
-                dependency: snapshot.dependency,
-                effectiveVisibility: snapshot.visibility === "private" ? "private" : "public",
-                lifecycle: "active",
-                deprecation: snapshot.deprecation,
-                message: `Dependency ${fqn} requests range "${snapshot.dependency.range}" and resolves to a deprecated extension.`,
-                suggestions: [
-                    { description: `Prefer a supported replacement for ${fqn} when one is available` },
-                ],
-            }),
-        ]
-        : [];
-};
 const dependencyIdentityKey = (dependency) => `${dependency.owner}\u0000${dependency.type}\u0000${dependency.name}`;
-export const evaluateProspectivePackDependencies = (input) => {
-    const snapshots = new Map(input.snapshots.map((snapshot) => [dependencyIdentityKey(snapshot.dependency), snapshot]));
-    const candidates = new Map(input.candidates.map((candidate) => [
-        publicationIdentityKey(candidate.descriptor.target),
-        candidate,
-    ]));
-    return input.dependencies
-        .flatMap((dependency) => {
-        const current = snapshots.get(dependencyIdentityKey(dependency)) ??
-            {
-                dependency,
-                exists: false,
-                visibility: null,
-                lifecycleState: null,
-                deprecation: null,
-                versions: [],
-            };
-        const selected = candidates.get(dependencyIdentityKey(dependency));
-        if (selected === undefined)
-            return evaluateDependencySnapshot(current, input.packVisibility);
-        if (selected.kind === "unavailable") {
-            return [
-                dependencyError({
-                    snapshot: current,
-                    reason: "target-unavailable",
-                    explanation: "that selected target is unavailable",
-                    suggestions: [
-                        {
-                            description: `Verify authority and availability for ${formatFqn(dependency)}, then preview the complete set again`,
-                        },
-                    ],
-                }),
-            ];
-        }
-        if (input.packVisibility === "public" && selected.visibility.resolved?.value === "private") {
-            return [
-                dependencyError({
-                    snapshot: { ...current, exists: true, visibility: "private" },
-                    reason: current.exists ? "selected-existing-private" : "selected-new-private",
-                    explanation: "the selected dependency will remain private",
-                    discloseState: true,
-                    suggestions: current.exists
-                        ? [
-                            {
-                                description: `Make ${formatFqn(dependency)} public explicitly, then preview the complete set again`,
-                            },
-                        ]
-                        : [
-                            {
-                                description: `Publish ${formatFqn(dependency)} as public, then preview the complete set again`,
-                                cmd: `axm publish ${formatFqn(dependency)} --visibility public`,
-                            },
-                        ],
-                }),
-            ];
-        }
-        return evaluateDependencySnapshot({
-            ...current,
-            exists: true,
-            visibility: selected.visibility.resolved?.value ?? current.visibility,
-            lifecycleState: current.exists ? current.lifecycleState : "active",
-            versions: selected.descriptor.participation === "publish"
-                ? [
-                    ...current.versions,
-                    {
-                        version: selected.descriptor.target.version,
-                        status: "available",
-                        yanked: false,
-                        purged: false,
-                    },
-                ]
-                : current.versions,
-        }, input.packVisibility);
-    })
-        .sort((left, right) => compareText(formatFqn(left.dependency), formatFqn(right.dependency)) ||
-        compareText(left.dependency.range, right.dependency.range));
-};
-/**
- * Evaluate dependency admission and expose the exact version an ordinary
- * Registry consumer would resolve from the same prospective snapshot.
- */
-export const evaluateProspectivePackDependencyState = (input) => {
-    const findings = evaluateProspectivePackDependencies(input);
-    const snapshots = new Map(input.snapshots.map((snapshot) => [dependencyIdentityKey(snapshot.dependency), snapshot]));
-    const candidates = new Map(input.candidates.map((candidate) => [
-        publicationIdentityKey(candidate.descriptor.target),
-        candidate,
-    ]));
-    const resolutions = input.dependencies.flatMap((dependency) => {
-        const current = snapshots.get(dependencyIdentityKey(dependency)) ??
-            {
-                dependency,
-                exists: false,
-                visibility: null,
-                lifecycleState: null,
-                deprecation: null,
-                versions: [],
-            };
-        const selected = candidates.get(dependencyIdentityKey(dependency));
-        if (selected?.kind === "unavailable" ||
-            (input.packVisibility === "public" && selected?.visibility.resolved?.value === "private")) {
-            return [];
-        }
-        const prospective = selected === undefined
-            ? current
-            : {
-                ...current,
-                exists: true,
-                visibility: selected.visibility.resolved?.value ?? current.visibility,
-                lifecycleState: current.exists ? current.lifecycleState : "active",
-                versions: selected.descriptor.participation === "publish"
-                    ? [
-                        ...current.versions,
-                        {
-                            version: selected.descriptor.target.version,
-                            status: "available",
-                            yanked: false,
-                            purged: false,
-                        },
-                    ]
-                    : current.versions,
-            };
-        if (!prospective.exists ||
-            (input.packVisibility === "public" && prospective.visibility !== "public") ||
-            prospective.lifecycleState !== "active") {
-            return [];
-        }
-        const effectiveVersion = semver.maxSatisfying(prospective.versions
-            .filter((version) => version.status === "available" && !version.yanked && !version.purged)
-            .map((version) => version.version), dependency.range);
-        return effectiveVersion === null
-            ? []
-            : [
-                {
-                    dependency,
-                    effectiveVersion: Schema.decodeUnknownSync(VersionSchema)(effectiveVersion),
-                },
-            ];
-    });
-    return {
-        findings,
-        resolutions: [...resolutions].sort((left, right) => compareDependencies(left.dependency, right.dependency)),
-    };
-};
 export const validatePublicationSetResponse = (descriptors, response) => {
     const normalized = validatePublicationDescriptors(descriptors);
     const expectedDigest = publicationSetDigest(normalized);

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.30.1",
+    "@agentxm/extension-model": "^0.31.0",
     "effect": "4.0.0-rc.115",
     "semver": "^7.8.5"
   },
@@ -72,5 +72,5 @@
     "url": "https://github.com/agentxm/axm.git"
   },
   "type": "module",
-  "version": "0.30.1"
+  "version": "0.31.0"
 }