@agentxm/extension-model 0.34.0 → 0.35.0

package/dist/src/unstable/extensions/common.d.ts

@@ -427,6 +427,26 @@ export type ExtensionFqnParts = Schema.Schema.Type<typeof ExtensionFqnPartsSchem
  * @experimental This API is unstable and may change without notice.
  */
 export declare const parseExtensionFqnParts: (input: string) => ExtensionFqnParts | undefined;
+/**
+ * A reference split into the name it identifies and the constraint appended
+ * to it. The constraint is everything after the first `@` that follows the
+ * last `/`, because the owner segment also starts with `@`; a trailing `@`
+ * yields an empty constraint for the caller to reject.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SplitExtensionReference {
+    readonly name: string;
+    readonly constraint: string | undefined;
+}
+/**
+ * Split `@owner/<plural>/name[@constraint]` into its name and constraint.
+ * This is the one place the separator between a name and its constraint is
+ * decided.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const splitExtensionReference: (input: string) => SplitExtensionReference;
 /**
  * Parse an extension spec string (with optional version constraint) into parts.
  * Strips the version constraint suffix and returns the validated FQN parts.
@@ -477,14 +497,6 @@ export declare const PackFqnSchema: Schema.String;
  * @experimental This API is unstable and may change without notice.
  */
 export type PackFqn = Schema.Schema.Type<typeof PackFqnSchema>;
-/**
- * Extension spec — fully qualified extension name with an optional version
- * constraint suffix. Accepts `@owner/type/name` or `@owner/type/name@constraint`
- * where the FQN portion validates through ExtensionFqnSchema and the optional
- * constraint validates as a semver VersionRange.
- *
- * @experimental This API is unstable and may change without notice.
- */
 export declare const ExtensionSpecSchema: Schema.brand<Schema.NonEmptyString, "ExtensionSpec">;
 /**
  * Inferred type for ExtensionSpec schema.

package/dist/src/unstable/extensions/common.js

@@ -360,17 +360,26 @@ export const parseExtensionFqnParts = (input) => {
     return Result.isSuccess(result) ? result.success : undefined;
 };
 /**
- * Parse an extension spec string (with optional version constraint) into parts.
- * Strips the version constraint suffix and returns the validated FQN parts.
+ * Split `@owner/<plural>/name[@constraint]` into its name and constraint.
+ * This is the one place the separator between a name and its constraint is
+ * decided.
  *
  * @experimental This API is unstable and may change without notice.
  */
-export const parseExtensionSpecParts = (input) => {
+export const splitExtensionReference = (input) => {
     const lastSlash = input.lastIndexOf("/");
     const constraintAt = lastSlash > 0 ? input.indexOf("@", lastSlash + 1) : -1;
-    const fqnPart = constraintAt > 0 ? input.slice(0, constraintAt) : input;
-    return parseExtensionFqnParts(fqnPart);
+    return constraintAt > 0
+        ? { name: input.slice(0, constraintAt), constraint: input.slice(constraintAt + 1) }
+        : { name: input, constraint: undefined };
 };
+/**
+ * Parse an extension spec string (with optional version constraint) into parts.
+ * Strips the version constraint suffix and returns the validated FQN parts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const parseExtensionSpecParts = (input) => parseExtensionFqnParts(splitExtensionReference(input).name);
 const INVALID_EXTENSION_FQN_MESSAGE = "Expected fully qualified name in @handle/(skills|mcps|subagents|rules|hooks|knowledge|packs)/name form";
 /**
  * Fully qualified name string schema validated against the composed handle,
@@ -425,24 +434,21 @@ export const PackFqnSchema = Schema.String.pipe(Schema.check(Schema.isPattern(PA
  *
  * @experimental This API is unstable and may change without notice.
  */
+/** The constraint issue of a split reference, or none when it has none or it is valid. */
+const constraintIssue = (constraint) => {
+    if (constraint === undefined)
+        return undefined;
+    const constraintResult = Schema.decodeUnknownResult(VersionRangeSchema)(constraint);
+    return Result.isFailure(constraintResult)
+        ? `Expected valid version constraint after @, got: ${constraint}`
+        : undefined;
+};
 export const ExtensionSpecSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.makeFilter((value) => {
-    // Find the constraint separator: the @ after the last slash
-    const lastSlash = value.lastIndexOf("/");
-    const constraintAt = lastSlash > 0 ? value.indexOf("@", lastSlash + 1) : -1;
-    const fqnPart = constraintAt > 0 ? value.slice(0, constraintAt) : value;
-    const constraintPart = constraintAt > 0 ? value.slice(constraintAt + 1) : undefined;
-    // Validate FQN portion
-    if (parseExtensionFqnParts(fqnPart) === undefined) {
+    const { name, constraint } = splitExtensionReference(value);
+    if (parseExtensionFqnParts(name) === undefined) {
         return `Expected extension spec in @handle/type/name[@constraint] form, got: ${value}`;
     }
-    // Validate constraint portion if present
-    if (constraintPart !== undefined) {
-        const constraintResult = Schema.decodeUnknownResult(VersionRangeSchema)(constraintPart);
-        if (Result.isFailure(constraintResult)) {
-            return `Expected valid version constraint after @, got: ${constraintPart}`;
-        }
-    }
-    return undefined;
+    return constraintIssue(constraint);
 })), Schema.check(Schema.isPattern(EXTENSION_SPEC_PATTERN, {
     message: "Expected extension spec in @handle/type/name[@constraint] form",
 })), Schema.annotate({
@@ -460,20 +466,11 @@ export const ExtensionSpecSchema = Schema.NonEmptyString.pipe(Schema.check(Schem
  * @experimental This API is unstable and may change without notice.
  */
 export const PackSpecSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.makeFilter((value) => {
-    const lastSlash = value.lastIndexOf("/");
-    const constraintAt = lastSlash > 0 ? value.indexOf("@", lastSlash + 1) : -1;
-    const fqnPart = constraintAt > 0 ? value.slice(0, constraintAt) : value;
-    const constraintPart = constraintAt > 0 ? value.slice(constraintAt + 1) : undefined;
-    if (!PACK_FQN_PATTERN.test(fqnPart)) {
+    const { name, constraint } = splitExtensionReference(value);
+    if (!PACK_FQN_PATTERN.test(name)) {
         return `Expected pack spec in @handle/packs/name[@constraint] form, got: ${value}`;
     }
-    if (constraintPart !== undefined) {
-        const constraintResult = Schema.decodeUnknownResult(VersionRangeSchema)(constraintPart);
-        if (Result.isFailure(constraintResult)) {
-            return `Expected valid version constraint after @, got: ${constraintPart}`;
-        }
-    }
-    return undefined;
+    return constraintIssue(constraint);
 })), Schema.check(Schema.isPattern(PACK_SPEC_PATTERN, {
     message: "Expected pack spec in @handle/packs/name[@constraint] form",
 })), Schema.annotate({

package/dist/src/unstable/extensions/deprecation.d.ts

@@ -9,6 +9,9 @@
  * @experimental This API is unstable and may change without notice.
  */
 import * as Schema from "effect/Schema";
+export declare const DeprecationReasons: readonly ["superseded", "obsolete", "unmaintained", "other"];
+export declare const DeprecationReasonSchema: Schema.Literals<readonly ["superseded", "obsolete", "unmaintained", "other"]>;
+export type DeprecationReason = typeof DeprecationReasonSchema.Type;
 export declare const DeprecationReplacementSchema: Schema.Union<readonly [Schema.Struct<{
     readonly status: Schema.Literal<"available">;
     readonly fqn: Schema.String;
@@ -18,7 +21,24 @@ export declare const DeprecationReplacementSchema: Schema.Union<readonly [Schema
 }>]>;
 export declare const DeprecationViewSchema: Schema.Union<readonly [Schema.Struct<{
     readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly reason: Schema.Literal<"superseded">;
+    readonly message: Schema.optional<Schema.String>;
+    readonly replacement: Schema.Union<readonly [Schema.Struct<{
+        readonly status: Schema.Literal<"available">;
+        readonly fqn: Schema.String;
+    }>, Schema.Struct<{
+        readonly status: Schema.Literal<"unavailable">;
+        readonly fqn: Schema.optional<Schema.String>;
+    }>]>;
+}>, Schema.Struct<{
+    readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly reason: Schema.Literal<"obsolete">;
     readonly message: Schema.String;
+    readonly replacement: Schema.optional<Schema.Never>;
+}>, Schema.Struct<{
+    readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly reason: Schema.Literal<"unmaintained">;
+    readonly message: Schema.optional<Schema.String>;
     readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
         readonly status: Schema.Literal<"available">;
         readonly fqn: Schema.String;
@@ -28,14 +48,15 @@ export declare const DeprecationViewSchema: Schema.Union<readonly [Schema.Struct
     }>]>>;
 }>, Schema.Struct<{
     readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
-    readonly message: Schema.optional<Schema.String>;
-    readonly replacement: Schema.Union<readonly [Schema.Struct<{
+    readonly reason: Schema.Literal<"other">;
+    readonly message: Schema.String;
+    readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
         readonly status: Schema.Literal<"available">;
         readonly fqn: Schema.String;
     }>, Schema.Struct<{
         readonly status: Schema.Literal<"unavailable">;
         readonly fqn: Schema.optional<Schema.String>;
-    }>]>;
+    }>]>>;
 }>]>;
 export type DeprecationReplacement = typeof DeprecationReplacementSchema.Type;
 export type DeprecationView = typeof DeprecationViewSchema.Type;

package/dist/src/unstable/extensions/deprecation.js

@@ -13,7 +13,12 @@ import { DateTimeUtcSchema } from "../date-time.js";
 import { ExtensionFqnSchema } from "./common.js";
 const DeprecationMessageSchema = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(500)).annotate({
     identifier: "DeprecationMessage",
-    description: "Concise publisher guidance for consumers of a deprecated extension.",
+    description: "Optional publisher notes for consumers of a deprecated extension.",
+});
+export const DeprecationReasons = ["superseded", "obsolete", "unmaintained", "other"];
+export const DeprecationReasonSchema = Schema.Literals(DeprecationReasons).annotate({
+    identifier: "DeprecationReason",
+    description: "The publisher's structured reason for deprecating an extension.",
 });
 export const DeprecationReplacementSchema = Schema.Union([
     Schema.Struct({
@@ -31,13 +36,27 @@ export const DeprecationReplacementSchema = Schema.Union([
 export const DeprecationViewSchema = Schema.Union([
     Schema.Struct({
         deprecatedAt: DateTimeUtcSchema,
+        reason: Schema.Literal("superseded"),
+        message: Schema.optional(DeprecationMessageSchema),
+        replacement: DeprecationReplacementSchema,
+    }),
+    Schema.Struct({
+        deprecatedAt: DateTimeUtcSchema,
+        reason: Schema.Literal("obsolete"),
         message: DeprecationMessageSchema,
-        replacement: Schema.optional(DeprecationReplacementSchema),
+        replacement: Schema.optional(Schema.Never),
     }),
     Schema.Struct({
         deprecatedAt: DateTimeUtcSchema,
+        reason: Schema.Literal("unmaintained"),
         message: Schema.optional(DeprecationMessageSchema),
-        replacement: DeprecationReplacementSchema,
+        replacement: Schema.optional(DeprecationReplacementSchema),
+    }),
+    Schema.Struct({
+        deprecatedAt: DateTimeUtcSchema,
+        reason: Schema.Literal("other"),
+        message: DeprecationMessageSchema,
+        replacement: Schema.optional(DeprecationReplacementSchema),
     }),
 ]).annotate({
     identifier: "DeprecationView",

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

@@ -3,7 +3,7 @@
  *
  * @experimental This API is unstable and may change without notice.
  */
-export { AgentIdSchema, type Author, AuthorSchema, CONTAINER_EXTENSION_TYPES, CommonManifestBaseFields, type ConfigurableAgentId, ConfigurableAgentIdSchema, type ContainerType, EXTENSION_NAME_PATTERN, INSTALLABLE_FROM_BY_TYPE, type ExtensionDependencyConstraintMap, ExtensionDependencyConstraintMapSchema, type ExtensionFqn, type ExtensionFqnParts, ExtensionFqnPartsSchema, ExtensionFqnSchema, type ExtensionName, ExtensionNameSchema, type ExtensionSpec, ExtensionSpecSchema, type ExtensionSourceFamily, type ExtensionType, type ExtensionTypePlural, ExtensionTypePluralSchema, ExtensionTypeSchema, type ExtensionVisibility, ExtensionVisibilitySchema, FQN_PATTERN, LicenseSchema, NON_PACK_FQN_PATTERN, type NonPackExtensionDependencyConstraintMap, NonPackExtensionDependencyConstraintMapSchema, type NonPackExtensionFqn, NonPackExtensionFqnSchema, type NonPackExtensionTypePlural, NonPackManifestFields, PACK_FQN_PATTERN, PER_AGENT_EXTENSION_TYPES, type PackFqn, PackFqnSchema, type PackMemberConstraint, PackMemberConstraintMapSchema, PackMemberConstraintSchema, type PackMemberConstraintMap, type PackMemberRegistrySource, PackMemberRegistrySourceSchema, packMemberRegistrySource, packMemberVersionRange, type PackSpec, PackSpecSchema, type PerAgentType, type PublishOptions, PublishOptionsSchema, type WorkspaceCapabilityType, decodeExtensionNameSync, extensionTypeFromPlural, extensionTypeLabels, extensionTypePluralLabels, extensionTypePluralSegments, extensionTypePluralSentenceLabels, extensionTypeSentenceLabels, extensionTypeToPlural, extensionTypes, extensionSourceFamilies, extensionTypesInstallableFrom, isInstallableFrom, isExtensionType, isExtensionTypePlural, nonPackExtensionTypePluralSegments, parseExtensionFqnParts, parseExtensionSpecParts, toAuthor, toExtensionType, toExtensionTypePlural, } from "./common.js";
+export { AgentIdSchema, type Author, AuthorSchema, CONTAINER_EXTENSION_TYPES, CommonManifestBaseFields, type ConfigurableAgentId, ConfigurableAgentIdSchema, type ContainerType, EXTENSION_NAME_PATTERN, INSTALLABLE_FROM_BY_TYPE, type ExtensionDependencyConstraintMap, ExtensionDependencyConstraintMapSchema, type ExtensionFqn, type ExtensionFqnParts, ExtensionFqnPartsSchema, ExtensionFqnSchema, type ExtensionName, ExtensionNameSchema, type ExtensionSpec, ExtensionSpecSchema, type ExtensionSourceFamily, type ExtensionType, type ExtensionTypePlural, ExtensionTypePluralSchema, ExtensionTypeSchema, type ExtensionVisibility, ExtensionVisibilitySchema, FQN_PATTERN, LicenseSchema, NON_PACK_FQN_PATTERN, type NonPackExtensionDependencyConstraintMap, NonPackExtensionDependencyConstraintMapSchema, type NonPackExtensionFqn, NonPackExtensionFqnSchema, type NonPackExtensionTypePlural, NonPackManifestFields, PACK_FQN_PATTERN, PER_AGENT_EXTENSION_TYPES, type PackFqn, PackFqnSchema, type PackMemberConstraint, PackMemberConstraintMapSchema, PackMemberConstraintSchema, type PackMemberConstraintMap, type PackMemberRegistrySource, PackMemberRegistrySourceSchema, packMemberRegistrySource, packMemberVersionRange, type PackSpec, PackSpecSchema, type PerAgentType, type PublishOptions, PublishOptionsSchema, type WorkspaceCapabilityType, decodeExtensionNameSync, extensionTypeFromPlural, extensionTypeLabels, extensionTypePluralLabels, extensionTypePluralSegments, extensionTypePluralSentenceLabels, extensionTypeSentenceLabels, extensionTypeToPlural, extensionTypes, extensionSourceFamilies, extensionTypesInstallableFrom, isInstallableFrom, isExtensionType, isExtensionTypePlural, nonPackExtensionTypePluralSegments, parseExtensionFqnParts, parseExtensionSpecParts, splitExtensionReference, type SplitExtensionReference, toAuthor, toExtensionType, toExtensionTypePlural, } from "./common.js";
 export { type ReleaseAgeExcludePattern, ReleaseAgeExcludePatternSchema, matchesReleaseAgeExcludePattern, } from "./fqn-pattern.js";
 export { FqnInvalidError, formatFqn, parseFqn, parseFqnOrThrow } from "./fqn.js";
 export { HANDLE_PATTERN, HANDLE_PATTERN_SOURCE, type Handle, HandleSchema, SLUG_PATTERN, SLUG_PATTERN_SOURCE, type Slug, SlugSchema, decodeHandleSync, decodeSlugSync, handleFromSlug, normalizeHandle, normalizeSlug, slugFromHandle, } from "./handle.js";

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

@@ -3,7 +3,7 @@
  *
  * @experimental This API is unstable and may change without notice.
  */
-export { AgentIdSchema, AuthorSchema, CONTAINER_EXTENSION_TYPES, CommonManifestBaseFields, ConfigurableAgentIdSchema, EXTENSION_NAME_PATTERN, INSTALLABLE_FROM_BY_TYPE, ExtensionDependencyConstraintMapSchema, ExtensionFqnPartsSchema, ExtensionFqnSchema, ExtensionNameSchema, ExtensionSpecSchema, ExtensionTypePluralSchema, ExtensionTypeSchema, ExtensionVisibilitySchema, FQN_PATTERN, LicenseSchema, NON_PACK_FQN_PATTERN, NonPackExtensionDependencyConstraintMapSchema, NonPackExtensionFqnSchema, NonPackManifestFields, PACK_FQN_PATTERN, PER_AGENT_EXTENSION_TYPES, PackFqnSchema, PackMemberConstraintMapSchema, PackMemberConstraintSchema, PackMemberRegistrySourceSchema, packMemberRegistrySource, packMemberVersionRange, PackSpecSchema, PublishOptionsSchema, decodeExtensionNameSync, extensionTypeFromPlural, extensionTypeLabels, extensionTypePluralLabels, extensionTypePluralSegments, extensionTypePluralSentenceLabels, extensionTypeSentenceLabels, extensionTypeToPlural, extensionTypes, extensionSourceFamilies, extensionTypesInstallableFrom, isInstallableFrom, isExtensionType, isExtensionTypePlural, nonPackExtensionTypePluralSegments, parseExtensionFqnParts, parseExtensionSpecParts, toAuthor, toExtensionType, toExtensionTypePlural, } from "./common.js";
+export { AgentIdSchema, AuthorSchema, CONTAINER_EXTENSION_TYPES, CommonManifestBaseFields, ConfigurableAgentIdSchema, EXTENSION_NAME_PATTERN, INSTALLABLE_FROM_BY_TYPE, ExtensionDependencyConstraintMapSchema, ExtensionFqnPartsSchema, ExtensionFqnSchema, ExtensionNameSchema, ExtensionSpecSchema, ExtensionTypePluralSchema, ExtensionTypeSchema, ExtensionVisibilitySchema, FQN_PATTERN, LicenseSchema, NON_PACK_FQN_PATTERN, NonPackExtensionDependencyConstraintMapSchema, NonPackExtensionFqnSchema, NonPackManifestFields, PACK_FQN_PATTERN, PER_AGENT_EXTENSION_TYPES, PackFqnSchema, PackMemberConstraintMapSchema, PackMemberConstraintSchema, PackMemberRegistrySourceSchema, packMemberRegistrySource, packMemberVersionRange, PackSpecSchema, PublishOptionsSchema, decodeExtensionNameSync, extensionTypeFromPlural, extensionTypeLabels, extensionTypePluralLabels, extensionTypePluralSegments, extensionTypePluralSentenceLabels, extensionTypeSentenceLabels, extensionTypeToPlural, extensionTypes, extensionSourceFamilies, extensionTypesInstallableFrom, isInstallableFrom, isExtensionType, isExtensionTypePlural, nonPackExtensionTypePluralSegments, parseExtensionFqnParts, parseExtensionSpecParts, splitExtensionReference, toAuthor, toExtensionType, toExtensionTypePlural, } from "./common.js";
 export { ReleaseAgeExcludePatternSchema, matchesReleaseAgeExcludePattern, } from "./fqn-pattern.js";
 export { FqnInvalidError, formatFqn, parseFqn, parseFqnOrThrow } from "./fqn.js";
 export { HANDLE_PATTERN, HANDLE_PATTERN_SOURCE, HandleSchema, SLUG_PATTERN, SLUG_PATTERN_SOURCE, SlugSchema, decodeHandleSync, decodeSlugSync, handleFromSlug, normalizeHandle, normalizeSlug, slugFromHandle, } from "./handle.js";

package/dist/src/unstable/extensions/refs/extension-ref.d.ts

@@ -8,6 +8,7 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
+import type { ExtensionName } from "../common.js";
 import type { SkillExtensionRef } from "./skill.js";
 import type { McpServerExtensionRef } from "./mcp-server.js";
 import type { SubagentExtensionRef } from "./subagent.js";
@@ -17,4 +18,12 @@ import type { KnowledgeExtensionRef } from "./knowledge.js";
 import type { PackRef } from "./pack.js";
 /** @experimental */
 export type ExtensionRef = SkillExtensionRef | McpServerExtensionRef | SubagentExtensionRef | RuleExtensionRef | HookExtensionRef | KnowledgeExtensionRef | PackRef;
+/**
+ * The name an extension's own manifest gives it: the configured workspace
+ * name it occupies. A Registry ref's `name` is the package the Registry
+ * serves it under and may differ; Registry operations use that one.
+ *
+ * @experimental
+ */
+export declare const extensionRefName: (ref: ExtensionRef) => ExtensionName;
 //# sourceMappingURL=extension-ref.d.ts.map

package/dist/src/unstable/extensions/refs/extension-ref.js

@@ -8,5 +8,29 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-export {};
+/**
+ * The name an extension's own manifest gives it: the configured workspace
+ * name it occupies. A Registry ref's `name` is the package the Registry
+ * serves it under and may differ; Registry operations use that one.
+ *
+ * @experimental
+ */
+export const extensionRefName = (ref) => {
+    switch (ref.type) {
+        case "skill":
+            return ref.skill.name;
+        case "mcp-server":
+            return ref.server.name;
+        case "pack":
+            return ref.pack.name;
+        case "subagent":
+            return ref.subagent.name;
+        case "rule":
+            return ref.rule.name;
+        case "hook":
+            return ref.hook.name;
+        case "knowledge":
+            return ref.knowledge.name;
+    }
+};
 //# sourceMappingURL=extension-ref.js.map

package/dist/src/unstable/extensions/registry-source.d.ts

@@ -1,3 +1,4 @@
+import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 export declare const RegistrySourcePatternPartsSchema: Schema.Struct<{
     readonly owner: Schema.brand<Schema.String, "Handle">;
@@ -6,8 +7,14 @@ export declare const RegistrySourcePatternPartsSchema: Schema.Struct<{
     readonly versionRange: Schema.optional<Schema.brand<Schema.NonEmptyString, "VersionRange">>;
 }>;
 export type RegistrySourcePatternParts = Schema.Schema.Type<typeof RegistrySourcePatternPartsSchema>;
+/**
+ * A Registry locator with the configured source it names, when it names one.
+ * An unqualified `@owner/...` locator names no source here: which configured
+ * Registry it binds to is a workspace decision, made beside the settings that
+ * hold the effective default Registry.
+ */
 export type SourceQualifiedRegistrySourcePatternParts = RegistrySourcePatternParts & {
-    readonly sourceName: string;
+    readonly sourceName: Option.Option<string>;
 };
 export declare const RegistrySourceRefPartsSchema: Schema.Struct<{
     readonly owner: Schema.brand<Schema.String, "Handle">;
@@ -17,7 +24,10 @@ export declare const RegistrySourceRefPartsSchema: Schema.Struct<{
 }>;
 export type RegistrySourceRefParts = Schema.Schema.Type<typeof RegistrySourceRefPartsSchema>;
 export declare const parseRegistrySourcePatternParts: (input: string) => RegistrySourcePatternParts | undefined;
-/** Parse a Registry locator, assigning unqualified input to the built-in agentxm source. */
+/**
+ * Parse a Registry locator, keeping the configured source name it spells
+ * (`<source>:@owner/...`) and leaving an unqualified locator unbound.
+ */
 export declare const parseSourceQualifiedRegistrySourcePatternParts: (input: string) => SourceQualifiedRegistrySourcePatternParts | undefined;
 export declare const parseRegistrySourceRef: (input: string) => RegistrySourceRefParts | undefined;
 export declare const formatRegistrySourcePatternParts: (value: RegistrySourcePatternParts) => string;

package/dist/src/unstable/extensions/registry-source.js

@@ -1,9 +1,10 @@
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as SchemaTransformation from "effect/SchemaTransformation";
-import { ExtensionNameSchema, ExtensionTypePluralSchema } from "./common.js";
+import { ExtensionNameSchema, ExtensionTypePluralSchema, splitExtensionReference, } from "./common.js";
 import { HandleSchema } from "./handle.js";
 import { VersionRangeSchema } from "../version-constraints/version-constraints.js";
 const invalidRegistrySourcePattern = (input) => `Expected registry source pattern in @handle, @handle/<plural-type>, or @handle/<plural-type>/<name>@<constraint> form, got: ${input}`;
@@ -44,26 +45,12 @@ export const RegistrySourceRefPartsSchema = Schema.Struct({
 });
 const decodeRegistrySourcePatternParts = Schema.decodeUnknownResult(RegistrySourcePatternPartsSchema);
 const decodeRegistrySourceRefParts = Schema.decodeUnknownResult(RegistrySourceRefPartsSchema);
-const parseNameAndConstraintSegment = (segment) => {
-    const atIndex = segment.indexOf("@");
-    if (atIndex === 0) {
-        return undefined;
-    }
-    if (atIndex === -1) {
-        return { name: segment };
-    }
-    const name = segment.slice(0, atIndex);
-    const versionRange = segment.slice(atIndex + 1);
-    if (name.length === 0 || versionRange.length === 0) {
-        return undefined;
-    }
-    return { name, versionRange };
-};
 export const parseRegistrySourcePatternParts = (input) => {
     if (!input.startsWith("@")) {
         return undefined;
     }
-    const segments = input.split("/");
+    const { name: reference, constraint } = splitExtensionReference(input);
+    const segments = reference.split("/");
     if (segments.length < 1 || segments.length > 3) {
         return undefined;
     }
@@ -83,17 +70,9 @@ export const parseRegistrySourcePatternParts = (input) => {
     }
     else {
         const type = segments[1];
-        const third = segments[2];
-        if (type !== undefined && third !== undefined) {
-            const parsedName = parseNameAndConstraintSegment(third);
-            if (parsedName !== undefined) {
-                candidate = {
-                    owner,
-                    type,
-                    name: parsedName.name,
-                    versionRange: parsedName.versionRange,
-                };
-            }
+        const name = segments[2];
+        if (type !== undefined && name !== undefined) {
+            candidate = { owner, type, name, versionRange: constraint };
         }
     }
     if (candidate === undefined) {
@@ -102,25 +81,31 @@ export const parseRegistrySourcePatternParts = (input) => {
     const result = decodeRegistrySourcePatternParts(candidate);
     return Result.isSuccess(result) ? result.success : undefined;
 };
-/** Parse a Registry locator, assigning unqualified input to the built-in agentxm source. */
+/**
+ * Parse a Registry locator, keeping the configured source name it spells
+ * (`<source>:@owner/...`) and leaving an unqualified locator unbound.
+ */
 export const parseSourceQualifiedRegistrySourcePatternParts = (input) => {
     const unqualified = parseRegistrySourcePatternParts(input);
     if (unqualified !== undefined) {
-        return { ...unqualified, sourceName: "agentxm" };
+        return { ...unqualified, sourceName: Option.none() };
     }
     const separator = input.indexOf(":");
     if (separator <= 0)
         return undefined;
     const sourceName = input.slice(0, separator);
     const qualified = parseRegistrySourcePatternParts(input.slice(separator + 1));
-    return qualified === undefined ? undefined : { ...qualified, sourceName };
+    return qualified === undefined
+        ? undefined
+        : { ...qualified, sourceName: Option.some(sourceName) };
 };
 export const parseRegistrySourceRef = (input) => {
     const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
     if (parsed?.type === undefined || parsed.name === undefined) {
         return undefined;
     }
-    const result = decodeRegistrySourceRefParts(parsed);
+    const { sourceName: _sourceName, ...parts } = parsed;
+    const result = decodeRegistrySourceRefParts(parts);
     return Result.isSuccess(result) ? result.success : undefined;
 };
 export const formatRegistrySourcePatternParts = (value) => {

package/dist/src/unstable/sources/parser.d.ts

@@ -17,10 +17,14 @@ type NameInput = {
     readonly pattern: "name-input";
     readonly name: string;
 };
-/** A namespaced registry source: `[source-name:]@owner/<plural-type>/name`. */
+/**
+ * A namespaced registry source: `[source-name:]@owner/<plural-type>/name`.
+ * `sourceName` is the configured source the input spells; an unqualified
+ * input leaves it unbound for the workspace to assign.
+ */
 type RegistryPatternInput = {
     readonly pattern: "registry-pattern-input";
-    readonly sourceName: string;
+    readonly sourceName: Option.Option<string>;
     readonly type: Option.Option<ExtensionTypePlural>;
     readonly owner: Handle;
     readonly name: Option.Option<ExtensionName>;

package/dist/src/unstable/sources/source-host-provider.d.ts

@@ -7,7 +7,6 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-import type * as Duration from "effect/Duration";
 import type * as Effect from "effect/Effect";
 import type * as Option from "effect/Option";
 import type { ExtensionType, Handle } from "../extensions/index.js";
@@ -29,11 +28,6 @@ export interface FindOptions {
     /** Registry owner filter (e.g. "@acme"). */
     readonly owner: Option.Option<Handle>;
     readonly versionRange: Option.Option<string>;
-    /**
-     * Optional minimum age a registry release must have before it is selectable.
-     * Omitted for explicit attended installs.
-     */
-    readonly minimumReleaseAge?: Option.Option<Duration.Duration>;
 }
 export interface NamedRegistryFindOptions {
     readonly name: string;
@@ -54,6 +48,8 @@ export type NamedRegistryResolution = {
         readonly refType: "registry";
     }>;
     readonly newerHeld?: ReleaseAgeEvidence;
+    /** The newest release a range could select, whatever range was requested. */
+    readonly newestVisible?: string;
 } | {
     readonly kind: "exempted";
     readonly target: string;
@@ -62,6 +58,7 @@ export type NamedRegistryResolution = {
     }>;
     readonly bypassed: ReleaseAgeEvidence;
     readonly exemption: ReleaseAgeExemption;
+    readonly newestVisible?: string;
 } | {
     readonly kind: "not_found";
     readonly target: string;
@@ -87,11 +84,18 @@ export type NamedRegistryVersionDecision = {
     readonly kind: "selected";
     readonly version: string;
     readonly newerHeld?: ReleaseAgeEvidence;
+    /**
+     * The newest release the index lists that a range could select — not
+     * yanked, whatever range was requested — so a caller can say what its
+     * constraint held the selection below.
+     */
+    readonly newestVisible?: string;
 } | {
     readonly kind: "exempted";
     readonly version: string;
     readonly bypassed: ReleaseAgeEvidence;
     readonly exemption: ReleaseAgeExemption;
+    readonly newestVisible?: string;
 } | {
     readonly kind: "not_found";
 } | {

package/dist/src/unstable/version-constraints/version-constraints.d.ts

@@ -39,12 +39,9 @@ export declare const decodeVersionSync: (input: unknown, options?: import("effec
  */
 export declare const decodeVersionRangeSync: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => string & import("effect/Brand").Brand<"VersionRange">;
 /**
- * Extract a version range suffix from a source string.
- *
- * Handles both namespaced (`@handle/name@^1.0.0`) and non-namespaced (`name@^1.0.0`) names.
- * Returns `Option.none()` when no version suffix is present.
+ * Decode a value as a semver version range, or none when it is not one.
  */
-export declare const parseVersionRange: (sourceString: string) => Option.Option<VersionRange>;
+export declare const decodeVersionRangeOption: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Option.Option<string & import("effect/Brand").Brand<"VersionRange">>;
 /**
  * Check whether a string is a valid semver version range.
  */
@@ -57,15 +54,16 @@ export declare const intersectVersionConstraints: (constraints: ReadonlyArray<st
  */
 export declare const hasMinorOrMajorVersionBump: (previousVersion: string, currentVersion: string) => boolean;
 /**
- * Check whether a version satisfies a semver version range.
+ * Whether a version is one the range admits: the one predicate every
+ * selection and every satisfaction check applies, so a range admits the same
+ * versions wherever it is asked. It follows semver exactly, so `*` and an
+ * absent range admit every stable version and no prerelease; a prerelease is
+ * admitted only by a range that names its version tuple.
  */
 export declare const versionSatisfiesRange: (version: Version, range: VersionRange) => boolean;
 /**
- * Select the maximum version that satisfies the range, independent of input
- * order.
- *
- * - `Option.none()` range or `"*"` matches any version.
- * - Invalid ranges match nothing.
+ * Select the highest version the range admits, independent of input order.
+ * An absent range admits what `*` admits; an invalid range admits nothing.
  */
 export declare const resolveVersionInRange: <T extends VersionEntryLike>(versions: ReadonlyArray<T>, range: Option.Option<string>) => Option.Option<T>;
 //# sourceMappingURL=version-constraints.d.ts.map

package/dist/src/unstable/version-constraints/version-constraints.js

@@ -46,36 +46,9 @@ export const decodeVersionSync = Schema.decodeUnknownSync(VersionSchema);
 export const decodeVersionRangeSync = Schema.decodeUnknownSync(VersionRangeSchema);
 const parseSemverVersion = (version) => semver.parse(version);
 /**
- * Extract a version range suffix from a source string.
- *
- * Handles both namespaced (`@handle/name@^1.0.0`) and non-namespaced (`name@^1.0.0`) names.
- * Returns `Option.none()` when no version suffix is present.
+ * Decode a value as a semver version range, or none when it is not one.
  */
-export const parseVersionRange = (sourceString) => {
-    const decodeRange = (value) => {
-        try {
-            return Option.some(decodeVersionRangeSync(value));
-        }
-        catch {
-            return Option.none();
-        }
-    };
-    // For namespaced packages (@handle/name@range), find the @ after the handle
-    if (sourceString.startsWith("@")) {
-        const slashIndex = sourceString.indexOf("/");
-        if (slashIndex === -1)
-            return Option.none();
-        const afterHandle = sourceString.indexOf("@", slashIndex + 1);
-        if (afterHandle === -1)
-            return Option.none();
-        return decodeRange(sourceString.slice(afterHandle + 1));
-    }
-    // For non-namespaced packages (name@range)
-    const atIndex = sourceString.indexOf("@");
-    if (atIndex === -1)
-        return Option.none();
-    return decodeRange(sourceString.slice(atIndex + 1));
-};
+export const decodeVersionRangeOption = Schema.decodeUnknownOption(VersionRangeSchema);
 /**
  * Check whether a string is a valid semver version range.
  */
@@ -159,29 +132,27 @@ export const hasMinorOrMajorVersionBump = (previousVersion, currentVersion) => {
     return current.major > previous.major || current.minor > previous.minor;
 };
 /**
- * Check whether a version satisfies a semver version range.
+ * Whether a version is one the range admits: the one predicate every
+ * selection and every satisfaction check applies, so a range admits the same
+ * versions wherever it is asked. It follows semver exactly, so `*` and an
+ * absent range admit every stable version and no prerelease; a prerelease is
+ * admitted only by a range that names its version tuple.
  */
 export const versionSatisfiesRange = (version, range) => semver.satisfies(version, range);
+/** The range an absent constraint stands for: every stable version. */
+const UNCONSTRAINED_RANGE = "*";
 /**
- * Select the maximum version that satisfies the range, independent of input
- * order.
- *
- * - `Option.none()` range or `"*"` matches any version.
- * - Invalid ranges match nothing.
+ * Select the highest version the range admits, independent of input order.
+ * An absent range admits what `*` admits; an invalid range admits nothing.
  */
 export const resolveVersionInRange = (versions, range) => {
-    const rangeStr = Option.getOrElse(range, () => "*");
-    // Wildcard means no range filtering
-    const isWildcard = rangeStr === "*";
-    // Validate the range early
-    if (!isWildcard && !isValidVersionRange(rangeStr)) {
+    const decoded = decodeVersionRangeOption(Option.getOrElse(range, () => UNCONSTRAINED_RANGE));
+    if (Option.isNone(decoded))
         return Option.none();
-    }
     let selected;
     for (const version of versions) {
-        if (!isWildcard && !semver.satisfies(version.version, rangeStr)) {
+        if (!versionSatisfiesRange(version.version, decoded.value))
             continue;
-        }
         if (selected === undefined || semver.compareBuild(version.version, selected.version) > 0) {
             selected = version;
         }

package/package.json

@@ -11,14 +11,14 @@
   },
   "description": "Shared AgentXM extension model: identities, manifests, version constraints, and agent capabilities. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
-    "@agentxm/specification-metadata": "0.34.0",
+    "@agentxm/specification-metadata": "0.35.0",
     "@effect/vitest": "4.0.0-rc.117",
     "@fast-check/vitest": "^0.5.0",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "4.0.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.19.0"
@@ -305,5 +305,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.34.0"
+  "version": "0.35.0"
 }